Compartilhar via

Função DnsQueryEx (windns.h)

  • Artigo

A função DnsQueryEx é a interface de consulta genérica assíncrona para o namespace DNS. Ele fornece aos desenvolvedores de aplicativos uma interface de resolução de consulta DNS.

Assim como DnsQuery, DnsQueryEx também podem ser usados para fazer consultas síncronas no namespace DNS.

Sintaxe

DNS_STATUS DnsQueryEx(
  [in]                PDNS_QUERY_REQUEST pQueryRequest,
  [in, out]           PDNS_QUERY_RESULT  pQueryResults,
  [in, out, optional] PDNS_QUERY_CANCEL  pCancelHandle
);

Parâmetros

[in] pQueryRequest

Um ponteiro para uma estrutura de DNS_QUERY_REQUEST ou DNS_QUERY_REQUEST3 que contém as informações da solicitação de consulta.

Observação ao omitir o retorno de chamada DNS_QUERY_COMPLETION_ROUTINE do membro pQueryCompleteCallback dessa estrutura, DnsQueryEx é chamado de forma síncrona.
 

[in, out] pQueryResults

Um ponteiro para uma estrutura de DNS_QUERY_RESULT que contém os resultados da consulta. Na entrada, a versão membro do pQueryResults deve ser DNS_QUERY_RESULTS_VERSION1 e todos os outros membros devem ser NULL. Na saída, os membros restantes serão preenchidos como parte da conclusão da consulta.

Observação Para consultas assíncronas, um aplicativo não deve liberar essa estrutura até que o retorno de chamada DNS_QUERY_COMPLETION_ROUTINE seja invocado. Quando a consulta for concluída, a estrutura DNS_QUERY_RESULT conterá um ponteiro para uma lista de DNS_RECORDS que devem ser liberadas usando DnsRecordListFree.
 

[in, out, optional] pCancelHandle

Um ponteiro para uma estrutura DNS_QUERY_CANCEL que pode ser usada para cancelar uma consulta assíncrona pendente.

Observação Um aplicativo não deve liberar essa estrutura até que o retorno de chamada DNS_QUERY_COMPLETION_ROUTINE seja invocado.
 

Valor de retorno

A função DnsQueryEx tem os seguintes valores de retorno possíveis:

Código de retorno Descrição
ERROR_SUCCESS
 A chamada foi bem-sucedida.
ERROR_INVALID_PARAMETER
 Os parâmetros pQueryRequest ou pQueryResults não são inicializados ou contêm a versão errada.
DNS RCODE
 A chamada resultou em um erro RCODE.
DNS_INFO_NO_RECORDS
 Nenhum registro na resposta.
DNS_REQUEST_PENDING
 A consulta será concluída de forma assíncrona.

Observações

Se uma chamada para DnsQueryEx for concluída de forma síncrona (ou seja, o valor retornado da função não será DNS_REQUEST_PENDING), o pQueryRecords membro do pQueryResults conterá um ponteiro para uma lista de DNS_RECORDS e DnsQueryEx retornará erro ou êxito.

As seguintes condições invocam uma chamada síncrona para DnsQueryEx e não utilizam o retorno de chamada DNS:

  • O retorno de chamada DNS_QUERY_COMPLETION_ROUTINE é omitido do membro pQueryCompleteCallback de pQueryRequest.
  • Uma consulta é para o nome do computador local e um ou AAAA tipo registros de recurso (RR).
  • Uma chamada para DnsQueryEx consulta um endereço IPv4 ou IPv6.
  • Uma chamada para DnsQueryEx retorna por erro.
Se uma chamada para DnsQueryEx for concluída de forma assíncrona, os resultados da consulta são retornados pelo DNS_QUERY_COMPLETION_ROUTINE retorno de chamada em pQueryRequest, o membro queryStatus de pQueryResults contém DNS_REQUEST_PENDINGe DnsQueryEx retorna DNS_REQUEST_PENDING. Os aplicativos devem acompanhar a estrutura de pQueryResults que é passada para DnsQueryEx até que o retorno de chamada DNS seja bem-sucedido. Os aplicativos podem cancelar uma consulta assíncrona usando o identificador de pCancelHandle retornado por DnsQueryEx.

pCancelHandle retornado de uma chamada assíncrona para DnsQueryEx e pQueryContext é válido até que o retorno de chamada DNS DNS_QUERY_COMPLETION_ROUTINE seja invocado.

Observação Aplicativos são notificados sobre a conclusão assíncrona DnsQueryEx por meio do retorno de chamada DNS_QUERY_COMPLETION_ROUTINE no mesmo contexto de processo.
 

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows 8 [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows Server 2012 [somente aplicativos da área de trabalho]
da Plataforma de Destino Windows
cabeçalho windns.h
biblioteca Dnsapi.lib
de DLL Dnsapi.dll

Consulte também