BLEClient Class

Properties   Methods   Events   Config Settings   Errors  

An easy-to-use Bluetooth Low Energy (BLE) GATT Client class.

Syntax

BLEClient

Remarks

The BLEClient class provides a simple but flexible BLE GATT client implementation, making it easy to work with the services, characteristics, and descriptors exposed by BLE GATT servers on remote devices.

Prerequisites

Important: Please note that the BLEClient component is only supported by Windows 10 Creator's Update (10.0.15063.0) and later.

C++ Options:

Additionally note that when using the C++ edition, the project must have the following options (found under Project Settings).

  • C/C++ > General > Consume Windows Runtime Extension > Yes(/ZW)
  • C/C++ > General > Additional #using Directories > "$(WindowsSdkDir_10)\UnionMetadata\10.0.15063.0;$(VSAPPIDDIR)\VC\vcpackages"
  • C/C++ > Code Generation > Enable Minimal Rebuild > No (/GM-)
Further, a threading model must be specified for the entry point, typically the "main" method. Here are a few examples: [Platform::MTAThread] int main(int argc, char* argv[]) ... [Platform::STAThread] int main(int argc, char* argv[]) ... int main(Platform::Array<Platform::String^>^ args)

Scanning and Connecting

To begin, call the StartScanning method, optionally passing in a list of service UUIDs that you're interested in so that irrelevant devices are ignored during scanning. While the class is scanning, the Advertisement event will fire for each relevant advertisement received from a GATT server.

The Advertisement event provides a wealth of information about the remote device, such as its Id and local name, whether or not you can connect to it, the list of service UUIDs it's advertising, and much more.

Once you've determined what device you wish to connect to, call the Connect method and pass its server Id, obtained from the Advertisement event. The class will stop scanning, then attempt to connect to the device. The Connected event is fired when the connection attempt finishes, and will contain error information in case of a failure.

// StartScan, StopScan, and Advertisement event handlers. bleclient1.OnStartScan += (s, e) => Console.WriteLine("Scanning has started"); bleclient1.OnStopScan += (s, e) => Console.WriteLine("Scanning has stopped"); bleclient1.OnAdvertisement += (s, e) => { // Your application should make every effort to handle the Advertisement event quickly. // BLEClient fires it as often as necessary, often multiple times per second. Console.WriteLine("Advertisement Received:\r\n\tServerId: " + e.ServerId + "\r\n\tName: " + e.Name + "\r\n\tServiceUuids: " + e.ServiceUuids + "\r\n\tManufacturerCompanyId: " + e.ManufacturerCompanyId + "\r\n\tIsConnectable: " + e.IsConnectable); }; // Scan for all devices. bleclient1.StartScanning(""); // Alternatively, you can scan for devices advertising specific service UUIDs. You can use a // mixture of 16-, 32-, and 128-bit UUID strings, they'll be converted to 128-bit internally. bleclient1.StartScanning("180A,0000180F,00001801-0000-1000-8000-00805F9B34FB"); // ...Once you find a device you wish to connect to... bleclient1.Connect("SERVER_ID");

Refer the StartScanning for more detailed code examples.

Service, Characteristic, and Descriptor Discovery

Once connected to a device, the next step is to discover the services that you're interested in. To do this, call the DiscoverServices method, optionally passing a list of service UUIDs to limit the discovery process. For each service discovered, ServiceCount will be incremented, and the Discovered event will fire.

After you've discovered the services you're interested in, you have to discover those services' characteristics. This is done with the DiscoverCharacteristics method, passing the Id of the service you wish to discover characteristics for, and optionally passing a list of characteristic UUIDs to limit the discovery process. For each characteristic discovered, CharacteristicCount will be incremented, and the Discovered event will fire.

Finally, you can discover descriptors for the discovered characteristics. To do this, you use the DiscoverDescriptors method, passing the Id of a characteristic, as well as the Id of the service which owns it. For each descriptor discovered, DescriptorCount will be incremented, and the Discovered event will fire.

If you would prefer to do multiple discovery steps with a single call, you can use the Discover method rather than the individual DiscoverServices, DiscoverCharacteristics, and DiscoverDescriptors methods. However, keep in mind that doing so will consume more power up front. Discovering services, characteristics, and descriptors as you need them is more energy-efficient.

// Discovered event handler. bleclient1.OnDiscovered += (s, e) => { string gattType = e.GattType == 0 ? "Service" : (e.GattType == 1 ? "Characteristic" : "Descriptor"); Console.WriteLine(gattType + " discovered:" + // The 128-bit UUID string, "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX". "\r\n\tUUID: " + e.Uuid + // For standard GATT objects whose UUIDs are defined by the Bluetooth // SIG, the Description event parameter will contain their name. "\r\n\tDescription: " + e.Description); }; string serviceIds = "180A,F000AA70-0451-4000-B000-000000000000,F000AA20-0451-4000-B000-000000000000"; // Discover specific root services. bleclient1.DiscoverServices(serviceIds, ""); foreach (Service s in bleclient1.Services) { // Discover all characteristics for this service. bleclient1.DiscoverCharacteristics(s.Id, ""); bleclient1.Service = s.Id; foreach (Characteristic c in bleclient1) { // Discover all descriptors for this characteristic. bleclient1.DiscoverDescriptors(s.Id, c.Id); } }

Refer to DiscoverServices, DiscoverCharacteristics, DiscoverDescriptors, and Discover for more detailed code examples.

Working with Discovered Data

Once you've discovered the services, characteristics, and descriptors that you need, you'll want to make use of them. BLEClient makes it easy to navigate the GATT data hierarchy. Start by iterating over the objects in the Services collection and inspecting the information discovered for each service.

Set the Service property to a specific service's Id to have the class populate the Characteristics collection based on the characteristics discovered for that service. You can then iterate over the characteristic objects to inspect the details of each characteristic. Depending on what flags a characteristic has, you may also be able to directly manipulate some of its information.

Set the Characteristic property to a specific characteristic's Id to have the class populate the Descriptors collection based on the descriptors discovered for that characteristic. You can then iterate over the descriptor objects to inspect the details of each descriptor.

// Loop through all discovered GATT objects and print out their UUIDs and descriptions. foreach (Service s in bleclient1.Services) { Console.WriteLine("Service: " + s.Description + " (" + s.Uuid + ")"); // Select this service and loop through its characteristics. bleclient1.Service = s.Id; foreach (Characteristic c in bleclient1.Characteristics) { Console.WriteLine("\tCharacteristic: " + c.Description + " (" + c.Uuid + ")"); // Select this characteristic and loop through its descriptors. bleclient1.Characteristic = c.Id; foreach (Descriptor d in bleclient1.Descriptors) { Console.WriteLine("\t\tDescriptor: " + d.Description + " (" + d.Uuid + ")"); } } }

Reading and Writing Values

The BLEClient class exposes CharacteristicCachedValue and DescriptorCachedValue fields, which retrieve values from the local system's value cache, preventing unnecessary power drain involved with communicating with the device.

// Print the cached value for a characteristic (which you can assume // we've already found and assigned to a variable called "c"). Console.WriteLine("Characteristic Value: " + BitConverter.ToUInt16(c.CachedValueB, 0)); // Print the cached value for a descriptor (again, assume it's stored in "d"). Console.WriteLine("Descriptor Value: " + BitConverter.ToString(d.CachedValueB));

To read a value directly from the remote device's GATT server, use the ReadValue method. For characteristics, you'll need to pass the Ids of the characteristic and the service which owns it. For descriptors, you'll pass both of those, as well as the Id of the descriptor. If the read succeeds, the method will return the value read from the device, and the Value event will be fired. If the read fails, the Error event is fired and the class fails with an error.

// Value event handler. bleclient1.OnValue += (s, e) => { Console.WriteLine("Read value {" + BitConverter.ToString(e.ValueB) + "} for " + (string.IsNullOrEmpty(e.DescriptorId) ? "characteristic" : "descriptor") + " with UUID " + e.Uuid); }; // Prints the live value for a characteristic. bleclient1.ReadValue("001C00000000", "001C001D0000", ""); // Prints the live value for a descriptor. bleclient1.ReadValue("001C00000000", "001C001D0000", "001C001D0021");

To write a characteristic or descriptor value, call the WriteValue method, passing the appropriate Ids and the value to be written. If the write succeeds, the method will return and the WriteResponse event will fire. If the write fails, the Error event is fired and the class fails with an error.

// WriteResponse event handler. bleclient1.OnWriteResponse += (s, e) => { string gattType = string.IsNullOrEmpty(e.DescriptorId) ? "characteristic" : "descriptor"; Console.WriteLine("Successfully wrote to " + gattType + " with UUID " + e.Uuid); }; // Write to a characteristic. bleclient1.WriteValue("004200000000", "004200460000", "", new byte[] { 0x1 }); // Write to a descriptor. bleclient1.WriteValue("004200000000", "004200430000", "004200430045", new byte[] { 0x1 });

You can also use the PostValue method to write values to characteristics that have the "Write Without Response" flag. Posting a value to a characteristic is more energy-efficient since the remote device's GATT server won't send back an acknowledgement, even if the write fails.

// Write without response to a characteristic. bleclient1.PostValue("00AA00000000", "00AA00BB0000", new byte[] { 0x1, 0x2, 0x3 });

Keep in mind that not all characteristics and descriptors support value writes, and some might not even support value reads. If you attempt to perform an operation that a characteristic or descriptor doesn't support, the class fails with an error.

For characteristics, you can inspect the CharacteristicFlags field to determine what operations the characteristic supports. For descriptors, you'll either need to know in advance what operations are supported, or be ready to handle exceptions which may occur.

Refer to ReadValue, WriteValue, and PostValue for more detailed code examples.

Subscribing to Characteristics

One of the most important features of the BLE GATT data model is the ability for a GATT server to send characteristic value updates to interested GATT clients in real-time. A GATT client can subscribe to either notifications or indications to get value updates. The difference between the two is simple: notifications are not acknowledged by GATT clients, while indications are.

When you want to subscribe to a characteristic, start by checking the CharacteristicCanSubscribe field to determine if it supports subscriptions.

For characteristics which do support subscriptions, you can subscribe and unsubscribe by using either the CharacteristicSubscribed field or the Subscribe and Unsubscribe methods. The Subscribed and Unsubscribed events are fired whenever a characteristic's subscription state changes, and the Value event is fired whenever a value update is received.

Note that characteristics do not have to support both subscription types, or even one of them. For characteristics which do support both, the class will subscribe for notifications by default. If you'd prefer that it subscribe for indications instead, enable the PreferIndications configuration setting.

// Subscribed, Unsubscribed, and Value event handlers. bleclient1.OnSubscribed += (s, e) => { Console.WriteLine("Subscribed to characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; bleclient1.OnUnsubscribed += (s, e) => { Console.WriteLine("Unsubscribed from characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; bleclient1.OnValue += (s, e) => { Console.WriteLine("Value update received for characteristic: " + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description + "\r\n\tValue: " + BitConverter.ToString(e.ValueB)); }; // Assume that we've already found a characteristic, its owning service, // and a descriptor on it; and we've stored them in variables called "c", // "s", and "d", respectively. You can subscribe to and unsubscribe from // the characteristic using any, or all, of the three methods below. // Subscribe and unsubscribe using methods. bleclient1.Subscribe(s.Id, c.Id); // ... bleclient1.Unsubscribe(s.Id, c.Id); // Subscribe and unsubscribe using the "Subscribed" field. c.Subscribed = true; // ... c.Subscribed = false; // Subscribe and unsubscribe by writing directly to the CCCD. bleclient1.WriteValue(s.Id, c.Id, d.Id, new byte[] { 1, 0 }); // ... bleclient1.WriteValue(s.Id, c.Id, d.Id, new byte[] { 0, 0 });

Usage Notes

It is very important that you do not block or perform any long-running operations within the class's event handlers. The platform APIs that the class uses rely on timely delivery of events in order to function properly.

Most platforms will in some way limit the use of Bluetooth APIs when your application is in the background. Be aware of the limitations your platform places on the usage of BLE APIs while in the background, and be ready to act accordingly.

