Função BluetoothGATTGetIncludedServices (bluetoothleapis.h)

A função BluetoothGATTGetIncludedServices obtém todos os serviços incluídos disponíveis para um determinado serviço.

Sintaxe

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

Parâmetros

[in] hDevice

Manipule para o dispositivo Bluetooth ou o serviço pai.

[in, optional] ParentService

Endereço de uma estrutura BTH_LE_GATT_SERVICE que contém o serviço pai dos serviços incluídos a serem recuperados. Esse parâmetro será necessário se um identificador de dispositivo for passado para hDevice. Esse parâmetro será opcional se um identificador de serviço tiver sido passado para hDevice, nesse caso, o serviço especificado pelo identificador de serviço será tratado como o pai.

[in] IncludedServicesBufferCount

O número de elementos alocados para o parâmetro IncludedServicesBuffer .

[out, optional] IncludedServicesBuffer

Endereço de um buffer que contém uma estrutura BTH_LE_GATT_SERVICE na qual retornar serviços incluídos.

[out] IncludedServicesBufferActual

Ponteiro para o buffer no qual o número real de serviços incluídos foi retornado no parâmetro IncludedServicesBuffer .

[in] Flags

Sinalizadores para modificar o comportamento de BluetoothGATTGetIncludedServices:

Sinalizador	Descrição
BLUETOOTH_GATT_FLAG_NONE	O cliente não tem requisitos de GATT específicos (padrão).

Retornar valor

Essa função retorna os seguintes valores:

Código de retorno	Descrição
S_OK	A operação foi concluída com sucesso.
ERROR_MORE_DATA	O parâmetro buffer é NULL e o número de itens disponíveis está sendo retornado.
ERROR_ACCESS_DENIED	Retornado se um serviço pai e um identificador de serviço forem fornecidos e a hierarquia de serviço não for acumulada para o identificador de serviço pai fornecido.
ERROR_INVALID_PARAMETER	Uma das seguintes condições ocorreu: IncludedServicesBuffer é NULL e IncludedServicesBufferCount é 0. IncludedServicesBuffer não é NULL, mas IncludedServicesBufferCount é NULL. IncludedServicesBuffer não é NULL e IncludedServicesBufferCount é 0.
ERROR_INVALID_USER_BUFFER	Um buffer é especificado, mas o tamanho da contagem de buffers é menor do que o necessário, em bytes.
ERROR_INVALID_FUNCTION	Os serviços foram especificados para serem recuperados do cache, mas nenhum serviço está presente no cache.
ERROR_BAD_COMMAND	Os dados atuais no cache parecem ser inconsistentes e estão levando a erros internos.
ERROR_NO_SYSTEM_RESOURCES	A operação ficou sem memória.

Comentários

Os serviços retornados são armazenados em cache após a recuperação bem-sucedida dos serviços do dispositivo diretamente. A menos que um evento de alteração de serviço seja recebido, a lista de serviços retornados não deverá ser alterada.

Os drivers de perfil devem pré-alocar um buffer suficientemente grande para que a matriz de serviços primários seja retornada. Os chamadores podem determinar o tamanho do buffer necessário passando um valor não NULL em IncludedServicesBufferActual e NULL em IncludedServicesBuffer.

Não modifique a estrutura de serviço retornada e use a estrutura modificada em chamadas de função subsequentes. O comportamento será indefinido se o chamador fizer isso.

Exemplo

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte em Windows 8 e versões posteriores do Windows.
Plataforma de Destino	Universal
Cabeçalho	bluetoothleapis.h
Biblioteca	BluetoothApis.lib
DLL	BluetoothAPIs.dll

Confira também

BTH_LE_GATT_SERVICE