função DnsQuery_W (windns.h)

Artigo
11/08/2024

O tipo de função DnsQuery é a interface de consulta genérica para o namespace DNS e fornece aos desenvolvedores de aplicativos uma interface de resolução de consulta DNS. Como muitas funções DNS, o tipo de função DnsQuery é implementado em várias formas para facilitar a codificação de caracteres diferente. Com base na codificação de caracteres envolvida, use uma das seguintes funções:

DnsQuery_A (para codificação ANSI)
DnsQuery_W (para codificação Unicode)
DnsQuery_UTF8 (para codificação UTF-8)

Windows 8: A função DnsQueryEx deverá ser usada se um aplicativo exigir consultas assíncronas para o namespace DNS.

Sintaxe

DNS_STATUS DnsQuery_W(
  [in]                PCWSTR      pszName,
  [in]                WORD        wType,
  [in]                DWORD       Options,
  [in, out, optional] PVOID       pExtra,
  [out, optional]     PDNS_RECORD *ppQueryResults,
  [out, optional]     PVOID       *pReserved
);

Parâmetros

[in] pszName

Um ponteiro para uma cadeia de caracteres que representa o nome DNS a ser consultado.

[in] wType

Um valor que representa o registro de recurso (RR) de tipo de registro DNS que é consultado. wType determina o formato dos dados apontados por ppQueryResultsSet. Por exemplo, se o valor de wType for DNS_TYPE_A, o formato dos dados apontados por ppQueryResultsSet será DNS_A_DATA.

[in] Options

Um valor que contém um bitmap de opções de consulta DNS a serem usadas na consulta DNS. As opções podem ser combinadas e todas as opções substituem DNS_QUERY_STANDARD.

[in, out, optional] pExtra

Esse parâmetro é reservado para uso futuro e deve ser definido como NULL.

[out, optional] ppQueryResults

Opcional. Um ponteiro para um ponteiro que aponta para a lista de RRs que compõem a resposta. Para obter mais informações, consulte a seção Comentários.

[out, optional] pReserved

Esse parâmetro é reservado para uso futuro e deve ser definido como NULL.

Valor de retorno

Retorna a confirmação de êxito após a conclusão bem-sucedida. Caso contrário, retorna o código de erro específico do DNS apropriado, conforme definido em Winerror.h.

Observações

Os aplicativos que chamam a função DnsQuery criam uma consulta usando um nome DNS totalmente qualificado e um tipo RR (Registro de Recurso) e definem opções de consulta dependendo do tipo de serviço desejado. Quando a opção DNS_QUERY_STANDARD é definida, o DNS usa o cache de resolvedor, consulta primeiro com UDP e, em seguida, tenta novamente com TCP se a resposta é truncada e solicita que o servidor execute resolução recursiva em nome do cliente para resolver a consulta.

Os aplicativos devem liberar conjuntos de RR retornados com a função DnsRecordListFree .

Observação Ao chamar um dos tipos de função DnsQuery, lembre-se de que um servidor DNS pode retornar vários registros em resposta a uma consulta. Um computador multihomed, por exemplo, receberá vários registros A para o mesmo endereço IP. O chamador deve usar quantos registros retornados forem necessários.

Considere o cenário a seguir, no qual vários registros retornados exigem atividade adicional em nome do aplicativo: uma chamada de função DnsQuery_A é feita para um computador multihomed e o aplicativo descobre que o endereço associado ao primeiro registro A não está respondendo. Em seguida, o aplicativo deve tentar usar outros endereços IP especificados no (adicional) um registro retornado da chamada de função DnsQuery_A.

Se o parâmetro lpstrName estiver definido como NULL, a função DnsQuery falhará com o erro INVALID_PARAMETER.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [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

DNS_RECORD

DnsQueryEx

DnsRecordListFree

Compartilhar via