Funzione BluetoothGATTGetIncludedServices (bluetoothleapis.h)

Articolo
02/23/2024

La funzione BluetoothGATTGetIncludedServices ottiene tutti i servizi inclusi disponibili per un determinato servizio.

Sintassi

HRESULT BluetoothGATTGetIncludedServices(
  [in]            HANDLE               hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE ParentService,
  [in]            USHORT               IncludedServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE IncludedServicesBuffer,
  [out]           USHORT               *IncludedServicesBufferActual,
  [in]            ULONG                Flags
);

Parametri

[in] hDevice

Gestire il dispositivo Bluetooth o il servizio padre.

[in, optional] ParentService

Indirizzo di una struttura BTH_LE_GATT_SERVICE che contiene il servizio padre dei servizi inclusi da recuperare. Questo parametro è obbligatorio se un handle del 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] IncludedServicesBufferCount

Numero di elementi allocati per il parametro IncludedServicesBuffer .

[out, optional] IncludedServicesBuffer

Indirizzo di un buffer contenente una struttura BTH_LE_GATT_SERVICE in cui restituire i servizi inclusi.

[out] IncludedServicesBufferActual

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

[in] Flags

Flag per modificare il comportamento di BluetoothGATTGetIncludedServices:

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: IncludedServicesBuffer è NULL e IncludedServicesBufferCount è 0. IncludedServicesBuffer non è NULL, ma IncludedServicesBufferCount è NULL. IncludedServicesBuffer non è NULL e IncludedServicesBufferCount è 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 in caso di recupero corretto dei servizi dal dispositivo direttamente. A meno che non venga ricevuto un evento di modifica del servizio, l'elenco dei servizi restituiti non deve cambiare.

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

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 Included Services Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetIncludedServices(
     hLEDevice,
     gattService,
     0,
     NULL,
     &inclServicesBufferSize,
     BLUETOOTH_GATT_FLAG_NONE);

     if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
         PrintHr("BluetoothGATTGetIncludedServices - Buffer Size", hr);
         goto Done;
     }

     if (inclServicesBufferSize > 0) {
         pInclServicesBuffer = (PBTH_LE_GATT_ PBTH_LE_GATT_SERVICE)
                    malloc(inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));

         if (NULL == pInclServicesBuffer) {
             printf("pInclServicesBuffer out of memory\r\n");
             goto Done;
         } else {
             RtlZeroMemory(pInclServicesBuffer, 
                    inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));
         }

         ////////////////////////////////////////////////////////////////////////////
         // Retrieve Included Services
         ////////////////////////////////////////////////////////////////////////////

         hr = BluetoothGATTGetIncludedServices (
              hLEDevice,
              gattService,
              inclServicesBufferSize,
              pInclServicesBuffer,
              &numIncludedServices
              BLUETOOTH_GATT_FLAG_NONE);

         if (S_OK != hr) {
             PrintHr("BluetoothGATTGetIncludedServices - 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