Merge branch 'master' into v5

src/@ionic-native/plugins/bluetooth-le/index.ts

@@ -1,5 +1,10 @@
 import { Injectable } from '@angular/core';
-import { Cordova, CordovaProperty, IonicNativePlugin, Plugin } from '@ionic-native/core';
+import {
+  Cordova,
+  CordovaProperty,
+  IonicNativePlugin,
+  Plugin
+} from '@ionic-native/core';
 import { Observable } from 'rxjs';
 
 /* Available status of device */
@@ -67,7 +72,7 @@ export interface InitParams extends InitPeripheralParams {
 export interface ScanParams {
   /* An array of service IDs to filter the scan or empty array / null. This parameter is not supported on Windows platform yet */
   services?: string[];
-  /** True/false to allow duplicate advertisement packets, defaults to false (iOS) */
+  /* True/false to allow duplicate advertisement packets, defaults to false (iOS)*/
   allowDuplicates?: boolean;
   /** Defaults to Low Power. Available from API21 / API 23 (Android) */
   scanMode?: BluetoothScanMode;
@@ -181,7 +186,7 @@ export interface MTU extends DeviceInfo {
 }
 
 export interface BondedStatus extends CommonInfo {
-  /** Bonded status */
+  /* Bonded status*/
   isBonded: boolean;
 }
 
@@ -322,7 +327,7 @@ export interface DescriptorResult extends OperationResult {
 export interface Characteristics extends DeviceInfo {
   /** Service's id */
   service: string;
-  /** Array of characteristic objects */
+  /* Array of characteristic objects*/
   characteristics: Characteristic[];
 }
 
@@ -374,6 +379,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 +429,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 +440,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 +450,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 +460,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<AdapterInfo>}
    */
-  @Cordova({ callbackOrder: 'reverse' })
-  getAdapterInfo(): Promise<{
-    name: string;
-    address: string;
-    isInitialized: boolean;
-    isEnabled: boolean;
-    isScanning: boolean;
-    isDiscoverable: boolean;
-  }> {
+  @Cordova({ callbackOrder: 'reverse', observable: true })
+  getAdapterInfo(): Promise<AdapterInfo> {
     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 +489,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 +500,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 +514,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 +532,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 +545,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 +565,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 +576,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 +588,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 +601,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 +623,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 +638,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 +652,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 +663,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<OperationResult>}
    */
   @Cordova({ callbackOrder: 'reverse' })
-  read(params: DescriptorParams): Promise<OperationResult> {
+  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<OperationResult>}
+   * @returns {(Observable<{ result: OperationResult }>)}
    */
   @Cordova({ callbackOrder: 'reverse', observable: true })
-  subscribe(params: DescriptorParams): Observable<OperationResult> {
+  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<UnsubscribeResult>}
    */
@@ -688,7 +698,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<OperationResult>}
@@ -700,7 +710,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<OperationResult>}
@@ -712,7 +722,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<DescriptorResult>}
    */
@@ -723,7 +733,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<DescriptorResult>}
@@ -735,7 +745,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 +756,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 +767,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<DeviceInfo>}
@@ -772,7 +782,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 +792,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 +802,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 +812,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<BondedStatus>}
    */
@@ -813,7 +823,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<PrevConnectionStatus>}
    */
@@ -824,7 +834,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<CurrConnectionStatus>}
    */
@@ -835,7 +845,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<DiscoverStatus>}
    */
@@ -846,7 +856,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 +866,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 +877,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 +887,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 +898,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<InitializeResult>}
    */
-  @Cordova({ callbackOrder: 'reverse' })
+  @Cordova({ callbackOrder: 'reverse', observable: true })
   initializePeripheral(
     params?: InitPeripheralParams
   ): Observable<InitializeResult> {
@@ -902,7 +912,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 +926,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 +939,7 @@ export class BluetoothLE extends IonicNativePlugin {
 
   /**
    * @name removeAllServices
-   * @description Remove all services
+   * Remove all services
    * @returns {Promise<{ status: Status }>}
    */
   @Cordova({ callbackOrder: 'reverse' })
@@ -939,7 +949,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 +962,7 @@ export class BluetoothLE extends IonicNativePlugin {
 
   /**
    * @name stopAdvertising
-   * @description Stop advertising
+   * Stop advertising
    * @returns {Promise<{ status: Status }>}
    */
   @Cordova({ callbackOrder: 'reverse' })
@@ -962,7 +972,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 +982,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 +993,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 +1006,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 +1017,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 +1028,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}
    */