Compartir a través de


Función BluetoothGATTGetDescriptorValue (bluetoothleapis.h)

La función BluetoothGATTGetDescriptorValue obtiene el valor del descriptor especificado.

Sintaxis

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

Parámetros

[in] hDevice

Identificador del servicio.

[in] Descriptor

Puntero a BTH_LE_GATT_DESCRIPTOR estructura que contiene el descriptor primario del valor del descriptor que se va a recuperar.

[in] DescriptorValueDataSize

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

[out, optional] DescriptorValue

Puntero a BTH_LE_GATT_DESCRIPTOR_VALUE estructura en la que se va a devolver el valor del descriptor.

[out, optional] DescriptorValueSizeRequired

Puntero al búfer en el que se almacenará el número de bytes adicionales necesarios para devolver datos en el búfer al que apunta DescriptorValue.

[in] Flags

Marcas para modificar el comportamiento de BluetoothGATTGetDescriptorValue:

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 del descriptor se va a 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 del descriptor es leer desde la memoria caché (independientemente de si está presente en la memoria caché o no).

Valor devuelto

La función BluetoothGATTGetDescriptorValue 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
DescriptorValue y DescriptorValueSizeRequired 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_INVALID_FUNCTION
Se especificó un valor descriptor para recuperarse de la memoria caché, pero el valor del descriptor no está presente en la memoria caché.
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_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 para 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 blob de lectura.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE
El tamaño de clave de cifrado que se usa 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
Error que se encuentra en el intervalo reservado.

Comentarios

El valor del descriptor se devuelve de la memoria caché si ya existe uno. Este sería el caso la mayor parte del tiempo, ya que todos los atributos del dispositivo se almacenan en caché en el momento del emparejamiento o la asociación. Sin embargo, si no está presente, el valor del descriptor se lee directamente desde el dispositivo y se almacenará en caché después de 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 del descriptor se lee mediante el método especificado.

Los valores de descriptor devueltos se almacenan en caché tras la recuperación correcta de los valores de descriptor desde el dispositivo directamente. A menos que se reciba un evento de cambio de servicio, no se espera que cambien los valores del descriptor.

Los controladores de perfil deben asignar previamente un búfer suficientemente grande para la matriz de valores de descriptor en los que se va a devolver. Los autores de llamadas pueden determinar el tamaño de búfer necesario pasando un valor distinto de NULL en DescriptorValueSizeRequired y NULL en DescriptorValue.

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


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

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_DESCRIPTOR

BTH_LE_GATT_DESCRIPTOR_VALUE