Subscribe Method

Subscribes to value updates for the specified characteristic.

Syntax

• C++

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

Unicode (Windows)
INT Subscribe(LPCWSTR lpszServiceId, LPCWSTR lpszCharacteristicId);

#define MID_BLECLIENT_SUBSCRIBE 15

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

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.)