Función BluetoothGATTGetCharacteristicValue (bluetoothleapis.h)

Artículo
03/14/2023

La función BluetoothGATTGetCharacteristicValue obtiene el valor de la característica especificada.

Sintaxis

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
);

Parámetros

[in] hDevice

Identificador del servicio.

[in] Characteristic

Puntero a la característica primaria del valor de característica que se va a recuperar.

[in] CharacteristicValueDataSize

Número de bytes asignados para el parámetro CharacteristicValue .

[out, optional] CharacteristicValue

Puntero al búfer en el que se va a devolver el valor de característica.

[out, optional] CharacteristicValueSizeRequired

Puntero al búfer en el que almacenar el número de bytes necesarios para devolver datos en el búfer al que apunta CharacteristicValue.

[in] Flags

Marcas para modificar el comportamiento de BluetoothGATTGetCharacteristicValue:

Marca	Descripción
BLUETOOTH_GATT_FLAG_NONE	El cliente no tiene requisitos GATT específicos (valor predeterminado).
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED	El cliente solicita que los datos se transmitan a través de un canal cifrado.
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED	El cliente solicita que los datos se transmitan a través de un canal autenticado.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE	El valor de característica es leer directamente desde el dispositivo. Esto sobrescribe el que se encuentra en la memoria caché si ya está presente.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE	El valor de característica debe leerse desde la memoria caché (independientemente de si está presente en la memoria caché o no).

Valor devuelto

La función BluetoothGATTGetCharacteristicValue devuelve los siguientes valores:

Código devuelto	Descripción
S_OK	La operación se ha completado correctamente.
ERROR_MORE_DATA	El parámetro de búfer es NULL y el número de elementos disponibles se devuelve en su lugar.
ERROR_ACCESS_DENIED	Se devuelve si se proporciona un servicio primario y un identificador de servicio y la jerarquía de servicios no se acumula en el identificador de servicio primario proporcionado.
ERROR_INVALID_PARAMETER	CharacteristicValue y CharacteristicValueSizeRequired son 0.
ERROR_INVALID_USER_BUFFER	Se especifica un búfer, pero el tamaño del recuento de búferes es menor que el necesario, en bytes.
ERROR_BAD_COMMAND	Los datos actuales de la memoria caché parecen ser incoherentes y conducen a errores internos.
ERROR_BAD_NET_RESP	El servidor de destino no proporcionó una respuesta de red adecuada.
ERROR_SEM_TIMEOUT	Se agota el tiempo de espera de la solicitud.
ERROR_PRIVILEGE_NOT_HELD	El valor de característica no se puede leer según lo dictado por las propiedades de características.
ERROR_NO_SYSTEM_RESOURCES	La operación se quedó sin memoria.
E_BLUETOOTH_ATT_INVALID_HANDLE	El identificador de atributo especificado no era válido en este servidor.
E_BLUETOOTH_ATT_READ_NOT_PERMITTED	El atributo no se puede leer.
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED	El atributo no se puede escribir.
E_BLUETOOTH_ATT_INVALID_PDU	El atributo PDU no era válido.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION	El atributo requiere autenticación antes de que se pueda leer o escribir.
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED	El servidor de atributos no admite la solicitud recibida del cliente.
E_BLUETOOTH_ATT_INVALID_OFFSET	Offset especificado fue pasado el final del atributo.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION	El atributo requiere autorización antes de que se pueda leer o escribir.
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL	Se han puesto en cola demasiadas escrituras de preparación.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND	No se encontró ningún atributo dentro del intervalo de identificadores de atributo especificado.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG	El atributo no se puede leer ni escribir mediante la solicitud de lectura de blobs.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE	El tamaño de la clave de cifrado usado para cifrar este vínculo no es suficiente.
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH	La longitud del valor del atributo no es válida para la operación.
E_BLUETOOTH_ATT_UNLIKELY	La solicitud de atributo solicitada ha encontrado un error poco probable y, por lo tanto, no se pudo completar como se solicitó.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION	El atributo requiere cifrado antes de que se pueda leer o escribir.
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE	El tipo de atributo no es un atributo de agrupación admitido según lo definido por una especificación de capa superior.
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES	Recursos insuficientes para completar la solicitud.
E_BLUETOOTH_ATT_UNKNOWN_ERROR	Se ha recibido un error que se encuentra en el intervalo reservado.

Comentarios

El valor de característica se devuelve de la memoria caché si ya hay uno presente. Este sería el caso la mayor parte del tiempo, ya que todos los atributos de dispositivo se almacenan en caché en el momento del emparejamiento o asociación. Sin embargo, si no está presente, el valor de característica se lee directamente desde el dispositivo y se almacenará en caché al leerlo correctamente desde el dispositivo. Si BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE o BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE está presente, el valor de característica se lee mediante el método especificado.

Las características devueltas se almacenan en caché tras la recuperación correcta de características del dispositivo directamente. A menos que se reciba un evento de cambio de servicio, no se espera que cambie la lista de características devueltas.

Los controladores de perfil deben asignar previamente un búfer suficientemente grande para que se devuelva la matriz de características. Los autores de llamadas pueden determinar el tamaño de búfer necesario pasando un valor distinto de NULL en CharacteristicValueSizeRequired y NULL en CharacteristicValue.

El servicio primario debe estar presente en la memoria caché; de lo contrario, se producirá un error en la función. El servicio primario debe ser un servicio devuelto por BluetoothGATTGetServices o BluetoothGATTGetIncludedServices.

Ejemplo


            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;
            }

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con Windows 8 y versiones posteriores de Windows.
Plataforma de destino	Universal
Encabezado	bluetoothleapis.h
Library	BluetoothAPIs.lib
Archivo DLL	BluetoothAPIs.dll

Consulte también

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_CHARACTERISTIC_VALUE

Compartir a través de

Función BluetoothGATTGetCharacteristicValue (bluetoothleapis.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Requisitos

Consulte también

Comentarios

Recursos adicionales