PBAP

The Phonebook Access Profile (PBAP) defines the protocols and procedures to exchange phonebook objects between two peer devices. More...

Overview

The Phonebook Access Profile (PBAP) defines the protocols and procedures to exchange phonebook objects between two peer devices.

PBAP client (PBAPC) is implemented for the client side connection according to the PBAP specification. It can initiate a connection to a remote device. The API provides the following functionalities, such as get the number of phonebook objects, get the phonebook objects, get the caller's name by the phone number and more. Note: It only supports access to phonebook objects storaged in Phone, not support in SIM.

How to use this module

• PBAPC connection with the server in open mode, as shown in the figure titled as "PBAPC connection establishment without authentication message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step1: Mandatory, call the function bt_pbapc_connect() to initiate a connection to a remote server.
    • Sample code:

      ret = bt_pbapc_connect(&handle, &address);

  • Step2: bt_app_event_callback() is triggered by BT_PBAPC_CONNECT_CNF event, if the connection is established.
    • Sample code:

      bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
      {
          switch (msg)
          {
              case BT_PBAPC_CONNECT_CNF:
              {
                  bt_pbapc_connect_cnf_t *data = (bt_pbapc_connect_cnf_t*)buff;
                  // Check the connection result and save conn_id if the connection is successful.
                  break;
              }
          }
      }

• Get the number of phonebook objects, as shown in the figure titled as "Get the number of phonebook objects message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step1: Mandatory, call the function bt_pbapc_get_num_of_phonebook_objects() to get the number of phonebook objects of type is Missed Calls History or Main Phonebook from a remote device.
    • Sample code:

      ret = bt_pbapc_get_num_of_phonebook_objects(handle, type);

  • Step2: bt_app_event_callback() is triggered by the BT_PBAPC_GET_NUMBER_OF_PHOENBOOK_OBJECTS_IND event, if there is data received from a remote device.
  • Step3: bt_app_event_callback() is triggered by the BT_PBAPC_GET_NUMBER_OF_PHOENBOOK_OBJECTS_CNF event, as a result of a call to the function bt_pbapc_get_num_of_phonebook_objects().
    • Sample code:

      bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
      {
          switch (event_id)
          {
               case BT_PBAPC_GET_NUMBER_OF_PHOENBOOK_OBJECTS_IND:
               {
                   bt_pbapc_get_num_of_phonebook_objects_ind_t *ind = (bt_pbapc_get_num_of_phonebook_objects_ind_t *)buff;
                    // Show the number of phonebook objects.
                   break;
               }
               case BT_PBAPC_GET_NUMBER_OF_PHOENBOOK_OBJECTS_CNF:
               {
                   bt_pbapc_get_num_of_phonebook_objects_cnf_t *cnf = (bt_pbapc_get_num_of_phonebook_objects_cnf_t *)buff;
                   // Check the response.
                   break;
               }
          }
      }

