Developer

API Reference

IBTPBAPClient

Brew Release
Brew MP 1.0.2
Description

Bluetooth Phone Book Access Profile, client role (PCE)
This interface enables the client role(PCE) of Phone Book Access as defined by the Bluetooth SIG.
Once the PBAP client object is created,PBAP client can connect to PBAP servers (PSE).To connect to a PBAP server, PBAP client application needs to provide the Bluetooth address of the server. It can also specify the server channel number(SCN) to use to establish connection. If application provides server channel number as 0, the stack will do SDP query to obtain SCN.
If application wants to enforce service level security for the connection it should call SetSecurity API with a minimum security level to be enforced. This API should be called before initiating the connection. The minimum security level required by PBAP is AEEBT_SEC_AUTHENTICATE. Default security level is AEEBT_SEC_AUTHENTICATE
If PBAP client application wants to OBEX authenticate the server before connection, application should send authentication request before a connection could be set up using IOBEXAuthentication interface.Please refer to IOBEXAuthentication Interface documentation for more information on IOBEXAuthentication APIs
Once a connection is set up, client can send Phonebook download request, vCard listing request or Pull vCard request.
Usage

Usage example:



   ===== To create an IBTPBAPClient object, see instruction in class header file

    ===== To register signal
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IBTPBAPClient_OnEventNotify (piBTPBAPCli, piSignal);

   ===== To set service level security
   IBTPBAPClient_SetSecurity (piBTPBAPCli,
                              AEEBT_SEC_AUTHENTICATE );

   ===== To get an IOBEXAuthentication object
   IBTPBAPClient_QueryInterface(piBTPBAPCli,
                                AEEIID_IOBEXAuthentication,
                                void**)&piAuth);                   

   ===== To Register for OBEX Authentication Requests from server
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IOBEXAuthentication_OnRequest(piAuth, pSigAuthReq);

   ===== To handle the OBEX Authentication requests from server
   ISignalCtl_Enable (pSigAuthReq);
   // Get Password and Uid(if required) from user
   IOBEXAuthentication_Authenticate(piAuth,
                                NULL,                // Uid
                                0,                   // Uid len
                                (uint8 *)szPasswd,   //Password
                                STRLEN(szUserData)   // password len 
                                );
   
   ===== To Configure OBEX Authentication related parameters 
   // This should be  used to set up authentication data that will
   // be sent to server prior to, or together with next operation (usually connection
   //  request)
    IOBEXAuthentication_Config( piAuth,
                          MIBENUM_CHARSET_US_ASCII, // character set for realm str
                          NULL,                     // Realm str
                          0,                        // realm str len len
                          FALSE,                    //UID is should not be used  
                          TRUE,                     // Full access
                          FALSE                     // This config data should NOT be considered invalid
                                                    // after one operation  
                         );

   ===== To Register for OBEX authenticate response from server
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IOBEXAuthentication_OnResponse(piAuth, pSigAuthResp);

   ===== To handle the OBEX Authentication response from server
   ISignalCtl_Enable (pSigAuthResp);
   // Get Password and Uid(if required) from user
   IOBEXAuthentication_Authenticate(piAuth,
                                NULL,              // Uid
                                0,                 // Uid len
                                (uint8 *)szPasswd, //Password
                                STRLEN(szUserData) // password len 
                                );

   ===== To connect to a  PBAP server (PSE)
   IBTPBAPClient_Connect (piBTPBAPCli, bdAddrOfSrv, 0 );

   ===== To get the number of used entries in the phonebook directory
   IBTPBAPClient_PullPhoneBookSize (piBTPBAPCli, AEEBTPBAP_OBJECT_LOCAL_PB,"" );

   ===== To Pull Phonebook object 
   IBTPBAPClient_PullPhoneBook(
                piBTPBAPCli,
                AEEBTPBAP_OBJECT_LOCAL_PB, // Phone phone book to retrieve
                AEEBT_PBAP_ATTRIBUTE_N | AEEBT_PBAP_ATTRIBUTE_TEL,// return name and Tel no 
                AEEBT_OBEX_FORMAT_VCARD_2_1, // return in vCard 2.1 format
                200,  // return max 200 entries.
                0,    // offset of the Phonebook Object at PSE to start with .
                NULL, // Not a user defined folder
                );

   ===== To Pull vCard Listing 
   IBTPBAPClient_PullVCardListing (
                     piBTPBAPCli, 
                     AEEBTPBAP_OBJECT_LOCAL_PB,// Phone book to retrieve vCard listing  
                     AEEBTPBAP_SORT_ORDER_ALPHANUMERIC, //sort order
                     AEEBTPBAP_SEARCH_ATTRIBUTE_NAME, // search attribute
                     "",    // search string. empty string means no specific search value, 
                     200,  // return max 200 entries. 
                     0     // offset of the Phonebook Object at PSE to start with .
                     "",   // Not a user defined folder
                     );

   ===== To Pull vCard
   IBTPBAPClient_PullVCardEntry ( 
                         piBTPBAPCli,
                         AEEBTPBAP_OBJECT_LOCAL_PB,
                         "2.vcf", 
                         AEEBT_PBAP_ATTRIBUTE_N | AEEBT_PBAP_ATTRIBUTE_TEL,// return name and Tel no
                         AEEBT_OBEX_FORMAT_VCARD_3_0, // return in vCard 3.0 format
                        );
   ===== To Abort an ongoing operation 
   IBTPBAPClient_Abort(piBTPBAPCli);

   ===== To retrieve and handle events when Event signal is triggered:

   while( IBTPBAPClient_GetEvent (piBTPBAPCli, &eventData) != AEE_ENOMORE )
   {
     switch( eventData.event )
     {
       case AEEBTPBAPCLI_EV_CONNECTED:   
       case AEEBTPBAPCLI_EV_DISCONNECTED:             
       case AEEBTPBAPCLI_EV_CONN_FAILED:              
         //eventData.bdAddr will have the BD address of the remote PSE.
         break;

       case AEEBTPBAPCLI_EV_PB_SIZE_PULL_DONE:
         // eventData.cResult has the status of the operation
         // If sucess eventData.nNumEntries has the number of phonebook entries 

       case AEEBTPBAPCLI_EV_PHONEBOOK_PULL_DONE: 
         //eventData. cResult has the status of the operation
         //If success invoke the following API to retrieve Phonebook data
         IBTPBAPClient_RetrievePhoneBook(piBTPBAPCli,
                                         &PbObject,        // place holder for Phonebook object 
                                         PbObjectLen,      // size of the buffer
                                         &PbObjectLenReq,  // placeholder to fill the size of actual data copied to 
                                                           // PbObject 
                                         &nNewMissedCalls);// Number of unchecked missed calls. Valid only
                                                           // if requested objct was AEEBTPBAP_OBJECT_LOCAL_MCH or
                                                           // AEEBTPBAP_OBJECT_SIM_MCH
                                       
                                                    
         break;
         
       case AEEBTPBAPCLI_EV_VCARD_LISTING_DONE:
         //eventData.cResult has the status of the operation
         //If success invoke the following API to retrieve vCard listing
         IBTPBAPClient_RetrieveVCardListing(piBTPBAPCli,
                                            &vCardListObject,      // place holder for vCard listing object
                                            vCardListObjectLen,    // Size of the buffer         
                                            &vCardListObjectLenReq,// placeholder to fill the size of actual data copied to 
                                                                   // vCardListObject 
                                            &nNewMissedCalls);     // Number of unchecked missed calls. Valid only
                                                                  // if requested vCard listing object was
                                                                  // AEEBTPBAP_OBJECT_LOCAL_MCH or
                                                                  // AEEBTPBAP_OBJECT_SIM_MCH
                                                                        

         break;
         
       case AEEBTPBAPCLI_EV_VCARD_PULL_DONE:
         //eventData. cResult has the status of the operation
         //If success invoke the following API to retrieve vCard
         IBTPBAPClient_RetrieveVCardEntry  ( piBTPBAPCli, 
                                             &vCardObject,       // place holder for vCard  object
                                             vCardObjectLen,     // Size of the buffer         
                                             &vCardObjectLenReq);// placeholder to fill the size of actual data copied to 
                                                                 // vCardObject

         break;  

       case AEEBTPBAPCLI_EV_OP_ABORTED:
         // Operation under progress is aborted
         // eventData.cResult has the status of the abort operation
         break;

       case AEEBTPBAPCLI_EV_PHONEBOOK_PULL_PROGRESS:
         // eventData.nBytes has number of bytes so far received
         // Application can invoke IBTPBAPClient_RetrievePhoneBook to retrieve
         // partial data
         IBTPBAPClient_RetrievePhoneBook(piBTPBAPCli,
                                       &PbObject,        // place holder for Phonebook object 
                                       PbObjectLen,      // size of the buffer
                                       &PbObjectLenReq,  // placeholder to fill the size of actual data copied to 
                                                         // PbObject 
                                       &nNewMissedCalls);// Number of unchecked missed calls. Valid only
                                                         // if requested objct was AEEBTPBAP_OBJECT_LOCAL_MCH or
                                                         // AEEBTPBAP_OBJECT_SIM_MCH
                                       
         break;
         
      case AEEBTPBAPCLI_EV_VCARD_LISTING_PROGRESS:
         // eventData.nBytes has number of bytes so far received
         // Application can invoke IBTPBAPClient_RetrieveVCardListing to retrieve
         // partial data
         IBTPBAPClient_RetrieveVCardListing(piBTPBAPCli,
                                            &vCardListObject,      // place holder for vCard listing object
                                            vCardListObjectLen,    // Size of the buffer         
                                            &vCardListObjectLenReq,// placeholder to fill the size of actual data copied to 
                                                                   // vCardListObject 
                                            &nNewMissedCalls);     // Number of unchecked missed calls. Valid only
                                                                   // if requested vCard listing object was
                                                                   // AEEBTPBAP_OBJECT_LOCAL_MCH or
                                                                   // AEEBTPBAP_OBJECT_SIM_MCH
                              

         break;
         
       case AEEBTPBAPCLI_EV_VCARD_PULL_PROGRESS:
         // eventData.nBytes has number of bytes so far received
         // Application can invoke IBTPBAPClient_RetrieveVCardEntry to retrieve
         // partial data
         IBTPBAPClient_RetrieveVCardEntry   (piBTPBAPCli,  
                                             &vCardObject,       // place holder for vCard  object
                                             vCardObjectLen      // Size of the buffer         
                                             &vCardObjectLenReq);// placeholder to fill the size of actual data copied to 
                                                                 // vCardObject 
                  

         break;    
       case AEEBTPBAPCLI_EV_BUFFER_FULL:
         // Buffer used for current operation is Full. When this event is received 
         // application MUST read the data to continue with any other operation except Abort or Disconnect.
         // eventData.nBytes has the number of bytes currently pending to be read by application
         // Invoke IBTPBAPClient_RetrieveVCardListing() or 
         // IBTPBAPClient_RetrieveVCardListing() or
         // IBTPBAPClient_RetrievePhoneBook () APIs to read the buffer based on the current operation

       case AEEBTPBAPCLI_EV_EVENT_Q_OVERFLOW:
         // eventData.nDroppedEvents tells how many events got dropped
         // since previous GetEvent()
         break;
     }
     ISignalCtl_Enable (piSignalCtl); // re-enable signal
   }
   ===== When done with PBAP client:
   IBTPBAPCli_Disconnect (piBTPBAPCli);
   IBTPBAPCli_Release (piBTPBAPCli);
   
   
  • Follow