This module implements the Host Advertiser. More...

Modules
	GapAdv Callbacks

	GapAdv Constants

	GapAdv Events

	GapAdv Params

	GapAdv Structures

Files
file	gap_advertiser.h
	GAP Advertiser layer interface.

Functions
bStatus_t	GapAdv_abortLoad (void)

bStatus_t	GapAdv_create (pfnGapCB_t cb, GapAdv_params_t advParam, uint8 *advHandle)

bStatus_t	GapAdv_destroy (uint8 handle, GapAdv_freeBufferOptions_t freeOptions)

bStatus_t	GapAdv_disable (uint8 handle)
	Disable an active advertising set. More...

bStatus_t	GapAdv_enable (uint8 handle, GapAdv_enableOptions_t enableOptions, uint16 durationOrMaxEvents)

bStatus_t	GapAdv_getBuffer (uint8 handle, GapAdv_dataTypes_t dataType, uint16 pLen, uint8 *ppBuf)

bStatus_t	GapAdv_getParam (uint8 handle, GapAdv_ParamId_t paramID, void pValue, uint8_t pLen)

bStatus_t	GapAdv_loadByBuffer (uint16 len, uint8 *pBuf)

bStatus_t	GapAdv_loadByHandle (uint8 handle, GapAdv_dataTypes_t dataType, uint16 len, uint8 *pBuf)

bStatus_t	GapAdv_prepareLoadByBuffer (uint8 *pBuf, bool freeOldData)

bStatus_t	GapAdv_prepareLoadByHandle (uint8 handle, GapAdv_freeBufferOptions_t freeOptions)

bStatus_t	GapAdv_setEventMask (uint8 handle, GapAdv_eventMaskFlags_t mask)

bStatus_t	GapAdv_setParam (uint8 handle, GapAdv_ParamId_t paramID, void *pValue)

Detailed Description

This module implements the Host Advertiser.

Function Documentation

§ GapAdv_abortLoad()

bStatus_t GapAdv_abortLoad ( void )

Abort an advertising load operation.

Can be used to abort a prepare or prepare / load operation after a call to GapAdv_prepareLoadByHandle or GapAdv_prepareLoadByBuffer.

Returns: SUCCESS

§ GapAdv_create()

bStatus_t GapAdv_create	(	pfnGapCB_t *	cb,
		GapAdv_params_t *	advParam,
		uint8 *	advHandle
	)

Create an advertising set.

This will allocate all required memory for the advertising set except for the advertising data. A pointer to a structure of advertising parameters (GapAdv_params_t) must be passed with advParam. This will be copied to the newly allocated memory for the advertising set and can then be freed if desired. Parameters can be changed individually later with GapAdv_setParam

Warning: It is required to pass a callback into this function in order to receive advertising events. The various events that are passed into this callback can be disabled / enabled with GapAdv_setEventMask

Parameters

cb	Function pointer to a callback for this advertising set
advParam	pointer to structure of adversing parameters
advHandle	Output parameter to return the created advertising handle

Returns: bleIncorrectMode : incorrect profile role or an update / prepare is in process; bleInvalidRange : the callback function was NULL; bleNoResources : there are no available advertising handles; bleMemAllocError : there is not enough memory to allocate the advertising set; SUCCESS

§ GapAdv_destroy()

bStatus_t GapAdv_destroy	(	uint8	handle,
		GapAdv_freeBufferOptions_t	freeOptions
	)

Delete an advertising set.

This will first disable advertising then free all of the memory that was allocated for the advertising set from GapAdv_create. It will also attempt to free the advertising / scan response data based on freeOptions.

Note: The advertising / scan response data can only be freed if the respective buffer is not used elsewhere by another advertising set.

Parameters

handle	Handle of advertising set to destroy
freeOptions	GapAdv_freeBufferOptions_t

Returns: bleIncorrectMode : incorrect profile role or an update / prepare is in process; bleGAPNotFound : advertising set does not exist; bleGAPBufferInUse : can't free since this buffer is used elsewhere; SUCCESS

§ GapAdv_disable()

bStatus_t GapAdv_disable ( uint8 handle )

Disable an active advertising set.

The set still exists and can be re-enabled with GapAdv_enable .

