Discover Method

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);
#define MID_BLECLIENT_DISCOVER 5

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

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.)
Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks BLE 2020 C++ Edition - Version 20.0 [Build 8158]