Tizen Native API  3.0
Bluetooth PBAP

Bluetooth PBAP (Phone Book Access Profile) API provides functions for managing connections to a phone book server and retrieving phone book data.

Required Header

#include <bluetooth.h>

Overview

The PBAP involves two roles, Server and Client. The Server is a device that has phone book data. The Client is a device that requests the phone book data from the Server. This API only supports Client role.

Related Features

This API is related to the following features:

It is recommended to use features in your application for reliability.

You can check if a device supports features related to this API by using System Information, thereby controlling your application's actions.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on using features in your application can be found from Feature Element.

Functions

int bt_pbap_client_initialize (void)
 Initializes the Bluetooth PBAP Client.
int bt_pbap_client_deinitialize (void)
 Deinitializes the Bluetooth PBAP Client.
int bt_pbap_client_set_connection_state_changed_cb (bt_pbap_connection_state_changed_cb callback, void *user_data)
 Registers a callback function that will be invoked when the connection state is changed.
int bt_pbap_client_unset_connection_state_changed_cb (void)
 Unregisters a callback function that will be invoked when the connection state is changed.
int bt_pbap_client_connect (const char *address)
 Connects to PBAP server, asynchronously.
int bt_pbap_client_disconnect (const char *address)
 Disconnects from PBAP server, asynchronously.
int bt_pbap_client_get_phone_book_size (const char *address, bt_pbap_address_book_source_e source, bt_pbap_folder_type_e folder_type, bt_pbap_phone_book_size_cb callback, void *user_data)
 Gets size of phone book from PBAP server, asynchronously.
int bt_pbap_client_get_phone_book (const char *address, bt_pbap_address_book_source_e source, bt_pbap_folder_type_e folder_type, bt_pbap_vcard_format_e format, bt_pbap_sort_order_e order, unsigned short offset, unsigned short max_list_count, unsigned int fields, bt_pbap_phone_book_received_cb callback, void *user_data)
 Gets all contacts and call logs as vCard from PBAP server, asynchronously.
int bt_pbap_client_get_list (const char *address, bt_pbap_address_book_source_e source, bt_pbap_folder_type_e folder_type, bt_pbap_sort_order_e order, unsigned short offset, unsigned short max_list_count, bt_pbap_list_vcards_cb callback, void *user_data)
 Gets contact and call log information from the PBAP server, asynchronously.
int bt_pbap_client_pull_vcard (const char *address, bt_pbap_address_book_source_e source, bt_pbap_folder_type_e folder_type, int index, bt_pbap_vcard_format_e format, unsigned int fields, bt_pbap_phone_book_received_cb callback, void *user_data)
 Gets the selected contact using the index parameter as vCard from PBAP server, asynchronously.
int bt_pbap_client_search_phone_book (const char *address, bt_pbap_address_book_source_e source, bt_pbap_folder_type_e folder_type, bt_pbap_search_field_e search_attribute, const char *search_value, bt_pbap_sort_order_e order, unsigned short offset, unsigned short max_list_count, bt_pbap_list_vcards_cb callback, void *user_data)
 Finds and fetches the contact and call log information from the PBAP server, asynchronously.

Typedefs

typedef void(* bt_pbap_connection_state_changed_cb )(int result, bool connected, const char *remote_address, void *user_data)
 Called when PBAP is Connected or Disconnected.
typedef void(* bt_pbap_phone_book_size_cb )(int result, const char *remote_address, int size, void *user_data)
 Called when PBAP Phonebook size calculation completes.
typedef void(* bt_pbap_phone_book_received_cb )(int result, const char *remote_address, const char *vcf_file, void *user_data)
 Called when PBAP Phonebook Pull completes.
typedef void(* bt_pbap_list_vcards_cb )(int result, const char *remote_address, const bt_pbap_vcard_info_s *vcard_info, int count, void *user_data)
 Called when PBAP List vCards completes.

Typedef Documentation

typedef void(* bt_pbap_connection_state_changed_cb)(int result, bool connected, const char *remote_address, void *user_data)

Called when PBAP is Connected or Disconnected.

The following error codes can be delivered:
BT_ERROR_NONE
BT_ERROR_OPERATION_FAILED

Since :
3.0
Parameters:
[in]resultThe result of connecting to or disconnecting from the remote device
[in]connectedThe PBAP connection status (true = connected, false = disconnected)
[in]remote_addressThe remote device address (remote_address is valid only inside this function. To use outside the callback, make a copy. remote_address should not be freed.)
[in]user_dataThe user data passed from the callback registration function
See also:
bt_pbap_client_connect()
bt_pbap_client_disconnect()
typedef void(* bt_pbap_list_vcards_cb)(int result, const char *remote_address, const bt_pbap_vcard_info_s *vcard_info, int count, void *user_data)

Called when PBAP List vCards completes.

