GAP

This module implements the Generic Access Protocol (GAP) More...

Modules
	GAP Callbacks
	GAP Constants
	GAP Events
	GAP Parameters
	GAP Structures

Files
file	gap.h
	GAP layer interface.

Macros
#define	GAP_IS_ADDR_RAND(pAddr)
#define	GAP_IS_ADDR_RPN(pAddr)
#define	GAP_IS_ADDR_RPR(pAddr)
#define	GAP_IS_ADDR_RS(pAddr)

Functions
bStatus_t	GAP_Authenticate (gapAuthParams_t *pParams, gapPairingReq_t *pPairReq)
bStatus_t	GAP_Bond (uint16_t connectionHandle, uint8_t authenticated, uint8_t secureConnections, smSecurityInfo_t *pParams, uint8_t startEncryption)
bStatus_t	gap_checkLtk_GapBondMgr (uint16_t connectionHandle)
	Checks the Long Term Key (LTK) for a given connection using the GAP Bond Manager. If GAP Bond Manager is used, this function will always return SUCCESS because the LTK is stored in the bond manager. More...
bStatus_t	gap_checkLtk_noGapBondMgr (uint16_t connectionHandle)
	Checks the Long Term Key (LTK) for a given connection without using the GAP Bond Manager. More...
bStatus_t	GAP_DeviceInit (uint8_t profileRole, uint8_t taskID, GAP_Addr_Modes_t addrMode, uint8_t *pRandomAddr)
uint8_t *	GAP_GetDevAddress (uint8 wantIA)
uint8 *	GAP_GetDevAddressByType (uint8 wantIA, uint8 deviceAddrType)
uint8_t *	GAP_GetIRK (void)
uint16_t	GAP_GetParamValue (uint16_t paramID)
uint8_t *	GAP_GetSRK (void)
void	GAP_Init (uint8_t task_id)
uint8_t	GAP_isPairing (void)
uint8_t	GAP_NumActiveConnections (void)
bStatus_t	GAP_PasscodeUpdate (uint32_t passcode, uint16_t connectionHandle)
bStatus_t	GAP_PasskeyUpdate (uint8_t *pPasskey, uint16_t connectionHandle)
uint32	GAP_ProcessEvent (uint8_t task_id, uint32 events)
void	GAP_RegisterBondMgrCBs (gapBondMgrCBs_t *pCBs)
bStatus_t	Gap_RegisterConnEventCb (pfnGapConnEvtCB_t cb, GAP_CB_Action_t action, GAP_CB_Event_e event, uint16_t connHandle)
void	GAP_RegisterForMsgs (uint8_t taskID)
bStatus_t	Gap_ReplyToLTKReq (uint16_t connectionHandle, smSecurityInfo_t *const pParams, uint8_t *isLTKUpdated)
bStatus_t	GAP_SendPeripheralSecurityRequest (uint16_t connectionHandle, uint8_t authReq)
bStatus_t	GAP_SetParamValue (uint16_t paramID, uint16_t paramValue)
bStatus_t	GAP_SetPrivacyMode (GAP_Peer_Addr_Types_t addrType, uint8_t *pAddr, uint8_t mode)
bStatus_t	GAP_Signable (uint16_t connectionHandle, uint8_t authenticated, smSigningInfo_t *pParams)
bStatus_t	GAP_TerminateAuth (uint16_t connectionHandle, uint8_t reason)
bStatus_t	GAP_TerminateLinkReq (uint16_t connectionHandle, uint8_t reason)
bStatus_t	GAP_UpdateLinkParamReq (gapUpdateLinkParamReq_t *pParams)
bStatus_t	GAP_UpdateLinkParamReqReply (gapUpdateLinkParamReqReply_t *pParams)
bStatus_t	GapConfig_SetParameter (Gap_configParamIds_t param, void *pValue)

Detailed Description

This module implements the Generic Access Protocol (GAP)

Macro Definition Documentation

GAP_IS_ADDR_RAND

#define GAP_IS_ADDR_RAND

(

pAddr

)

Value:

(GAP_IS_ADDR_RPR(pAddr) | \
                                 GAP_IS_ADDR_RPN(pAddr) | \
                                 GAP_IS_ADDR_RS(pAddr))

Is the address any type of random address?

