GAP

This module implements the Generic Access Protocol (GAP) For a detailed usage section describing how to send these commands and receive events, see the GAP Section of the User's Guide. More...

Modules
	GAP Callbacks
	GAP Constants
	GAP Structures

Files
file	gap.h
	GAP layer interface.

Functions
bStatus_t	GAP_Authenticate (gapAuthParams_t *pParams, gapPairingReq_t *pPairReq)
	Start Authentication. More...
bStatus_t	GAP_Bond (uint16 connectionHandle, uint8 authenticated, uint8 secureConnections, smSecurityInfo_t *pParams, uint8 startEncryption)
	Set up the connection's bound paramaters. More...
bStatus_t	GAP_ConfigDeviceAddr (uint8 addrMode, uint8 *pStaticAddr)
	Configure Device Address. More...
bStatus_t	GAP_DeviceDiscoveryCancel (uint8 taskID)
	Cancel an existing device discovery request. More...
bStatus_t	GAP_DeviceDiscoveryRequest (gapDevDiscReq_t *pParams)
	Start a device discovery scan. More...
bStatus_t	GAP_DeviceInit (uint8 taskID, uint8 profileRole, uint8 maxScanResponses, uint8 *pIRK, uint8 *pSRK, uint32 *pSignCounter)
	GAP Device Initialiation. More...
bStatus_t	GAP_EndDiscoverable (uint8 taskID)
	Stops advertising. More...
bStatus_t	GAP_EstablishLinkReq (gapEstLinkReq_t *pParams)
	Establish a link to a slave device. More...
gapAdvDataToken_t *	GAP_GetAdvToken (uint8 adType)
	Get Advertising Token. More...
uint16	GAP_GetParamValue (gapParamIDs_t paramID)
	Get a GAP Parameter value. More...
uint8	GAP_isPairing (void)
	Check if GAP is currently pairing. More...
bStatus_t	GAP_MakeDiscoverable (uint8 taskID, gapAdvertisingParams_t *pParams)
	Setup or change advertising. Also starts advertising. More...
uint8	GAP_NumActiveConnections (void)
	Returns the number of active connections. More...
bStatus_t	GAP_PasscodeUpdate (uint32 passcode, uint16 connectionHandle)
	Update the passkey in a numeric value (not string). More...
bStatus_t	GAP_PasskeyUpdate (uint8 *pPasskey, uint16 connectionHandle)
	Update the passkey in string format. More...
void	GAP_RegisterBondMgrCBs (gapBondMgrCBs_t *pCBs)
	Register bond manager call backs. More...
void	GAP_RegisterForMsgs (uint8 taskID)
	Register for GAP Messages. More...
gapAdvDataToken_t *	GAP_RemoveAdvToken (uint8 adType)
	Remove Advertising Token. More...
bStatus_t	GAP_ResolvePrivateAddr (uint8 *pIRK, uint8 *pAddr)
	Resolves a private address against an IRK. More...
bStatus_t	GAP_SendSlaveSecurityRequest (uint16 connectionHandle, uint8 authReq)
	Generate a Slave Requested Security message to the master. More...
bStatus_t	GAP_SetAdvToken (gapAdvDataToken_t *pToken)
	Set Advertising Token. More...
bStatus_t	GAP_SetParamValue (gapParamIDs_t paramID, uint16 paramValue)
	Set a GAP Parameter value. More...
bStatus_t	GAP_Signable (uint16 connectionHandle, uint8 authenticated, smSigningInfo_t *pParams)
	Set up the connection to accept signed data. More...
bStatus_t	GAP_TerminateAuth (uint16 connectionHandle, uint8 reason)
	Terminate Authnetication. More...
bStatus_t	GAP_TerminateLinkReq (uint8 taskID, uint16 connectionHandle, uint8 reason)
	Terminate a link connection. More...
bStatus_t	GAP_UpdateAdvertisingData (uint8 taskID, uint8 adType, uint8 dataLen, uint8 *pAdvertData)
	Setup or change advertising and scan response data. More...
bStatus_t	GAP_UpdateAdvTokens (void)
	Update Advertising Token. More...
bStatus_t	GAP_UpdateLinkParamReq (gapUpdateLinkParamReq_t *pParams)
	Update the link parameters to a Master or Slave device. More...
bStatus_t	GAP_UpdateLinkParamReqReply (gapUpdateLinkParamReqReply_t *pParams)
	Reply to a Connection Parameter Update Request sent from a peer device. More...
void	GAP_UpdateResolvingList (uint8 *pIRK)
	Update the resolving list. More...

Detailed Description

This module implements the Generic Access Protocol (GAP) For a detailed usage section describing how to send these commands and receive events, see the GAP Section of the User's Guide.

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 master and slave device (Central and Peripheral).

Note

This function must only be called after the link is established.

Corresponding Events:

