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