@ledgerhq/live-common
Version:
Common ground for the Ledger Live apps
52 lines • 3.31 kB
TypeScript
import type { DeviceModelId } from "@ledgerhq/types-devices";
import type { Observer as TransportObserver, Subscription as TransportSubscription, DescriptorEvent } from "@ledgerhq/hw-transport";
import { DeviceId } from "@ledgerhq/types-live";
import { HwTransportError } from "@ledgerhq/errors";
import { TransportBleDevice, ScannedDevice } from "../types";
export type ScanningBleError = HwTransportError | null;
export type UseBleDevicesScanningResult = {
scannedDevices: ScannedDevice[];
scanningBleError: ScanningBleError;
};
export type UseBleDevicesScanningDependencies = {
bleTransportListen: (observer: TransportObserver<DescriptorEvent<TransportBleDevice | null>, HwTransportError>) => TransportSubscription;
};
export type UseBleDevicesScanningOptions = {
stopBleScanning?: boolean;
filterByDeviceModelIds?: DeviceModelId[];
filterOutDevicesByDeviceIds?: DeviceId[];
restartScanningTimeoutMs?: number;
enabled?: boolean;
};
/**
* Scans the BLE devices around the user
*
* Warning: if a communication is started with a device, the scanning should be stopped
*
* Warning: handling of bluetooth (and location for Android) permissions and enabling bluetooth (and location) services are not handled here.
* They should be handled (with fallback logic) by the consumer of this hook.
*
* Reason: depending on the bleTransportListen function and the user's operating system, errors related to denied bluetooth (and location for Android) permissions
* or related to disabled bluetooth (and location) services might be different.
* For ex:
* - on Android, using the current Transport from react-native-hw-transport-ble, if the bluetooth is off,
* a BluetoothScanStartFailed error is thrown, not an actual "BluetoothOff" or "BluetoothUnauthorized" error.
* It is a problem because this BluetoothScanStartFailed error could happen for other reason than the BLE being off.
* On the other side, if the location service (needed for Android) is off, an error "LocationServicesDisabled" is thrown.
*
* - on iOS, using the current Transport from react-native-hw-transport-ble, if the bluetooth is off, no error is thrown at all.
*
* @param bleTransportListen The listen function from an implementation of a BLE transport
* @param filterByDeviceModelIds An array of device model ids to filter on
* @param filterOutDevicesByDeviceIds An array of device ids to filter out
* @param stopBleScanning Flag to stop or continue the scanning
* @param restartScanningTimeoutMs When a restart is needed (on some specific errors, or for the first restart
* that makes the scanning more resilient to a previously paired device with which a communication was happening),
* time in ms after which the restart is actually happening
* @param enabled flag to enable the hook
* @returns An object containing:
* - scannedDevices: list of ScannedDevice found by the scanning
* - scanningBleError: if an error occurred, a BleError, otherwise null
*/
export declare const useBleDevicesScanning: ({ bleTransportListen, stopBleScanning, filterByDeviceModelIds, filterOutDevicesByDeviceIds, restartScanningTimeoutMs, enabled, }: UseBleDevicesScanningDependencies & UseBleDevicesScanningOptions) => UseBleDevicesScanningResult;
//# sourceMappingURL=useBleDevicesScanning.d.ts.map