Função BluetoothGATTGetDescriptors (bluetoothleapis.h)

A função BluetoothGATTGetDescriptors obtém todos os descritores disponíveis para a característica especificada.

Sintaxe

HRESULT BluetoothGATTGetDescriptors(
  [in]            HANDLE                      hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC Characteristic,
  [in]            USHORT                      DescriptorsBufferCount,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR     DescriptorsBuffer,
  [out]           USHORT                      *DescriptorsBufferActual,
  [in]            ULONG                       Flags
);

Parâmetros

[in] hDevice

Identificador para o dispositivo ou serviço Bluetooth. Se um identificador de serviço for passado, o serviço deverá ser o avô do descritor.

[in] Characteristic

Ponteiro para BTH_LE_GATT_CHARACTERISTIC estrutura que contém a característica pai dos descritores a serem recuperados.

[in] DescriptorsBufferCount

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

[out, optional] DescriptorsBuffer

Ponteiro para o buffer que contém uma estrutura BTH_LE_GATT_DESCRIPTOR na qual os descritores devem ser retornados.

[out] DescriptorsBufferActual

Ponteiro para o buffer no qual o número real de descritores foi retornado no parâmetro DescriptorsBuffer .

[in] Flags

Sinalizadores para modificar o comportamento de BluetoothGATTGetDescriptors:

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 de 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 no identificador de serviço pai fornecido.
ERROR_INVALID_PARAMETER	Uma das seguintes condições ocorreu: DescriptorsBuffer é NULL e DescriptorsBufferCount é 0. DescriptorsBuffer não é NULL, mas DescriptorsBufferCount é NULL. DescriptorsBuffer não é NULL e DescriptorsBufferCount é 0.
ERROR_INVALID_USER_BUFFER	Um buffer é especificado, mas o tamanho da contagem de buffers é menor do que o necessário, em bytes.
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

As características retornadas são armazenadas em cache após a recuperação bem-sucedida das características do dispositivo diretamente. A menos que um evento de alteração de serviço seja recebido, não se espera que a lista de características retornadas seja alterada.

Os drivers de perfil devem pré-alocar um buffer suficientemente grande para que a matriz de características seja retornada. Os chamadores podem determinar o tamanho do buffer necessário passando um valor não NULL em DescritoresBufferActual e NULL em DescritoresBuffer.

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

A característica pai deve estar presente no cache, caso contrário, a função falhará. O serviço pai deve ser um serviço retornado por BluetoothGATTGetServices ou BluetoothGATTGetIncludedServices.

Exemplo

////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Buffer Size
////////////////////////////////////////////////////////////////////////////
GetDescriptors:
            hr = BluetoothGATTGetDescriptors(
                    hCurrService,
                    currGattChar,
                    0,
                    NULL,
                    &descriptorBufferSize,
                    BLUETOOTH_GATT_FLAG_NONE);
            
            if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                PrintHr("BluetoothGATTGetDescriptors - Buffer Size", hr);
                goto Done; // Allow continuation
            }
            
            if (descriptorBufferSize > 0) {
                pDescriptorBuffer = (PBTH_LE_GATT_DESCRIPTOR)
                        malloc(descriptorBufferSize 
                            * sizeof(BTH_LE_GATT_DESCRIPTOR));
            
                if (NULL == pDescriptorBuffer) {
                    printf("pDescriptorBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescriptorBuffer, descriptorBufferSize);
                }
            
////////////////////////////////////////////////////////////////////////////
// Retrieve Descriptors
////////////////////////////////////////////////////////////////////////////
    
                hr = BluetoothGATTGetDescriptors(
                        hCurrService,
                        currGattChar,
                        descriptorBufferSize,
                        pDescriptorBuffer,
                        &numDescriptors,
                        BLUETOOTH_GATT_FLAG_NONE);
            
                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptors - Actual Data", hr);
                    goto Done;
                }

                if (numDescriptors != descriptorBufferSize) {
                    printf("buffer size and buffer size actual size mismatch\r\n");
                    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_CHARACTERISTIC

BTH_LE_GATT_DESCRIPTOR