TI BLE5-Stack API Documentation
2.02.08.00
|
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_loadByBuffer_hook (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) |
bStatus_t | GapAdv_SetPeriodicAdvData (uint8 advHandle, GapAdv_periodicAdvData_t *periodicAdvData) |
bStatus_t | GapAdv_SetPeriodicAdvEnable (uint8 enable, uint8 advHandle) |
uint8_t | GapAdv_SetPeriodicAdvParams (uint8 advHandle, GapAdv_periodicAdvParams_t *periodicAdvParams) |
bStatus_t | GapAdv_setVirtualAdvAddr (uint8 advHandle, uint8 *bdAddr) |
This module implements the Host Advertiser.
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.
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
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 |
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.
handle | Handle of advertising set to destroy |
freeOptions | GapAdv_freeBufferOptions_t |
bStatus_t GapAdv_disable | ( | uint8 | handle | ) |
Disable an active advertising set.
The set still exists and can be re-enabled with GapAdv_enable .
handle | Handle of advertising set to disable |
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.
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 |
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.
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 |
bStatus_t GapAdv_getParam | ( | uint8 | handle, |
GapAdv_ParamId_t | paramID, | ||
void * | pValue, | ||
uint8_t * | pLen | ||
) |
Get a parameter for an advertising set.
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. |
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).
len | length of buffer to load |
pBuf | pointer to buffer to load |
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).
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 |
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:
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
pBuf | pointer to buffer to prepare |
freeOldData | whether or not free the old pointer |
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:
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.
Both of these options require first aborting this prepare operation with GapAdv_abortLoad
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 |
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
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 |
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
handle | Handle of advertising set to modify |
paramID | parameter to update. See GapAdv_ParamId_t |
pValue | input pointer |
bStatus_t GapAdv_SetPeriodicAdvData | ( | uint8 | advHandle, |
GapAdv_periodicAdvData_t * | periodicAdvData | ||
) |
GapAdv_SetPeriodicAdvData
Used to set the advertiser data used in periodic advertising PDUs. This command may be issued at any time after the advertising set identified by the Advertising_Handle parameter has been configured for periodic advertising
/ref did_302932730
advHandle | - Used to identify a periodic advertising train |
periodicAdvData | - Pointer to periodic advertising data |
bStatus_t GapAdv_SetPeriodicAdvEnable | ( | uint8 | enable, |
uint8 | advHandle | ||
) |
GapAdv_SetPeriodicAdvEnable
Used to request the advertiser to enable or disable the periodic advertising for the advertising set
/ref did_302932730
enable | - 0x00 - Periodic advertising is disabled (default) 0x01 - Periodic advertising is enabled |
advHandle | - Used to identify a periodic advertising train |
uint8_t GapAdv_SetPeriodicAdvParams | ( | uint8 | advHandle, |
GapAdv_periodicAdvParams_t * | periodicAdvParams | ||
) |
GapAdv_SetPeriodicAdvParams
Set the advertiser parameters for the periodic advertising
/ref did_302932730
advHandle | - Used to identify a periodic advertising train Created after creating extended advertising using GapAdv_create |
periodicAdvParams | - Pointer to periodic advertising parameters |
bStatus_t GapAdv_setVirtualAdvAddr | ( | uint8 | advHandle, |
uint8 * | bdAddr | ||
) |
Set the advertiser's virtual public address.
This API should be used after a handle was created using GapAdv_create and before enabling the advertise set using GapAdv_enable. Setting virtual address is allowed only for Legacy Non-Connectable and Non-Scanable PDUs. The virtual public address is not associated with the device's assigned public address.
/ref 239346186
advHandle | handle of the relevant advertise set. |
bdAddr | public virtual address which need to be assigned to the handle. |