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

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

  • Статья

Функция BluetoothGATTGetDescriptorValue получает значение указанного дескриптора.

Синтаксис

HRESULT BluetoothGATTGetDescriptorValue(
  [in]            HANDLE                        hDevice,
  [in]            PBTH_LE_GATT_DESCRIPTOR       Descriptor,
  [in]            ULONG                         DescriptorValueDataSize,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR_VALUE DescriptorValue,
  [out, optional] USHORT                        *DescriptorValueSizeRequired,
  [in]            ULONG                         Flags
);

Параметры

[in] hDevice

Дескриптор для службы.

[in] Descriptor

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

[in] DescriptorValueDataSize

Число байтов, выделенных для параметра DescriptorValue .

[out, optional] DescriptorValue

Указатель на BTH_LE_GATT_DESCRIPTOR_VALUE структуру, в которую возвращается значение дескриптора.

[out, optional] DescriptorValueSizeRequired

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

[in] Flags

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

Flag Описание
BLUETOOTH_GATT_FLAG_NONE Клиент не предъявляет особых требований к GATT (по умолчанию).
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED Клиент запрашивает передачу данных по зашифрованным каналам.
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED Клиент запрашивает передачу данных по каналу, прошедшему проверку подлинности.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE Значение дескриптора должно считываться непосредственно с устройства. Это перезаписывает объект в кэше, если он уже присутствует.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE Значение дескриптора должно считываться из кэша (независимо от того, присутствует ли оно в кэше).

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

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

Код возврата Описание
S_OK
 Операция выполнена успешно.
ERROR_MORE_DATA
 Параметр буфера имеет значение NULL , а вместо него возвращается количество доступных элементов.
ERROR_ACCESS_DENIED
 Возвращается, если предоставляются родительская служба и дескриптор службы, а иерархия служб не выполняет сверты до предоставленного дескриптора родительской службы.
ERROR_INVALID_PARAMETER
 Значения DescriptorValue и DescriptorValueSizeRequired имеют значение 0.
ERROR_INVALID_USER_BUFFER
 Указан буфер, но размер количества буферов меньше требуемого размера в байтах.
ERROR_INVALID_FUNCTION
 Было указано значение дескриптора для извлечения из кэша, но значение дескриптора отсутствует в кэше.
ERROR_BAD_COMMAND
 Текущие данные в кэше несогласованны и приводят к внутренним ошибкам.
ERROR_BAD_NET_RESP
 Целевой сервер не предоставил соответствующий сетевой ответ.
ERROR_SEM_TIMEOUT
 Время ожидания запроса истекло.
ERROR_NO_SYSTEM_RESOURCES
 В операции не хватает памяти.
E_BLUETOOTH_ATT_INVALID_HANDLE
 Указанный дескриптор атрибута был недопустим на этом сервере.
E_BLUETOOTH_ATT_READ_NOT_PERMITTED
 Атрибут не может быть прочитан.
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED
 Атрибут не может быть записан.
E_BLUETOOTH_ATT_INVALID_PDU
 Недопустимый атрибут PDU.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION
 Атрибут требует проверки подлинности, прежде чем его можно будет прочитать или записать.
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED
 Сервер атрибутов не поддерживает запрос, полученный от клиента.
E_BLUETOOTH_ATT_INVALID_OFFSET
 Указанное смещение прошло после конца атрибута.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION
 Атрибут требует авторизации, прежде чем его можно будет прочитать или записать.
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL
 Слишком много операций подготовки записей поставлено в очередь.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND
 Атрибут не найден в заданном диапазоне дескрипторов атрибута.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG
 Атрибут не может быть прочитан или записан с помощью запроса на чтение BLOB-объекта.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE
 Размер ключа шифрования, используемый для шифрования этой ссылки, недостаточен.
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH
 Длина значения атрибута недопустима для операции.
E_BLUETOOTH_ATT_UNLIKELY
 Запрошенный запрос атрибута столкнулся с ошибкой, которая была маловероятна и поэтому не может быть выполнена в соответствии с запросом.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION
 Атрибут требует шифрования, прежде чем его можно будет прочитать или записать.
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE
 Тип атрибута не является поддерживаемым атрибутом группирования, как определено спецификацией более высокого уровня.
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES
 Недостаточно ресурсов для выполнения запроса.
E_BLUETOOTH_ATT_UNKNOWN_ERROR
 Получена ошибка, связанная с зарезервированным диапазоном.

Комментарии

Значение дескриптора возвращается из кэша, если оно уже существует. Это происходит большую часть времени, так как все атрибуты устройства кэшируются во время связывания или связи. Однако если его нет, то значение дескриптора считывается непосредственно с устройства и будет кэшировано после успешного чтения с устройства. При наличии BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE или BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE значение дескриптора считывается с помощью указанного метода.

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

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

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

Пример


////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Value Buffer Size
////////////////////////////////////////////////////////////////////////////
                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        0,
                        NULL,
                        &descValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetDescriptorValue - Buffer Size", hr);
                    goto Done; // allow continuation
                }

                pDescValueBuffer = (PBTH_LE_GATT_DESCRIPTOR_VALUE)malloc(descValueDataSize);

                if (NULL == pDescValueBuffer) {
                    printf("pDescValueBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescValueBuffer, descValueDataSize);
                }

////////////////////////////////////////////////////////////////////////////
// Retrieve the Descriptor Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        (ULONG)descValueDataSize,
                        pDescValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

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

Требования

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

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

BTH_LE_GATT_DESCRIPTOR

BTH_LE_GATT_DESCRIPTOR_VALUE