After pairing is completed succesfully, 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	connectionHandle,
		uint8	authenticated,
		uint8	secureConnections,
		smSecurityInfo_t *	pParams,
		uint8	startEncryption
	)

Set up the connection's bound paramaters.

Note

This function must only called after the link is established.

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_ConfigDeviceAddr()

bStatus_t GAP_ConfigDeviceAddr	(	uint8	addrMode,
		uint8 *	pStaticAddr
	)

Configure Device Address.

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

Note

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

Corresponding Events:

If the device is correctly configured for ADDRMODE_PRIVATE_NONRESOLVE , the calling task will receive a GAP_RANDOM_ADDR_CHANGED_EVENT of type gapRandomAddrEvent_t when the random address changes

Parameters

addrMode	- GAP Addressing Modes
pStaticAddr	- Only used with ADDRMODE_STATIC or ADDRMODE_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

GAP_DeviceDiscoveryCancel()

bStatus_t GAP_DeviceDiscoveryCancel

(

uint8

taskID

)

Cancel an existing device discovery request.

Corresponding Events:

When disovery is complete, the calling app will receive a GAP_DEVICE_DISCOVERY_EVENT of type gapDevDiscEvent_t

Parameters

taskID

- task to receive event

Returns

SUCCESS : cancel request sent to stack

bleInvalidTaskID : Not the task that started discovery

bleIncorrectMode : not in discovery mode

GAP_DeviceDiscoveryRequest()

bStatus_t GAP_DeviceDiscoveryRequest

(

gapDevDiscReq_t *

pParams

)

Start a device discovery scan.

Parameters

pParams

- Device Discovery parameters

Corresponding Events:

As devices are discovered, the calling app will receive GAP_DEVICE_INFO_EVENT of type gapDeviceInfoEvent_t
When disovery is complete, the calling app will receive a GAP_DEVICE_DISCOVERY_EVENT of type gapDevDiscEvent_t

Returns

SUCCESS : scan request sent to stakc

bleIncorrectMode : invalid profile role

bleAlreadyInRequestedMode : not available

GAP_DeviceInit()

bStatus_t GAP_DeviceInit	(	uint8	taskID,
		uint8	profileRole,
		uint8	maxScanResponses,
		uint8 *	pIRK,
		uint8 *	pSRK,
		uint32 *	pSignCounter
	)

GAP Device Initialiation.

Setup the device. Call just once on initialization.

Corresponding Events:

GAP_DEVICE_INIT_DONE_EVENT of type gapDeviceInitDoneEvent_t

Parameters

taskID	- task to receive event
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 - initialization started

INVALIDPARAMETER - for invalid profile role or role combination

bleIncorrectMode - trouble communicating with HCI

GAP_EndDiscoverable()

bStatus_t GAP_EndDiscoverable

(

uint8

taskID

)

Stops advertising.

Corresponding Events:

GAP_END_DISCOVERABLE_DONE_EVENT of type gapEndDiscoverableRspEvent_t

Parameters

taskID

- task to receive event

Returns

SUCCESS : discovery cancel sent to stack

bleIncorrectMode : not in discoverable mode

bleInvalidTaskID : not correct task

GAP_EstablishLinkReq()

bStatus_t GAP_EstablishLinkReq

(

gapEstLinkReq_t *

pParams

)

Establish a link to a slave device.

Corresponding Events:

GAP_LINK_ESTABLISHED_EVENT of type gapEstLinkReqEvent_t

Parameters

pParams

- link establishment parameters

Returns

SUCCESS : connection request sent to stack

bleIncorrectMode : invalid profile role

bleNotReady : a scan is in progress

bleAlreadyInRequestedMode : can't process now

bleNoResources : Too many links

GAP_GetAdvToken()

gapAdvDataToken_t* GAP_GetAdvToken

(

uint8

adType

)

Get Advertising Token.

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.

GAP_GetParamValue()

uint16 GAP_GetParamValue

(

gapParamIDs_t

paramID

)

Get a GAP Parameter value.

Parameters

paramID

- parameter ID: GAP Parameter IDs

Returns

GAP Parameter value

0xFFFF if invalid

GAP_isPairing()

uint8 GAP_isPairing

(

void

)

Check if GAP is currently pairing.

Returns

TRUE if pairing

FALSE otherwise

GAP_MakeDiscoverable()

bStatus_t GAP_MakeDiscoverable	(	uint8	taskID,
		gapAdvertisingParams_t *	pParams
	)

Setup or change advertising. Also starts advertising.

Corresponding Events:

GAP_MAKE_DISCOVERABLE_DONE_EVENT of type gapMakeDiscoverableRspEvent_t

Parameters

taskID	- task to receive event
pParams	- advertising parameters

Returns

SUCCESS : advertising request sent to stack

bleIncorrectMode : invalid profile role

