Funzione BluetoothGATTGetCharacteristics (bluetoothleapis.h)

Articolo
03/14/2023

La funzione BluetoothGATTGetCharacteristics ottiene tutte le caratteristiche disponibili per il servizio specificato.

Sintassi

HRESULT BluetoothGATTGetCharacteristics(
  [in]            HANDLE                      hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE        Service,
  [in]            USHORT                      CharacteristicsBufferCount,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC CharacteristicsBuffer,
  [out]           USHORT                      *CharacteristicsBufferActual,
  [in]            ULONG                       Flags
);

Parametri

[in] hDevice

Gestire il dispositivo o il servizio Bluetooth.

[in, optional] Service

Indirizzo di una struttura di BTH_LE_GATT_SERVICE contenente il servizio padre dei servizi inclusi da recuperare. Questo parametro è obbligatorio se un handle di dispositivo viene passato a hDevice. Questo parametro è facoltativo se un handle di servizio è stato passato a hDevice, nel qual caso il servizio specificato dall'handle del servizio verrà considerato come padre.

[in] CharacteristicsBufferCount

Numero di elementi allocati per il parametro CharacteristicsBuffer .

[out, optional] CharacteristicsBuffer

Puntatore a un buffer in cui restituire le caratteristiche come matrice di strutture BTH_LE_GATT_CHARACTERISTIC .

[out] CharacteristicsBufferActual

Puntatore al buffer in cui viene restituito il numero effettivo di caratteristiche restituite nel parametro CharacteristicsBuffer .

[in] Flags

Flag per modificare il comportamento di BluetoothGATTGetCharacteristics:

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 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 rollup nell'handle del servizio padre fornito.
ERROR_INVALID_PARAMETER	Si è verificata una delle condizioni seguenti: CharacteristicsBuffer è NULL e CharacteristicsBufferCount è 0 CharacteristicsBuffer è diverso da NULL, ma CharacteristicsBufferCount è NULL CharacteristicsBuffer è diverso da NULL e CharacteristicsBufferCount è 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 in caso di recupero corretto delle caratteristiche dal dispositivo direttamente. A meno che non venga ricevuto un evento di modifica del servizio, non è previsto che l'elenco delle caratteristiche restituite cambi.

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

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

Il servizio 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 Characteristic Buffer Size
////////////////////////////////////////////////////////////////////////////

        hr = BluetoothGATTGetCharacteristics(
                hCurrService,
                currGattService,
                0,
                NULL,
                &charBufferSize,
                BLUETOOTH_GATT_FLAG_NONE);
        
        if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
            PrintHr("BluetoothGATTGetCharacteristics - Buffer Size", hr);
            goto Done;
        }
        
        if (charBufferSize > 0) {
            pCharBuffer = (PBTH_LE_GATT_CHARACTERISTIC)
                    malloc(charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
        
            if (NULL == pCharBuffer) {
                printf("pCharBuffer out of memory\r\n");
                goto Done;
            } else {
                RtlZeroMemory(pCharBuffer, 
                        charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
            }

////////////////////////////////////////////////////////////////////////////
// Retrieve Characteristics
////////////////////////////////////////////////////////////////////////////
    
            hr = BluetoothGATTGetCharacteristics(
                    hCurrService,
                    currGattService,
                    charBufferSize,
                    pCharBuffer,
                    &numChars,
                    BLUETOOTH_GATT_FLAG_NONE);

            if (S_OK != hr) {
                PrintHr("BluetoothGATTGetCharacteristics - Actual Data", hr);
                goto Done; // Allow continuation
            }

            if (numChars != charBufferSize) {
                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_SERVICE

Condividi tramite