DnsQueryEx, fonction (windns.h)

  • Article

La fonction DnsQueryEx est l’interface de requête générique asynchrone de l’espace de noms DNS. Il fournit aux développeurs d’applications une interface de résolution de requêtes DNS.

Comme DnsQuery, DnsQueryEx peut également être utilisé pour effectuer des requêtes synchrones sur l’espace de noms DNS.

Syntaxe

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

Paramètres

[in] pQueryRequest

Pointeur vers une structure DNS_QUERY_REQUEST ou DNS_QUERY_REQUEST3 qui contient les informations de requête.

Note En omettant le rappel DNS_QUERY_COMPLETION_ROUTINE du membre pQueryCompleteCallback de cette structure, DnsQueryEx est appelé de façon synchrone.
 

[in, out] pQueryResults

Pointeur vers une structure DNS_QUERY_RESULT qui contient les résultats de la requête. Lors de l’entrée, le membre de version de pQueryResults doit être DNS_QUERY_RESULTS_VERSION1 et tous les autres membres doivent avoir la valeur NULL. Lors de la sortie, les membres restants sont renseignés dans le cadre de la requête terminée.

Note Pour les requêtes asynchrones, une application ne doit pas libérer cette structure tant que le rappel DNS_QUERY_COMPLETION_ROUTINE n’a pas été appelé. Une fois la requête terminée, la structure DNS_QUERY_RESULT contient un pointeur vers une liste de DNS_RECORDS qui doivent être libérés à l’aide de DnsRecordListFree.
 

[in, out, optional] pCancelHandle

Pointeur vers une structure DNS_QUERY_CANCEL qui peut être utilisée pour annuler une requête asynchrone en attente.

Note Une application ne doit pas libérer cette structure tant que le rappel DNS_QUERY_COMPLETION_ROUTINE n’est pas appelé.
 

Valeur retournée

La fonction DnsQueryEx a les valeurs de retour possibles suivantes :

Code de retour Description
ERROR_SUCCESS
 L’appel a réussi.
ERROR_INVALID_PARAMETER
 Les paramètres pQueryRequest ou pQueryRequest sont non initialisés ou contiennent une version incorrecte.
DNS RCODE
 L’appel a entraîné une erreur RCODE .
DNS_INFO_NO_RECORDS
 Aucun enregistrement dans la réponse.
DNS_REQUEST_PENDING
 La requête sera effectuée de manière asynchrone.

Remarques

Si un appel à DnsQueryEx se termine de manière synchrone (c’est-à-dire que la valeur de retour de la fonction n’est pas DNS_REQUEST_PENDING), le membre pQueryRecords de pQueryResults contient un pointeur vers une liste de DNS_RECORDS et DnsQueryEx retourne une erreur ou une réussite.

Les conditions suivantes appellent un appel synchrone à DnsQueryEx et n’utilisent pas le rappel DNS :

  • Le rappel DNS_QUERY_COMPLETION_ROUTINE est omis du membre pQueryCompleteCallback de pQueryRequest.
  • Une requête concerne le nom de l’ordinateur local et le type A ou AAAA Resource Records (RR).
  • Un appel à DnsQueryEx interroge une adresse IPv4 ou IPv6.
  • Un appel à DnsQueryEx retourne par erreur.
Si un appel à DnsQueryEx se termine de manière asynchrone, les résultats de la requête sont retournés par le rappel DNS_QUERY_COMPLETION_ROUTINE dans pQueryRequest, le membre QueryStatus de pQueryResults contient DNS_REQUEST_PENDING et DnsQueryEx retourne DNS_REQUEST_PENDING. Les applications doivent suivre la structure pQueryResults passée dans DnsQueryEx jusqu’à ce que le rappel DNS réussisse. Les applications peuvent annuler une requête asynchrone à l’aide du handle pCancelHandle retourné par DnsQueryEx.

pCancelHandle retourné à partir d’un appel asynchrone à DnsQueryEx et pQueryContext est valide jusqu’à ce que le rappel DNS DNS_QUERY_COMPLETION_ROUTINE soit appelé.

Note Les applications sont averties de l’achèvement asynchrone de DnsQueryEx via le rappel DNS_QUERY_COMPLETION_ROUTINE dans le même contexte de processus.
 

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau uniquement]
Plateforme cible Windows
En-tête windns.h
Bibliothèque Dnsapi.lib
DLL Dnsapi.dll

Voir aussi