Be sure to disconnect from a remote device by calling Disconnect when you're finished using it. When you're completely finished using the BLEClient class, be sure that you've called StopScanning and Disconnect before disposing of the instance.

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

ActiveScanningWhether to use active scanning.
CharacteristicThe currently selected characteristic's Id.
CharacteristicsThe characteristics which have been discovered for the currently selected service.
DescriptorsThe descriptors which have been discovered for the currently selected characteristic.
ScanningWhether or not the class is currently scanning for servers.
ServerIdPlatform-specific string identifying the currently connected server.
ServerNameLocal name of the currently connected server.
ServiceThe currently selected service's Id.
ServicesThe services which have been discovered on the currently connected server.
TimeoutA timeout for the class.

Method List


The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

CheckCharacteristicSubscribedChecks to see if the class is subscribed to a characteristic.
ConfigSets or retrieves a configuration setting.
ConnectConnect to a BLE GATT server based on its identifier.
DisconnectDisconnects from the remote server.
DiscoverConvenience method to discover multiple levels of the GATT object hierarchy at once.
DiscoverCharacteristicsUsed to discover characteristics for a specific service.
DiscoverDescriptorsUsed to discover all descriptors for a specific characteristic.
DiscoverServicesUsed to discover services for the currently connected server.
DoEventsThis method processes events from the internal message queue.
PostValueWrite the value of a characteristic without expecting a response.
QueryCharacteristicCachedValReads and returns a characteristic value from the value cache.
QueryDescriptorCachedValReads and returns a descriptor value from the value cache.
ReadValueRead the value of a characteristic or descriptor from the server.
SelectUsed to set the currently selected service and characteristic by their Ids.
StartScanningCauses the class to begin scanning for BLE GATT servers.
StopScanningCauses the class to stop scanning for BLE GATT servers.
SubscribeSubscribes to value updates for the specified characteristic.
UnsubscribeUnsubscribes from value updates for one or more characteristics.
WriteValueWrite the value of a characteristic or descriptor.

Event List


The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

AdvertisementFired when an advertisement packet is received during scanning.
ConnectedFired immediately after a connection to a remote device completes (or fails).
DisconnectedFired when the class has been disconnected from the remote device.
DiscoveredFired when the class discovers a service, characteristic, or descriptor.
ErrorFired when information is available about errors during data delivery.
LogFires once for each log message.
PairingRequestTBD.
ServerUpdateFired when the currently connected server updates its name or available services.
StartScanFired when the class starts scanning.
StopScanFired when the class stops scanning.
SubscribedFired when the class has successfully subscribed to a characteristic.
UnsubscribedFired when the class has successfully unsubscribed from a characteristic.
ValueFired when a characteristic or descriptor value is received from the server.
WriteResponseFired when the server acknowledges a successful value write request.

Config Settings


The following is a list of config settings for the class with short descriptions. Click on the links for further details.

AutoDiscoverCharacteristicsWhether to automatically discover all characteristics when a service is discovered.
AutoDiscoverDescriptorsWhether to automatically discover all descriptors when a characteristic is discovered.
AutoDiscoverIncludedServicesWhether to automatically discover all included services when a service is discovered.
GattObjTreeInfoReturns a string representation of the currently discovered GATT object tree.
IncludeRediscoveredWhether to fire the Discovered event for rediscovered services, characteristics, and descriptors.
LogLevelThe level of detail that is logged.
ManufacturerCompanyId[i]The manufacturer company Id at index 'i'.
ManufacturerData[i]The manufacturer data at index 'i'.
ManufacturerDataCountThe number of manufacturer data sections an advertisement has.
ScanStartedTimeoutThe maximum amount of time to wait for scanning to start.
ServiceDataGets the data associated with a service UUID from an advertisement.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
MaskSensitiveDataWhether sensitive data is masked in log messages.
ProcessIdleEventsWhether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillisThe length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPIWhether or not to use the system security libraries or an internal implementation.

ActiveScanning Property (BLEClient Class)

Whether to use active scanning.

Syntax

ANSI (Cross Platform)
int GetActiveScanning();
int SetActiveScanning(int bActiveScanning); Unicode (Windows) BOOL GetActiveScanning();
INT SetActiveScanning(BOOL bActiveScanning);
int ipworksble_bleclient_getactivescanning(void* lpObj);
int ipworksble_bleclient_setactivescanning(void* lpObj, int bActiveScanning);
bool GetActiveScanning();
int SetActiveScanning(bool bActiveScanning);

Default Value

FALSE

Remarks

When enabled, the class will instruct the system to use active scanning rather than passive scanning, at the cost of higher power consumption.

Active scanning causes the system's BLE API to request a scan response packet for each advertisement received, which in turn means that you will be able to get more information from devices without connecting to them.

The tradeoff is that enabling this feature increases power consumption for both the client and server, but if your use-case doesn't call for ever actually connecting to the devices (which itself can be a power-intensive operation), then that tradeoff might be mitigated.

Note that you cannot change the value of the ActiveScanning property if the class is already scanning.

Active Scanning // Enable active scanning. bleclient1.ActiveScanning = true; bleclient1.StartScanning(""); // ... bleclient1.StopScanning();

This property is not available at design time.

Data Type

Boolean

Characteristic Property (BLEClient Class)

The currently selected characteristic's Id.

Syntax

ANSI (Cross Platform)
char* GetCharacteristic();
int SetCharacteristic(const char* lpszCharacteristic); Unicode (Windows) LPWSTR GetCharacteristic();
INT SetCharacteristic(LPCWSTR lpszCharacteristic);
char* ipworksble_bleclient_getcharacteristic(void* lpObj);
int ipworksble_bleclient_setcharacteristic(void* lpObj, const char* lpszCharacteristic);
QString GetCharacteristic();
int SetCharacteristic(QString qsCharacteristic);

Default Value

""

Remarks

Setting the Characteristic property to the Id of a discovered characteristic allows you to inspect the descriptors which have been discovered for it using the Descriptors collection.

Characteristic can either be set to the Id of a characteristic which has been discovered for the service currently selected by Service, or to empty string.

This property is automatically set when you call the Select method; and it is reset to empty string when you set Service.

This property is not available at design time.

Data Type

String

Characteristics Property (BLEClient Class)

The characteristics which have been discovered for the currently selected service.

Syntax

IPWorksBLEList<IPWorksBLECharacteristic>* GetCharacteristics();
int SetCharacteristics(IPWorksBLEList<IPWorksBLECharacteristic>* val);
int ipworksble_bleclient_getcharacteristiccount(void* lpObj);
int ipworksble_bleclient_setcharacteristiccount(void* lpObj, int iCharacteristicCount);
int ipworksble_bleclient_getcharacteristiccansubscribe(void* lpObj, int characteristicindex);
char* ipworksble_bleclient_getcharacteristicdescription(void* lpObj, int characteristicindex);
int ipworksble_bleclient_getcharacteristicflags(void* lpObj, int characteristicindex);
char* ipworksble_bleclient_getcharacteristicid(void* lpObj, int characteristicindex);
char* ipworksble_bleclient_getcharacteristicuserdescription(void* lpObj, int characteristicindex);
int ipworksble_bleclient_setcharacteristicuserdescription(void* lpObj, int characteristicindex, const char* lpszCharacteristicUserDescription);
char* ipworksble_bleclient_getcharacteristicuuid(void* lpObj, int characteristicindex);
int ipworksble_bleclient_getcharacteristicvalueexponent(void* lpObj, int characteristicindex);
int ipworksble_bleclient_getcharacteristicvalueformat(void* lpObj, int characteristicindex);
int ipworksble_bleclient_getcharacteristicvalueformatcount(void* lpObj, int characteristicindex);
int ipworksble_bleclient_getcharacteristicvalueformatindex(void* lpObj, int characteristicindex);
int ipworksble_bleclient_setcharacteristicvalueformatindex(void* lpObj, int characteristicindex, int iCharacteristicValueFormatIndex);
char* ipworksble_bleclient_getcharacteristicvalueunit(void* lpObj, int characteristicindex);
int GetCharacteristicCount();
int SetCharacteristicCount(int iCharacteristicCount); bool GetCharacteristicCanSubscribe(int iCharacteristicIndex); QString GetCharacteristicDescription(int iCharacteristicIndex); int GetCharacteristicFlags(int iCharacteristicIndex); QString GetCharacteristicId(int iCharacteristicIndex); QString GetCharacteristicUserDescription(int iCharacteristicIndex);
int SetCharacteristicUserDescription(int iCharacteristicIndex, QString qsCharacteristicUserDescription); QString GetCharacteristicUuid(int iCharacteristicIndex); int GetCharacteristicValueExponent(int iCharacteristicIndex); int GetCharacteristicValueFormat(int iCharacteristicIndex); int GetCharacteristicValueFormatCount(int iCharacteristicIndex); int GetCharacteristicValueFormatIndex(int iCharacteristicIndex);
int SetCharacteristicValueFormatIndex(int iCharacteristicIndex, int iCharacteristicValueFormatIndex); QString GetCharacteristicValueUnit(int iCharacteristicIndex);

Remarks

The characteristics which have been discovered for the service currently selected with Service. This collection is populated when characteristics are discovered for a service, which may occur due to a call to the Discover or DiscoverCharacteristics methods, or at the time when a service is discovered (if you have the AutoDiscoverCharacteristics configuration setting enabled).

Characteristics do not all have to be discovered at one time, and additional characteristics discovered for a service will automatically be added to this collection upon discovery. This collection is cleared when the class disconnects from the server.

If Service is set to empty string, or if no characteristics have been discovered for the currently selected service, this collection will be empty.

This property is not available at design time.

Data Type

IPWorksBLECharacteristic

Descriptors Property (BLEClient Class)

The descriptors which have been discovered for the currently selected characteristic.

Syntax

IPWorksBLEList<IPWorksBLEDescriptor>* GetDescriptors();

int ipworksble_bleclient_getdescriptorcount(void* lpObj);
char* ipworksble_bleclient_getdescriptordescription(void* lpObj, int descriptorindex);
char* ipworksble_bleclient_getdescriptorid(void* lpObj, int descriptorindex);
char* ipworksble_bleclient_getdescriptoruuid(void* lpObj, int descriptorindex);
int GetDescriptorCount();

QString GetDescriptorDescription(int iDescriptorIndex);

QString GetDescriptorId(int iDescriptorIndex);

QString GetDescriptorUuid(int iDescriptorIndex);

Remarks

The descriptors which have been discovered for the characteristic currently selected with Characteristic. This collection is populated when descriptors are discovered for a characteristic, which may occur due to a call to the Discover or DiscoverDescriptors methods, or at the time when a characteristic is discovered (if you have the AutoDiscoverDescriptors configuration setting enabled).

Descriptors do not all have to be discovered at one time, and additional descriptors discovered for a characteristic will automatically be added to this collection upon discovery. This collection is cleared when the class disconnects from the server.

If Characteristic is set to empty string, or if no descriptors have been discovered for the currently selected characteristic, this collection will be empty.

This property is read-only and not available at design time.

Data Type

IPWorksBLEDescriptor

Scanning Property (BLEClient Class)

Whether or not the class is currently scanning for servers.

Syntax

ANSI (Cross Platform)
int GetScanning();

Unicode (Windows)
BOOL GetScanning();
int ipworksble_bleclient_getscanning(void* lpObj);
bool GetScanning();

Default Value

FALSE

Remarks

This property indicates whether or not the class is currently scanning for servers. While the class is scanning, the Advertisement event will be fired whenever an advertisement from a remote device is received.

Refer to the StartScanning method for more information.

This property is read-only and not available at design time.

Data Type

Boolean

ServerId Property (BLEClient Class)

Platform-specific string identifying the currently connected server.

Syntax

ANSI (Cross Platform)
char* GetServerId();

Unicode (Windows)
LPWSTR GetServerId();
char* ipworksble_bleclient_getserverid(void* lpObj);
QString GetServerId();

Default Value

""

Remarks

When the class is connected to a server, this property contains the platform-specific server identification string.

