Função BluetoothGATTGetCharacteristics (bluetoothleapis.h)

A função BluetoothGATTGetCharacteristics obtém todas as características disponíveis para o serviço especificado.

Sintaxe

HRESULT BluetoothGATTGetCharacteristics(
  [in]            HANDLE                      hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE        Service,
  [in]            USHORT                      CharacteristicsBufferCount,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC CharacteristicsBuffer,
  [out]           USHORT                      *CharacteristicsBufferActual,
  [in]            ULONG                       Flags
);

Parâmetros

[in] hDevice

Identificador para o dispositivo ou serviço Bluetooth.

[in, optional] Service

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] CharacteristicsBufferCount

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

[out, optional] CharacteristicsBuffer

Ponteiro para um buffer no qual retornar características como uma matriz de estruturas BTH_LE_GATT_CHARACTERISTIC .

[out] CharacteristicsBufferActual

Ponteiro para o buffer no qual é retornado o número real de características que foram retornadas no parâmetro CharacteristicsBuffer .

[in] Flags

Sinalizadores para modificar o comportamento de BluetoothGATTGetCharacteristics:

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: CharacteristicsBuffer é NULL e CharacteristicsBufferCount é 0 CharacteristicsBuffer não é NULL, mas CharacteristicsBufferCount é NULL CharacteristicsBuffer não é NULL e CharacteristicsBufferCount é 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 CharacteristicsBufferActual e NULL em CharacteristicsBuffer.

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.

O serviço 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 Characteristic Buffer Size
////////////////////////////////////////////////////////////////////////////

        hr = BluetoothGATTGetCharacteristics(
                hCurrService,
                currGattService,
                0,
                NULL,
                &charBufferSize,
                BLUETOOTH_GATT_FLAG_NONE);
        
        if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
            PrintHr("BluetoothGATTGetCharacteristics - Buffer Size", hr);
            goto Done;
        }
        
        if (charBufferSize > 0) {
            pCharBuffer = (PBTH_LE_GATT_CHARACTERISTIC)
                    malloc(charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
        
            if (NULL == pCharBuffer) {
                printf("pCharBuffer out of memory\r\n");
                goto Done;
            } else {
                RtlZeroMemory(pCharBuffer, 
                        charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
            }

////////////////////////////////////////////////////////////////////////////
// Retrieve Characteristics
////////////////////////////////////////////////////////////////////////////
    
            hr = BluetoothGATTGetCharacteristics(
                    hCurrService,
                    currGattService,
                    charBufferSize,
                    pCharBuffer,
                    &numChars,
                    BLUETOOTH_GATT_FLAG_NONE);

            if (S_OK != hr) {
                PrintHr("BluetoothGATTGetCharacteristics - Actual Data", hr);
                goto Done; // Allow continuation
            }

            if (numChars != charBufferSize) {
                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_SERVICE