1# @ohos.bluetooth.pbap (Bluetooth PBAP Module) (System API) 2 3The **pbap** module provides APIs for accessing the phone book of a device using the Bluetooth Phone Book Access Profile (PBAP). 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.bluetooth.pbap (Bluetooth PBAP Module)](js-apis-bluetooth-pbap.md). 9 10 11## Modules to Import 12 13```js 14import { pbap } from '@kit.ConnectivityKit'; 15``` 16 17## PbapServerProfile 18 19Provides APIs for accessing the phone book of a device. Before using any API of **PbapServerProfile**, you need to create an instance of this class by using **createPbapServerProfile()**. 20 21### disconnect 22 23disconnect(deviceId: string): void 24 25Disconnects the PBAP service for a device. 26 27**System API**: This is a system API. 28 29**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 30 31**System capability**: SystemCapability.Communication.Bluetooth.Core 32 33**Parameters** 34 35| Name | Type | Mandatory | Description | 36| ------ | ------ | ---- | ------- | 37| deviceId | string | Yes | Address of the remote device.| 38 39**Error codes** 40 41For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 42 43| ID| Error Message| 44| -------- | ---------------------------- | 45|201 | Permission denied. | 46|202 | Non-system applications are not allowed to use system APIs. | 47|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 48|801 | Capability not supported. | 49|2900001 | Service stopped. | 50|2900003 | Bluetooth disabled. | 51|2900004 | Profile not supported. | 52|2900099 | Operation failed. | 53 54**Example** 55 56```js 57import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 58try { 59 let pbapServerProfile = pbap.createPbapServerProfile(); 60 pbapServerProfile.disconnect('XX:XX:XX:XX:XX:XX'); 61} catch (err) { 62 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 63} 64``` 65 66### setShareType 67 68setShareType(deviceId: string, type: ShareType, callback: AsyncCallback<void>): void 69 70Sets the share type of the phone book information for a device. This API uses an asynchronous callback to return the result. 71 72**System API**: This is a system API. 73 74**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 75 76**System capability**: SystemCapability.Communication.Bluetooth.Core 77 78**Parameters** 79 80| Name | Type | Mandatory | Description | 81| -------- | ------ | ---- | ----------------------------------- | 82| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 83| type | [ShareType](#sharetype) | Yes | Share type to set.| 84| callback | AsyncCallback<void> | Yes | Callback used to return the result.<br>If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 85 86**Error codes** 87 88For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 89 90| ID| Error Message| 91| -------- | ---------------------------- | 92|201 | Permission denied. | 93|202 | Non-system applications are not allowed to use system APIs. | 94|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 95|801 | Capability not supported. | 96|2900001 | Service stopped. | 97|2900003 | Bluetooth disabled. | 98|2900004 | Profile not supported. | 99|2900099 | Operation failed. | 100 101**Example** 102 103```js 104import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 105try { 106 let pbapServerProfile = pbap.createPbapServerProfile(); 107 pbapServerProfile.setShareType('XX:XX:XX:XX:XX:XX', 0, (err: BusinessError) => { 108 console.info('setShareType'); 109 }); 110} catch (err) { 111 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 112} 113``` 114 115 116### setShareType 117 118setShareType(deviceId: string, type: ShareType): Promise<void> 119 120Sets the share type of the phone book information for a device. This API uses a promise to return the result. 121 122**System API**: This is a system API. 123 124**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 125 126**System capability**: SystemCapability.Communication.Bluetooth.Core 127 128**Parameters** 129 130| Name | Type | Mandatory | Description | 131| -------- | ------ | ---- | ----------------------------------- | 132| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 133| type | [ShareType](#sharetype) | Yes | Share type to set.| 134 135**Return value** 136 137| Type | Description | 138| ------------------------------------------------- | ------------------- | 139| Promise<void> | Promise used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 140 141**Error codes** 142 143For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 144 145| ID| Error Message| 146| -------- | ---------------------------- | 147|201 | Permission denied. | 148|202 | Non-system applications are not allowed to use system APIs. | 149|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 150|801 | Capability not supported. | 151|2900001 | Service stopped. | 152|2900003 | Bluetooth disabled. | 153|2900004 | Profile not supported. | 154|2900099 | Operation failed. | 155 156**Example** 157 158```js 159import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 160try { 161 let pbapServerProfile = pbap.createPbapServerProfile(); 162 pbapServerProfile.setShareType('XX:XX:XX:XX:XX:XX', 0).then(() => { 163 console.info('setShareType'); 164 }); 165} catch (err) { 166 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 167} 168``` 169 170### getShareType 171 172getShareType(deviceId: string, callback: AsyncCallback<ShareType>): void 173 174Obtains the phone book share type of a device. This API uses an asynchronous callback to return the result. 175 176**System API**: This is a system API. 177 178**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 179 180**System capability**: SystemCapability.Communication.Bluetooth.Core 181 182**Parameters** 183 184| Name | Type | Mandatory | Description | 185| -------- | ------ | ---- | ----------------------------------- | 186| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 187| callback | AsyncCallback<[ShareType](#sharetype)> | Yes | Callback used to return the result.<br>If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 188 189**Error codes** 190 191For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 192 193| ID| Error Message| 194| -------- | ---------------------------- | 195|201 | Permission denied. | 196|202 | Non-system applications are not allowed to use system APIs. | 197|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 198|801 | Capability not supported. | 199|2900001 | Service stopped. | 200|2900003 | Bluetooth disabled. | 201|2900004 | Profile not supported. | 202|2900099 | Operation failed. | 203 204**Example** 205 206```js 207import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 208try { 209 let pbapServerProfile = pbap.createPbapServerProfile(); 210 pbapServerProfile.getShareType('XX:XX:XX:XX:XX:XX', (err, type) => { 211 console.info('getShareType ' + type); 212 }); 213} catch (err) { 214 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 215} 216``` 217 218### getShareType 219 220getShareType(deviceId: string): Promise<ShareType> 221 222Obtains the phone book share type of a device. This API uses a promise to return the result. 223 224**System API**: This is a system API. 225 226**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 227 228**System capability**: SystemCapability.Communication.Bluetooth.Core 229 230**Parameters** 231 232| Name | Type | Mandatory | Description | 233| -------- | ------ | ---- | ----------------------------------- | 234| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 235 236**Return value** 237 238| Type | Description | 239| ------------------------------------------------- | ------------------- | 240| Promise<[ShareType](#sharetype)> | Promise used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 241 242**Error codes** 243 244For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 245 246| ID| Error Message| 247| -------- | ---------------------------- | 248|201 | Permission denied. | 249|202 | Non-system applications are not allowed to use system APIs. | 250|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 251|801 | Capability not supported. | 252|2900001 | Service stopped. | 253|2900003 | Bluetooth disabled. | 254|2900004 | Profile not supported. | 255|2900099 | Operation failed. | 256 257**Example** 258 259```js 260import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 261try { 262 let pbapServerProfile = pbap.createPbapServerProfile(); 263 pbapServerProfile.getShareType('XX:XX:XX:XX:XX:XX').then((type) => { 264 console.info('getShareType ' + type); 265 }); 266} catch (err) { 267 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 268} 269``` 270 271### setPhoneBookAccessAuthorization 272 273setPhoneBookAccessAuthorization(deviceId: string, authorization: AccessAuthorization, callback: AsyncCallback<void>): void 274 275Sets the phone book access authorization for a device. This API uses an asynchronous callback to return the result. 276 277**System API**: This is a system API. 278 279**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 280 281**System capability**: SystemCapability.Communication.Bluetooth.Core 282 283**Parameters** 284 285| Name | Type | Mandatory | Description | 286| -------- | ------ | ---- | ----------------------------------- | 287| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 288| authorization | [AccessAuthorization](js-apis-bluetooth-constant-sys.md#AccessAuthorization) | Yes | Phone book access authorization to set.| 289| callback | AsyncCallback<void> | Yes | Callback used to return the result.<br>If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 290 291**Error codes** 292 293For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 294 295| ID| Error Message| 296| -------- | ---------------------------- | 297|201 | Permission denied. | 298|202 | Non-system applications are not allowed to use system APIs. | 299|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 300|801 | Capability not supported. | 301|2900001 | Service stopped. | 302|2900003 | Bluetooth disabled. | 303|2900004 | Profile not supported. | 304|2900099 | Operation failed. | 305 306**Example** 307 308```js 309import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 310try { 311 let pbapServerProfile = pbap.createPbapServerProfile(); 312 pbapServerProfile.setPhoneBookAccessAuthorization('XX:XX:XX:XX:XX:XX', 0, (err: BusinessError) => { 313 console.info('setPhoneBookAccessAuthorization'); 314 }); 315} catch (err) { 316 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 317} 318``` 319 320 321### setPhoneBookAccessAuthorization 322 323setPhoneBookAccessAuthorization(deviceId: string, authorization: AccessAuthorization): Promise<void> 324 325Sets the phone book access authorization for a device. This API uses a promise to return the result. 326 327**System API**: This is a system API. 328 329**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 330 331**System capability**: SystemCapability.Communication.Bluetooth.Core 332 333**Parameters** 334 335| Name | Type | Mandatory | Description | 336| -------- | ------ | ---- | ----------------------------------- | 337| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 338| authorization | [AccessAuthorization](js-apis-bluetooth-constant-sys.md#AccessAuthorization) | Yes | Phone book access authorization to set.| 339 340**Return value** 341 342| Type | Description | 343| ------------------------------------------------- | ------------------- | 344| Promise<void> | Promise used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 345 346**Error codes** 347 348For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 349 350| ID| Error Message| 351| -------- | ---------------------------- | 352|201 | Permission denied. | 353|202 | Non-system applications are not allowed to use system APIs. | 354|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 355|801 | Capability not supported. | 356|2900001 | Service stopped. | 357|2900003 | Bluetooth disabled. | 358|2900004 | Profile not supported. | 359|2900099 | Operation failed. | 360 361**Example** 362 363```js 364import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 365try { 366 let pbapServerProfile = pbap.createPbapServerProfile(); 367 pbapServerProfile.setPhoneBookAccessAuthorization('XX:XX:XX:XX:XX:XX', 0).then(() => { 368 console.info('setPhoneBookAccessAuthorization'); 369 }); 370} catch (err) { 371 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 372} 373``` 374 375### getPhoneBookAccessAuthorization 376 377getPhoneBookAccessAuthorization(deviceId: string, callback: AsyncCallback<AccessAuthorization>): void 378 379Obtains the phone book access authorization of a device. This API uses an asynchronous callback to return the result. 380 381**System API**: This is a system API. 382 383**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 384 385**System capability**: SystemCapability.Communication.Bluetooth.Core 386 387**Parameters** 388 389| Name | Type | Mandatory | Description | 390| -------- | ------ | ---- | ----------------------------------- | 391| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 392| callback | AsyncCallback<[AccessAuthorization](js-apis-bluetooth-constant-sys.md#AccessAuthorization)> | Yes | Callback used to return the result.<br>If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 393 394**Error codes** 395 396For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 397 398| ID| Error Message| 399| -------- | ---------------------------- | 400|201 | Permission denied. | 401|202 | Non-system applications are not allowed to use system APIs. | 402|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 403|801 | Capability not supported. | 404|2900001 | Service stopped. | 405|2900003 | Bluetooth disabled. | 406|2900004 | Profile not supported. | 407|2900099 | Operation failed. | 408 409**Example** 410 411```js 412import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 413try { 414 let pbapServerProfile = pbap.createPbapServerProfile(); 415 pbapServerProfile.getPhoneBookAccessAuthorization('XX:XX:XX:XX:XX:XX', (err, authorization) => { 416 console.info('authorization ' + authorization); 417 }); 418} catch (err) { 419 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 420} 421``` 422 423### getPhoneBookAccessAuthorization 424 425getPhoneBookAccessAuthorization(deviceId: string): Promise<AccessAuthorization> 426 427Obtains the phone book access authorization of a device. This API uses a promise to return the result. 428 429**System API**: This is a system API. 430 431**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 432 433**System capability**: SystemCapability.Communication.Bluetooth.Core 434 435**Parameters** 436 437| Name | Type | Mandatory | Description | 438| -------- | ------ | ---- | ----------------------------------- | 439| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 440 441**Return value** 442 443| Type | Description | 444| ------------------------------------------------- | ------------------- | 445| Promise<[AccessAuthorization](js-apis-bluetooth-constant-sys.md#AccessAuthorization)> | Promise used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 446 447**Error codes** 448 449For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 450 451| ID| Error Message| 452| -------- | ---------------------------- | 453|201 | Permission denied. | 454|202 | Non-system applications are not allowed to use system APIs. | 455|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 456|801 | Capability not supported. | 457|2900001 | Service stopped. | 458|2900003 | Bluetooth disabled. | 459|2900004 | Profile not supported. | 460|2900099 | Operation failed. | 461 462**Example** 463 464```js 465import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 466try { 467 let pbapServerProfile = pbap.createPbapServerProfile(); 468 pbapServerProfile.getPhoneBookAccessAuthorization('XX:XX:XX:XX:XX:XX').then((authorization) => { 469 console.info('authorization ' + authorization); 470 }); 471} catch (err) { 472 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 473} 474``` 475 476## ShareType 477 478Enumerates the phone book share types. 479 480**System API**: This is a system API. 481 482**System capability**: SystemCapability.Communication.Bluetooth.Core 483 484| Name | Value | Description | 485| ------------------ | ---- | ------ | 486| SHARE_NAME_AND_PHONE_NUMBER | 0 | Share the name and number.<br>This is a system API.| 487| SHARE_ALL | 1 | Share all information.<br>This is a system API. | 488| SHARE_NOTHING | 2 | Share nothing.<br>This is a system API. | 489