Funzione BluetoothGATTGetDescriptors (bluetoothleapis.h)

Articolo
02/26/2024

La funzione BluetoothGATTGetDescriptors ottiene tutti i descrittori disponibili per la caratteristica specificata.

Sintassi

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

Parametri

[in] hDevice

Gestire il dispositivo o il servizio Bluetooth. Se viene passato un handle di servizio, il servizio deve essere il nonno del descrittore.

[in] Characteristic

Puntatore a BTH_LE_GATT_CHARACTERISTIC struttura contenente la caratteristica padre dei descrittori da recuperare.

[in] DescriptorsBufferCount

Numero di elementi allocati per il parametro DescriptorsBuffer .

[out, optional] DescriptorsBuffer

Puntatore al buffer contenente una struttura BTH_LE_GATT_DESCRIPTOR in cui restituire i descrittori.

[out] DescriptorsBufferActual

Puntatore al buffer in cui è stato restituito il numero effettivo di descrittori nel parametro DescriptorsBuffer .

[in] Flags

Flag per modificare il comportamento di BluetoothGATTGetDescriptors:

Flag	Descrizione
BLUETOOTH_GATT_FLAG_NONE	Il client non ha requisiti GATT specifici (impostazione predefinita).

Valore restituito

Questa funzione restituisce i valori seguenti:

Codice restituito	Descrizione
S_OK	Operazione riuscita.
ERROR_MORE_DATA	Il parametro del buffer è NULL e viene restituito il numero di elementi disponibili.
ERROR_ACCESS_DENIED	Restituito se vengono forniti sia un servizio padre che un handle di servizio e la gerarchia del servizio non viene implementata nell'handle del servizio padre fornito.
ERROR_INVALID_PARAMETER	Si è verificata una delle seguenti condizioni: I descrittoriBuffer sono NULL e DescriptorsBufferCount è 0. I descrittoriBuffer non sono NULL, ma DescriptorsBufferCount è NULL. I descrittoriBuffer sono non NULL e DescriptorsBufferCount è 0.
ERROR_INVALID_USER_BUFFER	Viene specificato un buffer, ma le dimensioni del conteggio del buffer sono inferiori a quelle necessarie, in byte.
ERROR_BAD_COMMAND	I dati correnti nella cache sembrano incoerenti e comportano errori interni.
ERROR_NO_SYSTEM_RESOURCES	L'operazione ha esaurito la memoria.

Commenti

Le caratteristiche restituite vengono memorizzate nella cache al recupero corretto delle caratteristiche dal dispositivo direttamente. A meno che non venga ricevuto un evento di modifica del servizio, l'elenco delle caratteristiche restituite non deve cambiare.

I driver di profilo devono pre-allocare un buffer sufficientemente grande per la matrice di caratteristiche da restituire. I chiamanti possono determinare le dimensioni del buffer necessarie passando un valore non NULL in DescrittoriBufferActual e NULL in DescrittoriBuffer.

Non modificare la struttura caratteristica restituita e quindi usare la struttura modificata nelle chiamate di funzione successive. Il comportamento non è definito se il chiamante esegue questa operazione.

La caratteristica padre deve essere presente nella cache, in caso contrario la funzione avrà esito negativo. Il servizio padre deve essere un servizio restituito da BluetoothGATTGetServices o BluetoothGATTGetIncludedServices.

Esempio


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

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in Windows 8 e versioni successive di Windows.
Piattaforma di destinazione	Universale
Intestazione	bluetoothleapis.h
Libreria	BluetoothApis.lib
DLL	BluetoothAPIs.dll

Vedi anche

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_DESCRIPTOR

Condividi tramite