• Get data. Provides two methods, download and browsing.
  • Download. Get the data using PullPhonebook function, as shown in the figure titled as "PBAPC Get phonebook object message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
    • Step1: Optional, call bt_pbapc_get_phonebook_objects() to retrieve the phonebook objects of type Missed Calls History or Main Phonebook from a remote device.
      • Sample code:

        ret = bt_pbapc_get_phonebook_objects(handle, offset,  type);

    • Step2: bt_app_event_callback() is triggered by the BT_PBAPC_GET_PHOENBOOK_OBJECTS_IND event, if there is data received from a remote device.
    • Step3: bt_app_event_callback() is triggered by the BT_PBAPC_GET_PHONEBOOK_OBJECTS_CNF event, as a result of a call to the function bt_pbapc_get_phonebook_objects().
      • Sample code:

        bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
        {
            switch (event_id)
            {
                 case BT_PBAPC_GET_PHOENBOOK_OBJECTS_IND:
                 {
                     bt_pbapc_get_phonebook_objects_ind_t *ind = (bt_pbapc_get_phonebook_objects_ind_t *)buff;
                      // Show the name and number of phonebook objects.
                     break;
                 }
                 case BT_PBAPC_GET_PHONEBOOK_OBJECTS_CNF:
                 {
                     bt_pbapc_get_phonebook_objects_cnf_t *cnf = (bt_pbapc_get_phonebook_objects_cnf_t *)buff;
                     // Check the response.
                     break;
                 }
            }
        }

  • Browsing. Get the data using PullvCardlisting function, as shown in the figure titled as "PBAPC get caller name by number message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
    • Step1: Optional, call bt_pbapc_get_caller_name_by_number() to retrieve contact name of phonebook objects stored in the phone from a remote device.
      • Sample code:

        ret = bt_pbapc_get_caller_name_by_number(handle, number);

    • Step2: bt_app_event_callback() is triggered by the BT_PBAPC_GET_CALLER_NAME_IND event, if there is data received from a remote device.
    • Step3: bt_app_event_callback() is triggered by the BT_PBAPC_GET_CALLER_NAME_CNF event, as a result of a call to the function bt_pbapc_get_caller_name_by_number().
      • Sample code:

        bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
        {
            switch (event_id)
            {
                case BT_PBAPC_GET_CALLER_NAME_IND:
                {
                    bt_pbapc_get_caller_name_ind_t *ind = (bt_pbapc_get_caller_name_ind_t *)buff;
                    // Show  the contact name of phonebook objects.
                    break;
                }
                case BT_PBAPC_GET_CALLER_NAME_CNF:
                {
                    bt_pbapc_get_caller_name_cnf_t *cnf = (bt_pbapc_get_caller_name_cnf_t *)buff;
                    // Check the response.
                    break;
                }
            }
        }

• Pull the specific vCard, as shown in the figure titled as "PBAPC PullvCardEnty message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step1: Optional, call bt_pbapc_pull_vcard_entry() to retrieve the specific phonebook objects stored in the phone from a remote device.
    • Sample code:

      ret = bt_pbapc_pull_vcard_entry(handle,  index);

  • Step2: bt_app_event_callback() is triggered by the BT_PBAPC_GET_PHOENBOOK_OBJECTS_IND event, if there is data received from a remote device.
  • Step3: bt_app_event_callback() is triggered by the BT_PBAPC_GET_PHONEBOOK_OBJECTS_CNF event, as a result of a call to the function bt_pbapc_pull_vcard_entry().
    • Sample code:

      bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
      {
          switch (event_id)
          {
               case BT_PBAPC_GET_PHOENBOOK_OBJECTS_IND:
               {
                    bt_pbapc_get_phonebook_objects_ind_t *ind = (bt_pbapc_get_phonebook_objects_ind_t *)buff;
                     // Show the name and number of phonebook objects.
                    break;
               }
               case BT_PBAPC_GET_PHONEBOOK_OBJECTS_CNF:
               {
                   bt_pbapc_get_phonebook_objects_cnf_t *cnf = (bt_pbapc_get_phonebook_objects_cnf_t *)buff;
                   // Check the response.
                   break;
               }
          }
      }

• Disconnect PBAPC connection. Close the PBAPC connection, as shown in the figure titled as "Disconnect message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  • Step1: Call bt_pbapc_disconnect() to disconnect the PBAPC connection from a remote device.
    • Sample code:

      ret = bt_pbapc_disconnect(handle);

  • Step2: bt_app_event_callback() is triggered by the BT_PBAPC_DISCONNECT_IND event to indicate the result of the disconnection.
    • Sample code:

      bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
      {
          switch (msg)
          {
              case BT_PBAPC_DISCONNECT_IND:
              {
                  bt_pbapc_disconnect_ind_t *ind = (bt_pbapc_disconnect_ind_t *)buff;
                  if (status == BT_STATUS_SUCCESS) {
                      // The PBAPC has disconnected.
                  }
                  break;
              }
          }
      }

