TI BLE5-Stack API Documentation  3.02.01.00
Modules | Files | Functions
GAPBondMgr

Modules

 GAP Bond Manager Callbacks
 
 GAP Bond Manager Constants
 
 GAP Bond Manager Pairing State Events
 
 GAP Bond Manager Parameters
 
 GAP Bond Manager Structures
 

Files

file  gapbondmgr.h
 

Functions

bStatus_t GAPBondMgr_FindAddr (uint8_t *pDevAddr, GAP_Peer_Addr_Types_t addrType, uint8_t *pIdx, GAP_Peer_Addr_Types_t *pIdentityAddrType, uint8_t *pIdentityAddr)
 Search for an address in the bonding table. If the address is a random private resolvable address, attempt to resolve the random address against all IRK's in bonding table. As output parameters, return the following: More...
 
bStatus_t GAPBondMgr_GenerateEccKeys (void)
 Generates ECC keys. More...
 
bStatus_t GAPBondMgr_GetParameter (uint16_t param, void *pValue)
 
bStatus_t GAPBondMgr_Pair (uint16_t connHandle)
 
bStatus_t GAPBondMgr_PasscodeRsp (uint16_t connectionHandle, uint8_t status, uint32_t passcode)
 
void GAPBondMgr_Register (gapBondCBs_t *pCB)
 
bStatus_t GAPBondMgr_SCGetLocalOOBParameters (gapBondOOBData_t *localOobData)
 Get local Random number and confirm value for secure connection. More...
 
bStatus_t GAPBondMgr_SCSetRemoteOOBParameters (gapBondOOBData_t *remoteOobData, uint8 OOBDataFlag)
 Set remote's OOB parameters for secure connection. More...
 
bStatus_t GAPBondMgr_ServiceChangeInd (uint16_t connectionHandle, uint8_t setParam)
 
bStatus_t GAPBondMgr_SetParameter (uint16_t param, uint8_t len, void *pValue)
 
uint8_t gapBondMgrImportBond (gapBondRec_t *pBondRec, gapBondLTK_t *pLocalLtk, gapBondLTK_t *pDevLtk, uint8_t *pIRK, uint8_t *pSRK, uint32_t signCount, gapBondCharCfg_t *charCfg)
 Import bond record to NV. More...
 
uint8_t gapBondMgrReadBondRec (GAP_Peer_Addr_Types_t addrType, uint8_t *pDevAddr, gapBondRec_t *pBondRec, gapBondLTK_t *pLocalLtk, gapBondLTK_t *pDevLtk, uint8_t *pIRK, uint8_t *pSRK, uint32_t signCount, gapBondCharCfg_t *charCfg)
 Read bond record from NV. More...
 

Detailed Description

This module implements the GAP Bond Manager

Function Documentation

§ GAPBondMgr_FindAddr()

bStatus_t GAPBondMgr_FindAddr ( uint8_t *  pDevAddr,
GAP_Peer_Addr_Types_t  addrType,
uint8_t *  pIdx,
GAP_Peer_Addr_Types_t pIdentityAddrType,
uint8_t *  pIdentityAddr 
)

Search for an address in the bonding table. If the address is a random private resolvable address, attempt to resolve the random address against all IRK's in bonding table. As output parameters, return the following:

  • index into bonding table if the address (or resolved address) is found
  • identity address type if a resolved address was found. Only valid if the input address is random private resolvable
  • identity address if a resolved address was found. Only valid if the input address is random private resolvable

Note that the output parameters are optional. If it is not desired for them to be returned, a NULL pointer can safely be passed.

Parameters
pDevAddrpeer's address
addrTypepeer's address type
pIdxpointer to byte to put the bond index if found
pIdentityAddrTypepointer to byte to put the identity address type if applicable
pIdentityAddrpointer to buffer to put the identity address type if applicable
Returns
SUCCESS if the address was found or resolved to an address in the bonding table
INVALIDPARAMETER if a NULL address is passed in
bleGAPNotFound if the address was not found and didn't resolve to any addresses in the bonding table

§ GAPBondMgr_GenerateEccKeys()

bStatus_t GAPBondMgr_GenerateEccKeys ( void  )

Generates ECC keys.

/ref did_244389729

Returns
SUCCESS - if processing. FAILURE - if SM is pairing

§ GAPBondMgr_GetParameter()

bStatus_t GAPBondMgr_GetParameter ( uint16_t  param,
void *  pValue 
)

Get a GAP Bond Manager parameter.

Note
The "pValue" field must point to a "uint16_t".
Parameters
paramProfile parameter ID: GAP Bond Manager Parameters
pValuepointer to location to get the value. This is dependent on the parameter ID and WILL be cast to the appropriate data type (example: data type of uint16_t will be cast to uint16_t pointer).
Returns
SUCCESS
INVALIDPARAMETER

§ GAPBondMgr_Pair()

bStatus_t GAPBondMgr_Pair ( uint16_t  connHandle)

Start (or re-start) the pairing process

This API can be used to initiate pairing in cases where it is not started automatically by the gapbondmgr or to re-pair after the initial pairing has occurred if, for example, the pairing requirements have changed.