Corresponding Events:: @ref GAP_EVT_ADV_END_AFTER_DISABLE after advertising is disabled

Parameters

handle Handle of advertising set to disable

Returns: bleIncorrectMode : incorrect profile role or an update / prepare is in process; bleGAPNotFound : advertising set does not exist; bleAlreadyInRequestedMode : advertising set is not currently advertising; SUCCESS

§ GapAdv_enable()

bStatus_t GapAdv_enable	(	uint8	handle,
		GapAdv_enableOptions_t	enableOptions,
		uint16	durationOrMaxEvents
	)

Enable Advertising.

This will attempt to enable advertising for a set identified by the handle. The advertising set must first be created with GapAdv_create.

Corresponding Events:: GAP_EVT_ADV_START_AFTER_ENABLE after advertising is enabled
GAP_EVT_ADV_START after each advertising set starts
GAP_EVT_ADV_END after each advertising set ends
GAP_EVT_SCAN_REQ_RECEIVED after received scan requests

Parameters

handle	Handle of advertising set to enable
enableOptions	whether to advertise for the max possible time, for a user-specified duration, or for a user-specified number of advertising events
durationOrMaxEvents	If enableOptions is set to GAP_ADV_ENABLE_OPTIONS_USE_DURATION, this is the time (in 10 ms ticks) to advertise before stopping where the range is 10 ms - 655,540 ms If enableOptions is set to GAP_ADV_ENABLE_OPTIONS_USE_MAX_EVENTS, this is the maximum number of advertisements to send before stopping, where the range is 1-256 If enableOptions is set to GAP_ADV_ENABLE_OPTIONS_USE_MAX, this parameter is not used

Returns: bleIncorrectMode : incorrect profile role or an update / prepare is in process; bleGAPNotFound : advertising set does not exist; bleNotReady : the advertising set has not yet been loaded with advertising data; bleAlreadyInRequestedMode : device is already advertising; SUCCESS

§ GapAdv_getBuffer()

bStatus_t GapAdv_getBuffer	(	uint8	handle,
		GapAdv_dataTypes_t	dataType,
		uint16 *	pLen,
		uint8 **	ppBuf
	)

Find the address of the advertising or scan response data that an advertising set is using.

Warning: The ppBuf parameter is a pointer-to-a-pointer so the address to a pointer must be passed in.

Parameters

handle	Handle of advertising set to search.
dataType	GapAdv_dataTypes_t
pLen	output parameter to return length of data
ppBuf	output parameter to return pointer to data

Returns: bleIncorrectMode : incorrect profile role; bleInvalidRange : dataType out of range; bleGAPNotFound : advertising set does not exist; SUCCESS

§ GapAdv_getParam()

bStatus_t GapAdv_getParam	(	uint8	handle,
		GapAdv_ParamId_t	paramID,
		void *	pValue,
		uint8_t *	pLen
	)

Get a parameter for an advertising set.

Note: The data that the return pointer ( pValue) points to should be cast to a type based on the paramID . See the respective parameter in GapAdv_ParamId_t for the type to cast pValue to

Parameters

handle	Handle of advertising set to modify
paramID	parameter to read. See GapAdv_ParamId_t
pValue	return pointer
pLen	output parameter to return the length of the parameter. This is an optional return parameter. If the caller does not care about this, it can pass in NULL.

Returns: bleIncorrectMode : incorrect profile role; bleInvalidRange : paramID out of range; bleGAPNotFound : advertising set does not exist; SUCCESS

§ GapAdv_loadByBuffer()

bStatus_t GapAdv_loadByBuffer	(	uint16	len,
		uint8 *	pBuf
	)

Used in conjunction with GapAdv_prepareLoadByBuffer to update advertising / scan response buffers.

This function is called after GapAdv_prepareLoadByBuffer. It will search through all advertising sets and update any advertising data / scan response buffers that were marked as used by GapAdv_prepareLoadByBuffer. It will also re-enabling any advertising sets that were disabled by GapAdv_prepareLoadByBuffer.