The following error codes can be delivered:
BT_ERROR_NONE
BT_ERROR_OPERATION_FAILED

Since :
3.0
Parameters:
[in]resultThe result of getting the vcard list
[in]remote_addressThe remote device address (remote_address is valid only inside this function. To use outside the callback, make a copy. remote_address should not be freed.)
[in]vcard_infoList of vcard information (vcard_info is valid only inside this function. To use outside the callback, make a copy. vcard_info should not be freed.)
[in]countNumber of contacts in the list
[in]successfultrue if the operation was successful, false if not
[in]user_dataThe user data passed from the callback registration function
See also:
bt_pbap_client_get_list()
bt_pbap_client_connect()
bt_pbap_client_disconnect()
typedef void(* bt_pbap_phone_book_received_cb)(int result, const char *remote_address, const char *vcf_file, void *user_data)

Called when PBAP Phonebook Pull completes.

The received phone book file will be saved in the platform downloads folder.
The following error codes can be delivered:
BT_ERROR_NONE
BT_ERROR_OPERATION_FAILED

Since :
3.0
Parameters:
[in]resultThe result of getting the phone book
[in]remote_addressThe remote device address (remote_address is valid only inside this function. To use outside the callback, make a copy. remote_address should not be freed.)
[in]vcf_fileThe absolute path of the file in which the vCards are saved (vcf_file is valid only inside this function. To use outside the callback, make a copy. vcf_file should not be freed.)
[in]successfultrue if the operation was successful, false if not
[in]user_dataThe user data passed from the callback registration function
See also:
bt_pbap_client_get_phone_book()
bt_pbap_client_connect()
bt_pbap_client_disconnect()
typedef void(* bt_pbap_phone_book_size_cb)(int result, const char *remote_address, int size, void *user_data)

Called when PBAP Phonebook size calculation completes.

The following error codes can be delivered:
BT_ERROR_NONE
BT_ERROR_OPERATION_FAILED

Since :
3.0
Parameters:
[in]resultThe result of getting the phone book size
[in]remote_addressThe remote device address (remote_address is valid only inside this function. To use outside the callback, make a copy. remote_address should not be freed.)
[in]sizeSize of Phonebook
[in]user_dataThe user data passed from the callback registration function
See also:
bt_pbap_client_get_phone_book_size()
bt_pbap_client_connect()
bt_pbap_client_disconnect()

Enumeration Type Documentation

Enumeration of address book location for PBAP.

Since :
3.0
Enumerator:
BT_PBAP_SOURCE_DEVICE 

Request for Addressbook from remote device

BT_PBAP_SOURCE_SIM 

Request for address book from SIM

Enumeration of PBAP fields.

Since :
3.0
Enumerator:
BT_PBAP_FIELD_ALL 

All field

BT_PBAP_FIELD_VERSION 

vCard Version

BT_PBAP_FIELD_FN 

Formatted Name

BT_PBAP_FIELD_N 

Structured Presentation of Name

BT_PBAP_FIELD_PHOTO 

Associated Image or Photo

BT_PBAP_FIELD_BDAY 

Birthday

BT_PBAP_FIELD_ADR 

Delivery Address

BT_PBAP_FIELD_LABEL 

Delivery

BT_PBAP_FIELD_TEL 

Telephone Number

BT_PBAP_FIELD_EMAIL 

Electronic Mail Address

BT_PBAP_FIELD_MAILER 

Electronic Mail

BT_PBAP_FIELD_TZ 

Time Zone

BT_PBAP_FIELD_GEO 

Geographic Position

BT_PBAP_FIELD_TITLE 

Job

BT_PBAP_FIELD_ROLE 

Role within the Organization

BT_PBAP_FIELD_LOGO 

Organization Logo

BT_PBAP_FIELD_AGENT 

vCard of Person Representing

BT_PBAP_FIELD_ORG 

Name of Organization

BT_PBAP_FIELD_NOTE 

Comments

BT_PBAP_FIELD_REV 

Revision

BT_PBAP_FIELD_SOUND 

Pronunciation of Name

BT_PBAP_FIELD_URL 

Uniform Resource Locator

BT_PBAP_FIELD_UID 

Unique ID

BT_PBAP_FIELD_KEY 

Public Encryption Key

BT_PBAP_FIELD_NICKNAME 

Nickname

BT_PBAP_FIELD_CATEGORIES 

Categories

BT_PBAP_FIELD_PROID 

Product ID

BT_PBAP_FIELD_CLASS 

Class information

BT_PBAP_FIELD_SORT_STRING 

String used for sorting operations

BT_PBAP_FIELD_X_IRMC_CALL_DATETIME 

Time stamp

Enumeration of folder type.

Since :
3.0
Enumerator:
BT_PBAP_FOLDER_PHONE_BOOK 

Request for address book

