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

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

  • Статья

Функция BluetoothGATTGetCharacteristicValue получает значение указанной характеристики.

Синтаксис

HRESULT BluetoothGATTGetCharacteristicValue(
  [in]            HANDLE                            hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC       Characteristic,
  [in]            ULONG                             CharacteristicValueDataSize,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
  [out, optional] USHORT                            *CharacteristicValueSizeRequired,
  [in]            ULONG                             Flags
);

Параметры

[in] hDevice

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

[in] Characteristic

Указатель на родительскую характеристику извлекаемого значения характеристики.

[in] CharacteristicValueDataSize

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

[out, optional] CharacteristicValue

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

[out, optional] CharacteristicValueSizeRequired

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

[in] Flags

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

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 Значение характеристики должно считываться из кэша (независимо от того, присутствует ли оно в кэше).

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

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

Код возврата Описание
S_OK
 Операция выполнена успешно.
ERROR_MORE_DATA
 Параметр buffer имеет значение NULL, и вместо этого возвращается количество доступных элементов.
ERROR_ACCESS_DENIED
 Возвращается, если предоставляются как родительская служба, так и дескриптор службы, а иерархия служб не выполняет свертку до предоставленного дескриптора родительской службы.
ERROR_INVALID_PARAMETER
 Значения ПараметровЗначение и Значение ХарактеристикиЗначениеSizeRequired имеют значение 0.
ERROR_INVALID_USER_BUFFER
 Указан буфер, но размер количества буферов меньше, чем требуется, в байтах.
ERROR_BAD_COMMAND
 Текущие данные в кэше выглядят несогласованными и приводят к внутренним ошибкам.
ERROR_BAD_NET_RESP
 Целевой сервер не предоставил соответствующий ответ сети.
ERROR_SEM_TIMEOUT
 Истекло время ожидания запроса.
ERROR_PRIVILEGE_NOT_HELD
 Значение характеристики не является удобочитаемым, как это определяется свойствами характеристики.
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 , в Значение ХарактеристикиЗначениеSizeRequired и ЗНАЧЕНИЕ NULL в СвойствеЗначение.

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

Пример


            if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        0,
                        NULL,
                        &charValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);

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

////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        (ULONG)charValueDataSize,
                        pCharValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);

                // Free before going to next iteration, or memory leak.
                free(pCharValueBuffer);
                pCharValueBuffer = NULL;
            }

Требования

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

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

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_CHARACTERISTIC_VALUE