nf-bluetoothleapis-bluetoothgattgetcharacteristics.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:bluetoothleapis.BluetoothGATTGetCharacteristics	BluetoothGATTGetCharacteristics function (bluetoothleapis.h)	Gets all the characteristics available for the specified service.	BluetoothGATTGetCharacteristics BluetoothGATTGetCharacteristics function [Bluetooth Devices] bltooth.bluetoothgattgetcharacteristics bluetoothleapis/BluetoothGATTGetCharacteristics	bltooth\bluetoothgattgetcharacteristics.htm	bltooth	974270EE-6319-45E3-BAB8-3A57665591EA	12/05/2018	bluetoothleapis.h		Universal	Supported in Windows 8 and later versions of Windows.											BluetoothApis.lib	BluetoothApis.dll		Windows			19H1	BluetoothGATTGetCharacteristics bluetoothleapis/BluetoothGATTGetCharacteristics	c++	APIRef kbSyntax	DllExport	BluetoothApis.dll Ext-MS-Win-Bluetooth-APIs-l1-1-0.dll	BluetoothGATTGetCharacteristics

-description

The BluetoothGATTGetCharacteristics function gets all the characteristics available for the specified service.

-parameters

-param hDevice [in]

Handle to the Bluetooth device or service.

-param Service [in, optional]

Address of a BTH_LE_GATT_SERVICE structure containing the parent service of the included services to be retrieved. This parameter is required if a device handle is passed to hDevice. This parameter is optional if a service handle was passed to hDevice, in which case the service specified by the service handle will be treated as the parent.

-param CharacteristicsBufferCount [in]

The number of elements allocated for the CharacteristicsBuffer parameter.

-param CharacteristicsBuffer [out, optional]

Pointer to a buffer into which to return characteristics as an array of BTH_LE_GATT_CHARACTERISTIC structures.

-param CharacteristicsBufferActual [out]

Pointer to buffer into which is returned the actual number of characteristics that were returned in the CharacteristicsBuffer parameter.

-param Flags [in]

Flags to modify the behavior of BluetoothGATTGetCharacteristics:

Flag	Description
BLUETOOTH_GATT_FLAG_NONE	The client does not have specific GATT requirements (default).

-returns

This function returns the following values:

Return code	Description
S_OK	The operation completed successfully.
ERROR_MORE_DATA	The buffer parameter is NULL and the number of items available is being returned instead.
ERROR_ACCESS_DENIED	Returned if both a parent service and a service handle are provided and the service hierarchy does not roll up to the provided parent service handle.
ERROR_INVALID_PARAMETER	One of the following conditions occurred: CharacteristicsBuffer is NULL, and CharacteristicsBufferCount is 0 CharacteristicsBuffer is non-NULL, but CharacteristicsBufferCount is NULL CharacteristicsBuffer is non-NULL, and CharacteristicsBufferCount is 0
ERROR_INVALID_USER_BUFFER	A buffer is specified, but the buffer count size is smaller than what is required, in bytes.
ERROR_BAD_COMMAND	The current data in the cache appears to be inconsistent, and is leading to internal errors.
ERROR_NO_SYSTEM_RESOURCES	The operation ran out of memory.

-remarks

Returned characteristics are cached upon successful retrieval of characteristics from the device directly. Unless a service-change event is received, the list of returned characteristics is not expected to change.

Profile drivers should pre-allocate a sufficiently large buffer for the array of characteristics to be returned in. Callers can determine the necessary buffer size by passing a non-NULL value in CharacteristicsBufferActual and NULL in CharacteristicsBuffer.

Do not modify the returned characteristic structure, and then use the modified structure in subsequent function calls. Behavior is undefined if the caller does this.

The parent service must be present in the cache, otherwise the function will fail. The parent service must be a service returned by either BluetoothGATTGetServices or BluetoothGATTGetIncludedServices.

Example

////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Buffer Size
////////////////////////////////////////////////////////////////////////////

        hr = BluetoothGATTGetCharacteristics(
                hCurrService,
                currGattService,
                0,
                NULL,
                &charBufferSize,
                BLUETOOTH_GATT_FLAG_NONE);
        
        if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
            PrintHr("BluetoothGATTGetCharacteristics - Buffer Size", hr);
            goto Done;
        }
        
        if (charBufferSize > 0) {
            pCharBuffer = (PBTH_LE_GATT_CHARACTERISTIC)
                    malloc(charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
        
            if (NULL == pCharBuffer) {
                printf("pCharBuffer out of memory\r\n");
                goto Done;
            } else {
                RtlZeroMemory(pCharBuffer, 
                        charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
            }

////////////////////////////////////////////////////////////////////////////
// Retrieve Characteristics
////////////////////////////////////////////////////////////////////////////
    
            hr = BluetoothGATTGetCharacteristics(
                    hCurrService,
                    currGattService,
                    charBufferSize,
                    pCharBuffer,
                    &numChars,
                    BLUETOOTH_GATT_FLAG_NONE);

            if (S_OK != hr) {
                PrintHr("BluetoothGATTGetCharacteristics - Actual Data", hr);
                goto Done; // Allow continuation
            }

            if (numChars != charBufferSize) {
                printf("buffer size and buffer size actual size mismatch\r\n");
                goto Done;
            }
        }

-see-also

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_SERVICE