@react-native-ohos/react-native-ble-plx 3.2.1-rc.1

package/src/Characteristic.js

@@ -0,0 +1,166 @@
+// @flow
+'use strict'
+
+import type { BleManager } from './BleManager'
+import type { BleError } from './BleError'
+import { Descriptor } from './Descriptor'
+import type { NativeCharacteristic } from './BleModule'
+import type { DeviceId, Identifier, UUID, TransactionId, Base64, Subscription } from './TypeDefinition'
+
+/**
+ * Characteristic object.
+ */
+export class Characteristic implements NativeCharacteristic {
+  /**
+   * Internal BLE Manager handle
+   * @private
+   */
+  _manager: BleManager
+  /**
+   * Characteristic unique identifier
+   */
+  id: Identifier
+  /**
+   * Characteristic UUID
+   */
+  uuid: UUID
+  /**
+   * Service's ID to which characteristic belongs
+   */
+  serviceID: Identifier
+  /**
+   * Service's UUID to which characteristic belongs
+   */
+  serviceUUID: UUID
+  /**
+   * Device's ID to which characteristic belongs
+   */
+  deviceID: DeviceId
+  /**
+   * True if characteristic can be read
+   */
+  isReadable: boolean
+  /**
+   * True if characteristic can be written with response
+   */
+  isWritableWithResponse: boolean
+  /**
+   * True if characteristic can be written without response
+   */
+  isWritableWithoutResponse: boolean
+  /**
+   * True if characteristic can monitor value changes.
+   */
+  isNotifiable: boolean
+  /**
+   * True if characteristic is monitoring value changes without ACK.
+   */
+  isNotifying: boolean
+  /**
+   * True if characteristic is monitoring value changes with ACK.
+   */
+  isIndicatable: boolean
+  /**
+   * Characteristic value if present
+   */
+  value: ?Base64
+
+  /**
+   * Private constructor used to create instance of {@link Characteristic}.
+   * @param {NativeCharacteristic} nativeCharacteristic NativeCharacteristic
+   * @param {BleManager} manager BleManager
+   * @private
+   */
+  constructor(nativeCharacteristic: NativeCharacteristic, manager: BleManager) {
+    Object.assign(this, nativeCharacteristic, { _manager: manager })
+  }
+
+  /**
+   * {@link #blemanagerdescriptorsfordevice|bleManager.descriptorsForDevice()} with partially filled arguments.
+   *
+   * @returns {Promise<Array<Descriptor>>} Promise which emits array of {@link Descriptor} objects which are
+   * discovered for this {@link Characteristic}.
+   */
+  descriptors(): Promise<Array<Descriptor>> {
+    return this._manager._descriptorsForCharacteristic(this.id)
+  }
+
+  /**
+   * {@link #blemanagerreadcharacteristicfordevice|bleManager.readCharacteristicForDevice()} with partially filled arguments.
+   *
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Promise<Characteristic>} Promise which emits this {@link Characteristic}. Latest value will be stored
+   * inside returned object.
+   */
+  read(transactionId: ?TransactionId): Promise<Characteristic> {
+    return this._manager._readCharacteristic(this.id, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerwritecharacteristicwithresponsefordevice|bleManager.writeCharacteristicWithResponseForDevice()} with partially filled arguments.
+   *
+   * @param {Base64} valueBase64 Value in Base64 format.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Promise<Characteristic>} Promise which emits this {@link Characteristic}. Latest value may
+   * not be stored inside returned object.
+   */
+  writeWithResponse(valueBase64: Base64, transactionId: ?TransactionId): Promise<Characteristic> {
+    return this._manager._writeCharacteristicWithResponse(this.id, valueBase64, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerwritecharacteristicwithoutresponsefordevice|bleManager.writeCharacteristicWithoutResponseForDevice()} with partially filled arguments.
+   *
+   * @param {Base64} valueBase64 Value in Base64 format.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Promise<Characteristic>} Promise which emits this {@link Characteristic}. Latest value may
+   * not be stored inside returned object.
+   */
+  writeWithoutResponse(valueBase64: Base64, transactionId: ?TransactionId): Promise<Characteristic> {
+    return this._manager._writeCharacteristicWithoutResponse(this.id, valueBase64, transactionId)
+  }
+
+  /**
+   * {@link #blemanagermonitorcharacteristicfordevice|bleManager.monitorCharacteristicForDevice()} with partially filled arguments.
+   *
+   * @param {function(error: ?BleError, characteristic: ?Characteristic)} listener callback which emits
+   * this {@link Characteristic} with modified value for each notification.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Subscription} Subscription on which `remove()` function can be called to unsubscribe.
+   */
+  monitor(
+    listener: (error: ?BleError, characteristic: ?Characteristic) => void,
+    transactionId: ?TransactionId
+  ): Subscription {
+    return this._manager._monitorCharacteristic(this.id, listener, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerreaddescriptorfordevice|bleManager.readDescriptorForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} descriptorUUID {@link Descriptor} UUID.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|cancelTransaction()} function.
+   * @returns {Promise<Descriptor>} Promise which emits first {@link Descriptor} object matching specified
+   * UUID paths. Latest value of {@link Descriptor} will be stored inside returned object.
+   */
+  async readDescriptor(descriptorUUID: UUID, transactionId: ?TransactionId): Promise<Descriptor> {
+    return this._manager._readDescriptorForCharacteristic(this.id, descriptorUUID, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerwritedescriptorfordevice|bleManager.writeDescriptorForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} descriptorUUID Descriptor UUID
+   * @param {Base64} valueBase64 Value to be set coded in Base64
+   * @param {?TransactionId} transactionId Transaction handle used to cancel operation
+   * @returns {Promise<Descriptor>} Descriptor which saved passed value.
+   */
+  async writeDescriptor(descriptorUUID: UUID, valueBase64: Base64, transactionId: ?TransactionId): Promise<Descriptor> {
+    return this._manager._writeDescriptorForCharacteristic(this.id, descriptorUUID, valueBase64, transactionId)
+  }
+}

package/src/Descriptor.js

@@ -0,0 +1,82 @@
+// @flow
+'use strict'
+
+import type { BleManager } from './BleManager'
+import type { NativeDescriptor } from './BleModule'
+import type { DeviceId, Identifier, UUID, TransactionId, Base64 } from './TypeDefinition'
+
+/**
+ * Descriptor object.
+ */
+export class Descriptor implements NativeDescriptor {
+  /**
+   * Internal BLE Manager handle
+   * @private
+   */
+  _manager: BleManager
+  /**
+   * Descriptor unique identifier
+   */
+  id: Identifier
+  /**
+   * Descriptor UUID
+   */
+  uuid: UUID
+  /**
+   * Characteristic's ID to which descriptor belongs
+   */
+  characteristicID: Identifier
+  /**
+   * Characteristic's UUID to which descriptor belongs
+   */
+  characteristicUUID: UUID
+  /**
+   * Service's ID to which descriptor belongs
+   */
+  serviceID: Identifier
+  /**
+   * Service's UUID to which descriptor belongs
+   */
+  serviceUUID: UUID
+  /**
+   * Device's ID to which descriptor belongs
+   */
+  deviceID: DeviceId
+  /**
+   * Descriptor value if present
+   */
+  value: ?Base64
+
+  /**
+   * Private constructor used to create instance of {@link Descriptor}.
+   * @param {NativeDescriptor} nativeDescriptor NativeDescriptor
+   * @param {BleManager} manager BleManager
+   * @private
+   */
+  constructor(nativeDescriptor: NativeDescriptor, manager: BleManager) {
+    Object.assign(this, nativeDescriptor, { _manager: manager })
+  }
+
+  /**
+   * {@link #blemanagerreaddescriptorfordevice|bleManager.readDescriptorForDevice()} with partially filled arguments.
+   *
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|cancelTransaction()} function.
+   * @returns {Promise<Descriptor>} Promise which emits first {@link Descriptor} object matching specified
+   * UUID paths. Latest value of {@link Descriptor} will be stored inside returned object.
+   */
+  async read(transactionId: ?TransactionId): Promise<Descriptor> {
+    return this._manager._readDescriptor(this.id, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerwritedescriptorfordevice|bleManager.writeDescriptorForDevice()} with partially filled arguments.
+   *
+   * @param {Base64} valueBase64 Value to be set coded in Base64
+   * @param {?TransactionId} transactionId Transaction handle used to cancel operation
+   * @returns {Promise<Descriptor>} Descriptor which saved passed value.
+   */
+  async write(valueBase64: Base64, transactionId: ?TransactionId): Promise<Descriptor> {
+    return this._manager._writeDescriptor(this.id, valueBase64, transactionId)
+  }
+}

package/src/Device.js

@@ -0,0 +1,370 @@
+// @flow
+'use strict'
+
+import type { BleManager } from './BleManager'
+import type { BleError } from './BleError'
+import type { Characteristic } from './Characteristic'
+import type { Service } from './Service'
+import type { Descriptor } from './Descriptor'
+import { ConnectionPriority } from './TypeDefinition'
+import type { NativeDevice } from './BleModule'
+import type { DeviceId, Base64, UUID, Subscription, TransactionId, ConnectionOptions } from './TypeDefinition'
+
+/**
+ * Device instance which can be retrieved only by calling
+ * {@link #blemanagerstartdevicescan|bleManager.startDeviceScan()}.
+ */
+export class Device implements NativeDevice {
+  /**
+   * Internal BLE Manager handle
+   * @private
+   */
+  _manager: BleManager
+
+  /**
+   * Device identifier: MAC address on Android and UUID on iOS.
+   */
+  id: DeviceId
+
+  /**
+   * Device name if present
+   */
+  name: ?string
+
+  /**
+   * Current Received Signal Strength Indication of device
+   */
+  rssi: ?number
+
+  /**
+   * Current Maximum Transmission Unit for this device. When device is not connected
+   * default value of 23 is used.
+   */
+  mtu: number
+
+  // Advertisement
+
+  /**
+   * Device's custom manufacturer data. Its format is defined by manufacturer.
+   */
+  manufacturerData: ?Base64
+
+  /**
+   * Raw device scan data. When you have specific advertiser data,
+   * you can implement your own processing.
+   */
+  rawScanRecord: Base64
+
+  /**
+   * Map of service UUIDs (as keys) with associated data (as values).
+   */
+  serviceData: ?{ [uuid: UUID]: Base64 }
+
+  /**
+   * List of available services visible during scanning.
+   */
+  serviceUUIDs: ?Array<UUID>
+
+  /**
+   * User friendly name of device.
+   */
+  localName: ?string
+
+  /**
+   * Transmission power level of device.
+   */
+  txPowerLevel: ?number
+
+  /**
+   * List of solicited service UUIDs.
+   */
+  solicitedServiceUUIDs: ?Array<UUID>
+
+  /**
+   * Is device connectable. [iOS only]
+   */
+  isConnectable: ?boolean
+
+  /**
+   * List of overflow service UUIDs. [iOS only]
+   */
+  overflowServiceUUIDs: ?Array<UUID>
+
+  /**
+   * Private constructor used to create {@link Device} object.
+   *
+   * @param {NativeDevice} nativeDevice Native device properties
+   * @param {BleManager} manager {@link BleManager} handle
+   * @private
+   */
+  constructor(nativeDevice: NativeDevice, manager: BleManager) {
+    Object.assign(this, nativeDevice, { _manager: manager })
+  }
+
+  /**
+   * {@link #blemanagerrequestconnectionpriorityfordevice|bleManager.requestConnectionPriorityForDevice()} with partially filled arguments.
+   *
+   * @param {ConnectionPriority} connectionPriority: Connection priority.
+   * @param {?TransactionId} transactionId Transaction handle used to cancel operation.
+   * @returns {Promise<Device>} Connected device.
+   */
+  requestConnectionPriority(
+    connectionPriority: $Values<typeof ConnectionPriority>,
+    transactionId: ?TransactionId
+  ): Promise<Device> {
+    return this._manager.requestConnectionPriorityForDevice(this.id, connectionPriority, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerreadrssifordevice|bleManager.readRSSIForDevice()} with partially filled arguments.
+   *
+   * @param {?TransactionId} transactionId Transaction handle used to cancel operation.
+   * @returns {Promise<Device>} This device with updated RSSI value.
+   */
+  readRSSI(transactionId: ?TransactionId): Promise<Device> {
+    return this._manager.readRSSIForDevice(this.id, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerrequestmtufordevice|bleManager.requestMTUForDevice()} with partially filled arguments.
+   *
+   * @param {?TransactionId} transactionId Transaction handle used to cancel operation.
+   * @returns {Promise<Device>} Device with updated MTU size. Default value is 23.
+   */
+  requestMTU(mtu: number, transactionId: ?TransactionId): Promise<Device> {
+    return this._manager.requestMTUForDevice(this.id, mtu, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerconnecttodevice|bleManager.connectToDevice()} with partially filled arguments.
+   *
+   * @param {?ConnectionOptions} options Platform specific options for connection establishment. Not used currently.
+   * @returns {Promise<Device>} Connected {@link Device} object if successful.
+   */
+  connect(options: ?ConnectionOptions): Promise<Device> {
+    return this._manager.connectToDevice(this.id, options)
+  }
+
+  /**
+   * {@link #blemanagercanceldeviceconnection|bleManager.cancelDeviceConnection()} with partially filled arguments.
+   *
+   * @returns {Promise<Device>} Returns closed {@link Device} when operation is successful.
+   */
+  cancelConnection(): Promise<Device> {
+    return this._manager.cancelDeviceConnection(this.id)
+  }
+
+  /**
+   * {@link #blemanagerisdeviceconnected|bleManager.isDeviceConnected()} with partially filled arguments.
+   *
+   * @returns {Promise<boolean>} Promise which emits `true` if device is connected, and `false` otherwise.
+   */
+  isConnected(): Promise<boolean> {
+    return this._manager.isDeviceConnected(this.id)
+  }
+
+  /**
+   * {@link #blemanagerondevicedisconnected|bleManager.onDeviceDisconnected()} with partially filled arguments.
+   *
+   * @param {function(error: ?BleError, device: Device)} listener callback returning error as a reason of disconnection
+   * if available and {@link Device} object. If an error is null, that means the connection was terminated by
+   * {@link #blemanagercanceldeviceconnection|bleManager.cancelDeviceConnection()} call.
+   * @returns {Subscription} Subscription on which `remove()` function can be called to unsubscribe.
+   */
+  onDisconnected(listener: (error: ?BleError, device: Device) => void): Subscription {
+    return this._manager.onDeviceDisconnected(this.id, listener)
+  }
+
+  /**
+   * {@link #blemanagerdiscoverallservicesandcharacteristicsfordevice|bleManager.discoverAllServicesAndCharacteristicsForDevice()} with partially filled arguments.
+   *
+   * @param {?TransactionId} transactionId Transaction handle used to cancel operation
+   * @returns {Promise<Device>} Promise which emits {@link Device} object if all available services and
+   * characteristics have been discovered.
+   */
+  discoverAllServicesAndCharacteristics(transactionId: ?TransactionId): Promise<Device> {
+    return this._manager.discoverAllServicesAndCharacteristicsForDevice(this.id, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerservicesfordevice|bleManager.servicesForDevice()} with partially filled arguments.
+   *
+   * @returns {Promise<Service[]>} Promise which emits array of {@link Service} objects which are discovered by this
+   * device.
+   */
+  services(): Promise<Service[]> {
+    return this._manager.servicesForDevice(this.id)
+  }
+
+  /**
+   * {@link #blemanagercharacteristicsfordevice|bleManager.characteristicsForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @returns {Promise<Characteristic[]>} Promise which emits array of {@link Characteristic} objects which are
+   * discovered for a {@link Device} in specified {@link Service}.
+   */
+  characteristicsForService(serviceUUID: string): Promise<Characteristic[]> {
+    return this._manager.characteristicsForDevice(this.id, serviceUUID)
+  }
+
+  /**
+   * {@link #blemanagerdescriptorsfordevice|bleManager.descriptorsForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @param {UUID} characteristicUUID {@link Characteristic} UUID.
+   * @returns {Promise<Array<Descriptor>>} Promise which emits array of {@link Descriptor} objects which are
+   * discovered for this {@link Characteristic}.
+   */
+  descriptorsForService(serviceUUID: UUID, characteristicUUID: UUID): Promise<Array<Descriptor>> {
+    return this._manager.descriptorsForDevice(this.id, serviceUUID, characteristicUUID)
+  }
+
+  /**
+   * {@link #blemanagerreadcharacteristicfordevice|bleManager.readCharacteristicForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @param {UUID} characteristicUUID {@link Characteristic} UUID.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Promise<Characteristic>} Promise which emits first {@link Characteristic} object matching specified
+   * UUID paths. Latest value of {@link Characteristic} will be stored inside returned object.
+   */
+  readCharacteristicForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    transactionId: ?TransactionId
+  ): Promise<Characteristic> {
+    return this._manager.readCharacteristicForDevice(this.id, serviceUUID, characteristicUUID, transactionId)
+  }
+
+  /**
+   * {@link #blemanagerwritecharacteristicwithresponsefordevice|bleManager.writeCharacteristicWithResponseForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @param {UUID} characteristicUUID {@link Characteristic} UUID.
+   * @param {Base64} valueBase64 Value in Base64 format.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Promise<Characteristic>} Promise which emits first {@link Characteristic} object matching specified
+   * UUID paths. Latest value of characteristic may not be stored inside returned object.
+   */
+  writeCharacteristicWithResponseForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId: ?TransactionId
+  ): Promise<Characteristic> {
+    return this._manager.writeCharacteristicWithResponseForDevice(
+      this.id,
+      serviceUUID,
+      characteristicUUID,
+      valueBase64,
+      transactionId
+    )
+  }
+
+  /**
+   * {@link #blemanagerwritecharacteristicwithoutresponsefordevice|bleManager.writeCharacteristicWithoutResponseForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @param {UUID} characteristicUUID {@link Characteristic} UUID.
+   * @param {Base64} valueBase64 Value in Base64 format.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Promise<Characteristic>} Promise which emits first {@link Characteristic} object matching specified
+   * UUID paths. Latest value of characteristic may not be stored inside returned object.
+   */
+  writeCharacteristicWithoutResponseForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId: ?TransactionId
+  ): Promise<Characteristic> {
+    return this._manager.writeCharacteristicWithoutResponseForDevice(
+      this.id,
+      serviceUUID,
+      characteristicUUID,
+      valueBase64,
+      transactionId
+    )
+  }
+
+  /**
+   * {@link #blemanagermonitorcharacteristicfordevice|bleManager.monitorCharacteristicForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @param {UUID} characteristicUUID {@link Characteristic} UUID.
+   * @param {function(error: ?BleError, characteristic: ?Characteristic)} listener - callback which emits
+   * {@link Characteristic} objects with modified value for each notification.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|bleManager.cancelTransaction()} function.
+   * @returns {Subscription} Subscription on which `remove()` function can be called to unsubscribe.
+   */
+  monitorCharacteristicForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    listener: (error: ?BleError, characteristic: ?Characteristic) => void,
+    transactionId: ?TransactionId
+  ): Subscription {
+    return this._manager.monitorCharacteristicForDevice(
+      this.id,
+      serviceUUID,
+      characteristicUUID,
+      listener,
+      transactionId
+    )
+  }
+
+  /**
+   * {@link #blemanagerreaddescriptorfordevice|bleManager.readDescriptorForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @param {UUID} characteristicUUID {@link Characteristic} UUID.
+   * @param {UUID} descriptorUUID {@link Descriptor} UUID.
+   * @param {?TransactionId} transactionId optional `transactionId` which can be used in
+   * {@link #blemanagercanceltransaction|cancelTransaction()} function.
+   * @returns {Promise<Descriptor>} Promise which emits first {@link Descriptor} object matching specified
+   * UUID paths. Latest value of {@link Descriptor} will be stored inside returned object.
+   */
+  async readDescriptorForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    transactionId: ?TransactionId
+  ): Promise<Descriptor> {
+    return this._manager.readDescriptorForDevice(
+      this.id,
+      serviceUUID,
+      characteristicUUID,
+      descriptorUUID,
+      transactionId
+    )
+  }
+
+  /**
+   * {@link #blemanagerwritedescriptorfordevice|bleManager.writeDescriptorForDevice()} with partially filled arguments.
+   *
+   * @param {UUID} serviceUUID {@link Service} UUID.
+   * @param {UUID} characteristicUUID Characteristic UUID
+   * @param {UUID} descriptorUUID Descriptor UUID
+   * @param {Base64} valueBase64 Value to be set coded in Base64
+   * @param {?TransactionId} transactionId Transaction handle used to cancel operation
+   * @returns {Promise<Descriptor>} Descriptor which saved passed value.
+   */
+  async writeDescriptorForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    valueBase64: Base64,
+    transactionId: ?TransactionId
+  ): Promise<Descriptor> {
+    return this._manager.writeDescriptorForDevice(
+      this.id,
+      serviceUUID,
+      characteristicUUID,
+      descriptorUUID,
+      valueBase64,
+      transactionId
+    )
+  }
+}