BT_PBAP_FOLDER_INCOMING 

Request for incoming calls

BT_PBAP_FOLDER_OUTGOING 

Request for outgoing calls

BT_PBAP_FOLDER_MISSED 

Request for missed calls

BT_PBAP_FOLDER_COMBINED 

Request for combined calls

Enumeration of phone book search fields.

Since :
3.0
Enumerator:
BT_PBAP_SEARCH_NAME 

Request for search by name (default)

BT_PBAP_SEARCH_NUMBER 

Request for search by phone number

BT_PBAP_SEARCH_SOUND 

Request for search by sound

Enumeration of sorting orders.

Since :
3.0
Enumerator:
BT_PBAP_ORDER_INDEXED 

Filter order indexed (default)

BT_PBAP_ORDER_ALPHANUMERIC 

Filter order alphanumeric

BT_PBAP_ORDER_PHONETIC 

Filter order phonetic

Enumeration of vCard Formats.

Since :
3.0
Enumerator:
BT_PBAP_VCARD_FORMAT_VCARD21 

vCard format 2.1 (default)

BT_PBAP_VCARD_FORMAT_VCARD30 

vCard format 3.0


Function Documentation

int bt_pbap_client_connect ( const char *  address)

Connects to PBAP server, asynchronously.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]addressThe other device's address
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDAdapter is not enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
The PBAP client must be initialized with bt_pbap_client_initialize().
The local device must be bonded with the remote device by bt_device_create_bond().
Postcondition:
bt_pbap_connection_state_changed_cb() will be invoked.
See also:
bt_pbap_client_disconnect()
bt_pbap_client_set_connection_state_changed_cb()

Deinitializes the Bluetooth PBAP Client.

This deinitialization must be done to free resources when the PBAP client is not longer needed.

Since :
3.0
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED. The PBAP client must be initialized with bt_pbap_client_initialize().
See also:
bt_pbap_client_deinitialize()
bt_pbap_client_connect()
bt_pbap_client_disconnect()
bt_pbap_client_get_phone_book_size()
bt_pbap_client_get_phone_book()
bt_pbap_client_get_list()
bt_pbap_client_pull_vcard()
bt_pbap_client_search_phone_book()
int bt_pbap_client_disconnect ( const char *  address)

Disconnects from PBAP server, asynchronously.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]addressThe other device's address
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDAdapter is not enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
The PBAP client must be initialized with bt_pbap_client_initialize().
PBAP connection must be created with bt_pbap_client_connect().
Postcondition:
bt_pbap_connection_state_changed_cb() will be invoked.
See also:
bt_pbap_client_connect()
bt_pbap_client_set_connection_state_changed_cb()
int bt_pbap_client_get_list ( const char *  address,
bt_pbap_address_book_source_e  source,
bt_pbap_folder_type_e  folder_type,
bt_pbap_sort_order_e  order,
unsigned short  offset,
unsigned short  max_list_count,
bt_pbap_list_vcards_cb  callback,
void *  user_data 
)

Gets contact and call log information from the PBAP server, asynchronously.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]addressThe other device's address
[in]sourceSource of phone book (Phone/SIM)
[in]folder_typeType of folder
[in]orderSpecifies which field shall be used to sort vCards.
[in]offsetvCards to be excluded from beginning.
[in]max_list_countMaximum number of vCards to be fetched
[in]callbackThe callback function called when PBAP List is returned.
[in]user_dataData to be passed to the PBAP phone book pulling callback.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDAdapter is not enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
The PBAP client must be initialized with bt_pbap_client_initialize().
PBAP connection must be created with bt_pbap_client_connect().
See also:
bt_pbap_client_connect()
int bt_pbap_client_get_phone_book ( const char *  address,
bt_pbap_address_book_source_e  source,
bt_pbap_folder_type_e  folder_type,
bt_pbap_vcard_format_e  format,
bt_pbap_sort_order_e  order,
unsigned short  offset,
unsigned short  max_list_count,
unsigned int  fields,
bt_pbap_phone_book_received_cb  callback,
void *  user_data 
)

Gets all contacts and call logs as vCard from PBAP server, asynchronously.

The received phone book file will be saved in the platform downloads folder.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth http://tizen.org/privilege/mediastorage
Parameters:
[in]addressThe other device's address
[in]sourceSource of phone book (Phone/SIM)
[in]folder_typeType of folder
[in]formatThe vCard format
[in]orderSpecifies which field shall be used to sort vCards.
[in]offsetThe number of vCards to be excluded, counting from the beginning
[in]max_list_countThe maximum number of vCards to be fetched
[in]fieldsvCard fields to be fetched; one or more bt_pbap_field_e values combined with bitwise 'or'
[in]callbackThe callback function called when PBAP phone book is Pulled.
[in]user_dataData to be passed to the PBAP phone book pulling callback.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDAdapter is not enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
The PBAP client must be initialized with bt_pbap_client_initialize().
PBAP connection must be created with bt_pbap_client_connect().
See also:
bt_pbap_client_connect()
int bt_pbap_client_get_phone_book_size ( const char *  address,
bt_pbap_address_book_source_e  source,
bt_pbap_folder_type_e  folder_type,
bt_pbap_phone_book_size_cb  callback,
void *  user_data 
)

