Functions

GAP API Functions

Functions

bStatus_t GAP_DeviceInit (uint8 taskID, uint8 profileRole, uint8 maxScanResponses, uint8 *pIRK, uint8 *pSRK, uint32 *pSignCounter)
 Called to setup the device. Call just once on initialization.
bStatus_t GAP_SetAdvToken (gapAdvDataToken_t *pToken)
 Called to setup a GAP Advertisement/Scan Response data token.
gapAdvDataToken_tGAP_GetAdvToken (uint8 adType)
 Called to read a GAP Advertisement/Scan Response data token.
gapAdvDataToken_tGAP_RemoveAdvToken (uint8 adType)
 Called to remove a GAP Advertisement/Scan Response data token.
bStatus_t GAP_UpdateAdvTokens (void)
 Called to rebuild and load Advertisement and Scan Response data from existing GAP Advertisement Tokens.
bStatus_t GAP_SetParamValue (gapParamIDs_t paramID, uint16 paramValue)
 Set a GAP Parameter value. Use this function to change the default GAP parameter values.
uint16 GAP_GetParamValue (gapParamIDs_t paramID)
 Get a GAP Parameter value.
bStatus_t GAP_ConfigDeviceAddr (uint8 addrType, uint8 *pStaticAddr)
 Setup the device's address type. If ADDRTYPE_PRIVATE_RESOLVE is selected, the address will change periodically.
void GAP_RegisterForHCIMsgs (uint8 taskID)
 Register your task ID to receive extra (unwanted) HCI status and complete events.
bStatus_t GAP_DeviceDiscoveryRequest (gapDevDiscReq_t *pParams)
 Start a device discovery scan.
bStatus_t GAP_DeviceDiscoveryCancel (uint8 taskID)
 Cancel an existing device discovery request.
bStatus_t GAP_MakeDiscoverable (uint8 taskID, gapAdvertisingParams_t *pParams)
 Setup or change advertising. Also starts advertising.
bStatus_t GAP_UpdateAdvertisingData (uint8 taskID, uint8 adType, uint8 dataLen, uint8 *pAdvertData)
 Setup or change advertising and scan response data.
bStatus_t GAP_EndDiscoverable (uint8 taskID)
 Stops advertising.
bStatus_t GAP_ResolvePrivateAddr (uint8 *pIRK, uint8 *pAddr)
 Resolves a private address against an IRK.
bStatus_t GAP_EstablishLinkReq (gapEstLinkReq_t *pParams)
 Establish a link to a slave device.
bStatus_t GAP_TerminateLinkReq (uint8 taskID, uint16 connectionHandle, uint8 reason)
 Terminate a link connection.
bStatus_t GAP_UpdateLinkParamReq (gapUpdateLinkParamReq_t *pParams)
 Update the link parameters to a slave device.
uint8 GAP_NumActiveConnections (void)
 Returns the number of active connections.
bStatus_t GAP_Authenticate (gapAuthParams_t *pParams, gapPairingReq_t *pPairReq)
 Start the Authentication process with the requested device. This function is used to Initiate/Allow pairing. Called by both master and slave device (Central and Peripheral).
bStatus_t GAP_TerminateAuth (uint16 connectionHandle, uint8 reason)
 Send a Pairing Failed message and end any existing pairing.
bStatus_t GAP_PasskeyUpdate (uint8 *pPasskey, uint16 connectionHandle)
 Update the passkey in string format. This function is called by the application/profile in response to receiving the GAP_PASSKEY_NEEDED_EVENT message.
bStatus_t GAP_PasscodeUpdate (uint32 passcode, uint16 connectionHandle)
 Update the passkey in a numeric value (not string). This function is called by the application/profile in response to receiving the GAP_PASSKEY_NEEDED_EVENT message.
bStatus_t GAP_SendSlaveSecurityRequest (uint16 connectionHandle, uint8 authReq)
 Generate a Slave Requested Security message to the master.
bStatus_t GAP_Signable (uint16 connectionHandle, uint8 authenticated, smSigningInfo_t *pParams)
 Set up the connection to accept signed data.
