Funzione BluetoothGATTGetServices (bluetoothleapis.h)

Articolo
03/14/2023

La funzione BluetoothGATTGetServices ottiene tutti i servizi primari disponibili per un server.

Sintassi

HRESULT BluetoothGATTGetServices(
  [in]            HANDLE               hDevice,
  [in]            USHORT               ServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE ServicesBuffer,
  [out]           USHORT               *ServicesBufferActual,
  [in]            ULONG                Flags
);

Parametri

[in] hDevice

Gestire il dispositivo Bluetooth da cui ottenere l'elenco dei servizi primari.

[in] ServicesBufferCount

Numero di elementi allocati per il parametro ServicesBuffer .

[out, optional] ServicesBuffer

Puntatore al buffer contenente una struttura BTH_LE_GATT_SERVICE in cui restituire i servizi.

[out] ServicesBufferActual

Puntatore al buffer in cui è stato restituito il numero effettivo di servizi nel parametro ServicesBuffer .

[in] Flags

Flag per modificare il comportamento di BluetoothGATTGetServices:

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: ServicesBuffer è NULL e ServicesBufferCount è 0 ServicesBuffer è diverso da NULL, ma ServicesBufferCount è NULL ServicesBuffer è diverso da NULL e ServicesBufferCount è 0
ERROR_INVALID_USER_BUFFER	Viene specificato un buffer, ma le dimensioni del conteggio del buffer sono inferiori a quelle necessarie, in byte.
ERROR_INVALID_FUNCTION	I servizi sono stati specificati per essere recuperati dalla cache, ma non sono presenti servizi nella cache.
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

I servizi restituiti vengono memorizzati nella cache al completamento del recupero dei servizi dal dispositivo direttamente. A meno che non venga ricevuto un evento di modifica del servizio, non è previsto che venga modificato l'elenco dei servizi restituiti.

I driver di profilo devono pre-allocare un buffer sufficientemente grande in modo che venga restituita la matrice di servizi primari. I chiamanti possono determinare le dimensioni del buffer necessarie passando un valore non NULL in ServicesBufferActual e NULL in ServicesBuffer.

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

Esempio


////////////////////////////////////////////////////////////////////////////
// Determine Services Buffer Size
////////////////////////////////////////////////////////////////////////////

    hr = BluetoothGATTGetServices(
            hLEDevice,
            0,
            NULL,
            &serviceBufferCount,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
        PrintHr("BluetoothGATTGetServices - Buffer Size", hr);
        goto Done;
    }

    pServiceBuffer = (PBTH_LE_GATT_SERVICE)
            malloc(sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    
    if (NULL == pServiceBuffer) {
        printf("pServiceBuffer out of memory\r\n");
        goto Done;
    } else {
        RtlZeroMemory(pServiceBuffer, 
                sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    }
    
////////////////////////////////////////////////////////////////////////////
// Retrieve Services
////////////////////////////////////////////////////////////////////////////
    
    hr = BluetoothGATTGetServices(
            hLEDevice,
            serviceBufferCount,
            pServiceBuffer,
            &numServices,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (S_OK != hr) {
        PrintHr("BluetoothGATTGetServices - Actual Data", hr);
        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_SERVICE

Condividi tramite