Gets size of phone book from PBAP server, asynchronously.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]addressThe other device's address
[in]sourceSource of the phone book (Phone/SIM)
[in]folder_typeType of folder
[in]callbackThe callback function called when PBAP phone book size is returned.
[in]user_dataData to be passed to the PBAP phone book size callback.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDAdapter is not enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
The PBAP client must be initialized with bt_pbap_client_initialize().
PBAP connection must be created with bt_pbap_client_connect().
See also:
bt_pbap_client_connect()
int bt_pbap_client_initialize ( void  )

Initializes the Bluetooth PBAP Client.

This initialization is necessary to call other PBAP client APIs.

Since :
3.0
Remarks:
This function must be called to initialize Bluetooth PBAP client. You must free all resources of the Bluetooth service by calling bt_pbap_client_deinitialize() if Bluetooth PBAP Client is no longer needed.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
See also:
bt_pbap_client_deinitialize()
bt_pbap_client_connect()
bt_pbap_client_disconnect()
bt_pbap_client_get_phone_book_size()
bt_pbap_client_get_phone_book()
bt_pbap_client_get_list()
bt_pbap_client_pull_vcard()
bt_pbap_client_search_phone_book()
int bt_pbap_client_pull_vcard ( const char *  address,
bt_pbap_address_book_source_e  source,
bt_pbap_folder_type_e  folder_type,
int  index,
bt_pbap_vcard_format_e  format,
unsigned int  fields,
bt_pbap_phone_book_received_cb  callback,
void *  user_data 
)

Gets the selected contact using the index parameter as vCard from PBAP server, asynchronously.

The received phone book file will be saved in the platform downloads folder. The index value should be equal to the value of the index field in the bt_pbap_vcard_info_s structure, which can be obtained with bt_pbap_client_get_list() or bt_pbap_client_search_phone_book().

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth http://tizen.org/privilege/mediastorage
Parameters:
[in]addressThe other device's address
[in]sourceSource of phone book (Phone/SIM)
[in]folder_typeType of folder
[in]indexThe handle index of vCard to be fetched
[in]formatFormat of vCard
[in]fieldsvCard fields to be fetched; one or more bt_pbap_field_e values combined with bitwise 'or'
[in]callbackThe callback function called when PBAP phone book is Pulled.
[in]user_dataData to be passed to the PBAP phone book Pulling callback.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDAdapter is not enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
The PBAP client must be initialized with bt_pbap_client_initialize().
PBAP connection must be created with bt_pbap_client_connect().
The vCard information (bt_pbap_vcard_info_s) must be obtained with bt_pbap_client_get_list() or bt_pbap_client_search_phone_book().
See also:
bt_pbap_client_connect()
bt_pbap_client_get_list()
bt_pbap_client_search_phone_book()
int bt_pbap_client_search_phone_book ( const char *  address,
bt_pbap_address_book_source_e  source,
bt_pbap_folder_type_e  folder_type,
bt_pbap_search_field_e  search_attribute,
const char *  search_value,
bt_pbap_sort_order_e  order,
unsigned short  offset,
unsigned short  max_list_count,
bt_pbap_list_vcards_cb  callback,
void *  user_data 
)

Finds and fetches the contact and call log information from the PBAP server, asynchronously.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]addressThe other device's address
[in]sourceSource of phone book (Phone/SIM)
[in]folder_typeType of folder
[in]search_attributefield to be search
[in]search_valuepattern to be searched for
[in]orderSpecifies which field shall be used to sort vCards.
[in]offsetvCards to be excluded from beginning.
[in]max_list_countMaximum number of vCards to be fetched
[in]callbackThe callback function called when PBAP List is returned.
[in]user_dataData to be passed to the PBAP phone book pulling callback.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDAdapter is not enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state of the local Bluetooth adapter must be BT_ADAPTER_ENABLED.
The PBAP client must be initialized with bt_pbap_client_initialize().
PBAP connection must be created with bt_pbap_client_connect().
See also:
bt_pbap_client_connect()

Registers a callback function that will be invoked when the connection state is changed.

Since :
3.0
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The PBAP client must be initialized with bt_pbap_client_initialize().
See also:
bt_pbap_client_initialize()

Unregisters a callback function that will be invoked when the connection state is changed.

Since :
3.0
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The PBAP client must be initialized with bt_pbap_client_initialize().
See also:
bt_pbap_client_initialize()