bStatus_t GAP_Bond (uint16 connectionHandle, uint8 authenticated, smSecurityInfo_t *pParams, uint8 startEncryption)
 Set up the connection's bound paramaters.

Function Documentation

bStatus_t GAP_Authenticate ( gapAuthParams_t pParams,
gapPairingReq_t pPairReq 
)

Start the Authentication process with the requested device. This function is used to Initiate/Allow pairing. Called by both master and slave device (Central and Peripheral).

NOTE: This function is called after the link is established.

Parameters:
pParams - Authentication parameters
pPairReq - Enter these parameters if the Pairing Request was already received. NULL, if waiting for Pairing Request or if initiating.
Returns:
SUCCESS,
bleIncorrectMode: Not correct profile role,
INVALIDPARAMETER,
bleNotConnected,
bleAlreadyInRequestedMode,
FAILURE - not workable.
bStatus_t GAP_Bond ( uint16  connectionHandle,
uint8  authenticated,
smSecurityInfo_t *  pParams,
uint8  startEncryption 
)

Set up the connection's bound paramaters.

NOTE: This function is called after the link is established.

Parameters:
connectionHandle - connection handle of the signing information
authenticated - this connection was previously authenticated
pParams - the connected device's security parameters
startEncryption - whether or not to start encryption
Returns:
SUCCESS,
bleIncorrectMode: Not correct profile role,
INVALIDPARAMETER,
bleNotConnected,
FAILURE: not workable.
bStatus_t GAP_ConfigDeviceAddr ( uint8  addrType,
uint8 pStaticAddr 
)

Setup the device's address type. If ADDRTYPE_PRIVATE_RESOLVE is selected, the address will change periodically.

Parameters:
addrType - GAP Address Types
pStaticAddr - Only used with ADDRTYPE_STATIC or ADDRTYPE_PRIVATE_NONRESOLVE type.
NULL to auto generate otherwise the application can specify the address value
Returns:
SUCCESS: address type updated,
bleNotReady: Can't be called until GAP_DeviceInit() is called and the init process is completed,
bleIncorrectMode: can't change with an active connection,
or INVALIDPARAMETER.

If return value isn't SUCCESS, the address type remains the same as before this call.

bStatus_t GAP_DeviceDiscoveryCancel ( uint8  taskID  ) 

Cancel an existing device discovery request.

Parameters:
taskID - used to return GAP_DEVICE_DISCOVERY_EVENT
Returns:
SUCCESS: cancel started,
bleInvalidTaskID: Not the task that started discovery,
bleIncorrectMode: not in discovery mode
bStatus_t GAP_DeviceDiscoveryRequest ( gapDevDiscReq_t pParams  ) 

Start a device discovery scan.

Parameters:
pParams - Device Discovery parameters
Returns:
SUCCESS: scan started,
bleIncorrectMode: invalid profile role,
bleAlreadyInRequestedMode: not available
bStatus_t GAP_DeviceInit ( uint8  taskID,
uint8  profileRole,
uint8  maxScanResponses,
uint8 pIRK,
uint8 pSRK,
uint32 pSignCounter 
)

Called to setup the device. Call just once on initialization.

NOTE: When initialization is complete, the calling app will be sent the GAP_DEVICE_INIT_DONE_EVENT

Parameters:
taskID - Default task ID to send events.
profileRole - GAP Profile Roles: GAP Profile Roles
maxScanResponses - maximum number to scan responses we can receive during a device discovery.
pIRK - pointer to Identity Root Key, NULLKEY (all zeroes) if the app wants the GAP to generate the key.
pSRK - pointer to Sign Resolving Key, NULLKEY if the app wants the GAP to generate the key.
pSignCounter - 32 bit value used in the SM Signing algorithm that shall be initialized to zero and incremented with every new signing. This variable must also be maintained by the application.
Returns:
SUCCESS - Processing, expect GAP_DEVICE_INIT_DONE_EVENT,
INVALIDPARAMETER - for invalid profile role or role combination,
bleIncorrectMode - trouble communicating with HCI
bStatus_t GAP_EndDiscoverable ( uint8  taskID  ) 

Stops advertising.