Note that this value is not guaranteed to be the same at any point in time for a specific server device.

This property is read-only and not available at design time.

Data Type

String

ServerName Property (BLEClient Class)

Local name of the currently connected server.

Syntax

ANSI (Cross Platform)
char* GetServerName();

Unicode (Windows)
LPWSTR GetServerName();
char* ipworksble_bleclient_getservername(void* lpObj);
QString GetServerName();

Default Value

""

Remarks

When the class is connected to a server, this property contains the server's local name.

If the server's name changes while you're connected to it, the ServerUpdate event will fire with the Name parameter populated, and the new value will be reflected here.

This property is read-only and not available at design time.

Data Type

String

Service Property (BLEClient Class)

The currently selected service's Id.

Syntax

ANSI (Cross Platform)
char* GetService();
int SetService(const char* lpszService); Unicode (Windows) LPWSTR GetService();
INT SetService(LPCWSTR lpszService);
char* ipworksble_bleclient_getservice(void* lpObj);
int ipworksble_bleclient_setservice(void* lpObj, const char* lpszService);
QString GetService();
int SetService(QString qsService);

Default Value

""

Remarks

Setting the Service property to the Id of a discovered service allows you to inspect the characteristics which have been discovered for it using the Characteristics collection.

Service can either be set to the Id of a service which has been discovered for the currently connected server, or to empty string. Setting Service will automatically reset Characteristic to empty string.

This property is automatically set when you call the Select method.

This property is not available at design time.

Data Type

String

Services Property (BLEClient Class)

The services which have been discovered on the currently connected server.

Syntax

int ipworksble_bleclient_getservicecount(void* lpObj);
char* ipworksble_bleclient_getservicedescription(void* lpObj, int serviceindex);
char* ipworksble_bleclient_getserviceid(void* lpObj, int serviceindex);
char* ipworksble_bleclient_getserviceincludedsvcids(void* lpObj, int serviceindex);
char* ipworksble_bleclient_getserviceparentsvcids(void* lpObj, int serviceindex);
char* ipworksble_bleclient_getserviceuuid(void* lpObj, int serviceindex);
int GetServiceCount();

QString GetServiceDescription(int iServiceIndex);

QString GetServiceId(int iServiceIndex);

QString GetServiceIncludedSvcIds(int iServiceIndex);

QString GetServiceParentSvcIds(int iServiceIndex);

QString GetServiceUuid(int iServiceIndex);

Remarks

The services which have been discovered for the currently connected server. This collection is populated when services are discovered, which may occur due to a call to the Discover or DiscoverServices methods, or at the time when a service with included services is discovered (if you have the AutoDiscoverIncludedServices configuration setting enabled).

Included services are represented in this collection just like root ones are.

Services do not all have to be discovered at one time, and additional services discovered will automatically be added to this collection upon discovery. This collection is cleared when the class disconnects from the server.

This property is read-only and not available at design time.

Data Type

IPWorksBLEService

Timeout Property (BLEClient Class)

A timeout for the class.

Syntax

ANSI (Cross Platform)
int GetTimeout();
int SetTimeout(int iTimeout); Unicode (Windows) INT GetTimeout();
INT SetTimeout(INT iTimeout);
int ipworksble_bleclient_gettimeout(void* lpObj);
int ipworksble_bleclient_settimeout(void* lpObj, int iTimeout);
int GetTimeout();
int SetTimeout(int iTimeout);

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered (except the PostValue method, which always returns immediately).

If Timeout is set to a positive value, the class will wait for a maximum of Timeout seconds since the beginning of the operation. If Timeout expires, and the operation is not yet complete, the class fails with an error.

The default value for the Timeout property is 60 (seconds).

Data Type

Integer

CheckCharacteristicSubscribed Method (BLEClient Class)

Checks to see if the class is subscribed to a characteristic.

Syntax

ANSI (Cross Platform)
bool CheckCharacteristicSubscribed(int iindex);

Unicode (Windows)
INT CheckCharacteristicSubscribed(INT iindex);
bool ipworksble_bleclient_checkcharacteristicsubscribed(void* lpObj, int iindex);
bool CheckCharacteristicSubscribed(int iindex);

Remarks

This method is used to see if the component is subscribed to a characteristic. The method uses the given index parameter to find the characteristic at the index of the Characteristics property. The method will then return a bool value based on whether the client is currently subscribed to that characteristic.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Config Method (BLEClient Class)

Sets or retrieves a configuration setting.

Syntax

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);
char* ipworksble_bleclient_config(void* lpObj, const char* lpszConfigurationString);
QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Connect Method (BLEClient Class)

Connect to a BLE GATT server based on its identifier.

Syntax

ANSI (Cross Platform)
int Connect(const char* lpszServerId);

Unicode (Windows)
INT Connect(LPCWSTR lpszServerId);
int ipworksble_bleclient_connect(void* lpObj, const char* lpszServerId);
int Connect(const QString& qsServerId);

Remarks

This method will attempt to connect to the BLE GATT server represented by the platform-specific identifier supplied in the ServerId parameter. The Connected event will be fired when the connection attempt finishes, and will contain additional information if the attempt failed.

If the class is connected to a server already when Connect is called, and the given ServerId is different than the currently connected server's ServerId, it will attempt to gracefully disconnect prior to initiating a new connection.

Calling Connect does nothing if ServerId is empty or matches the currently connected server's ServerId.

If Connect is called while the class is Scanning, the class will stop scanning prior to attempting to initiate a connection.

Note that there are a variety of reasons that a connection to a server may fail, not the least of which includes the server device being out of range of the client device. For the best results, it is recommended that you scan for devices before attempting a connection. Also note that the device identifier is a platform-specific value which is not guaranteed to be the same at any given point in time for any specific server device.

Connecting and Disconnecting // Connect to our TI SensorTag device. bleclient1.Connect("546C0E795800"); // Use BLEClient... // Disconnect from the device. bleclient1.Disconnect();

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Disconnect Method (BLEClient Class)

Disconnects from the remote server.

Syntax

ANSI (Cross Platform)
int Disconnect();

Unicode (Windows)
INT Disconnect();
int ipworksble_bleclient_disconnect(void* lpObj);
int Disconnect();

Remarks

This method disconnects from the remote server and clears all service, characteristic, and descriptor data from the class. The Disconnected event will be fired when the class has disconnected from the remote device.

Refer to the Connect method for more information.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Discover Method (BLEClient Class)

Convenience method to discover multiple levels of the GATT object hierarchy at once.

Syntax

ANSI (Cross Platform)
int Discover(const char* lpszServiceUuids, const char* lpszCharacteristicUuids, int bDiscoverDescriptors, const char* lpszIncludedByServiceId);

Unicode (Windows)
INT Discover(LPCWSTR lpszServiceUuids, LPCWSTR lpszCharacteristicUuids, BOOL bDiscoverDescriptors, LPCWSTR lpszIncludedByServiceId);
int ipworksble_bleclient_discover(void* lpObj, const char* lpszServiceUuids, const char* lpszCharacteristicUuids, int bDiscoverDescriptors, const char* lpszIncludedByServiceId);
int Discover(const QString& qsServiceUuids, const QString& qsCharacteristicUuids, bool bDiscoverDescriptors, const QString& qsIncludedByServiceId);

Remarks

This method can be used in place of individual calls to the DiscoverServices, DiscoverCharacteristics, and DiscoverDescriptors methods in order to discover GATT objects from multiple levels of the GATT hierarchy at once.

To discover root services, their characteristics, and those characteristics' descriptors, you can:

  • Pass a comma-separated list of service UUIDs for the services which you are interested in to the ServiceUuids parameter.
  • Pass a comma-separated list of characteristic UUIDs for the characteristics which you are interested in (for any and all services which could be discovered) to the CharacteristicUuids parameter.
  • Pass either true or false to the DiscoverDescriptors parameter, based on whether or not you wish to discover descriptors for discovered characteristics.
  • Pass the empty string to the IncludedByServiceId parameter.

If you wish to discover included services, their characteristics, and those characteristics' descriptors, the above still applies, but you should pass the Id of an already discovered service to the IncludedByServiceId parameter.

You have the option of passing the empty string to either, or both, of the ServiceUuids and CharacteristicUuids parameters if you do not wish to limit your discovery to specific services and/or characteristics, but doing so is strongly discouraged due to the additional power consumption that will result.

During the discovery process, the Discovered event will fire once for each GATT object discovered. You may control whether it fires when a GATT object is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Multi-Level Discovery string serviceUUIDs = "180A,F000AA70-0451-4000-B000-000000000000,F000AA20-0451-4000-B000-000000000000"; string characteristicUUIDs = ""; //All Characteristics bool discoverDescriptors = true; string includedByServiceId = ""; //No included services // This will discover all characteristics and descriptors for specific services. bleclient1.Discover(serviceUUIDs, characteristicUUIDs, discoverDescriptors, includedByServiceId); // This will discover everything on the server, but won't discover // the "includes"/"included by" service relationships. bleclient1.Discover("", "", true, "");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DiscoverCharacteristics Method (BLEClient Class)

Used to discover characteristics for a specific service.

Syntax

ANSI (Cross Platform)
int DiscoverCharacteristics(const char* lpszServiceId, const char* lpszCharacteristicUuids);

Unicode (Windows)
INT DiscoverCharacteristics(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicUuids);
int ipworksble_bleclient_discovercharacteristics(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicUuids);
int DiscoverCharacteristics(const QString& qsServiceId, const QString& qsCharacteristicUuids);

Remarks

This method is used to discover characteristics that belong to the service represented by ServiceId. Discovered characteristics' data will be used to populate the Characteristics collection property when the Service property is set to the applicable service Id.

It is recommended that you pass a comma-separated list of characteristic UUIDs for the CharacteristicUuids parameter in order to limit discovery to just the characteristics that you are interested in. You may also pass the empty string to discover all of the service's characteristics, but doing so will result in higher power consumption.

During the discovery process, the Discovered event will fire once for each characteristic discovered. You may control whether it fires when a characteristic is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Characteristic Discovery // Discovered event handler. bleclient1.OnDiscovered += (s, e) => { Console.WriteLine("Characteristic discovered:" + "\r\n\tOwning Service Id: " + e.ServiceId + "\r\n\tCharacteristic Id: " + e.CharacteristicId + // The discovered characteristic's 128-bit UUID string, in the format // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" "\r\n\tUUID: " + e.Uuid + // For standard characteristics whose UUIDs are defined by the Bluetooth SIG, // the Description event parameter will contain the name of the characteristic. "\r\n\tDescription: " + e.Description); }; // Discover all characteristics for the service whose Id is "000900000000". // (On our CC2650STK TI SensorTag, this is the Device Information Service.) bleclient1.DiscoverCharacteristics("000900000000", "");

Filtered Characteristic Discovery // Discover specific characteristics for the service whose Id is "000900000000". // (On our CC2650STK TI SensorTag, this is the Device Information Service.) // This will cause the System Id, Model Number String, and Manufacturer Name String // characteristics to be discovered, respectively. bleclient1.DiscoverCharacteristics("000900000000", "2A23,2A24,2A29");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DiscoverDescriptors Method (BLEClient Class)

Used to discover all descriptors for a specific characteristic.

Syntax

ANSI (Cross Platform)
int DiscoverDescriptors(const char* lpszServiceId, const char* lpszCharacteristicId);

Unicode (Windows)
INT DiscoverDescriptors(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId);
int ipworksble_bleclient_discoverdescriptors(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicId);
int DiscoverDescriptors(const QString& qsServiceId, const QString& qsCharacteristicId);

Remarks

This method is used to discover all descriptors that belong to the characteristic represented by CharacteristicId (which is owned by the service represented by ServiceId). Discovered descriptors' data will be used to populate the Descriptors collection property when the Characteristic property is set to the applicable characteristic Id.

