DiscoverCharacteristics Method

Used to discover characteristics for a specific service.

Syntax

• C++

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

Unicode (Windows)
INT DiscoverCharacteristics(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicUuids);

#define MID_BLECLIENT_DISCOVERCHARACTERISTICS 6

IPWORKSBLE_EXTERNAL int IPWORKSBLE_CALL IPWorksBLE_BLEClient_Do(void *lpObj, int methid, int cparam, void *param[], int cbparam[], int64 *lpllVal);

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 Characteristic* properties 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.)