GAP_IS_ADDR_RPN

#define GAP_IS_ADDR_RPN

(

pAddr

)

Value:

((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \
                                 == PRIVATE_NON_RESOLVE_ADDR_HDR)

Is the address random private non-resolvable (NRPA)?

Parameters

pAddr

pointer to address

Returns

TRUE the address is an NRPA

FALSE the address is not an NRPA

GAP_IS_ADDR_RPR

#define GAP_IS_ADDR_RPR

(

pAddr

)

Value:

((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \
                                 == PRIVATE_RESOLVE_ADDR_HDR)

Is the address random private resolvable (RPA)?

Parameters

pAddr

pointer to address

Returns

TRUE the address is an RPA

FALSE the address is not an RPA

GAP_IS_ADDR_RS

#define GAP_IS_ADDR_RS

(

pAddr

)

Value:

((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \
                                 == STATIC_ADDR_HDR)

Is the address random static?

Parameters

pAddr

pointer to address

Returns

TRUE the address is random static

FALSE the address is not random static

Function Documentation

GAP_Authenticate()

bStatus_t GAP_Authenticate	(	gapAuthParams_t *	pParams,
		gapPairingReq_t *	pPairReq
	)

Start Authentication

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

Warning

This API should not be called by the application if the gapbondmgr exists as it will be used automatically based on GAPBOND_PAIRING_MODE

Corresponding Events:

After pairing is completed successfully, the calling task will receive a GAP_AUTHENTICATION_COMPLETE_EVENT of type gapAuthCompleteEvent_t
After a failed pairing, the calling task will receive a GAP_AUTHENTICATION_FAILURE_EVT

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 : authentication request sent to stack

bleIncorrectMode : Not correct profile role

INVALIDPARAMETER

bleNotConnected

bleAlreadyInRequestedMode

FAILURE : not workable

GAP_Bond()

bStatus_t GAP_Bond	(	uint16_t	connectionHandle,
		uint8_t	authenticated,
		uint8_t	secureConnections,
		smSecurityInfo_t *	pParams,
		uint8_t	startEncryption
	)

Set up the connection's bound parameters.

Warning

This API should not be called by the application if the gapbondmgr exists as it will be used automatically when a connection is formed to a previously bonded device

Corresponding Events:

GAP_BOND_COMPLETE_EVENT of type gapBondCompleteEvent_t

Parameters

connectionHandle	connection handle of the signing information
authenticated	TRUE if bond is authenticated.
secureConnections	TRUE if bond has Secure Connections strength.
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

gap_checkLtk_GapBondMgr()

bStatus_t gap_checkLtk_GapBondMgr

(

uint16_t

connectionHandle

)

Checks the Long Term Key (LTK) for a given connection using the GAP Bond Manager. If GAP Bond Manager is used, this function will always return SUCCESS because the LTK is stored in the bond manager.

Returns

bStatus_t Status of the operation. Returns success.

gap_checkLtk_noGapBondMgr()

bStatus_t gap_checkLtk_noGapBondMgr

(

uint16_t

connectionHandle

)

Checks the Long Term Key (LTK) for a given connection without using the GAP Bond Manager.

This function verifies the validity of the Long Term Key (LTK) associated with a specific connection. It is used in scenarios where the GAP Bond Manager is not utilized for managing security keys.

Parameters

pLinkItem	Pointer to the link database item containing connection information.
connectionHandle	The handle identifying the connection for which the LTK is being checked.

Returns

bStatus_t Status of the operation. Returns success or an error code indicating the result.

GAP_DeviceInit()

bStatus_t GAP_DeviceInit	(	uint8_t	profileRole,
		uint8_t	taskID,
		GAP_Addr_Modes_t	addrMode,
		uint8_t *	pRandomAddr
	)

GAP Device Initialization

Setup the device. Can only be called once per reset. In order to change the address mode / random address, it is necessary to reset the device and call this API again. In the case where the address mode or random address is different than it was for the last initialization, all bonds and local information stored in NV will be erased.

Corresponding Events:

GAP_DEVICE_INIT_DONE_EVENT of type gapDeviceInitDoneEvent_t

Parameters

profileRole	GAP Profile Roles: GAP Profile Roles
taskID	end application task to receive unprocessed GAP events.
addrMode	Own address mode. If always using Resolvable Private Address, set this to either ADDRMODE_RP_WITH_PUBLIC_ID or ADDRMODE_RP_WITH_RANDOM_ID. If always using Identity Address, set this to either ADDRMODE_PUBLIC or ADDRMODE_RANDOM.
pRandomAddr	Pointer to 6-byte Random Static Address of this device that will be copied to the stack. Valid only if addrMode is ADDRMODE_RANDOM or ADDRMODE_RP_WITH_RANDOM_ID and can not be NULL in these cases. Ignored for other address types.

Returns

SUCCESS : initialization started

INVALIDPARAMETER : invalid profile role, role combination, or invalid Random Static Address,

bleIncorrectMode : initialization has already occurred

bleInternalError : error erasing NV

GAP_GetDevAddress()

uint8_t* GAP_GetDevAddress

(

uint8

wantIA

)

Get the address of this device

Parameters

wantIA

TRUE for Identity Address. FALSE for Resolvable Private Address (if the device has been initialized with the address mode ADDRMODE_RP_WITH_PUBLIC_ID or ADDRMODE_RP_WITH_RANDOM_ID)

Returns

pointer to device address.

GAP_GetDevAddressByType()

uint8* GAP_GetDevAddressByType	(	uint8	wantIA,
		uint8	deviceAddrType
	)

Get the address of this device using the it's type

Parameters

wantIA	TRUE for Identity Address. FALSE for Resolvable Private Address (if the device has been initialized with the address mode ADDRMODE_RP_WITH_PUBLIC_ID or ADDRMODE_RP_WITH_RANDOM_ID)
deviceAddrType	- The own device address type

Returns

pointer to device address.

GAP_GetIRK()

uint8_t* GAP_GetIRK

(

void

)

Get the IRK

Warning

The memory indicated by the returned pointer should not be modified directly if it is desired to update the IRK. Instead, use the GAP_CONFIG_PARAM_IRK

Returns

pointer to the 16-byte IRK

GAP_GetParamValue()

uint16_t GAP_GetParamValue

(

uint16_t

paramID

)

Get a GAP Parameter value.

Parameters

paramID

parameter ID: Gap_ParamIDs_t

Returns

GAP Parameter value

0xFFFF if invalid

GAP_GetSRK()

uint8_t* GAP_GetSRK

(

void

)

Get the SRK

Warning

The memory indicated by the returned pointer should not be modified directly if it is desired to update the SRK. Instead, use the GAP_CONFIG_PARAM_SRK

Returns

pointer to the 16-byte SRK

GAP_Init()

void GAP_Init

(

uint8_t

task_id

)

Initialization for GAP module

This should only be used in osal_icall_ble.c in osalInitTasks()

Parameters

task_id

OSAL task ID

GAP_isPairing()

uint8_t GAP_isPairing

(

void

)

Check if GAP is currently pairing.

Note

This API is not needed if the gapbondmgr exists as pairing states are returned via the pfnPairStateCB_t callback

Returns

TRUE if pairing

FALSE otherwise

GAP_NumActiveConnections()

uint8_t GAP_NumActiveConnections

(

void

)

Returns the number of active connections.

Returns

Number of active connections.

GAP_PasscodeUpdate()

bStatus_t GAP_PasscodeUpdate	(	uint32_t	passcode,
		uint16_t	connectionHandle
	)

Update the passkey in a numeric value (not string).

This API should be called in response to receiving a GAP_PASSKEY_NEEDED_EVENT

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

GAP_PasskeyUpdate()

bStatus_t GAP_PasskeyUpdate	(	uint8_t *	pPasskey,
		uint16_t	connectionHandle
	)

Update the passkey in string format.

This API should be called in response to receiving a GAP_PASSKEY_NEEDED_EVENT

Note

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

Warning

This API should not be called by the application if the gapbondmgr exists as it is abstracted through GAPBondMgr_PasscodeRsp

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

GAP_ProcessEvent()

uint32 GAP_ProcessEvent	(	uint8_t	task_id,
		uint32	events
	)

GAP Module event processing

This should only be used in osal_icall_ble.c in tasksArr[]

Parameters

task_id	OSAL task ID
events	OSAL event received

Returns

bitmask of events that weren't processed

GAP_RegisterBondMgrCBs()

void GAP_RegisterBondMgrCBs

(

gapBondMgrCBs_t *

pCBs

)

Register bond manager call backs

Parameters

pCBs	pointer to Bond Manager Callbacks.

Gap_RegisterConnEventCb()

bStatus_t Gap_RegisterConnEventCb	(	pfnGapConnEvtCB_t	cb,
		GAP_CB_Action_t	action,
		GAP_CB_Event_e	event,
		uint16_t	connHandle
	)

Register/Unregister a connection event callback

It is only possible to register for one connection handle of for all connection handles. In the case of unregistering, it does not matter what connHandle or cb is passed in as whatever is currently registered will be unregistered. It it possible to register to certain type of connection event. The types that are currently supported are: Connection established, PHY Update Request Completed (without PHY change).

Warning

The application owns the memory pointed to by pReport in pfnGapConnEvtCB_t. That is, it is responsible for freeing this memory.

Note

The callback needs to be registered for each reconnection. It is not retained across a disconnect / reconnect.

There is no need to unregister in order to change the type of connection event registered. It can be changed with a new call.

Parameters

cb	Function pointer to a callback.
action	Register or unregister the callback.
event	Connection Event type to register to. Supported event options: GAP_CB_CONN_ESTABLISHED, GAP_CB_PHY_UPDATE, GAP_CB_CONN_EVENT_ALL
connHandle	if LINKDB_CONNHANDLE_ALL, apply to all connections. else, apply only for a specific connection.

Returns

SUCCESS

bleGAPNotFound : connection handle not found

bleInvalidRange : the callback function was NULL or action is invalid

bleMemAllocError : there is not enough memory to register the callback.

GAP_RegisterForMsgs()

void GAP_RegisterForMsgs

(

uint8_t

taskID

)

Register for GAP Messages

Register a task ID to receive extra (unprocessed) HCI status and complete, and Host events.

Parameters

taskID

Default task ID to send events.

Gap_ReplyToLTKReq()

bStatus_t Gap_ReplyToLTKReq	(	uint16_t	connectionHandle,
		smSecurityInfo_t *const	pParams,
		uint8_t *	isLTKUpdated
	)

Reply to an LTK request.

This API should be called in response to receiving a HCI_BLE_LTK_REQUESTED_EVENT

If encryption parameters exist for the connectionHandle, and are equal to the ones recieved in the event, the LTK provided in the pParams will be used.

If encryption parameters exist for the connectionHandle, but are not equal to the ones recieved in the event, the pParams will not be used.

If encryption parameters doesn't exist for the connectionHandle, use the provided pParams for the LTK replay.

Parameters

connectionHandle	connection handle of the signing information
pParams	the connected device's encription parameters and updated LTK parameter

Returns

SUCCESS

bleIncorrectMode : Not correct profile role

INVALIDPARAMETER

bleNotConnected

bleGAPBondRejected

GAP_SendPeripheralSecurityRequest()

bStatus_t GAP_SendPeripheralSecurityRequest	(	uint16_t	connectionHandle,
		uint8_t	authReq
	)

Generate a Peripheral Requested Security message to the central.

Warning

This API should not be called by the application if the gapbondmgr exists as it will be used automatically based on GAPBOND_PAIRING_MODE and the GAP role of the device

Parameters

connectionHandle	connection handle.
authReq	Authentication Requirements: Bit 2: MITM, Bits 0-1: bonding (0 - no bonding, 1 - bonding) Bit 3: Secure Connections

Returns

SUCCESS : will send

bleNotConnected : Link not found

bleIncorrectMode : wrong GAP role, must be a Peripheral Role

GAP_SetParamValue()

bStatus_t GAP_SetParamValue	(	uint16_t	paramID,
		uint16_t	paramValue
	)

Set a GAP Parameter value

Use this function to change the default GAP parameter values.

Parameters

paramID	parameter ID: Gap_ParamIDs_t
paramValue	new param value

Returns

SUCCESS

INVALIDPARAMETER

GAP_SetPrivacyMode()

bStatus_t GAP_SetPrivacyMode	(	GAP_Peer_Addr_Types_t	addrType,
		uint8_t *	pAddr,
		uint8_t	mode
	)

Set the Privacy Mode of the requested device to the desired mode.

Warning

This should not be called if the bond manager is present as the bond manager will handle this automatically based on the connected device's capabilities and the own device's capabilities.

Parameters

addrType	remote device's identity address type
pAddr	pointer to the address
mode	GAP Privacy Modes to use for this device

Returns

SUCCESS : match

FAILURE : don't match

INVALIDPARAMETER : parameters invalid

GAP_Signable()

bStatus_t GAP_Signable	(	uint16_t	connectionHandle,
		uint8_t	authenticated,
		smSigningInfo_t *	pParams
	)

Set up the connection to accept signed data.

Warning

This API should not be called by the application if the gapbondmgr exists as it will be used automatically when signing occurs

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

GAP_TerminateAuth()

bStatus_t GAP_TerminateAuth	(	uint16_t	connectionHandle,
		uint8_t	reason
	)

Terminate Authentication

Send a Pairing Failed message and end any existing pairing.

Corresponding Events:

GAP_AUTHENTICATION_FAILURE_EVT

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

GAP_TerminateLinkReq()

bStatus_t GAP_TerminateLinkReq	(	uint16_t	connectionHandle,
		uint8_t	reason
	)

Terminate a link connection.

Corresponding Events:

GAP_LINK_TERMINATED_EVENT of type gapTerminateLinkEvent_t

Parameters

connectionHandle	connection handle of link to terminate or LINKDB_CONNHANDLE_ALL
reason	terminate reason.

Returns

SUCCESS : termination request sent to stack

bleIncorrectMode : No Link to terminate

bleInvalidTaskID : not app that established link

GAP_UpdateLinkParamReq()

bStatus_t GAP_UpdateLinkParamReq

(

gapUpdateLinkParamReq_t *

pParams

)

Update the link parameters to a Central or Peripheral device.

As long as LL connection updates are supported on the own device (which is the case by default), an LL Connection Update procedure will be attempted. If this fails, the stack will automatically attempt an L2CAP parameter update request.

Corresponding Events:

After the update procedure is complete, the calling task will receive a GAP_LINK_PARAM_UPDATE_EVENT of type gapLinkUpdateEvent_t regardless of the connection parameter update procedure that occurred.

Parameters

pParams

link update parameters

Returns

SUCCESS : update request sent to stack

INVALIDPARAMETER : one of the parameters were invalid

bleIncorrectMode : invalid profile role

bleAlreadyInRequestedMode : already updating link parameters

bleNotConnected : not in a connection

GAP_UpdateLinkParamReqReply()

bStatus_t GAP_UpdateLinkParamReqReply

(

gapUpdateLinkParamReqReply_t *

pParams

)

Reply to a Connection Parameter Update Request that was received from a remote device.

This API should be used in response to a GAP_UPDATE_LINK_PARAM_REQ_EVENT which will only be received when GAP_PARAM_LINK_UPDATE_DECISION is set to GAP_UPDATE_REQ_PASS_TO_APP.

Corresponding Events:

The calling task should call this API in response to a GAP_UPDATE_LINK_PARAM_REQ_EVENT of type gapUpdateLinkParamReqEvent_t
After the update procedure is complete, the calling task will receive a GAP_LINK_PARAM_UPDATE_EVENT of type gapLinkUpdateEvent_t

Parameters

pParams

local device's desired connection parameters.

Returns

SUCCESS : reply sent successfully

INVALIDPARAMETER : one of the parameters were invalid

bleIncorrectMode : invalid profile role

bleAlreadyInRequestedMode : already updating link parameters

bleNotConnected : not in a connection

GapConfig_SetParameter()

bStatus_t GapConfig_SetParameter	(	Gap_configParamIds_t	param,
		void *	pValue
	)

Set a GAP Configuration Parameter

Use this function to write a GAP configuration parameter. These parameters must be set before GAP_DeviceInit

Parameters

param	parameter ID: Gap_configParamIds_t
pValue	pointer to parameter value. Cast based on the type defined in Gap_configParamIds_t

Note

if param is GAP_CONFIG_PARAM_IRK_UPDATE_IMMED and pValue is set to all 0xFFs, a new random IRK will be generated.

Returns

SUCCESS

INVALIDPARAMETER

bleInvalidRange NULL pointer was passed

bleIncorrectMode Device is already initialized