Note
Pairing will occur automatically if GAPBOND_PAIRING_MODE is set to GAPBOND_PAIRING_MODE_INITIATE or GAPBOND_PAIRING_MODE is set to GAPBOND_PAIRING_MODE_WAIT_FOR_REQ and a pairing request is received. In these cases, this API is not needed and will fail since pairing is already in progress.
Parameters
connHandleconnection handle to initiate pairing with
Returns
SUCCESS
bleAlreadyInRequestedMode already pairing

§ GAPBondMgr_PasscodeRsp()

bStatus_t GAPBondMgr_PasscodeRsp ( uint16_t  connectionHandle,
uint8_t  status,
uint32_t  passcode 
)

Respond to a passcode request.

Parameters
connectionHandleconnection handle of the connected device or 0xFFFF if all devices in database.
statusSUCCESS if passcode is available, otherwise see Pairing failure status values.
passcodeinteger value containing the passcode.
Returns
SUCCESS bond record found and changed,
bleIncorrectMode Link not found.
INVALIDPARAMETER : passcode is out of range
bleMemAllocError : heap is out of memory

§ GAPBondMgr_Register()

void GAPBondMgr_Register ( gapBondCBs_t pCB)

Register callback functions with the bond manager.

Parameters
pCBpointer to callback function structure.

§ GAPBondMgr_SCGetLocalOOBParameters()

bStatus_t GAPBondMgr_SCGetLocalOOBParameters ( gapBondOOBData_t *  localOobData)

Get local Random number and confirm value for secure connection.

/ref did_244389729

Parameters
localOobData- Struct holding local's random number and confirm value
Returns
SUCCESS - Finished successfully. FAILURE - One of the parameters returned FAILURE

§ GAPBondMgr_SCSetRemoteOOBParameters()

bStatus_t GAPBondMgr_SCSetRemoteOOBParameters ( gapBondOOBData_t *  remoteOobData,
uint8  OOBDataFlag 
)

Set remote's OOB parameters for secure connection.

/ref did_244389729

Parameters
remoteOobData- struct holding remote random number and confirm value
OOBDataFlag- 1 - OOB Authentication data from remote device present, else 0
Returns
SUCCESS - Finished successfully. FAILURE - If OOBDataFlag is set but remote's OOB parameters are not or if OOBDataFlag is not set but OOB parameters are set.

§ GAPBondMgr_ServiceChangeInd()

bStatus_t GAPBondMgr_ServiceChangeInd ( uint16_t  connectionHandle,
uint8_t  setParam 
)

Set/clear the service change indication in a bond record.

Parameters
connectionHandleconnection handle of the connected device or 0xFFFF if all devices in database.
setParamTRUE to set the service change indication, FALSE to clear it.
Returns
SUCCESS bond record found and changed,
bleNoResources bond record not found
bleNotConnected connection not found connectionHandle is invalid (for non-0xFFFF connectionHandle).

§ GAPBondMgr_SetParameter()

bStatus_t GAPBondMgr_SetParameter ( uint16_t  param,
uint8_t  len,
void *  pValue 
)

Set a GAP Bond Manager parameter.

Note
The "len" field must be set to the size of a "uint16_t" and the "pValue" field must point to a "uint16_t".
Parameters
paramGAP Bond Manager Parameters
lenlength of data to write
pValuepointer to data to write. This is dependent on the parameter ID and WILL be cast to the appropriate data type (example: data type of uint16_t will be cast to uint16_t pointer).
Returns
SUCCESS
INVALIDPARAMETER

§ gapBondMgrImportBond()

uint8_t gapBondMgrImportBond ( gapBondRec_t pBondRec,
gapBondLTK_t pLocalLtk,
gapBondLTK_t pDevLtk,
uint8_t *  pIRK,
uint8_t *  pSRK,
uint32_t  signCount,
gapBondCharCfg_t charCfg 
)

Import bond record to NV.

Parameters
pBondRec- basic bond record
pLocalLTK- LTK used by the device that has the same public address as current device
pDevLTK- LTK used by the peer device during pairing
pIRK- IRK used by the peer device during pairing
pSRK- SRK used by the peer device during pairing
signCounter- Sign counter used by the peer device during pairing
charCfg- GATT characteristic configuration
Returns
SUCCESS if bond was imported @ bleNoResources if there are no empty slots

§ gapBondMgrReadBondRec()

uint8_t gapBondMgrReadBondRec ( GAP_Peer_Addr_Types_t  addrType,
uint8_t *  pDevAddr,
gapBondRec_t pBondRec,
gapBondLTK_t pLocalLtk,
gapBondLTK_t pDevLtk,
uint8_t *  pIRK,
uint8_t *  pSRK,
uint32_t  signCount,
gapBondCharCfg_t charCfg 
)

Read bond record from NV.

Parameters
pBondRec- basic bond record
pLocalLTK- LTK used by this device during pairing
pDevLTK- LTK used by the peer device during pairing
pIRK- IRK used by the peer device during pairing
pSRK- SRK used by the peer device during pairing
signCounter- Sign counter used by the peer device during pairing
charCfg- GATT characteristic configuration
Returns
SUCCESS if bond was extracted bleGAPNotFound if there is no bond record
© Copyright 1995-2023, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale