Condividi tramite

Funzione BluetoothGATTGetCharacteristicValue (bluetoothleapis.h)

  • Articolo

La funzione BluetoothGATTGetCharacteristicValue ottiene il valore della caratteristica specificata.

Sintassi

HRESULT BluetoothGATTGetCharacteristicValue(
  [in]            HANDLE                            hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC       Characteristic,
  [in]            ULONG                             CharacteristicValueDataSize,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
  [out, optional] USHORT                            *CharacteristicValueSizeRequired,
  [in]            ULONG                             Flags
);

Parametri

[in] hDevice

Gestire il servizio.

[in] Characteristic

Puntatore alla caratteristica padre del valore della caratteristica da recuperare.

[in] CharacteristicValueDataSize

Numero di byte allocati per il parametro CharacteristicValue .

[out, optional] CharacteristicValue

Puntatore al buffer in cui restituire il valore della caratteristica.

[out, optional] CharacteristicValueSizeRequired

Puntatore al buffer in cui archiviare il numero di byte necessari per restituire i dati nel buffer a cui punta CharacteristicValue.

[in] Flags

Flag per modificare il comportamento di BluetoothGATTGetCharacteristicValue:

Flag Descrizione
BLUETOOTH_GATT_FLAG_NONE Il client non ha requisiti GATT specifici (impostazione predefinita).
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED Il client richiede la trasmissione dei dati su un canale crittografato.
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED Il client richiede la trasmissione dei dati su un canale autenticato.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE Il valore della caratteristica deve essere letto direttamente dal dispositivo. Questo sovrascrive quello nella cache, se ne è già presente uno.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE Il valore della caratteristica deve essere letto dalla cache , indipendentemente dal fatto che sia presente nella cache o meno.

Valore restituito

La funzione BluetoothGATTGetCharacteristicValue 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
 Sia CharacteristicValue che CharacteristicValueSizeRequired sono 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_BAD_NET_RESP
 Il server di destinazione non ha fornito una risposta di rete appropriata.
ERROR_SEM_TIMEOUT
 Timeout della richiesta.
ERROR_PRIVILEGE_NOT_HELD
 Il valore della caratteristica non è leggibile in base alle proprietà delle caratteristiche.
ERROR_NO_SYSTEM_RESOURCES
 L'operazione ha esaurito la memoria.
E_BLUETOOTH_ATT_INVALID_HANDLE
 L'handle di attributo specificato non è valido in questo server.
E_BLUETOOTH_ATT_READ_NOT_PERMITTED
 L'attributo non può essere letto.
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED
 L'attributo non può essere scritto.
E_BLUETOOTH_ATT_INVALID_PDU
 L'attributo PDU non è valido.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION
 L'attributo richiede l'autenticazione prima di poter essere letto o scritto.
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED
 Il server attributi non supporta la richiesta ricevuta dal client.
E_BLUETOOTH_ATT_INVALID_OFFSET
 L'offset specificato è passato alla fine dell'attributo.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION
 L'attributo richiede l'autorizzazione prima di poter essere letto o scritto.
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL
 Troppe scritture di preparazione sono state accodate.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND
 Nessun attributo trovato nell'intervallo di handle dell'attributo specificato.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG
 L'attributo non può essere letto o scritto usando la richiesta read BLOB.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE
 Le dimensioni della chiave di crittografia usate per crittografare questo collegamento non sono sufficienti.
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH
 La lunghezza del valore dell'attributo non è valida per l'operazione.
E_BLUETOOTH_ATT_UNLIKELY
 La richiesta di attributo richiesta ha rilevato un errore improbabile e pertanto non è stato possibile completare come richiesto.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION
 L'attributo richiede la crittografia prima di poter essere letto o scritto.
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE
 Il tipo di attributo non è un attributo di raggruppamento supportato, come definito da una specifica di livello superiore.
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES
 Risorse insufficienti per completare la richiesta.
E_BLUETOOTH_ATT_UNKNOWN_ERROR
 È stato ricevuto un errore che si trova nell'intervallo riservato.

Commenti

Il valore della caratteristica viene restituito dalla cache se ne è già presente uno. Questo è il caso nella maggior parte dei casi, perché tutti gli attributi del dispositivo vengono memorizzati nella cache al momento dell'associazione o dell'associazione. Tuttavia, se non è presente, il valore della caratteristica viene letto direttamente dal dispositivo e verrà memorizzato nella cache dopo averlo letto correttamente dal dispositivo. Se BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE o BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE è presente, il valore della caratteristica viene letto usando il metodo specificato.

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 CharacteristicValueSizeRequired e NULL in CharacteristicValue.

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


            if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        0,
                        NULL,
                        &charValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);

                if (NULL == pCharValueBuffer) {
                    printf("pCharValueBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pCharValueBuffer, charValueDataSize);
                }

////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        (ULONG)charValueDataSize,
                        pCharValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);

                // Free before going to next iteration, or memory leak.
                free(pCharValueBuffer);
                pCharValueBuffer = NULL;
            }

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_CHARACTERISTIC_VALUE