Función BluetoothGATTGetDescriptors (bluetoothleapis.h)

La función BluetoothGATTGetDescriptors obtiene todos los descriptores disponibles para la característica especificada.

Sintaxis

HRESULT BluetoothGATTGetDescriptors(
  [in]            HANDLE                      hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC Characteristic,
  [in]            USHORT                      DescriptorsBufferCount,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR     DescriptorsBuffer,
  [out]           USHORT                      *DescriptorsBufferActual,
  [in]            ULONG                       Flags
);

Parámetros

[in] hDevice

Controle el dispositivo o el servicio Bluetooth. Si se pasa un identificador de servicio, el servicio debe ser el abuelo del descriptor.

[in] Characteristic

Puntero a BTH_LE_GATT_CHARACTERISTIC estructura que contiene la característica primaria de los descriptores que se van a recuperar.

[in] DescriptorsBufferCount

Número de elementos asignados para el parámetro DescriptorsBuffer .

[out, optional] DescriptorsBuffer

Puntero al búfer que contiene una estructura de BTH_LE_GATT_DESCRIPTOR en la que se van a devolver descriptores.

[out] DescriptorsBufferActual

Puntero al búfer en el que se devolvió el número real de descriptores en el parámetro DescriptorsBuffer .

[in] Flags

Marcas para modificar el comportamiento de BluetoothGATTGetDescriptors:

Marca	Descripción
BLUETOOTH_GATT_FLAG_NONE	El cliente no tiene requisitos gatt específicos (valor predeterminado).

Valor devuelto

Esta función devuelve los valores siguientes:

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	Se produjo una de las siguientes condiciones: DescriptorsBuffer es NULL y DescriptorsBufferCount es 0. DescriptorsBuffer no es NULL, pero DescriptorsBufferCount es NULL. DescriptorsBuffer no es NULL y DescriptorsBufferCount es 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_NO_SYSTEM_RESOURCES	La operación se quedó sin memoria.

Comentarios

Las características devueltas se almacenan en caché después de recuperar correctamente las 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 DescriptorsBufferActual y NULL en DescriptoresBuffer.

No modifique la estructura de características devuelta y, a continuación, use la estructura modificada en las llamadas de función posteriores. El comportamiento no está definido si el autor de la llamada lo hace.

La característica primaria 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 Buffer Size
////////////////////////////////////////////////////////////////////////////
GetDescriptors:
            hr = BluetoothGATTGetDescriptors(
                    hCurrService,
                    currGattChar,
                    0,
                    NULL,
                    &descriptorBufferSize,
                    BLUETOOTH_GATT_FLAG_NONE);
            
            if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                PrintHr("BluetoothGATTGetDescriptors - Buffer Size", hr);
                goto Done; // Allow continuation
            }
            
            if (descriptorBufferSize > 0) {
                pDescriptorBuffer = (PBTH_LE_GATT_DESCRIPTOR)
                        malloc(descriptorBufferSize 
                            * sizeof(BTH_LE_GATT_DESCRIPTOR));
            
                if (NULL == pDescriptorBuffer) {
                    printf("pDescriptorBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescriptorBuffer, descriptorBufferSize);
                }
            
////////////////////////////////////////////////////////////////////////////
// Retrieve Descriptors
////////////////////////////////////////////////////////////////////////////
    
                hr = BluetoothGATTGetDescriptors(
                        hCurrService,
                        currGattChar,
                        descriptorBufferSize,
                        pDescriptorBuffer,
                        &numDescriptors,
                        BLUETOOTH_GATT_FLAG_NONE);
            
                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptors - Actual Data", hr);
                    goto Done;
                }

                if (numDescriptors != descriptorBufferSize) {
                    printf("buffer size and buffer size actual size mismatch\r\n");
                    goto Done;
                }
            }

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_DESCRIPTOR