@ohos.bluetooth.connection (Bluetooth Connection Module) (System API)

The connection 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. This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.bluetooth.connection (Bluetooth Connection Module).

Modules to Import

import { connection } from '@kit.ConnectivityKit';

connection.pairCredibleDevice

pairCredibleDevice(deviceId: string, transport: BluetoothTransport, callback: AsyncCallback<void>): void

Pairs a trusted device whose address is obtained in a non-Bluetooth scan mode (such as using NFC). This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to pair, for example, XX:XX:XX:XX:XX:XX.
transport	BluetoothTransport	Yes	Transport mode used for pairing with a remote device. - If the Bluetooth Classic (BR/EDR) or Bluetooth Low Energy (BLE) mode is used, pass in TRANSPORT_BR_EDR or TRANSPORT_LE. - If you are not sure which transport mode is used, pass in TRANSPORT_DUAL20+ or TRANSPORT_UNKNOWN20+. The Bluetooth subsystem will decide the transport mode based on the actual situation.
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.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.pairCredibleDevice('68:13:24:79:4C:8C', connection.BluetoothTransport
        .TRANSPORT_BR_EDR, (err: BusinessError) => {
        if (err) {
            console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
            return;
        }
        console.info('pairCredibleDevice, err: ' + JSON.stringify(err));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.pairCredibleDevice

pairCredibleDevice(deviceId: string, transport: BluetoothTransport): Promise<void>

Pairs a trusted device whose address is obtained in a non-Bluetooth scan mode (such as using NFC). This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to pair, for example, XX:XX:XX:XX:XX:XX.
transport	BluetoothTransport	Yes	Transport mode used for pairing with a remote device. - If the Bluetooth Classic (BR/EDR) or Bluetooth Low Energy (BLE) mode is used, pass in TRANSPORT_BR_EDR or TRANSPORT_LE. - If you are not sure which transport mode is used, pass in TRANSPORT_DUAL20+ or TRANSPORT_UNKNOWN20+. The Bluetooth subsystem will decide the transport mode based on the actual situation.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.pairCredibleDevice('68:13:24:79:4C:8C', 0).then(() => {
        console.info('PairCredibleDevice');
    }, (err: BusinessError) => {
        console.error('PairCredibleDevice:errCode' + err.code + ', errMessage: ' + err.message);
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.cancelPairedDevice

cancelPairedDevice(deviceId: string, callback: AsyncCallback<void>): void

Cancels a paired device. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to cancel, for example, XX:XX:XX:XX:XX:XX.
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.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
// callback
try {
    connection.cancelPairedDevice('11:22:33:44:55:66', (err: BusinessError) => {
        console.info('cancelPairedDevice, device name err:' + JSON.stringify(err));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.cancelPairedDevice

cancelPairedDevice(deviceId: string): Promise<void>

Cancels a paired device. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to cancel, for example, XX:XX:XX:XX:XX:XX.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.cancelPairedDevice('11:22:33:44:55:66').then(() => {
        console.info('cancelPairedDevice');
    }, (error: BusinessError) => {
        console.error('cancelPairedDevice: errCode:' + error.code + ',errMessage' + error.message);
    })

} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.cancelPairingDevice

cancelPairingDevice(deviceId: string, callback: AsyncCallback<void>): void

Cancels the pairing of a device. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to cancel, for example, XX:XX:XX:XX:XX:XX.
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.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.cancelPairingDevice('XX:XX:XX:XX:XX:XX');
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.cancelPairingDevice

cancelPairingDevice(deviceId: string): Promise<void>

Cancels the pairing of a device. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to cancel, for example, XX:XX:XX:XX:XX:XX.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.cancelPairingDevice('XX:XX:XX:XX:XX:XX');
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getLocalProfileUuids

getLocalProfileUuids(callback: AsyncCallback<Array<ProfileUuids>>): void

Obtains the profile UUIDs of the local device. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<ProfileUuids>>	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.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.getLocalProfileUuids((err: BusinessError, data: Array<connection.ProfileUuids>) => {
        console.info('getLocalProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getLocalProfileUuids

getLocalProfileUuids(): Promise<Array<ProfileUuids>>

Obtains the profile UUIDs of the local device. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Type	Description
Promise<Array<ProfileUuids>>	Promise used to return the result.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.getLocalProfileUuids().then(() => {
        console.info('getLocalProfileUuids');
    }, (err: BusinessError) => {
        console.error('getLocalProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.disconnectAllowedProfiles¹¹⁺

disconnectAllowedProfiles(deviceId: string, callback: AsyncCallback<void>): void

Disconnects all connected profiles for a remote device. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to disconnect, for example, XX:XX:XX:XX:XX:XX.
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.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.disconnectAllowedProfiles('68:13:24:79:4C:8C', (err: BusinessError) => {
        if (err) {
            console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
            return;
        }
        console.info('disconnectAllowedProfiles, err: ' + JSON.stringify(err));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.disconnectAllowedProfiles¹¹⁺

disconnectAllowedProfiles(deviceId: string): Promise<void>

Disconnects all connected profiles for a remote device. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Address of the remote device to disconnect, for example, XX:XX:XX:XX:XX:XX.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation is successful, true is returned; otherwise, false is returned.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.disconnectAllowedProfiles('68:13:24:79:4C:8C').then(() => {
        console.info('disconnectAllowedProfiles');
    }, (err: BusinessError) => {
        console.error('disconnectAllowedProfiles:errCode' + err.code + ', errMessage: ' + err.message);
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteProductId¹¹⁺

getRemoteProductId(deviceId: string): string

Obtains the product ID of a remote Bluetooth device. Since API version 16, the ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH permissions are no longer verified.

System API: This is a system API.

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
string	Product ID obtained.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID	Error Message
202	Non-system applications are not allowed to use system APIs.
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

try {
  let remoteDeviceProductId = connection.getRemoteProductId('XX:XX:XX:XX:XX:XX');
} catch (err) {
  console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}

connection.setRemoteDeviceType¹²⁺

setRemoteDeviceType(deviceId: string, type: DeviceType): Promise<void>

Sets the type of a remote Bluetooth device. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.
type	DeviceType	Yes	Device type to set.

Return value

Type	Description
Promise<void>	Promise used to return the device type set. If the operation fails, an error code is returned.

Error codes

For details about the error codes, see Bluetooth Error Codes.

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.
2900001	Service stopped.
2900003	Bluetooth disabled.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.setRemoteDeviceType('11:22:33:44:55:66', connection.DeviceType.DEVICE_TYPE_HEADSET).then(() => {
        console.info('setRemoteDeviceType success');
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteDeviceType¹²⁺

getRemoteDeviceType(deviceId: string): Promise<DeviceType>

Obtains the type of a remote Bluetooth device. This API uses a promise to return the result. Since API version 18, the ohos.permission.ACCESS_BLUETOOTH permission is no longer verified.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.

Return value

Type	Description
Promise<DeviceType>	Promise used to return the device type obtained.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID	Error Message
202	Non-system applications are not allowed to use system APIs.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
2900001	Service stopped.
2900003	Bluetooth disabled.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.getRemoteDeviceType('11:22:33:44:55:66').then((data: connection.DeviceType) => {
        console.info('getRemoteDeviceType success, DeviceType:' + JSON.stringify(data));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.controlDeviceAction¹⁵⁺

controlDeviceAction(controlDeviceActionParams: ControlDeviceActionParams): Promise<void>

Sends a control command to Bluetooth headsets during scanning. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH (available only for system applications)

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
controlDeviceActionParams15+	ControlDeviceActionParams	Yes	Bluetooth peripheral control information.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let controlDeviceActionParams: connection.ControlDeviceActionParams = {
        deviceId: '40:DC:A5:E5:75:C3',
        type: connection.ControlType.PLAY,
        typeValue: connection.ControlTypeValue.ENABLE,
        controlObject: connection.ControlObject.LEFT_EAR
    };
    connection.controlDeviceAction(controlDeviceActionParams).then(() => {
        console.info('controlDeviceAction success');
    }, (err: BusinessError) => {
        console.error('controlDeviceAction: errCode' + err.code + ', errMessage: ' + err.message);
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.updateCloudBluetoothDevice¹⁵⁺

updateCloudBluetoothDevice(trustedPairedDevices: TrustedPairedDevices): Promise<void>

Updates cloud devices in Bluetooth settings. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name	Type	Mandatory	Description
trustedPairedDevices	TrustedPairedDevices	Yes	Cloud device list.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the setting fails, an error code is returned.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
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

import { BusinessError } from '@kit.BasicServicesKit';
// promise
/**
 * Update cloud devices in Bluetooth settings.
 */
const trustPairDeviceArr: connection.TrustedPairedDevice[] = [];
let descBuffer = new ArrayBuffer(1);
trustPairDeviceArr.push({
    sn: '',
    deviceType: '',
    modelId: '',
    manufactory: '',
    productId: '',
    hiLinkVersion: '',
    macAddress: '11:22:33:44:55:66',
    serviceType: '',
    serviceId: '',
    deviceName: '',
    uuids: '',
    bluetoothClass: 0,
    token: descBuffer,
    deviceNameTime: 0,
    secureAdvertisingInfo: descBuffer,
    pairState: 0
    });
const trustPairDevices: connection.TrustedPairedDevices = { trustedPairedDevices: trustPairDeviceArr };
try {
    connection.updateCloudBluetoothDevice(trustPairDevices)
        .then(() => {
            console.info('updateCloudBluetoothDevice success!');
        })
        .catch((err: BusinessError) => {
            console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
        });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.pairDeviceOutOfBand²³⁺

pairDeviceOutOfBand(transport: BluetoothTransport, p192Data: OobData | null, p256Data: OobData | null): Promise<void>

Initiates pairing with the peer Bluetooth device through the out-of-band (OOB) communication mechanism. This API uses a promise to return the result.

• You can obtain the Bluetooth pairing status from the callback of on('bondStateChange').

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
transport	BluetoothTransport	Yes	Transport mode used for pairing with a peer device. - If BR/EDR is used, pass TRANSPORT_BR_EDR. If BLE is used, pass TRANSPORT_LE. Other BluetoothTransport types are not supported.
p192Data	OobData | null	Yes	OOB data used during pairing. P-192 is an elliptic curve algorithm with a 192-bit key length. It was widely used in legacy pairing schemes of Bluetooth 4.1 and earlier versions. - If this value is not used, pass null. - At least one of p192Data and p256Data must be passed. If both of them are passed, p256Data takes effect whereas p192Data does not.
p256Data	OobData | null	Yes	OOB data used during pairing. P-256 is an elliptic curve algorithm with a 256-bit key length. It has been the core of secure connections since Bluetooth 4.2. Compared with P-192 OOB data, P-256 OOB data has stronger anti-attack capability and confidentiality. p256Data is recommended unless the device needs to be compatible with Bluetooth 4.1 or earlier. - If this value is not used, pass null. - At least one of p192Data and p256Data must be passed. If both of them are passed, p256Data takes effect whereas p192Data does not.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
801	Capability not supported.
2900003	Bluetooth disabled.
2900099	Operation failed.

Example

import { common } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';
try {
    let transport: connection.BluetoothTransport = connection.BluetoothTransport.TRANSPORT_LE;
    let addressInfo: common.BluetoothAddress = {
        "address": "11:22:33:44:55:66",
        "addressType": common.BluetoothAddressType.REAL, // The value must be an actual MAC address.
        "rawAddressType": common.BluetoothRawAddressType.RANDOM
    };
    let confirmHash: Uint8Array = new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10]);
    let randomHash: Uint8Array = new Uint8Array([0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x11]);
    let oobData: connection.OobData = {
        "deviceId": addressInfo,
        "confirmationHash": confirmHash,
        "randomizerHash": randomHash,
        "deviceName": "testName",
        "deviceRole": connection.DeviceRole.DEVICE_ROLE_PERIPHERAL_ONLY
    }
    connection.pairDeviceOutOfBand(transport, null, oobData).then(() => {
        console.info('pairDeviceOufOfBand');
    }, (err: BusinessError) => {
        console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
    });
} catch (err) {
    console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
}

connection.generateLocalOobData²³⁺

generateLocalOobData(transport: BluetoothTransport): Promise<OobData>

Obtains the out-of-band (OOB) communication data of the local device. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
transport	BluetoothTransport	Yes	Transport mode used for pairing with a peer device. - If BR/EDR is used, pass TRANSPORT_BR_EDR. If BLE is used, pass TRANSPORT_LE. Other BluetoothTransport types are not supported.

Return value

Type	Description
Promise<OobData>	Promise used to return the OOB data of the local device.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID	Error Message
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
801	Capability not supported.
2900003	Bluetooth disabled.
2900099	Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let transport: connection.BluetoothTransport = connection.BluetoothTransport.TRANSPORT_LE;
    connection.generateLocalOobData(transport).then((oobData: connection.OobData) => {
        console.info(`generateLocalOobData: ${JSON.stringify(oobData)}`);
    }, (err: BusinessError) => {
        console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
    });
} catch (err) {
    console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
}

PinRequiredParam

Represents the pairing request parameters.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Type	Read-Only	Optional	Description
pinType	PinType	No	No	Type of the device to pair. This is a system API.

ControlDeviceActionParams¹⁵⁺

Defines the configuration parameters of the control command.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Type	Read-Only	Optional	Description
deviceId	string	No	No	Device ID.
type	ControlType	No	No	Control type.
typeValue	ControlTypeValue	No	No	Control action.
controlObject	ControlObject	No	No	Control object.

PinType

Enumerates the Bluetooth pairing types.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Value	Description
PIN_TYPE_ENTER_PIN_CODE	0	The user needs to enter the PIN displayed on the peer device. This is a system API.
PIN_TYPE_ENTER_PASSKEY	1	The user needs to enter the PASSKEY displayed on the peer device. This is a system API.
PIN_TYPE_CONFIRM_PASSKEY	2	The user needs to confirm the PASSKEY displayed on the local device. This is a system API.
PIN_TYPE_NO_PASSKEY_CONSENT	3	There is no PASSKEY, and the user needs to accept or reject the pairing request. This is a system API.
PIN_TYPE_NOTIFY_PASSKEY	4	The user needs to enter the PASSKEY displayed on the local device on the peer device. This is a system API.
PIN_TYPE_DISPLAY_PIN_CODE	5	The user needs to enter the PIN displayed on the peer device for Bluetooth 2.0 devices. This is a system API.
PIN_TYPE_OOB_CONSENT	6	The user needs to accept or reject the out of band (OOB) pairing request. This is a system API.
PIN_TYPE_PIN_16_DIGITS	7	The user needs to enter the 16-digit PIN displayed on the peer device. This is a system API.

DeviceType¹²⁺

Enumerates the custom types of a remote Bluetooth device.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Value	Description
DEVICE_TYPE_DEFAULT	0	Default device type, which is the same as the original type. This is a system API.
DEVICE_TYPE_CAR	1	Car. This is a system API.
DEVICE_TYPE_HEADSET	2	Headset. This is a system API.
DEVICE_TYPE_HEARING	3	Hearing aid. This is a system API.
DEVICE_TYPE_GLASSES	4	Glasses. This is a system API.
DEVICE_TYPE_WATCH	5	Watch. This is a system API.
DEVICE_TYPE_SPEAKER	6	Speaker. This is a system API.
DEVICE_TYPE_OTHERS	7	Other device. This is a system API.

BatteryInfo¹²⁺

Represents the battery information.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Type	Read-Only	Optional	Description
deviceId	string	No	No	MAC address of the remote device. This is a system API.

ControlType¹⁵⁺

Enumerates control types.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Value	Description
PLAY	0	Play
VIBRATE	1	Vibration
FLASH	2	Flash
LOCK	3	Lock
ERASE	4	Erase

ControlTypeValue¹⁵⁺

Enumerates control actions.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Value	Description
DISABLE	0	Disable
ENABLE	1	Enable
QUERY	2	Query

ControlObject¹⁵⁺

Enumerates control objects.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Value	Description
LEFT_EAR	0	Left earbud.
RIGHT_EAR	1	Right earbud.
LEFT_RIGHT_EAR	2	Left and right earbuds.

TrustedPairedDevices¹⁵⁺

Defines the cloud device list.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Type	Read-Only	Optional	Description
trustedPairedDevices	Array<TrustedPairedDevice>	No	No	Cloud device list.

TrustedPairedDevice¹⁵⁺

Defines the cloud device information.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Name	Type	Read-Only	Optional	Description
sn	string	No	No	Device SN.
deviceType	string	No	No	Device type to set.
modelId	string	No	No	Charging state of the left earbud.
manufactory	string	No	No	Manufacturer information.
productId	string	No	No	Product information.
hiLinkVersion	string	No	No	HiLink version.
macAddress	string	No	No	MAC address.
serviceType	string	No	No	Service type.
serviceId	string	No	No	Device ID.
deviceName	string	No	No	Device name.
uuids	string	No	No	Device UUID.
bluetoothClass	number	No	No	Peer device type.
token	ArrayBuffer	No	No	Device token information.
deviceNameTime	number	No	No	Device name modification time.
secureAdvertisingInfo	ArrayBuffer	No	No	Device advertising information.
pairState	number	No	No	Device pairing status.

OobData²³⁺

Represents the data object used for OOB pairing.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Model restriction: This API can be used only in the stage model.

Name	Type	Read-Only	Optional	Description
deviceId	BluetoothAddress	No	No	Address information of the Bluetooth device. - When OobData is used, the address, addressType, and rawAddressType parameters in BluetoothAddress are mandatory, and addressType must be set to REAL.
confirmationHash	Uint8Array	No	No	Confirmation hash, which contains 16 bytes.
randomizerHash	Uint8Array	No	Yes	Random hash, which contains 16 bytes. If this parameter is not set, the default value is all 0s.
deviceName	string	No	Yes	Bluetooth device name. If this parameter is not set, the default value is an empty string.
deviceRole	DeviceRole	No	Yes	Bluetooth device role during connection. If this parameter is not set, the default value is DEVICE_ROLE_PERIPHERAL_ONLY.

DeviceRole²³⁺

Enumerates Bluetooth device roles during connection.

System API: This is a system API.

System capability: SystemCapability.Communication.Bluetooth.Core

Model restriction: This API can be used only in the stage model.

Name	Value	Description
DEVICE_ROLE_PERIPHERAL_ONLY	0	The Bluetooth device can only be used as a peripheral device.
DEVICE_ROLE_CENTRAL_ONLY	1	The Bluetooth device can only be used as a central device.
DEVICE_ROLE_BOTH_PREFER_PERIPHERAL	2	The Bluetooth device can be used as a central device or a peripheral device, but it is preferentially used as a peripheral device.
DEVICE_ROLE_BOTH_PREFER_CENTRAL	3	The Bluetooth device can be used as a central device or a peripheral device, but it is preferentially used as a central device.