During the discovery process, the Discovered event will fire once for each descriptor discovered. You may control whether it fires when a descriptor is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Descriptor Discovery // Discovered event handler. bleclient1.OnDiscovered += (s, e) => { Console.WriteLine("Descriptor discovered:" + "\r\n\tOwning Service Id: " + e.ServiceId + "\r\n\tOwning Characteristic Id: " + e.CharacteristicId + "\r\n\tDescriptor Id: " + e.DescriptorId + // The discovered descriptor's 128-bit UUID string, in the format // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" "\r\n\tUUID: " + e.Uuid + // For standard descriptors whose UUIDs are defined by the Bluetooth SIG, // the Description event parameter will contain the name of the descriptor. "\r\n\tDescription: " + e.Description); }; // Discover all descriptors for characteristic Id "001C001D0000", owned by // service Id "001C00000000". (On our CC2650STK TI SensorTag, this is the // Battery Level characteristic, which is owned by the Battery Service.) bleclient1.DiscoverDescriptors("001C00000000", "001C001D0000");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DiscoverServices Method (BLEClient Class)

Used to discover services for the currently connected server.

Syntax

ANSI (Cross Platform)
int DiscoverServices(const char* lpszServiceUuids, const char* lpszIncludedByServiceId);

Unicode (Windows)
INT DiscoverServices(LPCWSTR lpszServiceUuids, LPCWSTR lpszIncludedByServiceId);
int ipworksble_bleclient_discoverservices(void* lpObj, const char* lpszServiceUuids, const char* lpszIncludedByServiceId);
int DiscoverServices(const QString& qsServiceUuids, const QString& qsIncludedByServiceId);

Remarks

This method is used to discover root services on the currently connected server when empty string is passed for the IncludedByServiceId parameter. Passing the Id of an already-discovered service instead will cause the class to discover services included by that service.

All discovered services, root or otherwise, are added to the Services collection property.

It is recommended that you pass a comma-separated list of service UUIDs for the ServiceUuids parameter in order to limit discovery to just the services that you are interested in. You may also pass the empty string to discover all of the server's services (or all of a service's included services), but doing so will result in much higher power consumption.

During the discovery process, the Discovered event will fire once for each service discovered. You may control whether it fires when a service is rediscovered by setting the IncludeRediscovered configuration setting.

Keep in mind that having any of the following configuration settings enabled when you call this method may cause additional, unwanted power consumption: AutoDiscoverCharacteristics, AutoDiscoverDescriptors, or AutoDiscoverIncludedServices.

Service Discovery // Discovered event handler. bleclient1.OnDiscovered += (s, e) => { Console.WriteLine("Service discovered:" + "\r\n\tService Id: " + e.ServiceId + // The discovered service's 128-bit UUID string, in the format // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" "\r\n\tUUID: " + e.Uuid + // For standard services whose UUIDs are defined by the Bluetooth SIG, // the Description event parameter will contain the name of the service. "\r\n\tDescription: " + e.Description); }; // Discover all root services. bleclient1.DiscoverServices("", ""); // Discover all services included by a discovered service whose Id is "000100000000". bleclient1.DiscoverServices("", "000100000000");

Filtered Service Discovery // Discover specific root services. These three UUIDs will cause the Device Information, // Luxometer, and Humidity services to be discovered on our CC2650STK TI SensorTag. // (Since the latter two are non-standard, you have to use their full UUIDs.) bleclient1.DiscoverServices("180A,F000AA70-0451-4000-B000-000000000000,F000AA20-0451-4000-B000-000000000000", ""); // Discover specific services included by a discovered service whose Id is "000100000000". // (The TI SensorTag doesn't have any included services, this is just an example.) bleclient1.DiscoverServices("FFFFFFFF-9000-4000-B000-000000000000", "000100000000")

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DoEvents Method (BLEClient Class)

This method processes events from the internal message queue.

Syntax

ANSI (Cross Platform)
int DoEvents();

Unicode (Windows)
INT DoEvents();
int ipworksble_bleclient_doevents(void* lpObj);
int DoEvents();

Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

PostValue Method (BLEClient Class)

Write the value of a characteristic without expecting a response.

Syntax

ANSI (Cross Platform)
int PostValue(const char* lpszServiceId, const char* lpszCharacteristicId, const char* lpValue, int lenValue);

Unicode (Windows)
INT PostValue(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId, LPCSTR lpValue, INT lenValue);
int ipworksble_bleclient_postvalue(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicId, const char* lpValue, int lenValue);
int PostValue(const QString& qsServiceId, const QString& qsCharacteristicId, QByteArray qbaValue);

Remarks

This method is used to write the value of a characteristic, but unlike WriteValue it instructs the server not to send a response, even if the write request fails. This method will return immediately after the request is sent, regardless of the current Timeout value.

If your use-case doesn't require confirmation of characteristic value writes, this method is preferred; it allows both devices (but especially the server) to save power by keeping the BLE radio hardware turned off.

If you do require confirmation of characteristic value writes, or need to write a descriptor's value, use the WriteValue method.

Posting Values // The CC2650STK TI SensorTag doesn't have any characteristics which support // write without response, so this is just an example. bleclient1.PostValue("00AA00000000", "00AA00BB0000", new byte[] { 0x1, 0x2, 0x3 });

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

QueryCharacteristicCachedVal Method (BLEClient Class)

Reads and returns a characteristic value from the value cache.

Syntax

ANSI (Cross Platform)
char* QueryCharacteristicCachedVal(int iindex, int *lpSize = NULL);

Unicode (Windows)
LPSTR QueryCharacteristicCachedVal(INT iindex, LPINT lpSize = NULL);
char* ipworksble_bleclient_querycharacteristiccachedval(void* lpObj, int iindex, int *lpSize);
QByteArray QueryCharacteristicCachedVal(int iindex);

Remarks

This method will return the cached value for the characteristic. The method uses the given index parameter to find the characteristic at the index of the Characteristics property. The method then uses that characteristic to retrieve information from the value cache. 

Error Handling (C++)

This method returns a Binary String value (with length lpSize); after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

QueryDescriptorCachedVal Method (BLEClient Class)

Reads and returns a descriptor value from the value cache.

Syntax

ANSI (Cross Platform)
char* QueryDescriptorCachedVal(int iindex, int *lpSize = NULL);

Unicode (Windows)
LPSTR QueryDescriptorCachedVal(INT iindex, LPINT lpSize = NULL);
char* ipworksble_bleclient_querydescriptorcachedval(void* lpObj, int iindex, int *lpSize);
QByteArray QueryDescriptorCachedVal(int iindex);

Remarks

This method will return the cached value for the descriptor. The method uses the given index parameter to find the descriptor at the index of the Descriptors property. The method then uses that descriptor to retrieve information from the value cache. 

Error Handling (C++)

This method returns a Binary String value (with length lpSize); after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ReadValue Method (BLEClient Class)

Read the value of a characteristic or descriptor from the server.

Syntax

ANSI (Cross Platform)
char* ReadValue(const char* lpszServiceId, const char* lpszCharacteristicId, const char* lpszDescriptorId, int *lpSize = NULL);

Unicode (Windows)
LPSTR ReadValue(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId, LPCWSTR lpszDescriptorId, LPINT lpSize = NULL);
char* ipworksble_bleclient_readvalue(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicId, const char* lpszDescriptorId, int *lpSize);
QByteArray ReadValue(const QString& qsServiceId, const QString& qsCharacteristicId, const QString& qsDescriptorId);

Remarks

This method is used to read the value of a characteristic or a descriptor directly from the server, bypassing the platform's cache in the process.

To read the value of a characteristic, pass the Ids of it and its owning service for the CharacteristicId and ServiceId parameters, and pass empty string for the DescriptorId parameter. To read the value of a descriptor, do the same thing, but pass the descriptor's Id for the DescriptorId parameter too.

If the read request is successful, the read value will be returned and the Value event will be fired. In addition, the platform will cache the value; you can retrieve the cached for a characteristic using CharacteristicCachedValue or for a descriptor using DescriptorCachedValue.

If the read request fails, the Error event will be fired and the class fails with an error.

If the value of a characteristic changes often, prefer subscribing to the characteristic over polling in order to prevent unnecessary power consumption. Refer to the Subscribe method for more information.

Reading Live Values // Value event handler. bleclient1.OnValue += (s, e) => { if (string.IsNullOrEmpty(e.DescriptorId)) { Console.WriteLine("Read value {" + BitConverter.ToString(e.ValueB) + "} for characteristic with UUID " + e.Uuid); } else { Console.WriteLine("Read value {" + BitConverter.ToString(e.ValueB) + "} for descriptor with UUID " + e.Uuid); } }; // Print the live value for the Battery Level characteristic. These Ids // are correct for our CC2650STK TI SensorTag, but yours might differ. byte[] rawBatteryVal = bleclient1.ReadValue("001C00000000", "001C001D0000", ""); Console.WriteLine("Battery Level Value: " + (int)rawBatteryVal[0]); // Print the live value for the Characteristic Presentation Format descriptor on // the Battery Level characteristic. Again, your Ids might differ. byte[] rawBatteryPF = bleclient1.ReadValue("001C00000000", "001C001D0000", "001C001D0021"); Console.WriteLine("Battery Level Presentation Format bytes: " + BitConverter.ToString(rawBatteryPF));

Reading Cached Values // Print the cached value for the Luxometer Data characteristic (which you can // assume we've already found and assigned to a variable called "luxChara"). byte[] rawLuxVal = luxChara.CachedValueB; ushort luxVal = BitConverter.ToUInt16(rawLuxVal, 0); Console.WriteLine("Luxometer Value: " + luxVal); // Print the cached value for the Client Characteristic Configuration descriptor on // the Luxometer Data characteristic (again, assume it's stored in "luxCCCD"). byte[] rawLuxCCCD = luxCCCD.CachedValueB; Console.WriteLine("Luxometer CCCD bytes: " + BitConverter.ToString(rawLuxCCCD));

Error Handling (C++)

This method returns a Binary String value (with length lpSize); after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Select Method (BLEClient Class)

Used to set the currently selected service and characteristic by their Ids.

Syntax

ANSI (Cross Platform)
int Select(const char* lpszServiceId, const char* lpszCharacteristicId);

Unicode (Windows)
INT Select(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId);
int ipworksble_bleclient_select(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicId);
int Select(const QString& qsServiceId, const QString& qsCharacteristicId);

Remarks

This is a convenience method used to select a specific service and/or characteristic.

To select just a service, only pass the desired service Id for ServiceId; pass empty string for CharacteristicId. To select a characteristic, pass both of the Ids.

