# @ohos.bluetooth.ble (Bluetooth BLE Module) The **ble** module provides APIs for operating and managing Bluetooth. > **NOTE** > > The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import ```js import { ble } from '@kit.ConnectivityKit'; ``` ## ble.createGattServer createGattServer(): GattServer Creates a **GattServer** instance. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Return value** | Type | Description | | ----------------------------- | ---------- | | [GattServer](#gattserver) | **GattServer** instance created.| **Example** ```js let gattServer: ble.GattServer = ble.createGattServer(); console.info('gatt success'); ``` ## ble.createGattClientDevice createGattClientDevice(deviceId: string): GattClientDevice Creates a **GattClientDevice** instance. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ------ | ---- | ------------------------------------ | | deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| **Return value** | Type | Description | | ------------------------------------- | ------------------------------------ | | [GattClientDevice](#gattclientdevice) | **GattClientDevice** instance created. Before using an API of the client, you must create a **GattClientDevice** instance.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.getConnectedBLEDevices getConnectedBLEDevices(): Array<string> Obtains the Bluetooth Low Energy (BLE) devices connected to this device. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Return value** | Type | Description | | ------------------- | ------------------- | | Array<string> | Addresses of the BLE devices connected to this device. For security purposes, the device addresses obtained are random MAC addresses. The random MAC address remains unchanged after a device is paired successfully. It changes when the paired device is unpaired and scanned again or the Bluetooth service is turned off.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let result: Array = ble.getConnectedBLEDevices(); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.startBLEScan startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void Starts BLE scanning. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------- | -------------------------------------- | ---- | ----------------------------------- | | filters | Array<[ScanFilter](#scanfilter)> | Yes | Rules for filtering the scan result. Devices that meet the filtering rules will be retained. Set this parameter to **null** if you do not want to filter the scan result.| | options | [ScanOptions](#scanoptions) | No | Scan options. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function onReceiveEvent(data: Array) { console.info('BLE scan device find result = '+ JSON.stringify(data)); } try { ble.on("BLEDeviceFind", onReceiveEvent); let scanFilter: ble.ScanFilter = { deviceId:"XX:XX:XX:XX:XX:XX", name:"test", serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" }; let scanOptions: ble.ScanOptions = { interval: 500, dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE } ble.startBLEScan([scanFilter],scanOptions); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.stopBLEScan stopBLEScan(): void Stops BLE scanning. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { ble.stopBLEScan(); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.startAdvertising startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void Starts BLE advertising. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ----------- | ------------------------------------- | ---- | -------------- | | setting | [AdvertiseSetting](#advertisesetting) | Yes | Settings related to BLE advertising. | | advData | [AdvertiseData](#advertisedata) | Yes | Content of the BLE advertisement packet. | | advResponse | [AdvertiseData](#advertisedata) | No | Response to the BLE scan request.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; ble.startAdvertising(setting, advData ,advResponse); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.stopAdvertising stopAdvertising(): void Stops BLE advertising. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { ble.stopAdvertising(); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.startAdvertising11+ startAdvertising(advertisingParams: AdvertisingParams, callback: AsyncCallback<number>): void Starts BLE advertising. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------- | --------------------------------------- | ----- | ------------------------------- | | advertisingParams | [AdvertisingParams](#advertisingparams11) | Yes | Parameters for starting BLE advertising. | | callback | AsyncCallback<number> | Yes | Callback used to return the advertisement ID.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | -------------------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true, }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 0 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { if (err) { return; } else { advHandle = outAdvHandle; console.info("advHandle: " + advHandle); } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.startAdvertising11+ startAdvertising(advertisingParams: AdvertisingParams): Promise<number> Starts BLE advertising. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------- | -------------------------------------- | ----- | ----------------------- | | advertisingParams | [AdvertisingParams](#advertisingparams11) | Yes | Parameters for starting BLE advertising. | **Return value** | Type | Description | | -------------------------- | ------------------------------- | | Promise<number> | Promise used to return the BLE advertisement ID.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | -------------------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 0 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams) .then(outAdvHandle => { advHandle = outAdvHandle; }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.enableAdvertising11+ enableAdvertising(advertisingEnableParams: AdvertisingEnableParams, callback: AsyncCallback<void>): void Temporarily enables BLE advertising. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | | advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | Yes | Parameters for temporarily enabling BLE advertising. | | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | ------- | -------------------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 300 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { if (err) { return; } else { advHandle = outAdvHandle; console.info("advHandle: " + advHandle); } }); let advertisingEnableParams: ble.AdvertisingEnableParams = { advertisingId: advHandle, duration: 0 } // after 3s, advertising disabled, then enable the advertising ble.enableAdvertising(advertisingEnableParams, (err) => { if (err) { return; } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.enableAdvertising11+ enableAdvertising(advertisingEnableParams: AdvertisingEnableParams): Promise<void> Temporarily enables BLE advertising. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | | advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | Yes | Parameters for temporarily enabling BLE advertising. | **Return value** | Type | Description | | -------------------------- | ------------ | | Promise<void> | Promise used to return the result. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | ------- | -------------------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 300 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { if (err) { return; } else { advHandle = outAdvHandle; console.info("advHandle: " + advHandle); } }); let advertisingEnableParams: ble.AdvertisingEnableParams = { advertisingId: advHandle, duration: 0 } // after 3s, advertising disabled, then enable the advertising ble.enableAdvertising(advertisingEnableParams) .then(() => { console.info("enable success"); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.disableAdvertising11+ disableAdvertising(advertisingDisableParams: AdvertisingDisableParams, callback: AsyncCallback<void>): void Disables BLE advertising temporarily. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | | advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | Yes | Parameters for temporarily disabling BLE advertising. | | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | ------- | -------------------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 0 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { if (err) { return; } else { advHandle = outAdvHandle; console.info("advHandle: " + advHandle); } }); let advertisingDisableParams: ble.AdvertisingDisableParams = { advertisingId: advHandle } ble.disableAdvertising(advertisingDisableParams, (err) => { if (err) { return; } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.disableAdvertising11+ disableAdvertising(advertisingDisableParams: AdvertisingDisableParams): Promise<void> Disables BLE advertising temporarily. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | | advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | Yes | Parameters for temporarily disabling BLE advertising. | **Return value** | Type | Description | | -------------------------- | ------------ | | Promise<void> | Promise used to return the result. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | ------- | -------------------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 0 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { if (err) { return; } else { advHandle = outAdvHandle; console.info("advHandle: " + advHandle); } }); let advertisingDisableParams: ble.AdvertisingDisableParams = { advertisingId: advHandle } ble.disableAdvertising(advertisingDisableParams) .then(() => { console.info("enable success"); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.stopAdvertising11+ stopAdvertising(advertisingId: number, callback: AsyncCallback<void>): void Stops BLE advertising. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------------- | ---------------------------- | ----- | --------------------------- | | advertisingId | number | Yes | ID of the advertisement to stop. | | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 0 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { if (err) { return; } else { advHandle = outAdvHandle; console.info("advHandle: " + advHandle); } }); ble.stopAdvertising(advHandle, (err) => { if (err) { return; } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.stopAdvertising11+ stopAdvertising(advertisingId: number): Promise<void> Stops BLE advertising. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------------------------- | ---------------------------- | ----- | --------------------------- | | advertisingId | number | Yes | ID of the advertisement to stop. | **Return value** | Type | Description | | -------------------------- | ------------ | | Promise<void> | Promise used to return the result. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; manufactureValueBuffer[2] = 3; manufactureValueBuffer[3] = 4; let serviceValueBuffer = new Uint8Array(4); serviceValueBuffer[0] = 4; serviceValueBuffer[1] = 6; serviceValueBuffer[2] = 7; serviceValueBuffer[3] = 8; console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); try { let setting: ble.AdvertiseSetting = { interval:150, txPower:0, connectable:true }; let manufactureDataUnit: ble.ManufactureData = { manufactureId:4567, manufactureValue:manufactureValueBuffer.buffer }; let serviceDataUnit: ble.ServiceData = { serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", serviceValue:serviceValueBuffer.buffer }; let advData: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advResponse: ble.AdvertiseData = { serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], manufactureData:[manufactureDataUnit], serviceData:[serviceDataUnit] }; let advertisingParams: ble.AdvertisingParams = { advertisingSettings: setting, advertisingData: advData, advertisingResponse: advResponse, duration: 0 } let advHandle = 0xFF; ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { if (err) { return; } else { advHandle = outAdvHandle; console.info("advHandle: " + advHandle); } }); ble.stopAdvertising(advHandle) .then(() => { console.info("enable success"); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.on('advertisingStateChange')11+ on(type: 'advertisingStateChange', callback: Callback<AdvertisingStateChangeInfo>): void Subscribes to BLE advertising status. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | | type | string | Yes | Event type. The value is **advertisingStateChange**, which indicates the advertising status change. | | callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | Yes | Callback used to return the advertising status. You need to implement this callback.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { console.info('bluetooth advertising state = ' + JSON.stringify(data)); } try { ble.on('advertisingStateChange', onReceiveEvent); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.off('advertisingStateChange')11+ off(type: 'advertisingStateChange', callback?: Callback<AdvertisingStateChangeInfo>): void Unsubscribes from BLE advertising status. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | | type | string | Yes | Event type. The value is **advertisingStateChange**, which indicates the advertising status change. | | callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { console.info('bluetooth advertising state = ' + JSON.stringify(data)); } try { ble.on('advertisingStateChange', onReceiveEvent); ble.off('advertisingStateChange', onReceiveEvent); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.on('BLEDeviceFind') on(type: 'BLEDeviceFind', callback: Callback<Array<ScanResult>>): void Subscribes to BLE device discovery events. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ----------------------------------- | | type | string | Yes | Event type. The value is **BLEDeviceFind**, which indicates an event of discovering a BLE device. | | callback | Callback<Array<[ScanResult](#scanresult)>> | Yes | Callback used to return the discovered devices. You need to implement this callback.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function onReceiveEvent(data: Array) { console.info('bluetooth device find = '+ JSON.stringify(data)); } try { ble.on('BLEDeviceFind', onReceiveEvent); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## ble.off('BLEDeviceFind') off(type: 'BLEDeviceFind', callback?: Callback<Array<ScanResult>>): void Unsubscribes from BLE device discovery events. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLEDeviceFind**, which indicates an event of discovering a BLE device. | | callback | Callback<Array<[ScanResult](#scanresult)>> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function onReceiveEvent(data: Array) { console.info('bluetooth device find = '+ JSON.stringify(data)); } try { ble.on('BLEDeviceFind', onReceiveEvent); ble.off('BLEDeviceFind', onReceiveEvent); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## GattServer Implements the Generic Attribute Profile (GATT) server. Before using an API of this class, you need to create a **GattServer** instance using **createGattServer()**. ### addService addService(service: GattService): void Adds a service to this GATT server. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ------- | --------------------------- | ---- | ------------------------ | | service | [GattService](#gattservice) | Yes | Service to add. Settings related to BLE advertising.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // Create descriptors. let descriptors: Array = []; let arrayBuffer = new ArrayBuffer(8); let descV = new Uint8Array(arrayBuffer); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; descriptors[0] = descriptor; // Create characteristics. let characteristics: Array = []; let arrayBufferC = new ArrayBuffer(8); let cccV = new Uint8Array(arrayBufferC); cccV[0] = 1; let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; characteristics[0] = characteristic; // Create a gattService instance. let gattService: ble.GattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]}; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.addService(gattService); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### removeService removeService(serviceUuid: string): void Removes a service from this GATT server. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ----------- | ------ | ---- | ---------------------------------------- | | serviceUuid | string | Yes | Universally unique identifier (UUID) of the service to remove, for example, **00001810-0000-1000-8000-00805F9B34FB**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900004 | Profile not supported. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let server: ble.GattServer = ble.createGattServer(); try { // Before removeService is called, the server and the client must be paired and connected. server.removeService('00001810-0000-1000-8000-00805F9B34FB'); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### close close(): void Closes this GATT server to unregister it from the protocol stack. The closed [GattServer](#gattserver) instance will no longer be used. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let server: ble.GattServer = ble.createGattServer(); try { server.close(); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### notifyCharacteristicChanged notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<void>): void Notifies a connected client device when a characteristic value changes. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------------- | ---------------------------------------- | ---- | --------------------------------------- | | deviceId | string | Yes | Address of the client that receives the notifications, for example, XX:XX:XX:XX:XX:XX.| | notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | Yes | New characteristic value. | | callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let arrayBufferC = new ArrayBuffer(8); let notifyCharacter: ble.NotifyCharacteristic = { serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, confirm: true }; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter, (err: BusinessError) => { if (err) { console.info('notifyCharacteristicChanged callback failed'); } else { console.info('notifyCharacteristicChanged callback successful'); } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### notifyCharacteristicChanged notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): Promise<void> Notifies a connected client device when a characteristic value changes. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------------- | ---------------------------------------- | ---- | --------------------------------------- | | deviceId | string | Yes | Address of the client that receives the notifications, for example, XX:XX:XX:XX:XX:XX.| | notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | Yes | New characteristic value. | **Return value** | Type | Description | | ------------------- | ------------- | | Promise<void> | Promise used to return the result.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let arrayBufferC = new ArrayBuffer(8); let notifyCharacter: ble.NotifyCharacteristic = { serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, confirm: true }; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter).then(() => { console.info('notifyCharacteristicChanged promise successful'); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### sendResponse sendResponse(serverResponse: ServerResponse): void Sends a response to a read or write request from the GATT client. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------- | ---- | --------------- | | serverResponse | [ServerResponse](#serverresponse) | Yes | Response returned by the GATT server.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; /* send response */ let arrayBufferCCC = new ArrayBuffer(8); let cccValue = new Uint8Array(arrayBufferCCC); cccValue[0] = 1123; let serverResponse: ble.ServerResponse = { deviceId: 'XX:XX:XX:XX:XX:XX', transId: 0, status: 0, offset: 0, value: arrayBufferCCC }; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.sendResponse(serverResponse); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### on('characteristicRead') on(type: 'characteristicRead', callback: Callback<CharacteristicReadRequest>): void Subscribes to characteristic read request events. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------------- | | type | string | Yes | Event type. The value is **characteristicRead**, which indicates a characteristic read request event.| | callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | Yes | Callback used to return a characteristic read request event from the GATT client. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let arrayBufferCCC = new ArrayBuffer(8); let cccValue = new Uint8Array(arrayBufferCCC); cccValue[0] = 1123; let gattServer: ble.GattServer = ble.createGattServer(); function ReadCharacteristicReq(characteristicReadRequest: ble.CharacteristicReadRequest) { let deviceId: string = characteristicReadRequest.deviceId; let transId: number = characteristicReadRequest.transId; let offset: number = characteristicReadRequest.offset; let characteristicUuid: string = characteristicReadRequest.characteristicUuid; let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; try { gattServer.sendResponse(serverResponse); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } } gattServer.on('characteristicRead', ReadCharacteristicReq); ``` ### off('characteristicRead') off(type: 'characteristicRead', callback?: Callback<CharacteristicReadRequest>): void Unsubscribes from characteristic read request events. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **characteristicRead**, which indicates a characteristic read request event. | | callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.off('characteristicRead'); } catch (err) { console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); } ``` ### on('characteristicWrite') on(type: 'characteristicWrite', callback: Callback<CharacteristicWriteRequest>): void Subscribes to characteristic write request events. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | -------------------------------------- | | type | string | Yes | Event type. The value is **characteristicWrite**, which indicates a characteristic write request event.| | callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | Yes | Callback used to return a characteristic write request from the GATT client. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let arrayBufferCCC = new ArrayBuffer(8); let cccValue = new Uint8Array(arrayBufferCCC); let gattServer: ble.GattServer = ble.createGattServer(); function WriteCharacteristicReq(characteristicWriteRequest: ble.CharacteristicWriteRequest) { let deviceId: string = characteristicWriteRequest.deviceId; let transId: number = characteristicWriteRequest.transId; let offset: number = characteristicWriteRequest.offset; let isPrepared: boolean = characteristicWriteRequest.isPrepared; let needRsp: boolean = characteristicWriteRequest.needRsp; let value: Uint8Array = new Uint8Array(characteristicWriteRequest.value); let characteristicUuid: string = characteristicWriteRequest.characteristicUuid; cccValue[0] = value[0]; let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; try { gattServer.sendResponse(serverResponse); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } } gattServer.on('characteristicWrite', WriteCharacteristicReq); ``` ### off('characteristicWrite') off(type: 'characteristicWrite', callback?: Callback<CharacteristicWriteRequest>): void Unsubscribes from characteristic write request events. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **characteristicWrite**, which indicates a characteristic write request event. | | callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.off('characteristicWrite'); } catch (err) { console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); } ``` ### on('descriptorRead') on(type: 'descriptorRead', callback: Callback<DescriptorReadRequest>): void Subscribes to descriptor read request events. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | --------------------------------- | | type | string | Yes | Event type. The value is **descriptorRead**, which indicates a descriptor read request event.| | callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | Yes | Callback used to return a characteristic read request event from the GATT client. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let arrayBufferDesc = new ArrayBuffer(8); let descValue = new Uint8Array(arrayBufferDesc); descValue[0] = 1101; let gattServer: ble.GattServer = ble.createGattServer(); function ReadDescriptorReq(descriptorReadRequest: ble.DescriptorReadRequest) { let deviceId: string = descriptorReadRequest.deviceId; let transId: number = descriptorReadRequest.transId; let offset: number = descriptorReadRequest.offset; let descriptorUuid: string = descriptorReadRequest.descriptorUuid; let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; try { gattServer.sendResponse(serverResponse); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } } gattServer.on('descriptorRead', ReadDescriptorReq); ``` ### off('descriptorRead') off(type: 'descriptorRead', callback?: Callback<DescriptorReadRequest>): void Unsubscribes from descriptor read request events. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **descriptorRead**, which indicates a descriptor read request event. | | callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.off('descriptorRead'); } catch (err) { console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); } ``` ### on('descriptorWrite') on(type: 'descriptorWrite', callback: Callback<DescriptorWriteRequest>): void Subscribes to descriptor write request events. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------- | | type | string | Yes | Event type. The value is **descriptorWrite**, which indicates a descriptor write request event.| | callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | Yes | Callback used to return a characteristic write request from the GATT client. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let arrayBufferDesc = new ArrayBuffer(8); let descValue = new Uint8Array(arrayBufferDesc); let gattServer: ble.GattServer = ble.createGattServer(); function WriteDescriptorReq(descriptorWriteRequest: ble.DescriptorWriteRequest) { let deviceId: string = descriptorWriteRequest.deviceId; let transId: number = descriptorWriteRequest.transId; let offset: number = descriptorWriteRequest.offset; let isPrepared: boolean = descriptorWriteRequest.isPrepared; let needRsp: boolean = descriptorWriteRequest.needRsp; let value: Uint8Array = new Uint8Array(descriptorWriteRequest.value); let descriptorUuid: string = descriptorWriteRequest.descriptorUuid; descValue[0] = value[0]; let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; try { gattServer.sendResponse(serverResponse); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } } gattServer.on('descriptorWrite', WriteDescriptorReq); ``` ### off('descriptorWrite') off(type: 'descriptorWrite', callback?: Callback<DescriptorWriteRequest>): void Unsubscribes from descriptor write request events. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **descriptorWrite**, which indicates a descriptor write request event. | | callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.off('descriptorWrite'); } catch (err) { console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); } ``` ### on('connectionStateChange') on(type: 'connectionStateChange', callback: Callback<BLEConnectionChangeState>): void Subscribes to BLE connection state changes. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **connectionStateChange**, which indicates BLE connection state changes.| | callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | Yes | Callback used to return the BLE connection state. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; import { constant } from '@kit.ConnectivityKit'; let Connected = (bleConnectionChangeState: ble.BLEConnectionChangeState) => { let deviceId: string = bleConnectionChangeState.deviceId; let status: constant.ProfileConnectionState = bleConnectionChangeState.state; } try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.on('connectionStateChange', Connected); } catch (err) { console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); } ``` ### off('connectionStateChange') off(type: 'connectionStateChange', callback?: Callback<BLEConnectionChangeState>): void Unsubscribes from BLE connection state changes. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **connectionStateChange**, which indicates BLE connection state changes.| | callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.off('connectionStateChange'); } catch (err) { console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); } ``` ### on('BLEMtuChange') on(type: 'BLEMtuChange', callback: Callback<number>): void Subscribes to MTU status changes for the server. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLEMtuChange**, which indicates MTU status changes. If this parameter is not set correctly, the callback cannot be registered.| | callback | Callback<number> | Yes | Callback used to return the number of MTU bytes.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.on('BLEMtuChange', (mtu: number) => { console.info('BLEMtuChange, mtu: ' + mtu); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### off('BLEMtuChange') off(type: 'BLEMtuChange', callback?: Callback<number>): void Unsubscribes from MTU status changes for the server. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLEMtuChange**, which indicates MTU status changes. If this parameter is not set correctly, the callback cannot be registered.| | callback | Callback<number> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattServer: ble.GattServer = ble.createGattServer(); gattServer.off('BLEMtuChange'); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## GattClientDevice Implements the GATT client. Before using an API of this class, you must create a **GattClientDevice** instance using **createGattClientDevice(deviceId: string)**. ### connect connect(): void Connects to the remote BLE device. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.connect(); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### disconnect disconnect(): void Disconnects from the remote BLE device. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.disconnect(); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### close close(): void Closes this GATT client to unregister it from the protocol stack. The closed [GattClientDevice](#gattclientdevice) instance will no longer be used. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900003 | Bluetooth disabled. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.close(); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### getDeviceName getDeviceName(callback: AsyncCallback<string>): void Obtains the name of the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | --------------------------- | ---- | ------------------------------- | | callback | AsyncCallback<string> | Yes | Callback used to return the remote BLE device name obtained.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // callback try { let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); gattClient.connect(); gattClient.getDeviceName((err: BusinessError, data: string)=> { console.info('device name err ' + JSON.stringify(err)); console.info('device name' + JSON.stringify(data)); }) } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### getDeviceName getDeviceName(): Promise<string> Obtains the name of the remote BLE device. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Return value** | Type | Description | | --------------------- | ---------------------------------- | | Promise<string> | Promise used to return the remote BLE device name.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // promise try { let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); gattClient.connect(); gattClient.getDeviceName().then((data: string) => { console.info('device name' + JSON.stringify(data)); }) } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### getServices getServices(callback: AsyncCallback<Array<GattService>>): void Obtains all services of the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------ | | callback | AsyncCallback<Array<[GattService](#gattservice)>> | Yes | Callback used to return the services obtained.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // Callback mode. let getServices = (code: BusinessError, gattServices: Array) => { if (code && code.code != 0) { console.info('bluetooth code is ' + code.code); return; } let services: Array = gattServices; console.info('bluetooth services size is ', services.length); for (let i = 0; i < services.length; i++) { console.info('bluetooth serviceUuid is ' + services[i].serviceUuid); } } try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.connect(); device.getServices(getServices); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### getServices getServices(): Promise<Array<GattService>> Obtains all services of the remote BLE device. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Return value** | Type | Description | | ---------------------------------------- | --------------------------- | | Promise<Array<[GattService](#gattservice)>> | Promise used to return the services obtained.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // Promise try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.connect(); device.getServices().then((result: Array) => { console.info('getServices successfully:' + JSON.stringify(result)); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### readCharacteristicValue readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void Reads the characteristic value of the specific service of the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | ---------------------------------------- | ---- | ----------------------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Characteristic value to read. | | callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | Yes | Callback used to return the characteristic value read.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901000 | Read forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function readCcc(code: BusinessError, BLECharacteristic: ble.BLECharacteristic) { if (code.code != 0) { return; } console.info('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid); let value = new Uint8Array(BLECharacteristic.characteristicValue); console.info('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); } let descriptors: Array = []; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; descriptors[0] = descriptor; let bufferCCC = new ArrayBuffer(8); let cccV = new Uint8Array(bufferCCC); cccV[0] = 1; let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: bufferCCC, descriptors:descriptors}; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.readCharacteristicValue(characteristic, readCcc); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### readCharacteristicValue readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> Reads the characteristic value of the specific service of the remote BLE device. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------------- | ---- | -------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Characteristic value to read.| **Return value** | Type | Description | | ---------------------------------------- | -------------------------- | | Promise<[BLECharacteristic](#blecharacteristic)> | Promise used to return the characteristic value read.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901000 | Read forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let descriptors: Array = []; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; descriptors[0] = descriptor; let bufferCCC = new ArrayBuffer(8); let cccV = new Uint8Array(bufferCCC); cccV[0] = 1; let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: bufferCCC, descriptors:descriptors}; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.readCharacteristicValue(characteristic); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### readDescriptorValue readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void Reads the descriptor contained in the specific characteristic of the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ---------- | ---------------------------------------- | ---- | ----------------------- | | descriptor | [BLEDescriptor](#bledescriptor) | Yes | Descriptor to read. | | callback | AsyncCallback<[BLEDescriptor](#bledescriptor)> | Yes | Callback used to return the descriptor read.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901000 | Read forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function readDesc(code: BusinessError, BLEDescriptor: ble.BLEDescriptor) { if (code.code != 0) { return; } console.info('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid); let value = new Uint8Array(BLEDescriptor.descriptorValue); console.info('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); } let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; let descriptor: ble.BLEDescriptor = { serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc }; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.readDescriptorValue(descriptor, readDesc); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### readDescriptorValue readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> Reads the descriptor contained in the specific characteristic of the remote BLE device. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ---------- | ------------------------------- | ---- | -------- | | descriptor | [BLEDescriptor](#bledescriptor) | Yes | Descriptor to read.| **Return value** | Type | Description | | ---------------------------------------- | -------------------------- | | Promise<[BLEDescriptor](#bledescriptor)> | Promise used to return the descriptor read.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901000 | Read forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; let descriptor: ble.BLEDescriptor = { serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc }; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.readDescriptorValue(descriptor); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### writeCharacteristicValue writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void>): void Writes a characteristic value to the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------------- | ---- | ------------------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Binary value and other parameters of the BLE device characteristic.| | writeType | [GattWriteType](#gattwritetype) | Yes | Write type of the Bluetooth device characteristic value.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. If the write operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901001 | Write forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let descriptors: Array = []; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; descriptors[0] = descriptor; let bufferCCC = new ArrayBuffer(8); let cccV = new Uint8Array(bufferCCC); cccV[0] = 1; let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: bufferCCC, descriptors:descriptors}; function writeCharacteristicValueCallBack(code: BusinessError) { if (code != null) { return; } console.info('bluetooth writeCharacteristicValue success'); } try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE, writeCharacteristicValueCallBack); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### writeCharacteristicValue writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void> Writes a characteristic value to the remote BLE device. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------------- | ---- | ------------------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Binary value and other parameters of the BLE device characteristic.| | writeType | [GattWriteType](#gattwritetype) | Yes | Write type of the Bluetooth device characteristic value.| **Return value** | Type | Description | | ---------------------------------------- | -------------------------- | | Promise<void> | Promise used to return the descriptor read.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901001 | Write forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let descriptors: Array = []; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; descriptors[0] = descriptor; let bufferCCC = new ArrayBuffer(8); let cccV = new Uint8Array(bufferCCC); cccV[0] = 1; let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: bufferCCC, descriptors:descriptors}; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### writeDescriptorValue writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void Writes binary data to the specific descriptor of the remote BLE device. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ---------- | ------------------------------- | ---- | ------------------ | | descriptor | [BLEDescriptor](#bledescriptor) | Yes | Binary value and other parameters of the BLE device descriptor.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. If the write operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901001 | Write forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 22; let descriptor: ble.BLEDescriptor = { serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc }; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.writeDescriptorValue(descriptor, (err: BusinessError) => { if (err) { console.info('notifyCharacteristicChanged callback failed'); } else { console.info('notifyCharacteristicChanged callback successful'); } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### writeDescriptorValue writeDescriptorValue(descriptor: BLEDescriptor): Promise<void> Writes binary data to the specific descriptor of the remote BLE device. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ---------- | ------------------------------- | ---- | ------------------ | | descriptor | [BLEDescriptor](#bledescriptor) | Yes | Binary value and other parameters of the BLE device descriptor.| **Return value** | Type | Description | | ---------------------------------------- | -------------------------- | | Promise<void> | Promise used to return the descriptor read.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2901001 | Write forbidden. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 22; let descriptor: ble.BLEDescriptor = { serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc }; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.writeDescriptorValue(descriptor).then(() => { console.info('writeDescriptorValue promise success'); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### getRssiValue getRssiValue(callback: AsyncCallback<number>): void Obtains the RSSI of the remote BLE device. It can be used only after a connection is set up by calling [connect](#connect). This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | --------------------------- | ---- | ------------------------------ | | callback | AsyncCallback<number> | Yes | Callback used to return the RSSI, in dBm.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // callback try { let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); gattClient.connect(); let rssi = gattClient.getRssiValue((err: BusinessError, data: number)=> { console.info('rssi err ' + JSON.stringify(err)); console.info('rssi value' + JSON.stringify(data)); }) } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### getRssiValue getRssiValue(): Promise<number> Obtains the RSSI of the remote BLE device. It can be used only after a connection is set up by calling [connect](#connect). This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Return value** | Type | Description | | --------------------- | --------------------------------- | | Promise<number> | Promise used to return the RSSI, in dBm.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | |801 | Capability not supported. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // promise try { let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); gattClient.getRssiValue().then((data: number) => { console.info('rssi' + JSON.stringify(data)); }) } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### setBLEMtuSize setBLEMtuSize(mtu: number): void Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its remote BLE device. This API can be used only after a connection is set up by calling [connect](#connect). **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | ---- | ------ | ---- | -------------- | | mtu | number | Yes | MTU to set, which ranges from 22 to 512 bytes.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.setBLEMtuSize(128); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### setCharacteristicChangeNotification setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void Sets a notification for the change of a characteristic. The GATT client that subscribes to the change will be notified when the characteristic changes. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------------- | ---- | ----------------------------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | | enable | boolean | Yes | Whether to notify the client of the characteristic change. The value **true** means to notify the client, and the value **false** means the opposite.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // Create descriptors. let descriptors: Array = []; let arrayBuffer = new ArrayBuffer(8); let descV = new Uint8Array(arrayBuffer); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; descriptors[0] = descriptor; let arrayBufferC = new ArrayBuffer(8); let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.setCharacteristicChangeNotification(characteristic, false, (err: BusinessError) => { if (err) { console.info('notifyCharacteristicChanged callback failed'); } else { console.info('notifyCharacteristicChanged callback successful'); } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### setCharacteristicChangeNotification setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void> Sets a notification for the change of a characteristic. The GATT client that subscribes to the change will be notified when the characteristic changes. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------------- | ---- | ----------------------------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | | enable | boolean | Yes | Whether to notify the client of the characteristic change. The value **true** means to notify the client, and the value **false** means the opposite.| **Return value** | Type | Description | | ---------------------------------------- | -------------------------- | | Promise<void> | Promise used to return the result.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // Create descriptors. let descriptors: Array = []; let arrayBuffer = new ArrayBuffer(8); let descV = new Uint8Array(arrayBuffer); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; descriptors[0] = descriptor; let arrayBufferC = new ArrayBuffer(8); let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.setCharacteristicChangeNotification(characteristic, false); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### setCharacteristicChangeIndication setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void Sets an indication for the change of a characteristic. The GATT client must acknowledge the indication received. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------------- | ---- | ----------------------------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | | enable | boolean | Yes | Whether to indicate the client of the characteristic change. The value **true** means to indicate the client, and the value **false** means the opposite. | | callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // Create descriptors. let descriptors: Array = []; let arrayBuffer = new ArrayBuffer(8); let descV = new Uint8Array(arrayBuffer); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; descriptors[0] = descriptor; let arrayBufferC = new ArrayBuffer(8); let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.setCharacteristicChangeIndication(characteristic, false, (err: BusinessError) => { if (err) { console.info('notifyCharacteristicChanged callback failed'); } else { console.info('notifyCharacteristicChanged callback successful'); } }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### setCharacteristicChangeIndication setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void> Sets an indication for the change of a characteristic. The GATT client must acknowledge the indication received. This API uses a promise to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------------- | --------------------------------------- | ---- | ----------------------------- | | characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | | enable | boolean | Yes | Whether to indicate the client of the characteristic change. The value **true** means to indicate the client, and the value **false** means the opposite. | **Return value** | Type | Description | | ---------------------------------------- | -------------------------- | | Promise<void> | Promise used to return the result.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | |2900001 | Service stopped. | |2900099 | Operation failed. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; // Create descriptors. let descriptors: Array = []; let arrayBuffer = new ArrayBuffer(8); let descV = new Uint8Array(arrayBuffer); descV[0] = 11; let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; descriptors[0] = descriptor; let arrayBufferC = new ArrayBuffer(8); let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.setCharacteristicChangeIndication(characteristic, false); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### on('BLECharacteristicChange') on(type: 'BLECharacteristicChange', callback: Callback<BLECharacteristic>): void Subscribes to BLE characteristic changes. Before calling this API, use [setCharacteristicChangeNotification](#setcharacteristicchangenotification) or [setCharacteristicChangeIndication](#setcharacteristicchangeindication) to enable the client to receive notifications or indications from the server. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLECharacteristicChange**, which indicates characteristic value changes.| | callback | Callback<[BLECharacteristic](#blecharacteristic)> | Yes | Callback used to return the characteristic value changes. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function CharacteristicChange(characteristicChangeReq: ble.BLECharacteristic) { let serviceUuid: string = characteristicChangeReq.serviceUuid; let characteristicUuid: string = characteristicChangeReq.characteristicUuid; let value: Uint8Array = new Uint8Array(characteristicChangeReq.characteristicValue); } try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.on('BLECharacteristicChange', CharacteristicChange); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### off('BLECharacteristicChange') off(type: 'BLECharacteristicChange', callback?: Callback<BLECharacteristic>): void Unsubscribes from BLE characteristic changes. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLECharacteristicChange**, which indicates characteristic value changes.| | callback | Callback<[BLECharacteristic](#blecharacteristic)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.off('BLECharacteristicChange'); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### on('BLEConnectionStateChange') on(type: 'BLEConnectionStateChange', callback: Callback<BLEConnectionChangeState>): void Subscribes to BLE connection state changes. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLEConnectionStateChange**, which indicates BLE connection state changes.| | callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | Yes | Callback used to return the BLE connection state. | **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; function ConnectStateChanged(state: ble.BLEConnectionChangeState) { console.info('bluetooth connect state changed'); let connectState: ble.ProfileConnectionState = state.state; } try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.on('BLEConnectionStateChange', ConnectStateChanged); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### off('BLEConnectionStateChange') off(type: 'BLEConnectionStateChange', callback?: Callback<BLEConnectionChangeState>): void Unsubscribes from BLE connection state changes. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLEConnectionStateChange**, which indicates BLE connection state changes.| | callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.off('BLEConnectionStateChange'); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### on('BLEMtuChange') on(type: 'BLEMtuChange', callback: Callback<number>): void Subscribes to MTU status changes for the client. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLEMtuChange**, which indicates the MTU status changes. If this parameter is not set correctly, the callback cannot be registered.| | callback | Callback<number> | Yes | Callback used to return the number of MTU bytes.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let gattClient: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); gattClient.on('BLEMtuChange', (mtu: number) => { console.info('BLEMtuChange, mtu: ' + mtu); }); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ### off('BLEMtuChange') off(type: 'BLEMtuChange', callback?: Callback<number>): void Unsubscribes from MTU status changes for the client. **Required permissions**: ohos.permission.ACCESS_BLUETOOTH **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core **Parameters** | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | Yes | Event type. The value is **BLEMtuChange**, which indicates the MTU status changes. If this parameter is not set correctly, the callback cannot be registered.| | callback | Callback<number> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| **Error codes** For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). | ID| Error Message| | -------- | ---------------------------- | |201 | Permission denied. | |401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | |801 | Capability not supported. | **Example** ```js import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; try { let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.off('BLEMtuChange'); } catch (err) { console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); } ``` ## GattService Defines the GATT service API parameters. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | --------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | | serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| | isPrimary | boolean | Yes | Yes | Whether the service is a primary service. The value **true** means a primary service. | | characteristics | Array<[BLECharacteristic](#blecharacteristic)> | Yes | Yes | List of characteristics of the service. | | includeServices | Array<[GattService](#gattservice)> | Yes | Yes | Services on which the service depends. | ## BLECharacteristic Defines the characteristic API parameters. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | | serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| | characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| | characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. | | descriptors | Array<[BLEDescriptor](#bledescriptor)> | Yes | Yes | List of descriptors of the characteristic. | | properties | [GattProperties](#gattproperties) | Yes | Yes | Properties of the characteristic. | ## BLEDescriptor Represents a BLE descriptor. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------ | ----------- | ---- | ---- | ---------------------------------------- | | serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| | characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| | descriptorUuid | string | Yes | Yes | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| | descriptorValue | ArrayBuffer | Yes | Yes | Binary value of the descriptor. | ## NotifyCharacteristic Defines the parameters in the notifications sent when the server characteristic value changes. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------- | ----------- | ---- | ---- | ---------------------------------------- | | serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| | characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| | characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. | | confirm | boolean | Yes | Yes | Whether the indication or notification needs to be acknowledged by the remote end. Set this parameter to **true** for an indication, which needs to be acknowledged by the remote end. Set this parameter to **false** for a notification, which does not need to be acknowledged by the remote end. | ## CharacteristicReadRequest Defines the parameters of the **CharacteristicReadReq** event received by the server. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------ | ------ | ---- | ---- | ---------------------------------------- | | deviceId | string | Yes | No | Address of the remote device that sends the **CharacteristicReadReq** event, for example, XX:XX:XX:XX:XX:XX.| | transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. | | offset | number | Yes | No | Position from which the characteristic value is read. For example, **k** means to read from the kth byte. The response returned by the server must use the same offset.| | characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| | serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## CharacteristicWriteRequest Defines the parameters of the **CharacteristicWriteReq** event received by the server. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------ | ------ | ---- | ---- | ---------------------------------------- | | deviceId | string | Yes | No | Address of the remote device that sends the **CharacteristicWriteReq** event, for example, XX:XX:XX:XX:XX:XX.| | transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. | | offset | number | Yes | No | Start position for writing the characteristic value. For example, **k** means to write from the kth byte. The response returned by the server must use the same offset.| | isPrepared | boolean | Yes | No | Whether the write request is executed immediately. The value **true** means to execute the write request immediately.| | needRsp | boolean | Yes | No | Whether to send a response to the GATT client. The value **true** means to send a response.| | value | ArrayBuffer | Yes | No | Binary value of the descriptor to write.| | characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| | serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## DescriptorReadRequest Defines the parameters of the **DescriptorReadReq** event received by the server. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------ | ------ | ---- | ---- | ---------------------------------------- | | deviceId | string | Yes | No | Address of the remote device that sends a **DescriptorReadReq** event, for example, XX:XX:XX:XX:XX:XX.| | transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. | | offset | number | Yes | No | Position from which the descriptor is read. For example, **k** means to read from the kth byte. The response returned by the server must use the same offset.| | descriptorUuid | string | Yes | No | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| | characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| | serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## DescriptorWriteRequest Defines the parameters of the **DescriptorWriteReq** event received by the server. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------ | ----------- | ---- | ---- | ---------------------------------------- | | deviceId | string | Yes | No | Address of the remote device that sends a **DescriptorWriteReq** event, for example, XX:XX:XX:XX:XX:XX.| | transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. | | offset | number | Yes | No | Start position for writing the descriptor. For example, **k** means to write from the kth byte. The response returned by the server must use the same offset.| | isPrepared | boolean | Yes | No | Whether the write request is executed immediately. | | needRsp | boolean | Yes | No | Whether to send a response to the GATT client. | | value | ArrayBuffer | Yes | No | Binary value of the descriptor to write. | | descriptorUuid | string | Yes | No | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| | characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| | serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## ServerResponse Defines the parameters of the server's response to the GATT client's read/write request. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | -------- | ----------- | ---- | ---- | -------------------------------------- | | deviceId | string | Yes | No | Address of the remote device, for example, XX:XX:XX:XX:XX:XX. | | transId | number | Yes | No | Transmission ID of the request. The value must be the same as the ID carried in the read/write request received. | | status | number | Yes | No | Response state. Set this parameter to **0**, which indicates a normal response. | | offset | number | Yes | No | Start read/write position. The value must be the same as the offset carried in the read/write request.| | value | ArrayBuffer | Yes | No | Binary data in the response. | ## BLEConnectionChangeState Represents the GATT profile connection state. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable| Writable| Description | | -------- | ------------------------------------------------- | ---- | ---- | --------------------------------------------- | | deviceId | string | Yes | No | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| | state | [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | Yes | Yes | BLE connection state. | ## ScanResult Defines the scan result. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | -------- | ----------- | ---- | ---- | ---------------------------------- | | deviceId | string | Yes | No | Address of the scanned device, for example, XX:XX:XX:XX:XX:XX. For security purposes, the device address is a random MAC address. The random MAC address remains unchanged after a device is paired successfully. It changes when the paired device is unpaired and scanned again or the Bluetooth service is turned off.| | rssi | number | Yes | No | RSSI of the device. | | data | ArrayBuffer | Yes | No | Advertisement packets sent by the device. | | deviceName | string | Yes | No | Name of the device detected. | | connectable | boolean | Yes | No | Whether the discovered device is connectable. The value **true** means the discovered device is connectable; the value **false** means the opposite. | ## AdvertiseSetting Defines the BLE advertising parameters. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ----------- | ------- | ---- | ---- | ---------------------------------------- | | interval | number | Yes | Yes | Interval for BLE advertising. The minimum value is **160** slots (100 ms). The maximum value is **16384** slots. The default value is **1600** slots (1s).| | txPower | number | Yes | Yes | Transmit power, in dBm. The value range is -127 to 1. The default value is **-7**. Recommended value: **1** for high transmit power, **-7** for medium transmit power, and **-15** for low transmit power. | | connectable | boolean | Yes | Yes | Whether the advertisement is connectable. The value **true** (default) means the advertisement is connectable; the value **false** means the opposite. | ## AdvertiseData Represents the content of a BLE advertising packet, which is 31 bytes in size. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | --------------- | ---------------------------------------- | ---- | ---- | --------------------------- | | serviceUuids | Array<string> | Yes | Yes | List of service UUIDs to broadcast.| | manufactureData | Array<[ManufactureData](#manufacturedata)> | Yes | Yes | List of manufacturers to broadcast. | | serviceData | Array<[ServiceData](#servicedata)> | Yes | Yes | List of service data to broadcast. | | includeDeviceName | boolean | Yes | Yes | Whether the device name is contained. This parameter is optional. To carry the device name, set this parameter to **true**. Otherwise, set this parameter to **false** or leave it unspecified. Note that the advertising packet containing the device name cannot exceed 31 bytes. | ## AdvertisingParams11+ Defines the parameters for starting BLE advertising for the first time. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------- | ------------------------------- | ----- | ----- | ------------------------ | | advertisingSettings11+ | [AdvertiseSetting](#advertisesetting) | Yes | Yes | Parameters related advertising settings. | | advertisingData11+ | [AdvertiseData](#advertisedata) | Yes | Yes | Content of the advertising packet. | | advertisingResponse11+ | [AdvertiseData](#advertisedata) | Yes | Yes | Content of the response to the scan request.| | duration11+ | number | Yes | Yes | Duration for the advertising, in 10 ms.
Value range: **1** (10 ms) to **65535** (655350 ms)
If this parameter is not specified or set to 0, advertising packet are sent continuously. | ## AdvertisingEnableParams11+ Defines the parameters for temporarily enabling BLE advertising. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------- | --------------------- | ----- | ----- | ------------------------ | | advertisingId11+ | number | Yes | Yes | ID of the advertisement. | | duration11+ | number | Yes | Yes | Duration for the advertising, in 10 ms.
Value range: **1** (10 ms) to **65535** (655350 ms)
If this parameter is not specified or set to 0, advertising packet are sent continuously. | ## AdvertisingDisableParams11+ Defines the parameters for temporarily disabling BLE advertising. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------- | --------------------- | ----- | ----- | ------------------------ | | advertisingId11+ | number | Yes | Yes | ID of the advertisement. | ## AdvertisingStateChangeInfo11+ Represents the advertising status information. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------------- | --------------------------------------- | ----- | ----- | ------------------------ | | advertisingId11+ | number | Yes | Yes | ID of the advertisement. | | state11+ | [AdvertisingState](#advertisingstate11) | Yes | Yes | Advertising status. | ## ManufactureData Defines the content of a BLE advertisement packet. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ---------------- | ------------------- | ---- | ---- | ------------------ | | manufactureId | number | Yes | Yes | Manufacturer ID allocated by the Bluetooth SIG.| | manufactureValue | ArrayBuffer | Yes | Yes | Manufacturer data. | ## ServiceData Defines the service data contained in an advertisement packet. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | ------------ | ----------- | ---- | ---- | ---------- | | serviceUuid | string | Yes | Yes | Service UUID.| | serviceValue | ArrayBuffer | Yes | Yes | Service data. | ## ScanFilter Defines the scan filter parameters. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Mandatory | Description | | ------------------------------------------ | -------- | ---- | ------------------------------------------------------------ | | deviceId | string | No | Address of the BLE device to filter, for example, XX:XX:XX:XX:XX:XX. | | name | string | No | Name of the BLE device to filter. | | serviceUuid | string | No | Service UUID of the device to filter, for example, **00001888-0000-1000-8000-00805f9b34fb**.| | serviceUuidMask | string | No | Service UUID mask of the device to filter, for example, **FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF**.| | serviceSolicitationUuid | string | No | Service solicitation UUID of the device to filter, for example, **00001888-0000-1000-8000-00805F9B34FB**.| | serviceSolicitationUuidMask | string | No | Service solicitation UUID mask of the device to filter, for example, **FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF**.| | serviceData | ArrayBuffer | No | Service data of the device to filter, for example, **[0x90, 0x00, 0xF1, 0xF2]**.| | serviceDataMask | ArrayBuffer | No | Service data mask of the device to filter, for example, **[0xFF,0xFF,0xFF,0xFF]**.| | manufactureId | number | No | Manufacturer ID of the device to filter, for example, **0x0006**. | | manufactureData | ArrayBuffer | No | Manufacturer data of the device to filter, for example, **[0x1F,0x2F,0x3F]**.| | manufactureDataMask | ArrayBuffer | No | Manufacturer data mask of the device to filter, for example, **[0xFF, 0xFF, 0xFF]**.| ## ScanOptions Defines the scan configuration parameters. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Readable | Writable | Description | | --------- | ----------------------- | ---- | ---- | -------------------------------------- | | interval | number | Yes | Yes | Delay in reporting the scan result. The default value is **0**. | | dutyMode | [ScanDuty](#scanduty) | Yes | Yes | Scan duty. The default value is SCAN_MODE_LOW_POWER. | | matchMode | [MatchMode](#matchmode) | Yes | Yes | Hardware filtering match mode. The default value is **MATCH_MODE_AGGRESSIVE**.| | phyType12+ | [PhyType](#phytype12) | Yes | Yes | Physical layer (PHY) type used in scanning.| ## GattProperties Defines the properties of a GATT characteristic. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Type | Mandatory | Description | | -------- | ------ |---- | ----------- | | write | boolean | No | Whether the characteristic is writeable. The value **true** means to allow writes to the characteristic with an acknowledgment.| | writeNoResponse | boolean | No | Whether to allow the characteristic to be written without an acknowledgment. The value **true** means to allow writes to the characteristic without an acknowledgment.| | read | boolean | No | Whether the characteristic is readable. The value **true** means the characteristic is readable. | | notify | boolean | No | Whether to notify the client when the characteristic value changes. The value **true** means to notify the client of the characteristic change.| | indicate | boolean | No | Whether to indicate the client when the characteristic value changes. The value **true** means to indicate the client of the characteristic change. An acknowledgment from the client is also required.| ## GattWriteType Enumerates the GATT write types. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Value | Description | | ------------------------------------| ------ | --------------- | | WRITE | 1 | Write a characteristic value with a response from the peer device. | | WRITE_NO_RESPONSE | 2 | Write characteristic value without a response from the peer device. | ## ScanDuty Enumerates the scan duties. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Value | Description | | --------------------- | ---- | ------------ | | SCAN_MODE_LOW_POWER | 0 | Low-power mode, which is the default value.| | SCAN_MODE_BALANCED | 1 | Balanced mode. | | SCAN_MODE_LOW_LATENCY | 2 | Low-latency mode. | ## MatchMode Enumerates the hardware match modes of BLE scan filters. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Value | Description | | --------------------- | ---- | ---------------------------------------- | | MATCH_MODE_AGGRESSIVE | 1 | Hardware reports the scan result with a lower threshold of signal strength and few number of matches in a duration. This is the default value.| | MATCH_MODE_STICKY | 2 | Hardware reports the scan result with a higher threshold of signal strength and sightings. | ## AdvertisingState11+ Enumerates the advertising statuses. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Value | Description | | -------- | ---- | ------------------------------ | | STARTED11+ | 1 | The BLE advertising is started for the first time. | | ENABLED11+ | 2 | The BLE advertising is enabled temporarily. | | DISABLED11+ | 3 | The BLE advertising is disabled temporarily. | | STOPPED11+ | 4 | The BLE advertising is stopped. | ## PhyType12+ Enumerates the PHY types used in scanning. **Atomic service API**: This API can be used in atomic services since API version 12. **System capability**: SystemCapability.Communication.Bluetooth.Core | Name | Value | Description | | -------- | ---- | ------------------------------ | | PHY_LE_1M12+ | 1 | 1 M PHY. | | PHY_LE_ALL_SUPPORTED12+ | 255 | PHY mode supported by the Bluetooth profile used in scanning. |