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. More...

bStatus_t	GAP_SetAdvToken (gapAdvDataToken_t *pToken)
	Called to setup a GAP Advertisement/Scan Response data token. More...

gapAdvDataToken_t *	GAP_GetAdvToken (uint8 adType)
	Called to read a GAP Advertisement/Scan Response data token. More...

gapAdvDataToken_t *	GAP_RemoveAdvToken (uint8 adType)
	Called to remove a GAP Advertisement/Scan Response data token. More...

bStatus_t	GAP_UpdateAdvTokens (void)
	Called to rebuild and load Advertisement and Scan Response data from existing GAP Advertisement Tokens. More...

bStatus_t	GAP_SetParamValue (gapParamIDs_t paramID, uint16 paramValue)
	Set a GAP Parameter value. Use this function to change the default GAP parameter values. More...

uint16	GAP_GetParamValue (gapParamIDs_t paramID)
	Get a GAP Parameter value. More...

bStatus_t	GAP_ConfigDeviceAddr (uint8 addrMode, uint8 *pStaticAddr)
	Setup the device's address type. If ADDRMODE_PRIVATE_RESOLVE is selected, the address will change periodically. More...

void	GAP_RegisterForMsgs (uint8 taskID)
	Register your task ID to receive extra (unprocessed) HCI status and complete, and Host events. More...

void	GAP_RegisterBondMgrCBs (gapBondMgrCBs_t *pCBs)
	Register bond manager call backs. More...

bStatus_t	GAP_DeviceDiscoveryRequest (gapDevDiscReq_t *pParams)
	Start a device discovery scan. More...

bStatus_t	GAP_DeviceDiscoveryCancel (uint8 taskID)
	Cancel an existing device discovery request. More...

bStatus_t	GAP_MakeDiscoverable (uint8 taskID, gapAdvertisingParams_t *pParams)
	Setup or change advertising. Also starts advertising. 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_EndDiscoverable (uint8 taskID)
	Stops advertising. More...

bStatus_t	GAP_ResolvePrivateAddr (uint8 pIRK, uint8 pAddr)
	Resolves a private address against an IRK. More...

bStatus_t	GAP_EstablishLinkReq (gapEstLinkReq_t *pParams)
	Establish a link to a slave device. More...

bStatus_t	GAP_TerminateLinkReq (uint8 taskID, uint16 connectionHandle, uint8 reason)
	Terminate a link connection. 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 remote device. More...

uint8	GAP_NumActiveConnections (void)
	Returns the number of active connections. More...

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). More...

bStatus_t	GAP_TerminateAuth (uint16 connectionHandle, uint8 reason)
	Send a Pairing Failed message and end any existing pairing. More...

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. More...

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. More...

bStatus_t	GAP_SendSlaveSecurityRequest (uint16 connectionHandle, uint8 authReq)
	Generate a Slave Requested Security message to the master. More...

bStatus_t	GAP_Signable (uint16 connectionHandle, uint8 authenticated, smSigningInfo_t *pParams)
	Set up the connection to accept signed data. More...

bStatus_t	GAP_Bond (uint16 connectionHandle, uint8 authenticated, uint8 secureConnections, smSecurityInfo_t *pParams, uint8 startEncryption)
	Set up the connection's bound paramaters. More...

Detailed Description

Function Documentation

§ GAP_Authenticate()

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.

§ 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 is called after the link is established.

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
	)

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

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.

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

§ GAP_DeviceDiscoveryCancel()

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

§ GAP_DeviceDiscoveryRequest()

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

§ GAP_DeviceInit()

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

§ GAP_EndDiscoverable()

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

§ GAP_EstablishLinkReq()

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

§ GAP_GetAdvToken()

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.

§ GAP_GetParamValue()

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

§ GAP_MakeDiscoverable()

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.

§ 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). 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.

§ GAP_PasskeyUpdate()

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.

§ GAP_RegisterBondMgrCBs()

void GAP_RegisterBondMgrCBs ( gapBondMgrCBs_t * pCBs )

Register bond manager call backs.

Parameters

pCBs	- pointer to Bond Manager Callbacks.

Returns: none

§ GAP_RegisterForMsgs()

void GAP_RegisterForMsgs ( uint8 taskID )

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

Parameters

taskID - Default task ID to send events.

Returns: none

§ GAP_RemoveAdvToken()

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.

§ 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.

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 )

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 or INVALIDPARAMETER (invalid paramID)

§ 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
	)

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.

§ GAP_TerminateLinkReq()

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

§ GAP_UpdateAdvertisingData()

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,

§ GAP_UpdateAdvTokens()

bStatus_t GAP_UpdateAdvTokens ( void )

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.

Parameters

pParams - link update parameters

Returns: SUCCESS: started update link process,
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 remote device.

Parameters

pParams - local device's desired connection parameters.

Returns: SUCCESS: reply sent successfully,
INVALIDPARAMETER: one of the parameters were invalid,
bleIncorectMode: invalid profile role,
bleAlreadyInRequestedMode: already updating link parameters,
bleNotConnected: not in a connection

Functions

Detailed Description

Function Documentation

§ GAP_Authenticate()

§ GAP_Bond()

§ GAP_ConfigDeviceAddr()

§ GAP_DeviceDiscoveryCancel()

§ GAP_DeviceDiscoveryRequest()

§ GAP_DeviceInit()

§ GAP_EndDiscoverable()

§ GAP_EstablishLinkReq()

§ GAP_GetAdvToken()

§ GAP_GetParamValue()

§ GAP_MakeDiscoverable()

§ GAP_NumActiveConnections()

§ GAP_PasscodeUpdate()

§ GAP_PasskeyUpdate()

§ GAP_RegisterBondMgrCBs()

§ GAP_RegisterForMsgs()

§ GAP_RemoveAdvToken()

§ GAP_ResolvePrivateAddr()

§ GAP_SendSlaveSecurityRequest()

§ GAP_SetAdvToken()

§ GAP_SetParamValue()

§ GAP_Signable()

§ GAP_TerminateAuth()

§ GAP_TerminateLinkReq()

§ GAP_UpdateAdvertisingData()

§ GAP_UpdateAdvTokens()

§ GAP_UpdateLinkParamReq()

§ GAP_UpdateLinkParamReqReply()