Compartilhar via

Função BluetoothGATTGetDescriptorValue (bluetoothleapis.h)

  • Artigo

A função BluetoothGATTGetDescriptorValue obtém o valor do descritor especificado.

Sintaxe

HRESULT BluetoothGATTGetDescriptorValue(
  [in]            HANDLE                        hDevice,
  [in]            PBTH_LE_GATT_DESCRIPTOR       Descriptor,
  [in]            ULONG                         DescriptorValueDataSize,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR_VALUE DescriptorValue,
  [out, optional] USHORT                        *DescriptorValueSizeRequired,
  [in]            ULONG                         Flags
);

Parâmetros

[in] hDevice

Identificador para o serviço.

[in] Descriptor

Ponteiro para BTH_LE_GATT_DESCRIPTOR estrutura que contém o descritor pai do valor do descritor a ser recuperado.

[in] DescriptorValueDataSize

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

[out, optional] DescriptorValue

Ponteiro para BTH_LE_GATT_DESCRIPTOR_VALUE estrutura na qual retornar o valor do descritor.

[out, optional] DescriptorValueSizeRequired

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

[in] Flags

Sinalizadores para modificar o comportamento de BluetoothGATTGetDescriptorValue:

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 do descritor deve ser lido diretamente do dispositivo. Isso substituirá aquele no cache se já estiver presente.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE O valor do descritor deve ser lido do cache (independentemente de ele estar presente no cache ou não).

Retornar valor

A função BluetoothGATTGetDescriptorValue 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
 DescriptorValue e DescriptorValueSizeRequired 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_INVALID_FUNCTION
 Um valor de descritor foi especificado para ser recuperado do cache, mas o valor do descritor não está presente no cache.
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_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 do descritor 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 do descritor será lido diretamente do dispositivo e será armazenado em cache ao lê-lo com êxito do dispositivo. Se BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE ou BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE estiver presente, o valor do descritor será lido usando o método especificado.

Os valores de descritor retornados são armazenados em cache após a recuperação bem-sucedida de valores do descritor diretamente do dispositivo. A menos que um evento de alteração de serviço seja recebido, os valores do descritor não devem ser alterados.

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

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 Descriptor Value Buffer Size
////////////////////////////////////////////////////////////////////////////
                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        0,
                        NULL,
                        &descValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetDescriptorValue - Buffer Size", hr);
                    goto Done; // allow continuation
                }

                pDescValueBuffer = (PBTH_LE_GATT_DESCRIPTOR_VALUE)malloc(descValueDataSize);

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

////////////////////////////////////////////////////////////////////////////
// Retrieve the Descriptor Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        (ULONG)descValueDataSize,
                        pDescValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

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

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_DESCRIPTOR

BTH_LE_GATT_DESCRIPTOR_VALUE