As long as both of the Ids are valid, the Service and Characteristic properties will be set accordingly (Characteristic is cleared if a characteristic Id isn't given).

An error will be thrown if any of the Ids aren't valid, or if an invalid combination of Ids is passed.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

StartScanning Method (BLEClient Class)

Causes the class to begin scanning for BLE GATT servers.

Syntax

ANSI (Cross Platform)
int StartScanning(const char* lpszServiceUuids);

Unicode (Windows)
INT StartScanning(LPCWSTR lpszServiceUuids);
int ipworksble_bleclient_startscanning(void* lpObj, const char* lpszServiceUuids);
int StartScanning(const QString& qsServiceUuids);

Remarks

This method causes the class to start scanning for BLE GATT servers, optionally filtered to include only servers which are advertising one or more services of interest.

To scan for all servers, pass empty string as the ServiceUuids parameter.

To scan for only servers advertising specific services, pass a comma-separated list of service UUIDs as the ServiceUuids parameter. (Only servers advertising all of the given services will be detected. Be aware that, due to the limited space in an advertisement packet, it's common for servers to support more services than they advertise.)

The StartScan event will be fired when the scanning has begun, after which the Advertisement event is fired whenever an advertisement from a server is received; the Error event is fired if an error occurs.

If you wish to use active scanning, enable the ActiveScanning property before you call StartScanning (refer to its documentation for more information).

You may start scanning while already connected to a server, but the class will stop scanning automatically if you attempt to initiate a new server connection (regardless of whether or not that connection attempt ends up succeeding).

Please be aware that scanning is a power-intensive activity, and you should call the StopScanning method as soon as is appropriate in order to prevent unnecessary power consumption.

Calling StartScanning when the class is already scanning does nothing.

Basic Scanning and Advertisement Handling Example // StartScan event handler. bleclient1.OnStartScan += (s, e) => Console.WriteLine("Scanning has started"); // StopScan event handler. bleclient1.OnStopScan += (s, e) => Console.WriteLine("Scanning has stopped"); // Advertisement event handler. bleclient1.OnAdvertisement += (s, e) => { // Your application should make every effort to handle the Advertisement event quickly. // BLEClient fires it as often as necessary, often multiple times per second. Console.WriteLine("Advertisement Received:" + "\r\n\tServerId: " + e.ServerId + "\r\n\tName: " + e.Name + "\r\n\tRSSI: " + e.RSSI + "\r\n\tTxPower: " + e.TxPower + "\r\n\tServiceUuids: " + e.ServiceUuids + "\r\n\tServicesWithData: " + e.ServicesWithData + "\r\n\tSolicitedServiceUuids: " + e.SolicitedServiceUuids + "\r\n\tManufacturerCompanyId: " + e.ManufacturerCompanyId + // We use BitConverter.ToString() to print data as hex bytes; this also prevents // an issue where the string could be cut off early if the data has a 0 byte in it. "\r\n\tManufacturerCompanyData: " + BitConverter.ToString(e.ManufacturerDataB) + "\r\n\tIsConnectable: " + e.IsConnectable + "\r\n\tIsScanResponse: " + e.IsScanResponse); }; // Scan for all devices. bleclient1.StartScanning(""); // Wait a while... bleclient1.StopScanning();

Filtered Scanning Example // Scan for devices which are advertising at least these UUIDs. You can use a mixture // of 16-, 32-, and 128-bit UUID strings, they'll be converted to 128-bit internally. bleclient1.StartScanning("180A,0000180F,00001801-0000-1000-8000-00805F9B34FB"); // ... bleclient1.StopScanning();

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

StopScanning Method (BLEClient Class)

Causes the class to stop scanning for BLE GATT servers.

Syntax

ANSI (Cross Platform)
int StopScanning();

Unicode (Windows)
INT StopScanning();
int ipworksble_bleclient_stopscanning(void* lpObj);
int StopScanning();

Remarks

This method will request that the class stop scanning for BLE GATT servers if it is currently doing so, otherwise it will do nothing. The StopScan event will fire when the scanning has stopped.

Note that scanning may be stopped automatically by the platform under certain conditions; the StopScan event will contain the error code and description if applicable.

You can check the Scanning property to determine whether or not the class is currently scanning.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Subscribe Method (BLEClient Class)

Subscribes to value updates for the specified characteristic.

Syntax

ANSI (Cross Platform)
int Subscribe(const char* lpszServiceId, const char* lpszCharacteristicId);

Unicode (Windows)
INT Subscribe(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId);
int ipworksble_bleclient_subscribe(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicId);
int Subscribe(const QString& qsServiceId, const QString& qsCharacteristicId);

Remarks

This method will subscribe the class to value updates for the characteristic whose Id is passed to CharacteristicId (which is owned by the service specified by ServiceId), as long as the characteristic supports it.

You can check a characteristic's CharacteristicCanSubscribe property to determine whether or not it supports subscriptions.

The Subscribed event will fire whenever you subscribe to a characteristic. While subscribed to a characteristic, the Value event will be fired each time the server sends an updated value for it (and its cached value will be updated as well).

The characteristic's CharacteristicSubscribed property can be used to determine whether or not the class is currently subscribed to a characteristic. You can also set it to true or false, which will automatically call Subscribe or Unsubscribe.

An error will be thrown if either of the given Ids are invalid, if the characteristic does not support subscribing for updates, or if there is an issue while trying to subscribe. Trying to subscribe to an already-subscribed characteristic does nothing.

Subscriptions // Subscribed event handler. bleclient1.OnSubscribed += (s, e) => { Console.WriteLine("Subscribed to characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; // Unsubscribed event handler. bleclient1.OnUnsubscribed += (s, e) => { Console.WriteLine("Unsubscribed from characteristic:" + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description); }; // Value event handler. bleclient1.OnValue += (s, e) => { Console.WriteLine("Value update received for characteristic: " + "\r\n\tID: " + e.CharacteristicId + "\r\n\tUUID: " + e.Uuid + "\r\n\tDescription: " + e.Description + "\r\n\tValue: " + BitConverter.ToString(e.ValueB)); }; // Assume that we've already found the Luxometer Data characteristic, // its owning service, and the Client Characteristic Configuration // descriptor on it; and we've stored them in variables called "luxSvc", // "luxData", and "luxCCCD". // Subscribe and unsubscribe using methods. bleclient1.Subscribe(luxSvc.Id, luxData.Id); // ... bleclient1.Unsubscribe(luxSvc.Id, luxData.Id); // Subscribe and unsubscribe using the "Subscribed" field. luxData.Subscribed = true; // ... luxData.Subscribed = false; // Subscribe and unsubscribe by writing directly to the CCCD. bleclient1.WriteValue(luxSvc.Id, luxData.Id, luxCCCD.Id, new byte[] { 1, 0 }); // ... bleclient1.WriteValue(luxSvc.Id, luxData.Id, luxCCCD.Id, new byte[] { 0, 0 });

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Unsubscribe Method (BLEClient Class)

Unsubscribes from value updates for one or more characteristics.

Syntax

ANSI (Cross Platform)
int Unsubscribe(const char* lpszServiceId, const char* lpszCharacteristicId);

Unicode (Windows)
INT Unsubscribe(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId);
int ipworksble_bleclient_unsubscribe(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicId);
int Unsubscribe(const QString& qsServiceId, const QString& qsCharacteristicId);

Remarks

This method will unsubscribe from value updates for the characteristic represented by CharacteristicId (which is owned by the service specified by ServiceId). The Unsubscribed event will fire each time you unsubscribe from a characteristic.

Passing empty string for CharacteristicId will cause the class to unsubscribe from any characteristic it is subscribed to in the specified service. Passing empty string for both parameters does the same, but for all services. (Unsubscribing en masse may take time since every subscribe/unsubscribe operation requires a write request and response behind the scenes.)

An error will be thrown if either of the given Ids are invalid (when both are passed), if only CharacteristicId is passed, if the characteristic does not support subscribing for updates, or if there is an issue while trying to unsubscribe.

Refer to the Subscribe method for more information.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

WriteValue Method (BLEClient Class)

Write the value of a characteristic or descriptor.

Syntax

ANSI (Cross Platform)
int WriteValue(const char* lpszServiceId, const char* lpszCharacteristicId, const char* lpszDescriptorId, const char* lpValue, int lenValue);

Unicode (Windows)
INT WriteValue(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId, LPCWSTR lpszDescriptorId, LPCSTR lpValue, INT lenValue);
int ipworksble_bleclient_writevalue(void* lpObj, const char* lpszServiceId, const char* lpszCharacteristicId, const char* lpszDescriptorId, const char* lpValue, int lenValue);
int WriteValue(const QString& qsServiceId, const QString& qsCharacteristicId, const QString& qsDescriptorId, QByteArray qbaValue);

Remarks

This method is used to write the value of a characteristic or descriptor. The method will return and the WriteResponse event will fire if the write is a success. If the write fails, the Error event will fire and the class fails with an error.

To write the value of a characteristic, pass the Ids of it and its owning service for the CharacteristicId and ServiceId parameters, and pass empty string for the DescriptorId parameter. To write the value of a descriptor, do the same thing, but pass the descriptor's Id for the DescriptorId parameter too.

If your use-case doesn't require confirmation of characteristic value writes, prefer the PostValue method in order to reduce power consumption.

Writing Values // WriteResponse event handler. bleclient1.OnWriteResponse += (s, e) => { if (string.IsNullOrEmpty(e.DescriptorId)) { Console.WriteLine("Successfully wrote to characteristic with UUID " + e.Uuid); } else { Console.WriteLine("Successfully wrote to descriptor with UUID " + e.Uuid); } }; // Write to the Luxometer Config characteristic. These Ids are correct // for our CC2650STK TI SensorTag, but yours might differ. bleclient1.WriteValue("004200000000", "004200460000", "", new byte[] { 0x1 }); // Write to the Client Characteristic Configuration descriptor on the // Luxometer Data characteristic. Again, your Ids might differ. bleclient1.WriteValue("004200000000", "004200430000", "004200430045", new byte[] { 0x1 });

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Advertisement Event (BLEClient Class)

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);
class BLEClientAdvertisementEventParams {
public:
  const QString &ServerId();

  const QString &Name();

  int RSSI();

  int TxPower();

  const QString &ServiceUuids();

  const QString &ServicesWithData();

  const QString &SolicitedServiceUuids();

  int ManufacturerCompanyId();

  const QByteArray &ManufacturerData();

  bool IsConnectable();

  bool IsScanResponse();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Advertisement(BLEClientAdvertisementEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireAdvertisement(BLEClientAdvertisementEventParams *e) {...}

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.

Connected Event (BLEClient Class)

Fired immediately after a connection to a remote device completes (or fails).

Syntax

ANSI (Cross Platform)
virtual int FireConnected(BLEClientConnectedEventParams *e);
typedef struct {
int StatusCode;
const char *Description; int reserved; } BLEClientConnectedEventParams;
Unicode (Windows) virtual INT FireConnected(BLEClientConnectedEventParams *e);
typedef struct {
INT StatusCode;
LPCWSTR Description; INT reserved; } BLEClientConnectedEventParams;
#define EID_BLECLIENT_CONNECTED 2

virtual INT IPWORKSBLE_CALL FireConnected(INT &iStatusCode, LPSTR &lpszDescription);
class BLEClientConnectedEventParams {
public:
  int StatusCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Connected(BLEClientConnectedEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireConnected(BLEClientConnectedEventParams *e) {...}

Remarks

If the connection is made successfully, StatusCode is 0 and Description is "OK".

If the connection fails, StatusCode has the error code returned by the Bluetooth stack. Description contains a description of this code.

Refer to the Connect method for more information.

Disconnected Event (BLEClient Class)

Fired when the class has been disconnected from the remote device.

Syntax

ANSI (Cross Platform)
virtual int FireDisconnected(BLEClientDisconnectedEventParams *e);
typedef struct {
int StatusCode;
const char *Description; int reserved; } BLEClientDisconnectedEventParams;
Unicode (Windows) virtual INT FireDisconnected(BLEClientDisconnectedEventParams *e);
typedef struct {
INT StatusCode;
LPCWSTR Description; INT reserved; } BLEClientDisconnectedEventParams;
#define EID_BLECLIENT_DISCONNECTED 3

virtual INT IPWORKSBLE_CALL FireDisconnected(INT &iStatusCode, LPSTR &lpszDescription);
class BLEClientDisconnectedEventParams {
public:
  int StatusCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Disconnected(BLEClientDisconnectedEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireDisconnected(BLEClientDisconnectedEventParams *e) {...}

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

If the connection is broken for any other reason, StatusCode has the error code returned by the Bluetooth stack. Description contains a description of this code.

Refer to the Disconnect section for more information.

Discovered Event (BLEClient Class)

Fired when the class discovers a service, characteristic, or descriptor.

Syntax

ANSI (Cross Platform)
virtual int FireDiscovered(BLEClientDiscoveredEventParams *e);
typedef struct {
int GattType;
const char *ServiceId;
const char *CharacteristicId;
const char *DescriptorId;
const char *Uuid;
const char *Description; int reserved; } BLEClientDiscoveredEventParams;
Unicode (Windows) virtual INT FireDiscovered(BLEClientDiscoveredEventParams *e);
typedef struct {
INT GattType;
LPCWSTR ServiceId;
LPCWSTR CharacteristicId;
LPCWSTR DescriptorId;
LPCWSTR Uuid;
LPCWSTR Description; INT reserved; } BLEClientDiscoveredEventParams;
#define EID_BLECLIENT_DISCOVERED 4

virtual INT IPWORKSBLE_CALL FireDiscovered(INT &iGattType, LPSTR &lpszServiceId, LPSTR &lpszCharacteristicId, LPSTR &lpszDescriptorId, LPSTR &lpszUuid, LPSTR &lpszDescription);
class BLEClientDiscoveredEventParams {
public:
  int GattType();

  const QString &ServiceId();

  const QString &CharacteristicId();

  const QString &DescriptorId();

  const QString &Uuid();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Discovered(BLEClientDiscoveredEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireDiscovered(BLEClientDiscoveredEventParams *e) {...}

Remarks

This event is fired during any discovery process to indicate that the class has discovered a service, characteristic, or descriptor. Discovery processes take place whenever Discover, DiscoverServices, DiscoverCharacteristics, or DiscoverDescriptors is called.

GattType indicates what type of GATT object was discovered:

  • 0 - Service
  • 1 - Characteristic
  • 2 - Descriptor

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the discovered service, characteristic, or descriptor.

When a service is discovered:

  • ServiceId is the Id of the newly discovered service.
  • CharacteristicId is empty.
  • DescriptorId is empty.

When a characteristic is discovered:

  • ServiceId is the Id of the previously discovered service which owns the newly discovered characteristic.
  • CharacteristicId is the Id of the newly discovered characteristic.
  • DescriptorId is empty.

When a descriptor is discovered:

  • ServiceId is the Id of the previously discovered service which owns the previously discovered characteristic.
  • CharacteristicId is the Id of the previously discovered characteristic which owns the newly discovered descriptor.
  • DescriptorId is the Id of the newly discovered descriptor.

Error Event (BLEClient Class)

Fired when information is available about errors during data delivery.

Syntax

ANSI (Cross Platform)
virtual int FireError(BLEClientErrorEventParams *e);
typedef struct {
int ErrorCode;
const char *Description; int reserved; } BLEClientErrorEventParams;
Unicode (Windows) virtual INT FireError(BLEClientErrorEventParams *e);
typedef struct {
INT ErrorCode;
LPCWSTR Description; INT reserved; } BLEClientErrorEventParams;
#define EID_BLECLIENT_ERROR 5

virtual INT IPWORKSBLE_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);
class BLEClientErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Error(BLEClientErrorEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireError(BLEClientErrorEventParams *e) {...}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (BLEClient Class)

Fires once for each log message.

Syntax

ANSI (Cross Platform)
virtual int FireLog(BLEClientLogEventParams *e);
typedef struct {
int LogLevel;
const char *Message;
const char *LogType; int reserved; } BLEClientLogEventParams;
Unicode (Windows) virtual INT FireLog(BLEClientLogEventParams *e);
typedef struct {
INT LogLevel;
LPCWSTR Message;
LPCWSTR LogType; INT reserved; } BLEClientLogEventParams;
#define EID_BLECLIENT_LOG 6

virtual INT IPWORKSBLE_CALL FireLog(INT &iLogLevel, LPSTR &lpszMessage, LPSTR &lpszLogType);
class BLEClientLogEventParams {
public:
  int LogLevel();

  const QString &Message();

  const QString &LogType();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Log(BLEClientLogEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireLog(BLEClientLogEventParams *e) {...}

Remarks

This events fires once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the Message. Possible values are:

0 (None) No events are logged.
1 (Info - default) Informational events are logged.
2 (Verbose) Detailed data is logged.
3 (Debug) Debug data is logged.

The default log level, Info, provides information when most BLE operations begin and end, and should be sufficient to get a good idea of what the class is doing at a high level.

The Verbose log level adds a few extra operation timing messages, and adds more detail to some messages logged at the Info level.

The Debug log level causes the class to output as much information as possible about what it is doing at all times. All BLE communications, even those which are typically abstracted away by the API, are logged in full detail. Typically the additional information added by this log level is not helpful to the end user, and would only be necessary to capture if you wish to report an issue to the support team.

LogType identifies the type of log entry. Possible values are:

  • Scanning: Messages relating to scanning and advertisements.
  • Connection: Messages relating to connecting, disconnecting, and connection failures.
  • Discovery: Messages relating to any service, characteristic, or descriptor discovery process.
  • Read: Messages relating to reading values from the remote device.
  • Write: Messages relating to writing values to the remote device.
  • Subscriptions: Messages relating to subscribing to and unsubscribing from characteristics.
  • Info, Verbose, and Debug: Miscellaneous messages fired at the applicable log level concerning internal class operations.

PairingRequest Event (BLEClient Class)

TBD.

Syntax

ANSI (Cross Platform)
virtual int FirePairingRequest(BLEClientPairingRequestEventParams *e);
typedef struct {
const char *ServerId;
int PairingKind;
char *Pin;
int Accept; int reserved; } BLEClientPairingRequestEventParams;
Unicode (Windows) virtual INT FirePairingRequest(BLEClientPairingRequestEventParams *e);
typedef struct {
LPCWSTR ServerId;
INT PairingKind;
LPWSTR Pin;
BOOL Accept; INT reserved; } BLEClientPairingRequestEventParams;
#define EID_BLECLIENT_PAIRINGREQUEST 7

virtual INT IPWORKSBLE_CALL FirePairingRequest(LPSTR &lpszServerId, INT &iPairingKind, LPSTR &lpszPin, BOOL &bAccept);
class BLEClientPairingRequestEventParams {
public:
  const QString &ServerId();

  int PairingKind();

  const QString &Pin();
  void SetPin(const QString &qsPin);

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void PairingRequest(BLEClientPairingRequestEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FirePairingRequest(BLEClientPairingRequestEventParams *e) {...}

Remarks

TBD.

ServerUpdate Event (BLEClient Class)

Fired when the currently connected server updates its name or available services.

Syntax

ANSI (Cross Platform)
virtual int FireServerUpdate(BLEClientServerUpdateEventParams *e);
typedef struct {
const char *Name;
const char *ChangedServices; int reserved; } BLEClientServerUpdateEventParams;
Unicode (Windows) virtual INT FireServerUpdate(BLEClientServerUpdateEventParams *e);
typedef struct {
LPCWSTR Name;
LPCWSTR ChangedServices; INT reserved; } BLEClientServerUpdateEventParams;
#define EID_BLECLIENT_SERVERUPDATE 8

virtual INT IPWORKSBLE_CALL FireServerUpdate(LPSTR &lpszName, LPSTR &lpszChangedServices);
class BLEClientServerUpdateEventParams {
public:
  const QString &Name();

  const QString &ChangedServices();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void ServerUpdate(BLEClientServerUpdateEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireServerUpdate(BLEClientServerUpdateEventParams *e) {...}

Remarks

This event is fired under one of two conditions, both of which involve some sort of server-side change other than the value of a subscribed characteristic having changed (subscribed characteristic value updates are delivered through the Value event).

If the server's name has changed, this event is fired with the new name in the Name parameter, and the ServerName property is updated as well.

If the server's services have changed, this event is fired with a non-empty value in the ChangedServices parameter.

StartScan Event (BLEClient Class)

Fired when the class starts scanning.

Syntax

ANSI (Cross Platform)
virtual int FireStartScan(BLEClientStartScanEventParams *e);
typedef struct {
const char *ServiceUuids; int reserved; } BLEClientStartScanEventParams;
Unicode (Windows) virtual INT FireStartScan(BLEClientStartScanEventParams *e);
typedef struct {
LPCWSTR ServiceUuids; INT reserved; } BLEClientStartScanEventParams;
#define EID_BLECLIENT_STARTSCAN 9

virtual INT IPWORKSBLE_CALL FireStartScan(LPSTR &lpszServiceUuids);
class BLEClientStartScanEventParams {
public:
  const QString &ServiceUuids();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void StartScan(BLEClientStartScanEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireStartScan(BLEClientStartScanEventParams *e) {...}

Remarks

This event is fired when the class starts scanning. ServiceUuids is a comma-separated list of 128-bit service UUIDs that the scan is being filtered by. Refer to the StartScanning method for more information.

StopScan Event (BLEClient Class)

Fired when the class stops scanning.

Syntax

ANSI (Cross Platform)
virtual int FireStopScan(BLEClientStopScanEventParams *e);
typedef struct {
int ErrorCode;
const char *ErrorDescription; int reserved; } BLEClientStopScanEventParams;
Unicode (Windows) virtual INT FireStopScan(BLEClientStopScanEventParams *e);
typedef struct {
INT ErrorCode;
LPCWSTR ErrorDescription; INT reserved; } BLEClientStopScanEventParams;
#define EID_BLECLIENT_STOPSCAN 10

virtual INT IPWORKSBLE_CALL FireStopScan(INT &iErrorCode, LPSTR &lpszErrorDescription);
class BLEClientStopScanEventParams {
public:
  int ErrorCode();

  const QString &ErrorDescription();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void StopScan(BLEClientStopScanEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireStopScan(BLEClientStopScanEventParams *e) {...}

Remarks

This event is fired when the class stops scanning. If the scanning stopped due to an error, the ErrorCode and ErrorDescription parameters will be set accordingly; otherwise they will be 0 and empty string. Refer to the StopScanning method for more information.

Subscribed Event (BLEClient Class)

Fired when the class has successfully subscribed to a characteristic.

Syntax

ANSI (Cross Platform)
virtual int FireSubscribed(BLEClientSubscribedEventParams *e);
typedef struct {
const char *ServiceId;
const char *CharacteristicId;
const char *Uuid;
const char *Description; int reserved; } BLEClientSubscribedEventParams;
Unicode (Windows) virtual INT FireSubscribed(BLEClientSubscribedEventParams *e);
typedef struct {
LPCWSTR ServiceId;
LPCWSTR CharacteristicId;
LPCWSTR Uuid;
LPCWSTR Description; INT reserved; } BLEClientSubscribedEventParams;
#define EID_BLECLIENT_SUBSCRIBED 11

virtual INT IPWORKSBLE_CALL FireSubscribed(LPSTR &lpszServiceId, LPSTR &lpszCharacteristicId, LPSTR &lpszUuid, LPSTR &lpszDescription);
class BLEClientSubscribedEventParams {
public:
  const QString &ServiceId();

  const QString &CharacteristicId();

  const QString &Uuid();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Subscribed(BLEClientSubscribedEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireSubscribed(BLEClientSubscribedEventParams *e) {...}

Remarks

This event is fired when the class has successfully subscribed to a characteristic.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic.

Refer to the Subscribe method for more information.

Unsubscribed Event (BLEClient Class)

Fired when the class has successfully unsubscribed from a characteristic.

Syntax

ANSI (Cross Platform)
virtual int FireUnsubscribed(BLEClientUnsubscribedEventParams *e);
typedef struct {
const char *ServiceId;
const char *CharacteristicId;
const char *Uuid;
const char *Description; int reserved; } BLEClientUnsubscribedEventParams;
Unicode (Windows) virtual INT FireUnsubscribed(BLEClientUnsubscribedEventParams *e);
typedef struct {
LPCWSTR ServiceId;
LPCWSTR CharacteristicId;
LPCWSTR Uuid;
LPCWSTR Description; INT reserved; } BLEClientUnsubscribedEventParams;
#define EID_BLECLIENT_UNSUBSCRIBED 12

virtual INT IPWORKSBLE_CALL FireUnsubscribed(LPSTR &lpszServiceId, LPSTR &lpszCharacteristicId, LPSTR &lpszUuid, LPSTR &lpszDescription);
class BLEClientUnsubscribedEventParams {
public:
  const QString &ServiceId();

  const QString &CharacteristicId();

  const QString &Uuid();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Unsubscribed(BLEClientUnsubscribedEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireUnsubscribed(BLEClientUnsubscribedEventParams *e) {...}

Remarks

This event is fired when the class has successfully unsubscribed from a characteristic.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic

Refer to the Unsubscribe method for more information.

Value Event (BLEClient Class)

Fired when a characteristic or descriptor value is received from the server.

Syntax

ANSI (Cross Platform)
virtual int FireValue(BLEClientValueEventParams *e);
typedef struct {
const char *ServiceId;
const char *CharacteristicId;
const char *DescriptorId;
const char *Uuid;
const char *Description;
const char *Value; int lenValue; int reserved; } BLEClientValueEventParams;
Unicode (Windows) virtual INT FireValue(BLEClientValueEventParams *e);
typedef struct {
LPCWSTR ServiceId;
LPCWSTR CharacteristicId;
LPCWSTR DescriptorId;
LPCWSTR Uuid;
LPCWSTR Description;
LPCSTR Value; INT lenValue; INT reserved; } BLEClientValueEventParams;
#define EID_BLECLIENT_VALUE 13

virtual INT IPWORKSBLE_CALL FireValue(LPSTR &lpszServiceId, LPSTR &lpszCharacteristicId, LPSTR &lpszDescriptorId, LPSTR &lpszUuid, LPSTR &lpszDescription, LPSTR &lpValue, INT &lenValue);
class BLEClientValueEventParams {
public:
  const QString &ServiceId();

  const QString &CharacteristicId();

  const QString &DescriptorId();

  const QString &Uuid();

  const QString &Description();

  const QByteArray &Value();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Value(BLEClientValueEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireValue(BLEClientValueEventParams *e) {...}

Remarks

This event is fired to signify that a value has been received for a characteristic or descriptor. The DescriptorId parameter will be empty string if the value is for a characteristic.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic or descriptor.

There are three scenarios which can cause this event to fire:

  • The server has responded to a read request for a characteristic.
  • The server has responded to a read request for a descriptor.
  • The server has sent an updated value for a subscribed characteristic.

Whenever a value is received for a characteristic or descriptor, the value that the platform has cached for it is updated as well. You can read the cached value for a characteristic using CharacteristicCachedValue, or for a descriptor using DescriptorCachedValue.

Refer to the ReadValue and/or Subscribe methods for more information.

WriteResponse Event (BLEClient Class)

Fired when the server acknowledges a successful value write request.

Syntax

ANSI (Cross Platform)
virtual int FireWriteResponse(BLEClientWriteResponseEventParams *e);
typedef struct {
const char *ServiceId;
const char *CharacteristicId;
const char *DescriptorId;
const char *Uuid;
const char *Description; int reserved; } BLEClientWriteResponseEventParams;
Unicode (Windows) virtual INT FireWriteResponse(BLEClientWriteResponseEventParams *e);
typedef struct {
LPCWSTR ServiceId;
LPCWSTR CharacteristicId;
LPCWSTR DescriptorId;
LPCWSTR Uuid;
LPCWSTR Description; INT reserved; } BLEClientWriteResponseEventParams;
#define EID_BLECLIENT_WRITERESPONSE 14

virtual INT IPWORKSBLE_CALL FireWriteResponse(LPSTR &lpszServiceId, LPSTR &lpszCharacteristicId, LPSTR &lpszDescriptorId, LPSTR &lpszUuid, LPSTR &lpszDescription);
class BLEClientWriteResponseEventParams {
public:
  const QString &ServiceId();

  const QString &CharacteristicId();

  const QString &DescriptorId();

  const QString &Uuid();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void WriteResponse(BLEClientWriteResponseEventParams *e);
// Or, subclass BLEClient and override this emitter function. virtual int FireWriteResponse(BLEClientWriteResponseEventParams *e) {...}

Remarks

This event is fired when the server acknowledges a successful value write request for a characteristic or descriptor.

ServiceId holds the Id of the service.

CharacteristicId holds the Id of the characteristic.

DescriptorId holds the Id of the descriptor. This is only populated when a descriptor value is written.

Uuid and Description are the UUID and Bluetooth SIG user-friendly name (if one is defined) of the characteristic or descriptor.

Note that this event is not fired if the write request was sent using PostValue, regardless of the outcome.

Refer to the WriteValue method for more information.

Characteristic Type

A GATT characteristic.

Syntax

IPWorksBLECharacteristic (declared in ipworksble.h)

Remarks

This type represents a GATT characteristic.

The following fields are available:

Fields

CanSubscribe
int (read-only)

Default Value: FALSE

Whether or not you can subscribe to receive value updates for this characteristic.

Description
char* (read-only)

Default Value: ""

This characteristic's Bluetooth SIG user-friendly name, if one is defined.

Flags
int (read-only)

Default Value: 0

A bitmask of this characteristic's flags.

This field is a bitmask which represents all of the flags (or, in BLE terms, "properties") which this characteristic has set. The following table shows what bitmask is used to represent each flag:

BitmaskFlag
0x00000001 Broadcast
0x00000002 Read
0x00000004 Write Without Response
0x00000008 Write
0x00000010 Notify
0x00000020 Indicate
0x00000040 Authenticated Signed Writes
0x00000080 Reliable Writes (extended property)
0x00000100 Writable Auxiliaries (extended property)

Note that, on some platforms, the class might have to automatically discover specific descriptors for the value this returns to be accurate. The class take care of handling this automatic discovery in the most energy-efficient manner possible.

Id
char* (read-only)

Default Value: ""

An identification string which uniquely identifies this instance of this characteristic.

This identification string is guaranteed to be unchanged while the class remains connected to the device.

UserDescription
char*

Default Value: ""

The value of the user description descriptor for this characteristic.

If the "Writable Auxiliaries" property is set for this characteristic, you can change this value, which updates it on the server too.

Note that, on some platforms, the class might have to automatically discover specific descriptors for the value this returns to be accurate. The class take care of handling this automatic discovery in the most energy-efficient manner possible.

Uuid
char* (read-only)

Default Value: ""

This characteristic's 128-bit UUID string.

ValueExponent
int (read-only)

Default Value: -1

The exponent of this characteristic's value, for applicable value formats.

For an applicable ValueFormat, this signed integer should be used as an exponent in the following formula in order to determine the actual value of the characteristic: [Value] * 10^[Exponent].

ValueFormat
int (read-only)

Default Value: 0

The data type of this characteristic's value.

The valid options are as follows:

Value TypeDescription
vfUndefined (0) Undefined
vfBoolean (1) Unsigned 1-bit; 0 = false, 1 = true
vf2Bit (2) Unsigned 2-bit integer
vfNibble (3) Unsigned 4-bit integer
vfUInt8 (4) Unsigned 8-bit integer; exponent applies
vfUInt12 (5) Unsigned 12-bit integer; exponent applies
vfUInt16 (6) Unsigned 16-bit integer; exponent applies
vfUInt24 (7) Unsigned 24-bit integer; exponent applies
vfUInt32 (8) Unsigned 32-bit integer; exponent applies
vfUInt48 (9) Unsigned 48-bit integer; exponent applies
vfUInt64 (10) Unsigned 64-bit integer; exponent applies
vfUInt128 (11) Unsigned 128-bit integer; exponent applies
vfSInt8 (12) Signed 8-bit integer; exponent applies
vfSInt12 (13) Signed 12-bit integer; exponent applies
vfSInt16 (14) Signed 16-bit integer; exponent applies
vfSInt24 (15) Signed 24-bit integer; exponent applies
vfSInt32 (16) Signed 32-bit integer; exponent applies
vfSInt48 (17) Signed 48-bit integer; exponent applies
vfSInt64 (18) Signed 64-bit integer; exponent applies
vfSInt128 (19) Signed 128-bit integer; exponent applies
vfFloat32 (20) IEEE-754 32-bit floating point
vfFloat64 (21) IEEE-754 64-bit floating point
vfSFloat (22) IEEE-11073 16-bit SFLOAT
vfFloat (23) IEEE-11073 32-bit FLOAT
vfDUInt16 (24) IEEE-20601 format (Two UInt16 values concatenated)
vfUtf8Str (25) UTF-8 string
vfUtf16Str (26) UTF-16 string
vfStruct (27) Opaque structure

ValueFormatCount
int (read-only)

Default Value: 0

The number of value formats this characteristic has.

Characteristics whose values are an aggregate of multiple other values will often have multiple value formats as a result. In such cases, this field's value will be greater than 1, and the ValueFormatIndex field can be used to choose which value format the ValueFormat, ValueExponent, and ValueUnit fields are populated with.

Note that, on some platforms, the class might have to automatically discover specific descriptors for the value this returns to be accurate. The class take care of handling this automatic discovery in the most energy-efficient manner possible.

ValueFormatIndex
int

Default Value: -1

Selects the currently populated value format details for this characteristic.

See ValueFormatCount for more details.

ValueUnit
char* (read-only)

Default Value: ""

The 128-bit UUID string that represents the unit of measurement for this characteristic's value.

Constructors

Characteristic()

Descriptor Type

A GATT descriptor.

Syntax

IPWorksBLEDescriptor (declared in ipworksble.h)

Remarks

This type represents a GATT descriptor.

The following fields are available:

Fields

Description
char* (read-only)

Default Value: ""

This descriptor's Bluetooth SIG user-friendly name, if one is defined.

Id
char* (read-only)

Default Value: ""

An identification string which uniquely identifies this instance of this descriptor.

This identification string is guaranteed to be unchanged while the class remains connected to the device.

Uuid
char* (read-only)

Default Value: ""

This descriptor's 128-bit UUID string.

Constructors

Descriptor()

Service Type

A GATT service.

Syntax

IPWorksBLEService (declared in ipworksble.h)

Remarks

This type represents a GATT service.

The following fields are available:

Fields

Description
char* (read-only)

Default Value: ""

This service's Bluetooth SIG user-friendly name, if one is defined.

Id
char* (read-only)

Default Value: ""

An identification string which uniquely identifies this instance of this service.

This identification string is guaranteed to be unchanged while the class remains connected to the device.

IncludedSvcIds
char* (read-only)

Default Value: ""

If any included services have been discovered for this service, this is a comma-separated list of their Ids.

If additional included services are discovered later, their Ids will be appended.

ParentSvcIds
char* (read-only)

Default Value: ""

If this services is included by any other services, this is a comma-separated list of those services' Ids.

If it is discovered later that additional services include this service, their Ids will be appended.

Uuid
char* (read-only)

Default Value: ""

This service's 128-bit UUID string.

Constructors

Service()

IPWorksBLEList Type

Syntax

IPWorksBLEList<T> (declared in ipworksble.h)

Remarks

IPWorksBLEList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the BLEClient class.

Methods

GetCount This method returns the current size of the collection.

int GetCount() {}

SetCount This method sets the size of the collection. This method returns 0 if setting the size was successful; or -1 if the collection is ReadOnly. When adding additional objects to a collection call this method to specify the new size. Increasing the size of the collection preserves existing objects in the collection.

int SetCount(int count) {}

Get This method gets the item at the specified position. The index parameter specifies the index of the item in the collection. This method returns NULL if an invalid index is specified.

T* Get(int index) {}

Set This method sets the item at the specified position. The index parameter specifies the index of the item in the collection that is being set. This method returns -1 if an invalid index is specified. Note: Objects created using the new operator must be freed using the delete operator; they will not be automatically freed by the class.

T* Set(int index, T* value) {}

Config Settings (BLEClient Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

BLEClient Config Settings

AutoDiscoverCharacteristics:   Whether to automatically discover all characteristics when a service is discovered.

When enabled, the class will automatically attempt to discover all characteristics for every service (or included service) that it discovers.

This is disabled by default; keep in mind that enabling it will likely cause increased power consumption.

AutoDiscoverDescriptors:   Whether to automatically discover all descriptors when a characteristic is discovered.

When enabled, the class will automatically attempt to discover all descriptors for every characteristic that it discovers.

This is disabled by default; keep in mind that enabling it will likely cause increased power consumption.

AutoDiscoverIncludedServices:   Whether to automatically discover all included services when a service is discovered.

When enabled, the class will automatically attempt to discover all included services for every service (or included service) that it discovers.

An exception will be thrown if a cycle of included services is detected (this should not occur on a properly configured server).

This is disabled by default; keep in mind that enabling it will likely cause increased power consumption.

GattObjTreeInfo:   Returns a string representation of the currently discovered GATT object tree.

When queried, the class will return a string with information about the current discovered GATT object tree. This is only useful for debugging purposes.

IncludeRediscovered:   Whether to fire the Discovered event for rediscovered services, characteristics, and descriptors.

When disabled, the class will not fire the Discovered event during a discovery process for any services, characteristics, or descriptors which have already been discovered.

This is enabled by default (the class will fire Discovered for every discovery, regardless of whether or not it was a rediscovery).

LogLevel:   The level of detail that is logged.

This setting controls the level of detail that is logged through the Log event. Possible values are:

0 (None) No events are logged.
1 (Info - default) Informational events are logged.
2 (Verbose) Detailed data is logged.
3 (Debug) Debug data is logged.

The default log level, Info, provides information when most BLE operations begin and end, and should be sufficient to get a good idea of what the class is doing at a high level.

The Verbose log level adds a few extra operation timing messages, and adds more detail to some messages logged at the Info level.

The Debug log level causes the class to output as much information as possible about what it is doing at all times. All BLE communications, even those which are typically abstracted away by the API, are logged in full detail. Typically the additional information added by this log level is not helpful to the end user, and would only be necessary to capture if you wish to report an issue to the support team.

ManufacturerCompanyId[i]:   The manufacturer company Id at index 'i'.

The setting can be queried while within the Advertisement event handler to get the company Id from the manufacturer data section at index 'i'.

Valid indices are from 0 to ManufacturerDataCount - 1. This setting is only valid when used within the Advertisement event handler.

ManufacturerData[i]:   The manufacturer data at index 'i'.

The setting can be queried while within the Advertisement event handler to get the data from the manufacturer data section at index 'i'. The data is returned as a byte string.

Valid indices are from 0 to ManufacturerDataCount - 1. This setting is only valid when used within the Advertisement event handler.

ManufacturerDataCount:   The number of manufacturer data sections an advertisement has.

This setting can be queried while within the Advertisement event handler to determine how many manufacturer data sections the advertisement contains.

This setting is only valid when used within the Advertisement event handler.

ScanStartedTimeout:   The maximum amount of time to wait for scanning to start.

This setting determines how long the StartScanning method will wait to let the scanning process start. If the scan status does not update in that time, the Log event will fire with a message that scanning failed to start. The default value is 2 seconds.

ServiceData:   Gets the data associated with a service UUID from an advertisement.

While within the Advertisement event handler, you can set this to one of the UUIDs from the Advertisement event's ServicesWithData parameter to get the data associated with it. The data is returned as a byte string.

This setting is only valid when used within the Advertisement event handler.

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

CodePage:   The system code page used for Unicode to Multibyte translations.

The default code page is Unicode UTF-8 (65001).

The following is a list of valid code page identifiers:

IdentifierName
037IBM EBCDIC - U.S./Canada
437OEM - United States
500IBM EBCDIC - International
708Arabic - ASMO 708
709Arabic - ASMO 449+, BCON V4
710Arabic - Transparent Arabic
720Arabic - Transparent ASMO
737OEM - Greek (formerly 437G)
775OEM - Baltic
850OEM - Multilingual Latin I
852OEM - Latin II
855OEM - Cyrillic (primarily Russian)
857OEM - Turkish
858OEM - Multilingual Latin I + Euro symbol
860OEM - Portuguese
861OEM - Icelandic
862OEM - Hebrew
863OEM - Canadian-French
864OEM - Arabic
865OEM - Nordic
866OEM - Russian
869OEM - Modern Greek
870IBM EBCDIC - Multilingual/ROECE (Latin-2)
874ANSI/OEM - Thai (same as 28605, ISO 8859-15)
875IBM EBCDIC - Modern Greek
932ANSI/OEM - Japanese, Shift-JIS
936ANSI/OEM - Simplified Chinese (PRC, Singapore)
949ANSI/OEM - Korean (Unified Hangul Code)
950ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)
1026IBM EBCDIC - Turkish (Latin-5)
1047IBM EBCDIC - Latin 1/Open System
1140IBM EBCDIC - U.S./Canada (037 + Euro symbol)
1141IBM EBCDIC - Germany (20273 + Euro symbol)
1142IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)
1143IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)
1144IBM EBCDIC - Italy (20280 + Euro symbol)
1145IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)
1146IBM EBCDIC - United Kingdom (20285 + Euro symbol)
1147IBM EBCDIC - France (20297 + Euro symbol)
1148IBM EBCDIC - International (500 + Euro symbol)
1149IBM EBCDIC - Icelandic (20871 + Euro symbol)
1200Unicode UCS-2 Little-Endian (BMP of ISO 10646)
1201Unicode UCS-2 Big-Endian
1250ANSI - Central European
1251ANSI - Cyrillic
1252ANSI - Latin I
1253ANSI - Greek
1254ANSI - Turkish
1255ANSI - Hebrew
1256ANSI - Arabic
1257ANSI - Baltic
1258ANSI/OEM - Vietnamese
1361Korean (Johab)
10000MAC - Roman
10001MAC - Japanese
10002MAC - Traditional Chinese (Big5)
10003MAC - Korean
10004MAC - Arabic
10005MAC - Hebrew
10006MAC - Greek I
10007MAC - Cyrillic
10008MAC - Simplified Chinese (GB 2312)
10010MAC - Romania
10017MAC - Ukraine
10021MAC - Thai
10029MAC - Latin II
10079MAC - Icelandic
10081MAC - Turkish
10082MAC - Croatia
12000Unicode UCS-4 Little-Endian
12001Unicode UCS-4 Big-Endian
20000CNS - Taiwan
20001TCA - Taiwan
20002Eten - Taiwan
20003IBM5550 - Taiwan
20004TeleText - Taiwan
20005Wang - Taiwan
20105IA5 IRV International Alphabet No. 5 (7-bit)
20106IA5 German (7-bit)
20107IA5 Swedish (7-bit)
20108IA5 Norwegian (7-bit)
20127US-ASCII (7-bit)
20261T.61
20269ISO 6937 Non-Spacing Accent
20273IBM EBCDIC - Germany
20277IBM EBCDIC - Denmark/Norway
20278IBM EBCDIC - Finland/Sweden
20280IBM EBCDIC - Italy
20284IBM EBCDIC - Latin America/Spain
20285IBM EBCDIC - United Kingdom
20290IBM EBCDIC - Japanese Katakana Extended
20297IBM EBCDIC - France
20420IBM EBCDIC - Arabic
20423IBM EBCDIC - Greek
20424IBM EBCDIC - Hebrew
20833IBM EBCDIC - Korean Extended
20838IBM EBCDIC - Thai
20866Russian - KOI8-R
20871IBM EBCDIC - Icelandic
20880IBM EBCDIC - Cyrillic (Russian)
20905IBM EBCDIC - Turkish
20924IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)
20932JIS X 0208-1990 & 0121-1990
20936Simplified Chinese (GB2312)
21025IBM EBCDIC - Cyrillic (Serbian, Bulgarian)
21027Extended Alpha Lowercase
21866Ukrainian (KOI8-U)
28591ISO 8859-1 Latin I
28592ISO 8859-2 Central Europe
28593ISO 8859-3 Latin 3
28594ISO 8859-4 Baltic
28595ISO 8859-5 Cyrillic
28596ISO 8859-6 Arabic
28597ISO 8859-7 Greek
28598ISO 8859-8 Hebrew
28599ISO 8859-9 Latin 5
28605ISO 8859-15 Latin 9
29001Europa 3
38598ISO 8859-8 Hebrew
50220ISO 2022 Japanese with no halfwidth Katakana
50221ISO 2022 Japanese with halfwidth Katakana
50222ISO 2022 Japanese JIS X 0201-1989
50225ISO 2022 Korean
50227ISO 2022 Simplified Chinese
50229ISO 2022 Traditional Chinese
50930Japanese (Katakana) Extended
50931US/Canada and Japanese
50933Korean Extended and Korean
50935Simplified Chinese Extended and Simplified Chinese
50936Simplified Chinese
50937US/Canada and Traditional Chinese
50939Japanese (Latin) Extended and Japanese
51932EUC - Japanese
51936EUC - Simplified Chinese
51949EUC - Korean
51950EUC - Traditional Chinese
52936HZ-GB2312 Simplified Chinese
54936Windows XP: GB18030 Simplified Chinese (4 Byte)
57002ISCII Devanagari
57003ISCII Bengali
57004ISCII Tamil
57005ISCII Telugu
57006ISCII Assamese
57007ISCII Oriya
57008ISCII Kannada
57009ISCII Malayalam
57010ISCII Gujarati
57011ISCII Punjabi
65000Unicode UTF-7
65001Unicode UTF-8
The following is a list of valid code page identifiers for Mac OS only:
IdentifierName
1ASCII
2NEXTSTEP
3JapaneseEUC
4UTF8
5ISOLatin1
6Symbol
7NonLossyASCII
8ShiftJIS
9ISOLatin2
10Unicode
11WindowsCP1251
12WindowsCP1252
13WindowsCP1253
14WindowsCP1254
15WindowsCP1250
21ISO2022JP
30MacOSRoman
10UTF16String
0x90000100UTF16BigEndian
0x94000100UTF16LittleEndian
0x8c000100UTF32String
0x98000100UTF32BigEndian
0x9c000100UTF32LittleEndian
65536Proprietary

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).
  • Last Valid Build: The last valid build number for which the license will work.
MaskSensitiveData:   Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.

This setting only works on these classes: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

ProcessIdleEvents:   Whether the class uses its internal event loop to process events when the main thread is idle.

If set to False, the class will not fire internal idle events. Set this to False to use the class in a background thread on Mac OS. By default, this setting is True.

SelectWaitMillis:   The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.

If there are no events to process when DoEvents is called, the class will wait for the amount of time specified here before returning. The default value is 20.

UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

When set to false, the class will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to true tells the class to use the internal implementation instead of using the system security libraries.

On Windows, this setting is set to false by default. On Linux/macOS, this setting is set to true by default.

To use the system security libraries for Linux, OpenSSL support must be enabled. For more information on how to enable OpenSSL, please refer to the OpenSSL Notes section.

Trappable Errors (BLEClient Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

BLEClient Errors

600   Invalid UUID.
601   Invalid Id.
602   Action not allowed. See error message for more details.
603   Scanning error. See error message for more details.
604   Connection error. See error message for more details.
605   Must be connected to a device to perform the requested action.
606   Error during communication. See error message for more details.
607   Device unreachable during communication attempt.
608   Error during discovery. See error message for more details.
609   Class detected a cycle of included services.
610   General read error. See error message for more details.
611   General write error. See error message for more details.
612   Application-specific protocol error. This error code indicates that a protocol error code in the range 0x80-0x9F was returned during a BLE communication. Such error codes are reserved for applications to use as they see fit. Refer to the documentation of your remote device for more information.
613   Bluetooth low energy not supported.
701   Invalid Handle: The attribute handle given was not valid on this server.
702   Read Not Permitted: The attribute cannot be read due to its permissions.
703   Write Not Permitted: The attribute cannot be written due to its permissions.
704   Invalid PDU: The attribute PDU was invalid.
705   Insufficient Authentication: The attribute requires authentication before it can be read or written.
706   Request Not Supported: Attribute server does not support the request received from the client.
707   Invalid Offset: Offset specified was past the end of the attribute's value.
708   Insufficient Authorization: The attribute requires authorization before it can be read or written.
709   Prepare Queue Full: Too many prepare writes have been queued.
710   Attribute Not Found: No attribute found within the given attribute handle range.
711   Attribute Not Long: The attribute cannot be read or written using the Read Blob Request.
712   Insufficient Encryption Key Size: The Encryption Key Size used for encrypting this link is insufficient.
713   Invalid Attribute Value Length: The attribute value length is invalid for the operation.
714   Unlikely Error: The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested.
715   Insufficient Encryption: The attribute requires encryption before it can be read or written.
716   Unsupported Group Type: The attribute type is not a supported grouping attribute as defined by a higher layer specification.
717   Insufficient Resources: Insufficient Resources to complete the request.
952   Write Request Rejected: A requested write operation could not be fulfilled for reasons other than its permissions.
953   Client Characteristic Configuration Descriptor (CCCD) Improperly Configured: The CCCD is not configured according to the requirements of the profile or service.
954   Procedure Already in Progress: A profile or service request cannot be serviced because a previously triggered operation is still in progress.
955   Out of Range: An attribute value is out of range (as defined by a profile or service specification).