bleAlreadyInRequestedMode : already advertising

bleNotReady : advertising data isn't set up yet

GAP_NumActiveConnections()

uint8 GAP_NumActiveConnections

(

void

)

Returns the number of active connections.

Returns

Number of active connections.

GAP_PasscodeUpdate()

bStatus_t GAP_PasscodeUpdate	(	uint32	passcode,
		uint16	connectionHandle
	)

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

Note

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

: Corresponding Events: This API should be called in response to receiving a GAP_PASSKEY_NEEDED_EVENT of type gapPasskeyNeededEvent_t

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 *	pPasskey,
		uint16	connectionHandle
	)

Update the passkey in string format.

Note

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

: Corresponding Events: This API should be called in response to receiving a GAP_PASSKEY_NEEDED_EVENT of type gapPasskeyNeededEvent_t

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_RegisterBondMgrCBs()

void GAP_RegisterBondMgrCBs

(

gapBondMgrCBs_t *

pCBs

)

Register bond manager call backs.

Parameters

pCBs	- pointer to Bond Manager Callbacks.

GAP_RegisterForMsgs()

void GAP_RegisterForMsgs

(

uint8

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_RemoveAdvToken()

gapAdvDataToken_t* GAP_RemoveAdvToken

(

uint8

adType

)

Remove Advertising Token.

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.

GAP_ResolvePrivateAddr()

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 Resolvable Private address

Returns

SUCCESS : match

FAILURE : don't match

INVALIDPARAMETER : parameters invalid

GAP_SendSlaveSecurityRequest()

bStatus_t GAP_SendSlaveSecurityRequest	(	uint16	connectionHandle,
		uint8	authReq
	)

Generate a Slave Requested Security message to the master.

This API can be used to initiate security as a slave.

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_SetAdvToken()

bStatus_t GAP_SetAdvToken

(

gapAdvDataToken_t *

pToken

)

Set Advertising Token.

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 Advertisement data and Scan Response Data

bleInvalidRange : token ID already exists.

bleIncorrectMode - not a peripheral device

bleMemAllocError - memory allocation failure,

GAP_SetParamValue()

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

INVALIDPARAMETER

GAP_Signable()

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.

GAP_TerminateAuth()

bStatus_t GAP_TerminateAuth	(	uint16	connectionHandle,
		uint8	reason
	)

Terminate Authnetication.

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	(	uint8	taskID,
		uint16	connectionHandle,
		uint8	reason
	)

Terminate a link connection.

Corresponding Events:

GAP_LINK_TERMINATED_EVENT of type gapTerminateLinkEvent_t

Parameters

taskID	- requesting app's task id.
connectionHandle	- connection handle of link to terminate or GAP Special Connection Handles
reason	- terminate reason.

Returns

SUCCESS : termination request sent to stack

bleIncorrectMode : No Link to terminate

bleInvalidTaskID : not app that established link

GAP_UpdateAdvertisingData()

bStatus_t GAP_UpdateAdvertisingData	(	uint8	taskID,
		uint8	adType,
		uint8	dataLen,
		uint8 *	pAdvertData
	)

Setup or change advertising and scan response data.

Corresponding Events:

GAP_ADV_DATA_UPDATE_DONE_EVENT of type gapAdvDataUpdateEvent_t

Parameters

taskID	- task to receive event
adType	- TRUE - advertisement data, FALSE - scan response data
dataLen	- Octet length of advertData
pAdvertData	- advertising or scan response data

Returns

SUCCESS : advertising data sent to stack

bleIncorrectMode : invalid profile role

GAP_UpdateAdvTokens()

bStatus_t GAP_UpdateAdvTokens

(

void

)

Update Advertising Token.

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

Returns

SUCCESS or bleIncorrectMode

GAP_UpdateLinkParamReq()

bStatus_t GAP_UpdateLinkParamReq

(

gapUpdateLinkParamReq_t *

pParams

)

Update the link parameters to a Master or Slave device.

Corresponding Events:

After the update procedure is complete, the calling task will receive a GAP_LINK_PARAM_UPDATE_EVENT of type gapLinkUpdateEvent_t

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 sent from a peer device.

Corresponding Events:

The calling task should call this API in response to a GAP_UPDATE_LINK_PARAM_REQ_EVENT of type gapUpdateLinkParamReqEvent_t

The host should fill in the connection parameters it desires as well as whether or not this request was accepted. The controller will use the connection parameters passed into this command to respond over-the-air to the peer.

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

GAP_UpdateResolvingList()

void GAP_UpdateResolvingList

(

uint8 *

pIRK

)

Update the resolving list.

Based on whether the bond manager is included, this will call HCI_LE_SetAddressResolutionEnableCmd directly or go through the bond manager.

Parameters

pIRK	- pointer to Identity Root Key, NULLKEY (all zeroes) if the app wants the GAP to generate the key.