Since this function accepts any pointer, it is possible to pass in a new buffer or re-use the original buffer (assuming it wasn't freed with GapAdv_prepareLoadByBuffer). It is also possible to modify the length of the original buffer (assuming the buffer / length still point to valid memory).

Note: The prepare / load operation must be run to completion before another prepare operation, an advertising disable, enable, create, or destroy can begin. It is possible to abort the prepare / load with GapAdv_abortLoad

Warning: It is the application's responsibility to ensure that it is passing a len / pBuf to valid memory.

Parameters

len	length of buffer to load
pBuf	pointer to buffer to load

Returns: bleIncorrectMode : incorrect profile role or GapAdv_prepareLoadByBuffer has not been called first; SUCCESS

§ GapAdv_loadByHandle()

bStatus_t GapAdv_loadByHandle	(	uint8	handle,
		GapAdv_dataTypes_t	dataType,
		uint16	len,
		uint8 *	pBuf
	)

Load advertising / scan response data to an advertising set.

The first use for this function is to load a new advertising / scan response buffer to the advertising set initially after the set has been created with GapAdv_create.

A second use for this function is in conjunction with GapAdv_prepareLoadByHandle in order to prevent double-copying of data when updating the advertising / scan response data for a single handle. Also, advertising will be automatically re-enabled by the host if it was disabled during GapAdv_prepareLoadByHandle. This will result in the application receiving the GAP_EVT_ADV_START_AFTER_ENABLE event.

Since this function accepts any pointer, it is possible to pass in a new buffer or re-use the original buffer (assuming it wasn't freed with GapAdv_prepareLoadByHandle). It is also possible to modify the length of the original buffer (assuming the buffer / length still point to valid memory).

Note: The prepare / load operation must run to completion before another prepare operation or advertising disable, enable, create, or destroy. It is possible to abort the prepare / load with GapAdv_abortLoad.

Warning: It is the application's responsibility to ensure that it is passing a len / pBuf to valid memory.

Corresponding Events: GAP_EVT_ADV_START_AFTER_ENABLE

Parameters

handle	Handle of advertising to (re)load advertising / scan response data
dataType	see GapAdv_dataTypes_t
len	Length of new data
pBuf	pointer to new data

Returns: bleIncorrectMode : incorrect profile role or GapAdv_prepareLoadByHandle has not been called first; bleInvalidRange : dataType out of range or len is too large; bleGAPNotFound : advertising set does not exist; bleGAPBufferInUse : can't free because this buffer is used elsewhere; SUCCESS

§ GapAdv_prepareLoadByBuffer()

bStatus_t GapAdv_prepareLoadByBuffer	(	uint8 *	pBuf,
		bool	freeOldData
	)

Used in conjunction with GapAdv_loadByBuffer to update an advertising / scan response buffer that is used by multiple advertising handles.

This function must be used in the following cases:

It is desired to update the contents of a data buffer that is currently being used by multiple advertising sets
It is desired to load a new buffer to multiple advertising sets without double-copying

This function is called first to search through all active advertising sets. If the advertising or scan response data of an advertising set matches the input buffer, this data will be marked as used. If the advertising set is currently advertising, it will be disabled and marked for re-enabling. This re-enabling will occur when GapAdv_loadByBuffer is called.

For case 1, the buffer can be updated as desired after this function returns successfully, then reloaded with GapAdv_loadByBuffer

For case 2, in order to prevent double-copying, the data that was being used by the advertising sets should be freed before calling GapAdv_loadByBuffer. It is recommended that this is done by setting the freeOldData of GapAdv_prepareLoadByBuffer. The new buffer can then be loaded with GapAdv_loadByBuffer

Note: The prepare / load operation must run to completion before another prepare operation, an advertising disable, enable, create, or destroy can begin. It is possible to abort the prepare / load with GapAdv_abortLoad.

Parameters

pBuf	pointer to buffer to prepare
freeOldData	whether or not free the old pointer

Returns: bleIncorrectMode : incorrect profile role or there is already an ongoing prepare or prepare / load; bleGAPNotFound : no advertising sets are using this buffer; SUCCESS

§ GapAdv_prepareLoadByHandle()

bStatus_t GapAdv_prepareLoadByHandle	(	uint8	handle,
		GapAdv_freeBufferOptions_t	freeOptions
	)

Prepares advertising for a given handle and optionally frees the old data that was being used for advertisement / scan response data.

This function must be used in the following cases:

It is desired to update the contents of a data buffer that is currently being used for an enabled advertising handle
It is desired to load a new buffer to an advertising handle

This function is used in conjunction with GapAdv_loadByHandle to support either of the cases stated above. This function is called first before GapAdv_loadByHandle and will disable advertising on the handle if it is currently enabled. This will result in the GAP_EVT_ADV_END_AFTER_DISABLE being sent

For case 1, the buffer can be updated as desired after this function returns successfully, then reloaded with GapAdv_loadByHandle

For case 2, in order to prevent double-copying, the data that was being used by the advertising set should be freed before calling GapAdv_loadByHandle. It is recommended that this is done by setting the freeOptions of GapAdv_prepareLoadByHandle . This will prompt the host to search through other advertising sets to ensure that the data buffer is not being used elsewhere. If the data is being used elsewhere, the free will not occur and bleGAPBufferInUse will be returned. In this case, there are now two options to update this advertising data.

If it is desired to only update this handle, the only way to do this is to: destroy this handle with GapAdv_destroy, recreate this handle with GapAdv_create, and load it using GapAdv_loadByHandle
Update the buffer (which will affect all handles using this buffer) using GapAdv_prepareLoadByBuffer and GapAdv_loadByBuffer

Both of these options require first aborting this prepare operation with GapAdv_abortLoad

Note: It is not possible to free the advertising data and the scan response at the same time. A prepare / load operation must run to completion before performing another prepare operation, an advertising disable, enable, create or destroy. It is possible to abort the prepare / load with GapAdv_abortLoad .

Corresponding events: GAP_EVT_ADV_END_AFTER_DISABLE

Parameters

handle	Handle of advertising set to prepare
freeOptions	Whether to free the original buffer and, if so, whether it is advertising data or scan response data

Returns: bleIncorrectMode : incorrect profile role or there is already an ongoing prepare or prepare / load; bleInvalidRange : freeOptions out of range; bleGAPNotFound : advertising set does not exist; bleAlreadyInRequestedMode : advertising set is not currently advertising; bleGAPBufferInUse : can't free because this buffer is used elsewhere; SUCCESS

§ GapAdv_setEventMask()

bStatus_t GapAdv_setEventMask	(	uint8	handle,
		GapAdv_eventMaskFlags_t	mask
	)

Set the per-advertising set event mask to select which events are sent

A value of 1 enables the event and a value of 0 disables the event

Parameters

handle	handle of advertising set to mask events for
mask	A bitfield to enable / disable events returned to the per-advertising set callback function (pfnGapCB_t ). See GapAdv_eventMaskFlags_t

Returns: bleIncorrectMode : incorrect profile role; bleInvalidRange : invalid event mask; bleGAPNotFound : advertising set does not exist; bleNotReady : advertising needs to be disabled; SUCCESS

§ GapAdv_setParam()

bStatus_t GapAdv_setParam	(	uint8	handle,
		GapAdv_ParamId_t	paramID,
		void *	pValue
	)

Set a parameter for an advertising set.

The input pointer (pValue) should point to a type based on the paramID. See the respective parameter in GapAdv_ParamId_t for the type to pass in as pValue

Note: Advertising must be disabled in order to update a parameter.

Parameters

handle	Handle of advertising set to modify
paramID	parameter to update. See GapAdv_ParamId_t
pValue	input pointer

Returns: bleIncorrectMode : incorrect profile role; bleInvalidRange : paramID out of range; bleGAPNotFound : advertising set does not exist; SUCCESS

Modules

Files

Functions

Detailed Description

Function Documentation

§ GapAdv_abortLoad()

§ GapAdv_create()

§ GapAdv_destroy()

§ GapAdv_disable()

§ GapAdv_enable()

§ GapAdv_getBuffer()

§ GapAdv_getParam()

§ GapAdv_loadByBuffer()

§ GapAdv_loadByHandle()

§ GapAdv_prepareLoadByBuffer()

§ GapAdv_prepareLoadByHandle()

§ GapAdv_setEventMask()

§ GapAdv_setParam()