Compartilhar via

Função BluetoothGATTGetCharacteristicValue (bluetoothleapis.h)

  • Artigo

A função BluetoothGATTGetCharacteristicValue obtém o valor da característica especificada.

Sintaxe

HRESULT BluetoothGATTGetCharacteristicValue(
  [in]            HANDLE                            hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC       Characteristic,
  [in]            ULONG                             CharacteristicValueDataSize,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
  [out, optional] USHORT                            *CharacteristicValueSizeRequired,
  [in]            ULONG                             Flags
);

Parâmetros

[in] hDevice

Identificador para o serviço.

[in] Characteristic

Ponteiro para a característica pai do valor de característica a ser recuperado.

[in] CharacteristicValueDataSize

O número de bytes alocados para o parâmetro CharacteristicValue .

[out, optional] CharacteristicValue

Ponteiro para buffer no qual retornar o valor de característica.

[out, optional] CharacteristicValueSizeRequired

Ponteiro para o buffer no qual armazenar o número de bytes necessários para retornar dados no buffer apontado por CharacteristicValue.

[in] Flags

Sinalizadores para modificar o comportamento de BluetoothGATTGetCharacteristicValue:

Sinalizador Descrição
BLUETOOTH_GATT_FLAG_NONE O cliente não tem requisitos de GATT específicos (padrão).
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED O cliente solicita que os dados sejam transmitidos por um canal criptografado.
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED O cliente solicita que os dados sejam transmitidos por um canal autenticado.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE O valor de característica deve ser lido diretamente do dispositivo. Isso substituirá aquele no cache se já estiver presente.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE O valor de característica deve ser lido do cache (independentemente de ele estar presente no cache ou não).

Retornar valor

A função BluetoothGATTGetCharacteristicValue 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
 CharacteristicValue e CharacteristicValueSizeRequired são 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_BAD_NET_RESP
 O servidor de destino não forneceu uma resposta de rede apropriada.
ERROR_SEM_TIMEOUT
 A solicitação atingiu o tempo limite.
ERROR_PRIVILEGE_NOT_HELD
 O valor de característica não é legível conforme ditado pelas propriedades características.
ERROR_NO_SYSTEM_RESOURCES
 A operação ficou sem memória.
E_BLUETOOTH_ATT_INVALID_HANDLE
 O identificador de atributo dado não era válido neste servidor.
E_BLUETOOTH_ATT_READ_NOT_PERMITTED
 O atributo não pode ser lido.
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED
 O atributo não pode ser gravado.
E_BLUETOOTH_ATT_INVALID_PDU
 O atributo PDU era inválido.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION
 O atributo requer autenticação antes de ser lido ou gravado.
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED
 O servidor de atributos não dá suporte à solicitação recebida do cliente.
E_BLUETOOTH_ATT_INVALID_OFFSET
 O deslocamento especificado foi passado do final do atributo.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION
 O atributo requer autorização antes de ser lido ou gravado.
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL
 Muitas gravações de preparação foram enfileiradas.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND
 Nenhum atributo encontrado no intervalo de identificador de atributo fornecido.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG
 O atributo não pode ser lido ou gravado usando a Solicitação de Blob de Leitura.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE
 O tamanho da chave de criptografia usado para criptografar esse link é insuficiente.
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH
 O comprimento do valor do atributo é inválido para a operação.
E_BLUETOOTH_ATT_UNLIKELY
 A solicitação de atributo solicitada encontrou um erro improvável e, portanto, não pôde ser concluído conforme solicitado.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION
 O atributo requer criptografia antes de ser lido ou gravado.
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE
 O tipo de atributo não é um atributo de agrupamento com suporte, conforme definido por uma especificação de camada superior.
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES
 Recursos insuficientes para concluir a solicitação.
E_BLUETOOTH_ATT_UNKNOWN_ERROR
 Um erro que está no intervalo reservado foi recebido.

Comentários

O valor de característica será retornado do cache se já houver um. Esse seria o caso na maior parte do tempo, pois todos os atributos do dispositivo são armazenados em cache no momento do emparelhamento ou da associação. No entanto, se não estiver presente, o valor de característica será lido diretamente do dispositivo e será armazenado em cache após a leitura com êxito do dispositivo. Se BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE ou BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE estiver presente, o valor de característica será lido usando o método especificado.

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 CharacteristicValueSizeRequired e NULL em CharacteristicValue.

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


            if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        0,
                        NULL,
                        &charValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);

                if (NULL == pCharValueBuffer) {
                    printf("pCharValueBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pCharValueBuffer, charValueDataSize);
                }

////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        (ULONG)charValueDataSize,
                        pCharValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);

                // Free before going to next iteration, or memory leak.
                free(pCharValueBuffer);
                pCharValueBuffer = NULL;
            }

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_CHARACTERISTIC_VALUE