API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

IBTSECURITY

Brew Release
Brew MP 1.0.2
Description

Bluetooth Security management interface
This interface provides methods to configure Bluetooth Security settings. It provides a mechanism for clients of this interface to set the device in different modes.
This interface supports The Bluetooth Secure Simple Pairing feature in the Bluetooth 2.1+EDR specification.The same interface also allows for legacy security procedures, and depending on the supported features of the underlying driver and remote device, SSP or Legacy procedures to be used will be determined automatically.
In order to set the IO Capability of the device, IBTSecurity_SetIOCapability() API should be used. Based on the IO Capability of local device and that of the remote device, the associatation model to be used will be will be determined.
The interface provides APIs to intiate the Bonding procedure to a remote device and intiate the Unbond operation with an already bonded device.
The Bondable state of the device (allow or disallow incoming bond request) can be controlled using IBTSecurity_SetBondable() API.
The interface provides APIs to set the security level for a given service and retrieve the security level for a given service.Service can be specified based on L2CAP PSM, RFCOMM SCN, Protocol UUID or Service Class UUID.
The interface also provides an API to get a reference to the security Handler object. The security handler interface provides for mechanisms to respond to the all security procedure events such as user confirmation request, pass key request etc.
Usage

Usage example:



   ===== To create an IBTSecurity object, see instruction in class header file
  
   ===== To register signal with IBTSecurity to get notified whenever
         Bond status changes
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IBTSecurity_OnbondStatusChange (piBTSecurity, piSignal);
   
   ===== To set/clear bondable state of Bluetooth driver
   IBTSecurity_SetBondable (piBTSecurity,
                            TRUE, // Bondable 
                            TRUE) // MITM Protection required for incomming requests
   or
   IBTSecurity_SetBondable (piBTSecurity, FALSE, FALSE) // FALSE: Not Bondable 

   ===== To bond with a remote Bluetooth device
   IBTSecurity_Bond (piBTSecurity,
                    &BDAddr, // BDAddr:remote Bd address
                    TRUE);  // Man in the middle protection required.
   ===== To unbond from an existing bonded device
   IBTSecurity_UnBond (piBTSecurity, &BDAddr) // BDAddr:remote Bd address

   ===== To Cancel the ongoing bonding operation
   IBTSecurity_CancelBond (piBTSecurity, &BDAddr) // BDAddr:remote Bd address

                       
   ===== To set IO Capability of the device
   IBTSecurity_SetIOCapability (piBTSecurity,
                               &AEEBTSEC_IOC_DISPLAY_YESNO);
                        
   ===== To set service level security for a service based on PSM
   BTServiceIdentifier1 svcSecIdent;
   secIdent.dIDMethod = AEEBT_SEC_BY_L2CAP_PSM;
   secIdent.uPsm = 0x03; // RFCOMM PSM
   
   IBTSecurity_SetSvcSecurity (piBTSecurity,
                              &svcSecIdent,// service security identifier
                              AEEBT_SEC_HIGH, // Security level
                              TRUE ); // notify app of incomming connection request
                       
   ===== To set service level security for a service based on service UUID
   BTServiceIdentifier1 svcSecIdent;
   secIdent.dIDMethod = AEEBT_SEC_BY_SERVICE_CLASS;
   secIdent.dSvcCls = AEEBT_SCU_HANDSFREE_AUDIO_GATEWAY; // Audio gateway UUID
   
   IBTSecurity_SetSvcSecurity (piBTSecurity,
                              &svcSecIdent,// service security identifier
                              AEEBT_SEC_HIGH, // Security level
                              TRUE ); // notify app of incomming connection request
                          
   ===== To retrieve current security level for a service
   IBTSecurity_GetSvcSecurity (piBTSecurity,
                              &svcSecIdent,   // service security identifier for the service
                              &sec_level,     // Security Level 
                              &bAuthorize);   //Authorization required...? 

   ===== To register a signal to get notified when Security Handler Object is available
      // first create the signals;
      // for example, use ISignalCBFactory_CreateSignal()
      // then register the signals:
   IBTSecurity_OnSecurityHandler(piBTSecurity, piSignal);
  
   ===== To retrieve security handler interface object
   IBTSecurity_GetSecurityHandler(piBTSecurity, 
                                &pIBTSecurityHandler); // Address of IBTSecurityHandler
                                                         interface pointer.
                              

                               
   ===== To retrieve last Bond/Unbond status
   AEEBTSecEvent eventData; 
   IBTSecurity_GetbondStatus(piBTSecurity, &eventData);

   switch( eventData.event )
   {
       case AEEBTSEC_EV_BOND_DONE:
       // Bond operation is complete. eventData.bdAddr has the BD Address of remote device
       // eventData.cResult has the status of the Bond operation.
       break;
   
       case AEEBTSEC_EV_UNBOND_DONE:
       // UnBond operation is complete. eventData.bdAddr has the BD Address of remote device
       // eventData.cResult has the status of the UnBond operation.
       break;

       case AEEBTSEC_EV_UNBOND_NONE:
       // No status available.
       break;
   }
   ISignalCtl_Enable (piSignalCtl); // re-enable signal

   ===== When done with IBTSecurity object:
   IBTSecurity_Release (piBTSecurity);