Parameters:
taskID - of task that called GAP_MakeDiscoverable
Returns:
SUCCESS: stopping discoverable mode,
bleIncorrectMode: not in discoverable mode,
bleInvalidTaskID: not correct task
bStatus_t GAP_EstablishLinkReq ( gapEstLinkReq_t pParams  ) 

Establish a link to a slave device.

Parameters:
pParams - link establishment parameters
Returns:
SUCCESS: started establish link process,
bleIncorrectMode: invalid profile role,
bleNotReady: a scan is in progress,
bleAlreadyInRequestedMode: can’t process now,
bleNoResources: Too many links
gapAdvDataToken_t* GAP_GetAdvToken ( uint8  adType  ) 

Called to read a GAP Advertisement/Scan Response data token.

Parameters:
adType - Advertisement type to get
Returns:
pointer to the advertisement data token structure, NULL if not found.
uint16 GAP_GetParamValue ( gapParamIDs_t  paramID  ) 

Get a GAP Parameter value.

Parameters:
paramID - parameter ID: GAP Parameter IDs
Returns:
GAP Parameter value or 0xFFFF if invalid
bStatus_t GAP_MakeDiscoverable ( uint8  taskID,
gapAdvertisingParams_t pParams 
)

Setup or change advertising. Also starts advertising.

Parameters:
taskID - used to return GAP_DISCOVERABLE_RESPONSE_EVENT
pParams - advertising parameters
Returns:
SUCCESS: advertising started,
bleIncorrectMode: invalid profile role,
bleAlreadyInRequestedMode: not available at this time,
bleNotReady: advertising data isn't set up yet.
uint8 GAP_NumActiveConnections ( void   ) 

Returns the number of active connections.

Returns:
Number of active connections.
bStatus_t GAP_PasscodeUpdate ( uint32  passcode,
uint16  connectionHandle 
)

Update the passkey in a numeric value (not string). This function is called by the application/profile in response to receiving the GAP_PASSKEY_NEEDED_EVENT message.

NOTE: This function is the same as GAP_PasskeyUpdate(), except that the passkey is passed in as a non-string format.

Parameters:
passcode - not string - range: 0 - 999,999.
connectionHandle - connection handle.
Returns:
SUCCESS: will start pairing with this entry,
bleIncorrectMode: Link not found,
INVALIDPARAMETER: passkey == NULL or passkey isn't formatted properly.
bStatus_t GAP_PasskeyUpdate ( uint8 pPasskey,
uint16  connectionHandle 
)

Update the passkey in string format. This function is called by the application/profile in response to receiving the GAP_PASSKEY_NEEDED_EVENT message.

NOTE: This function is the same as GAP_PasscodeUpdate(), except that the passkey is passed in as a string format.

Parameters:
pPasskey - new passkey - pointer to numeric string (ie. "019655" ). This string's range is "000000" to "999999".
connectionHandle - connection handle.
Returns:
SUCCESS: will start pairing with this entry,
bleIncorrectMode: Link not found,
INVALIDPARAMETER: passkey == NULL or passkey isn't formatted properly.
void GAP_RegisterForHCIMsgs ( uint8  taskID  ) 

Register your task ID to receive extra (unwanted) HCI status and complete events.

Parameters:
taskID - Default task ID to send events.
Returns:
none
gapAdvDataToken_t* GAP_RemoveAdvToken ( uint8  adType  ) 

Called to remove a GAP Advertisement/Scan Response data token.

Parameters:
adType - Advertisement type to remove
Returns:
pointer to the token structure removed from the GAP ADType list NULL if the requested adType wasn't found.
bStatus_t GAP_ResolvePrivateAddr ( uint8 pIRK,
uint8 pAddr 
)

Resolves a private address against an IRK.

Parameters:
pIRK - pointer to the IRK
pAddr - pointer to the Resovable Private address
Returns:
SUCCESS: match,
FAILURE: don't match,
INVALIDPARAMETER: parameters invalid
bStatus_t GAP_SendSlaveSecurityRequest ( uint16  connectionHandle,
uint8  authReq 
)

Generate a Slave Requested Security message to the master.

