Advertisement Event

Fired when an advertisement packet is received during scanning.

Syntax

ANSI (Cross Platform)
virtual int FireAdvertisement(BLEClientAdvertisementEventParams *e);
typedef struct {
const char *ServerId;
const char *Name;
int RSSI;
int TxPower;
const char *ServiceUuids;
const char *ServicesWithData;
const char *SolicitedServiceUuids;
int ManufacturerCompanyId;
const char *ManufacturerData; int lenManufacturerData;
int IsConnectable;
int IsScanResponse; int reserved; } BLEClientAdvertisementEventParams; Unicode (Windows) virtual INT FireAdvertisement(BLEClientAdvertisementEventParams *e);
typedef struct {
LPCWSTR ServerId;
LPCWSTR Name;
INT RSSI;
INT TxPower;
LPCWSTR ServiceUuids;
LPCWSTR ServicesWithData;
LPCWSTR SolicitedServiceUuids;
INT ManufacturerCompanyId;
LPCSTR ManufacturerData; INT lenManufacturerData;
BOOL IsConnectable;
BOOL IsScanResponse; INT reserved; } BLEClientAdvertisementEventParams;
#define EID_BLECLIENT_ADVERTISEMENT 1

virtual INT IPWORKSBLE_CALL FireAdvertisement(LPSTR &lpszServerId, LPSTR &lpszName, INT &iRSSI, INT &iTxPower, LPSTR &lpszServiceUuids, LPSTR &lpszServicesWithData, LPSTR &lpszSolicitedServiceUuids, INT &iManufacturerCompanyId, LPSTR &lpManufacturerData, INT &lenManufacturerData, BOOL &bIsConnectable, BOOL &bIsScanResponse);

Remarks

The Advertisement event is fired each time an advertisement is received while the class is Scanning for servers to connect to. Based on the information in the advertisement, you can decide whether or not you wish to connect to the associated device (if it is connectable).

Not all of the parameters are relevant for all platforms. Additionally, since advertisement packets are somewhat flexible in their contents, it is not guaranteed that every parameter relevant to your platform will be populated for every advertisement. Please refer to the following table for descriptions of the parameters:

Parameter Description
ServerId Platform-specific server Id string
Name Server's local name, either shortened or complete
RSSI Server RSSI in dBm (.NET), or dB (macOS/iOS)
TxPower Server transmit power in dBm (Or integer's MinValue if not in advertisement)
ServiceUuids Comma-separated list of 128-bit service UUID strings
ServicesWithData Comma-separated list of 128-bit service UUID strings for services which the advertisement contained data for
SolicitedServiceUuids Comma-separated list of 128-bit solicited service UUID strings
ManufacturerCompanyId Company Id from the first manufacturer data section in the advertisement (Or -1 if there are none)
ManufacturerData Data from the first manufacturer data section in the advertisement (Or empty if there are none)
IsConnectable Whether the device which sent this advertisement is accepting connections
IsScanResponse Whether this is a scan response packet

Setting the ServiceData configuration setting to any of the service UUIDs in the ServicesWithData parameter will return the associated data.

You can use the ManufacturerDataCount configuration setting to determine whether the advertisement contains multiple manufacturer data sections; if it does, the ManufacturerData and ManufacturerCompanyId configuration settings can be used to iterate over them.

Note that all of the configuration settings mentioned above are only valid while you are within the Advertisement event handler.

Please refer to the following table to determine which parameters are relevant for your platform:

Parameter .NETmacOS/iOS
ServerId X X
Name X X
RSSI X X
TxPower X X
ServiceUuids X X
ServicesWithData X X
SolicitedServiceUuids X X
ManufacturerCompanyId X X
ManufacturerData X X
IsConnectable X X
IsScanResponse X

Refer to the StartScanning method for more information.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks BLE 2020 C++ Edition - Version 20.0 [Build 8158]