Functions
bt_status_t	bt_pbapc_connect (uint32_t *handle, const bt_bd_addr_t *address)
	This function connects to the specified remote device. More...
bt_status_t	bt_pbapc_get_num_of_phonebook_objects (uint32_t handle, bt_pbapc_phonebook_type_t type)
	This function gets the number of phonebook objects of type Missed Calls History or Main Phonebook of the specified remote device. More...
bt_status_t	bt_pbapc_get_phonebook_objects (uint32_t handle, uint16_t offset, bt_pbapc_phonebook_type_t type)
	This function gets the phonebook objects of type Missed Calls History or Main Phone Book of the specified remote device. More...
bt_status_t	bt_pbapc_get_caller_name_by_number (uint32_t handle, uint8_t *number)
	This function gets the contact name of a phonebook object stored in the phonebook of the remote device. More...
bt_status_t	bt_pbapc_pull_vcard_entry (uint32_t handle, uint8_t index)
	This function pulls a specific vCard object from the specified remote device. More...
bt_status_t	bt_pbapc_disconnect (uint32_t handle)
	This function disconnects from the specified remote device. More...

Modules
	Define
	Struct

Function Documentation

bt_status_t bt_pbapc_connect	(	uint32_t *	handle,
		const bt_bd_addr_t *	address
	)

This function connects to the specified remote device.

BT_PBAPC_CONNECT_CNF event is sent to the upper layer with the connection result.

Parameters

[out]	handle	is the identifier of the remote device.
[in]	address	is the Bluetooth address of the remote device.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_pbapc_disconnect

(

uint32_t

handle

)

This function disconnects from the specified remote device.

BT_PBAPC_DISCONNECT_IND event is sent to the upper layer with the result of the disconnection.

Parameters

[in]

handle

is the identifier of the remote device.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_pbapc_get_caller_name_by_number	(	uint32_t	handle,
		uint8_t *	number
	)

This function gets the contact name of a phonebook object stored in the phonebook of the remote device.

The BT_PBAPC_GET_CALLER_NAME_IND and BT_PBAPC_GET_CALLER_NAME_CNF events are sent to the upper layer with the connection result.

Parameters

[in]	handle	is the identifier of the remote device.
[in]	number	is the telephone number, if it is null, the result is the number of phonebook objects stored in the phone.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_pbapc_get_num_of_phonebook_objects	(	uint32_t	handle,
		bt_pbapc_phonebook_type_t	type
	)

This function gets the number of phonebook objects of type Missed Calls History or Main Phonebook of the specified remote device.

The BT_PBAPC_GET_NUMBER_OF_PHOENBOOK_OBJECTS_IND & BT_PBAPC_GET_NUMBER_OF_PHOENBOOK_OBJECTS_CNF event is sent to the upper layer with the connection result.

Parameters

[in]	handle	is the identifier of the remote device.
[in]	type	is the type of phonebook objects.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_pbapc_get_phonebook_objects	(	uint32_t	handle,
		uint16_t	offset,
		bt_pbapc_phonebook_type_t	type
	)

This function gets the phonebook objects of type Missed Calls History or Main Phone Book of the specified remote device.

BT_PBAPC_GET_PHOENBOOK_OBJECTS_IND and BT_PBAPC_GET_PHONEBOOK_OBJECTS_CNF events are sent to the upper layer with the connection result.

Parameters

[in]	handle	is the identifier of the remote device.
[in]	offset	is the start offset.
[in]	type	is the type of phonebook objects.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_pbapc_pull_vcard_entry	(	uint32_t	handle,
		uint8_t	index
	)

This function pulls a specific vCard object from the specified remote device.

The BT_PBAPC_GET_PHOENBOOK_OBJECTS_IND and BT_PBAPC_GET_PHONEBOOK_OBJECTS_CNF events are sent to the upper layer with the connection result.

Parameters

[in]	handle	is the identifier of the remote device.
[in]	index	is the index of phonebook objects.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.