Поделиться через

Функция BluetoothGATTGetDescriptors (bluetoothleapis.h)

  • Статья

Функция BluetoothGATTGetDescriptors получает все дескрипторы, доступные для указанной характеристики.

Синтаксис

HRESULT BluetoothGATTGetDescriptors(
  [in]            HANDLE                      hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC Characteristic,
  [in]            USHORT                      DescriptorsBufferCount,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR     DescriptorsBuffer,
  [out]           USHORT                      *DescriptorsBufferActual,
  [in]            ULONG                       Flags
);

Параметры

[in] hDevice

Дескриптор устройства или службы Bluetooth. Если передается дескриптор службы, служба должна быть дедушкой дескриптора.

[in] Characteristic

Указатель на BTH_LE_GATT_CHARACTERISTIC структуру, содержащую родительскую характеристику извлекаемых дескрипторов.

[in] DescriptorsBufferCount

Количество элементов, выделенных для параметра DescriptorsBuffer .

[out, optional] DescriptorsBuffer

Указатель на буфер, содержащий BTH_LE_GATT_DESCRIPTOR структуру, в которую возвращаются дескрипторы.

[out] DescriptorsBufferActual

Указатель на буфер, в который было возвращено фактическое количество дескрипторов в параметре DescriptorsBuffer .

[in] Flags

Флаги для изменения поведения BluetoothGATTGetDescriptors:

Flag Описание
BLUETOOTH_GATT_FLAG_NONE У клиента нет конкретных требований GATT (по умолчанию).

Возвращаемое значение

Эта функция возвращает следующие значения:

Код возврата Описание
S_OK
 Операция выполнена успешно.
ERROR_MORE_DATA
 Параметр buffer имеет значение NULL, и вместо этого возвращается количество доступных элементов.
ERROR_ACCESS_DENIED
 Возвращается, если предоставляются как родительская служба, так и дескриптор службы, а иерархия служб не выполняет свертку до предоставленного дескриптора родительской службы.
ERROR_INVALID_PARAMETER
 Произошло одно из следующих условий:
  • DescriptorsBuffer имеет значение NULL, а DescriptorsBufferCount — 0.
  • DescriptorsBuffer не равно NULL, но DescriptorsBufferCount имеет значение NULL.
  • DescriptorsBuffer не равно NULL, а DescriptorsBufferCount — 0.
ERROR_INVALID_USER_BUFFER
 Указан буфер, но размер количества буферов меньше, чем требуется, в байтах.
ERROR_BAD_COMMAND
 Текущие данные в кэше выглядят несогласованными и приводят к внутренним ошибкам.
ERROR_NO_SYSTEM_RESOURCES
 Для операции не хватает памяти.

Комментарии

Возвращаемые характеристики кэшируются при успешном извлечении характеристик непосредственно с устройства. Если событие изменения службы не получено, список возвращаемых характеристик не изменится.

Драйверы профилей должны предварительно выделить достаточно большой буфер для возвращаемого массива характеристик. Вызывающие стороны могут определить необходимый размер буфера, передав значение, отличное от NULL , в descriptorsBufferActual и NULL в DescriptorsBuffer.

Не изменяйте возвращаемую структуру характеристик, а затем используйте измененную структуру в последующих вызовах функций. Поведение не определено, если это делает вызывающий объект.

Родительская характеристика должна присутствовать в кэше, в противном случае функция завершится ошибкой. Родительская служба должна быть службой, возвращаемой bluetoothGATTGetServices или BluetoothGATTGetIncludedServices.

Пример


////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Buffer Size
////////////////////////////////////////////////////////////////////////////
GetDescriptors:
            hr = BluetoothGATTGetDescriptors(
                    hCurrService,
                    currGattChar,
                    0,
                    NULL,
                    &descriptorBufferSize,
                    BLUETOOTH_GATT_FLAG_NONE);
            
            if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                PrintHr("BluetoothGATTGetDescriptors - Buffer Size", hr);
                goto Done; // Allow continuation
            }
            
            if (descriptorBufferSize > 0) {
                pDescriptorBuffer = (PBTH_LE_GATT_DESCRIPTOR)
                        malloc(descriptorBufferSize 
                            * sizeof(BTH_LE_GATT_DESCRIPTOR));
            
                if (NULL == pDescriptorBuffer) {
                    printf("pDescriptorBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescriptorBuffer, descriptorBufferSize);
                }
            
////////////////////////////////////////////////////////////////////////////
// Retrieve Descriptors
////////////////////////////////////////////////////////////////////////////
    
                hr = BluetoothGATTGetDescriptors(
                        hCurrService,
                        currGattChar,
                        descriptorBufferSize,
                        pDescriptorBuffer,
                        &numDescriptors,
                        BLUETOOTH_GATT_FLAG_NONE);
            
                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptors - Actual Data", hr);
                    goto Done;
                }

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

Требования

Требование Значение
Минимальная версия клиента Поддерживается в Windows 8 и более поздних версиях Windows.
Целевая платформа Универсальное
Верхняя часть bluetoothleapis.h
Библиотека BluetoothApis.lib
DLL BluetoothAPIs.dll

См. также раздел

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_DESCRIPTOR