ReadValue Method

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

Syntax

• C++

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

#define MID_BLECLIENT_READVALUE 11

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