diff --git a/src/@ionic-native/plugins/bluetooth-le/index.ts b/src/@ionic-native/plugins/bluetooth-le/index.ts index c2ee3024cd..45bbaa8333 100644 --- a/src/@ionic-native/plugins/bluetooth-le/index.ts +++ b/src/@ionic-native/plugins/bluetooth-le/index.ts @@ -374,6 +374,15 @@ export interface Error { message: string; } +export interface AdapterInfo { + name: string; + address: string; + isInitialized: boolean; + isEnabled: boolean; + isScanning: boolean; + isDiscoverable: boolean; +} + /** * @name BluetoothLE * @description @@ -415,7 +424,7 @@ export interface Error { export class BluetoothLE extends IonicNativePlugin { /** * @name initialize - * @description Initialize Bluetooth on the device + * Initialize Bluetooth on the device * @param {InitParams} [params] * @returns {(Promise<{ status: 'enabled' | 'disabled'}>)} The callback that is passed initialize status (enabled/disabled) */ @@ -426,7 +435,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name enable (Android) - * @description Enable Bluetooth on the device. Android support only + * Enable Bluetooth on the device. Android support only * @returns {Promise<{ status: boolean }>} */ @Cordova({ callbackOrder: 'reverse', sync: true }) @@ -436,7 +445,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name disable (Android) - * @description Disable Bluetooth on the device. Android support only + * Disable Bluetooth on the device. Android support only * @returns void */ @Cordova({ callbackOrder: 'reverse', sync: true }) @@ -446,30 +455,26 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name getAdapterInfo (Android) - * @description @todo - * @returns {Promise<{ name: string, address: string, isInitialized: boolean, isEnabled: boolean, isScanning: boolean, isDiscoverable: boolean}>} + * Retrieve useful information such as the address, name, and various states (initialized, enabled, scanning, discoverable). + * This can be very useful when the general state of the adapter has been lost, and we would otherwise need to go through a series of callbacks to get the correct state (first initialized, then enabled, then isScanning, and so forth). + * The result of this method allows us to take business logic decisions while avoiding a large part of the callback hell. + * Currently the discoverable state does not have any relevance because there is no "setDiscoverable" functionality in place. That may change in the future. + * @returns {Promise} */ - @Cordova({ callbackOrder: 'reverse' }) - getAdapterInfo(): Promise<{ - name: string; - address: string; - isInitialized: boolean; - isEnabled: boolean; - isScanning: boolean; - isDiscoverable: boolean; - }> { + @Cordova({ callbackOrder: 'reverse', observable: true }) + getAdapterInfo(): Promise { return; } /** * @name startScan - * @description Scan for Bluetooth LE devices. + * Scan for Bluetooth LE devices. * Since scanning is expensive, stop as soon as possible. The Cordova app should use a timer to limit the scan interval. * Android API >= 23 requires ACCESS_COARSE_LOCATION permissions to find unpaired devices. * Permissions can be requested by using the hasPermission and requestPermission functions. * Android API >= 23 also requires location services to be enabled. Use isLocationEnabled to determine whether location services are enabled. * If not enabled, use requestLocation to prompt the location services settings page. - * @param params Scan params + * @param {ScanParams} params Scan params * @returns {(Observable<{ status: ScanStatus }>)} */ @Cordova({ callbackOrder: 'reverse', observable: true }) @@ -479,7 +484,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name stopScan - * @description Stop scan for Bluetooth LE devices. Since scanning is expensive, stop as soon as possible + * Stop scan for Bluetooth LE devices. Since scanning is expensive, stop as soon as possible * The app should use a timer to limit the scanning time. * @returns {Promise<{status: 'scanStopped'}>} */ @@ -490,7 +495,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name retrieveConnected - * @description Retrieved paired Bluetooth LE devices. In iOS, devices that are "paired" to will not return during a normal scan. + * Retrieved paired Bluetooth LE devices. In iOS, devices that are "paired" to will not return during a normal scan. * Callback is "instant" compared to a scan. * @param {{ services: string[] }} An array of service IDs to filter the retrieval by. If no service IDs are specified, no devices will be returned. * @returns {Promise<{ devices: DeviceInfo[] }>} @@ -504,7 +509,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name bond (Android) - * @description Bond with a device. + * Bond with a device. * The device doesn't need to be connected to initiate bonding. Android support only. * @param {{ address: string }} params The address/identifier provided by the scan's return object * @returns {(Observable<{ status: DeviceInfo }>)} @@ -522,7 +527,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name unbond (Android) - * @description Unbond with a device. The device doesn't need to be connected to initiate bonding. Android support only. + * Unbond with a device. The device doesn't need to be connected to initiate bonding. Android support only. * @param {{address: string}} params The address/identifier * @returns {Promise<{ status: DeviceInfo }>} * success: The success callback should always return with status == unbonded, that is passed with device object @@ -535,7 +540,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name connect - * @description Connect to a Bluetooth LE device + * Connect to a Bluetooth LE device * @param connectSuccess The success callback that is passed with device object * @param connectError The callback that will be triggered when the connect operation fails * @param params The address/identifier @@ -555,7 +560,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name reconnect - * @description Reconnect to a previously connected Bluetooth device + * Reconnect to a previously connected Bluetooth device * @param {{address: string}} params The address/identifier * @returns {(Observable<{ status: DeviceInfo }>)} */ @@ -566,7 +571,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name disconnect - * @description Disconnect from a Bluetooth LE device. + * Disconnect from a Bluetooth LE device. * Note: It's simpler to just call close(). Starting with iOS 10, disconnecting before closing seems required! * @param {{address: string}} params The address/identifier * @returns {Promise<{ status: DeviceInfo }>} @@ -578,7 +583,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name close - * @description Close/dispose a Bluetooth LE device. + * Close/dispose a Bluetooth LE device. * Prior to 2.7.0, you needed to disconnect to the device before closing, but this is no longer the case. * Starting with iOS 10, disconnecting before closing seems required! * @param {{ address: string }} params The address/identifier @@ -591,7 +596,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name discover - * @description Discover all the devices services, characteristics and descriptors. + * Discover all the devices services, characteristics and descriptors. * Doesn't need to be called again after disconnecting and then reconnecting. * If using iOS, you shouldn't use discover and services/characteristics/descriptors on the same device. * There seems to be an issue with calling discover on iOS8 devices, so use with caution. @@ -613,7 +618,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name services (iOS) - * @description Discover the device's services. + * Discover the device's services. * Not providing an array of services will return all services and take longer to discover. iOS support only. * @param {{address: string, services: string[]}} params * @returns {Promise<{ services: Services }>} @@ -628,7 +633,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name characteristics (iOS) - * @description Discover the service's characteristics. + * Discover the service's characteristics. * Not providing an array of characteristics will return all characteristics and take longer to discover. iOS support only. * @param {CharacteristicParams} params Characteristic params * @returns {Promise<{ characteristics: Characteristics }>} The service id and an Array of characteristics @@ -642,7 +647,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name descriptors (iOS) - * @description Discover the characteristic's descriptors. iOS support only. + * Discover the characteristic's descriptors. iOS support only. * @param {DescriptorParams} params * @returns {Promise<{ descriptors: Descriptors }>} */ @@ -653,31 +658,31 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name read - * @description Read a particular service's characteristic once + * Read a particular service's characteristic once * @param {DescriptorParams} params * @returns {Promise} */ @Cordova({ callbackOrder: 'reverse' }) - read(params: DescriptorParams): Promise { + read(params: DescriptorParams): Promise<{ result: OperationResult }> { return; } /** * @name subscribe - * @description Subscribe to a particular service's characteristic. + * Subscribe to a particular service's characteristic. * Once a subscription is no longer needed, execute unsubscribe in a similar fashion. * The Client Configuration descriptor will automatically be written to enable notification/indication based on the characteristic's properties. * @param {DescriptorParams} params - * @returns {Promise} + * @returns {(Observable<{ result: OperationResult }>)} */ @Cordova({ callbackOrder: 'reverse', observable: true }) - subscribe(params: DescriptorParams): Observable { + subscribe(params: DescriptorParams): Observable<{ result: OperationResult }> { return; } /** * @name unsubscribe - * @description Unsubscribe to a particular service's characteristic. + * Unsubscribe to a particular service's characteristic. * @param {DescriptorParams} params * @returns {Promise} */ @@ -688,7 +693,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name write (limitation on iOS, read below) - * @description Write a particular service's characteristic + * Write a particular service's characteristic * Note: no callback will occur on write without response on iOS. * @param {WriteCharacteristicParams} params * @returns {Promise} @@ -700,7 +705,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name write (limitation on iOS, read below) - * @description Write Quick / Queue, use this method to quickly execute write without response commands when writing more than 20 bytes at a time. + * Write Quick / Queue, use this method to quickly execute write without response commands when writing more than 20 bytes at a time. * Note: no callback will occur on write without response on iOS. * @param {WriteCharacteristicParams} params * @returns {Promise} @@ -712,7 +717,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name readDescriptor - * @description Read a particular characterist's descriptor + * Read a particular characterist's descriptor * @param {OperationDescriptorParams} params * @returns {Promise} */ @@ -723,7 +728,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name writeDescriptor - * @description Write a particular characteristic's descriptor. Unable to write characteristic configuration directly to keep in line with iOS implementation. + * Write a particular characteristic's descriptor. Unable to write characteristic configuration directly to keep in line with iOS implementation. * Instead use subscribe/unsubscribe, which will automatically enable/disable notification. * @param {WriteDescriptorParams} params * @returns {Promise} @@ -735,7 +740,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name rssi - * @description Read RSSI of a connected device. RSSI is also returned with scanning. + * Read RSSI of a connected device. RSSI is also returned with scanning. * @param {{ address: string }} params * @returns {Promise<{ rssi: RSSI }>} */ @@ -746,7 +751,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name mtu (Android, Android 5+) - * @description Set MTU of a connected device. Android only. + * Set MTU of a connected device. Android only. * @param {{ address: string, mtu: number }} params * @returns {Promise<{ mtu: MTU }>} */ @@ -757,7 +762,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name requestConnectionPriority (Android, Android 5+) - * @description Request a change in the connection priority to improve throughput when transfer large amounts of data via BLE. + * Request a change in the connection priority to improve throughput when transfer large amounts of data via BLE. * Android support only. iOS will return error. * @param {{ address: string, connectionPriority: ConnectionPriority }} params * @returns {Promise} @@ -772,7 +777,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isInitialized - * @description Determine whether the adapter is initialized. No error callback. Returns true or false + * Determine whether the adapter is initialized. No error callback. Returns true or false * @returns {Promise<{ isInitialized: boolean }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -782,7 +787,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isEnabled - * @description Determine whether the adapter is enabled. No error callback + * Determine whether the adapter is enabled. No error callback * @returns {Promise<{ isEnabled: boolean }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -792,7 +797,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isScanning - * @description Determine whether the adapter is scanning. No error callback. Returns true or false + * Determine whether the adapter is scanning. No error callback. Returns true or false * @returns {Promise<{ isScanning: boolean }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -802,7 +807,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isBonded (Android) - * @description Determine whether the device is bonded or not, or error if not initialized. Android support only. + * Determine whether the device is bonded or not, or error if not initialized. Android support only. * @param {{ address: string }} params * @returns {Promise} */ @@ -813,7 +818,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name wasConnected - * @description Determine whether the device was connected, or error if not initialized. + * Determine whether the device was connected, or error if not initialized. * @param {{ address: string }} params * @returns {Promise} */ @@ -824,7 +829,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isConnected - * @description Determine whether the device is connected, or error if not initialized or never connected to device + * Determine whether the device is connected, or error if not initialized or never connected to device * @param {{ address: string }} params * @returns {Promise} */ @@ -835,7 +840,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isDiscovered - * @description Determine whether the device's characteristics and descriptors have been discovered, or error if not initialized or not connected to device. + * Determine whether the device's characteristics and descriptors have been discovered, or error if not initialized or not connected to device. * @param {{ address: string }} params * @returns {Promise} */ @@ -846,7 +851,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name hasPermission (useful only for Android 6+ / API 23) - * @description Determine whether coarse location privileges are granted since scanning for unpaired devices requires it in Android API 23 + * Determine whether coarse location privileges are granted since scanning for unpaired devices requires it in Android API 23 * @returns {Promise<{ hasPermission: boolean }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -856,7 +861,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name requestPermission (useful only for Android 6+ / API 23) - * @description Request coarse location privileges since scanning for unpaired devices requires it in Android API 23. + * Request coarse location privileges since scanning for unpaired devices requires it in Android API 23. * Will return an error if called on iOS or Android versions prior to 6.0. * @returns {Promise<{ requestPermission: boolean }>} */ @@ -867,7 +872,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isLocationEnabled (useful only for Android 6+ / API 23) - * @description Determine if location services are enabled or not. Location Services are required to find devices in Android API 23 + * Determine if location services are enabled or not. Location Services are required to find devices in Android API 23 * @returns {Promise<{ isLocationEnabled: boolean }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -877,7 +882,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name requestLocation (useful only for Android 6+ / API 23) - * @description Prompt location services settings pages. requestLocation property returns whether location services are enabled or disabled. + * Prompt location services settings pages. requestLocation property returns whether location services are enabled or disabled. * Location Services are required to find devices in Android API 23. * @returns {Promise<{ requestLocation: boolean }>} */ @@ -888,12 +893,12 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name initializePeripheral - * @description Initialize Bluetooth on the device. Must be called before anything else. + * Initialize Bluetooth on the device. Must be called before anything else. * Callback will continuously be used whenever Bluetooth is enabled or disabled. * @param {InitPeripheralParams} [params] * @returns {Observable} */ - @Cordova({ callbackOrder: 'reverse' }) + @Cordova({ callbackOrder: 'reverse', observable: true }) initializePeripheral( params?: InitPeripheralParams ): Observable { @@ -902,7 +907,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name addService - * @description Add a service with characteristics and descriptors. If more than one service is added, add them sequentially + * Add a service with characteristics and descriptors. If more than one service is added, add them sequentially * @param {{ service: string, characteristics: Characteristic[] }} params * @returns {Promise<{ service: string, status: Status }>} */ @@ -916,7 +921,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name removeService - * @description Remove a service + * Remove a service * @param {{ service: string }} params * @returns {Promise<{ service: string, status: Status }>} */ @@ -929,7 +934,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name removeAllServices - * @description Remove all services + * Remove all services * @returns {Promise<{ status: Status }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -939,7 +944,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name startAdvertising (different behavior on Android/iOS, read below) - * @description Start advertising as a BLE device. + * Start advertising as a BLE device. * Note: This needs to be improved so services can be used for both Android and iOS. * On iOS, the advertising devices likes to rename itself back to the name of the device, i.e. Rand' iPhone * @param {AdvertisingParams} params @@ -952,7 +957,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name stopAdvertising - * @description Stop advertising + * Stop advertising * @returns {Promise<{ status: Status }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -962,7 +967,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name isAdvertising - * @description Determine if app is advertising or not. + * Determine if app is advertising or not. * @returns {Promise<{ status: boolean }>} */ @Cordova({ callbackOrder: 'reverse' }) @@ -972,7 +977,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name respond - * @description Respond to a read or write request + * Respond to a read or write request * @param {RespondParams} params * @returns {Promise<{ status: Status }>} */ @@ -983,7 +988,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name notify - * @description Update a value for a subscription. Currently all subscribed devices will receive update. + * Update a value for a subscription. Currently all subscribed devices will receive update. * Device specific updates will be added in the future. * If sent equals false in the return value, you must wait for the peripheralManagerIsReadyToUpdateSubscribers event before sending more updates. * @param {NotifyParams} params @@ -996,7 +1001,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name encodedStringToBytes - * @description Helper function to convert a base64 encoded string from a characteristic or descriptor value into a uint8Array object + * Helper function to convert a base64 encoded string from a characteristic or descriptor value into a uint8Array object * @param {string} str * @returns {Uint8Array} */ @@ -1007,7 +1012,7 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name bytesToEncodedString - * @description Helper function to convert a unit8Array to a base64 encoded string for a characteric or descriptor write + * Helper function to convert a unit8Array to a base64 encoded string for a characteric or descriptor write * @param {Uint8Array} bytes * @returns {string} */ @@ -1018,18 +1023,18 @@ export class BluetoothLE extends IonicNativePlugin { /** * @name stringToBytes - * @description Helper function to convert a string to bytes - * @param {Uint8Array} value - * @returns {string} + * Helper function to convert a string to bytes + * @param {string} value + * @returns {Uint8Array} */ @Cordova({ sync: true }) - stringToBytes(value: Uint8Array): string { + stringToBytes(value: string): Uint8Array { return; } /** * @name bytesToString - * @description Helper function to convert bytes to a string. + * Helper function to convert bytes to a string. * @param {Uint8Array} value * @returns {string} */