Parameters:
connectionHandle - connection handle.
authReq - Authentication Requirements: Bit 2: MITM, Bits 0-1: bonding (0 - no bonding, 1 - bonding)
Returns:
SUCCESS: will send,
bleNotConnected: Link not found,
bleIncorrectMode: wrong GAP role, must be a Peripheral Role
bStatus_t GAP_SetAdvToken ( gapAdvDataToken_t pToken  ) 

Called to setup a GAP Advertisement/Scan Response data token.

NOTE: The data in these items are stored as low byte first (OTA format). The passed in structure "token" should be allocated by the calling app/profile and not released until after calling GAP_RemoveAdvToken().

Parameters:
pToken - Advertisement/Scan response token to write.
Returns:
SUCCESS - advertisement token added to the GAP list
INVALIDPARAMETER - Invalid Advertisement Type or pAttrData is NULL
INVALID_MEM_SIZE - The tokens take up too much space and don't fit into Advertisment data and Scan Response Data
bleInvalidRange - token ID already exists.
bleIncorrectMode - not a peripheral device
bleMemAllocError - memory allocation failure,
bStatus_t GAP_SetParamValue ( gapParamIDs_t  paramID,
uint16  paramValue 
)

Set a GAP Parameter value. Use this function to change the default GAP parameter values.

Parameters:
paramID - parameter ID: GAP Parameter IDs
paramValue - new param value
Returns:
SUCCESS or INVALIDPARAMETER (invalid paramID)
bStatus_t GAP_Signable ( uint16  connectionHandle,
uint8  authenticated,
smSigningInfo_t *  pParams 
)

Set up the connection to accept signed data.

NOTE: This function is called after the link is established.

Parameters:
connectionHandle - connection handle of the signing information
authenticated - TRUE if the signing information is authenticated, FALSE otherwise
pParams - signing parameters
Returns:
SUCCESS,
bleIncorrectMode: Not correct profile role,
INVALIDPARAMETER,
bleNotConnected,
FAILURE: not workable.
bStatus_t GAP_TerminateAuth ( uint16  connectionHandle,
uint8  reason 
)

Send a Pairing Failed message and end any existing pairing.

Parameters:
connectionHandle - connection handle.
reason - Pairing Failed reason code.
Returns:
SUCCESS - function was successful,
bleMemAllocError - memory allocation error,
INVALIDPARAMETER - one of the parameters were invalid,
bleNotConnected - link not found,
bleInvalidRange - one of the parameters were not within range.
bStatus_t GAP_TerminateLinkReq ( uint8  taskID,
uint16  connectionHandle,
uint8  reason 
)

Terminate a link connection.

Parameters:
taskID - requesting app's task id.
connectionHandle - connection handle of link to terminate or GAP Special Connection Handles
reason - terminate reason.
Returns:
SUCCESS: Terminate started,
bleIncorrectMode: No Link to terminate,
bleInvalidTaskID: not app that established link
bStatus_t GAP_UpdateAdvertisingData ( uint8  taskID,
uint8  adType,
uint8  dataLen,
uint8 pAdvertData 
)

Setup or change advertising and scan response data.

NOTE: if the return status from this function is SUCCESS, the task isn't complete until the GAP_ADV_DATA_UPDATE_DONE_EVENT is sent to the calling application task.

Parameters:
taskID - task ID of the app requesting the change
adType - TRUE - advertisement data, FALSE - scan response data
dataLen - Octet length of advertData
pAdvertData - advertising or scan response data
Returns:
SUCCESS: data accepted,
bleIncorrectMode: invalid profile role,
bStatus_t GAP_UpdateAdvTokens ( void   ) 

Called to rebuild and load Advertisement and Scan Response data from existing GAP Advertisement Tokens.

Returns:
SUCCESS or bleIncorrectMode
bStatus_t GAP_UpdateLinkParamReq ( gapUpdateLinkParamReq_t pParams  ) 

Update the link parameters to a slave device.

Parameters:
pParams - link update parameters
Returns:
SUCCESS: started update link process,<BR INVALIDPARAMETER: one of the parameters were invalid,
bleIncorrectMode: invalid profile role,
bleNotConnected: not in a connection