Partager via

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 dans 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 demande de requête.

Remarque En omettant le rappel DNS_QUERY_COMPLETION_ROUTINE à partir 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, la version membre de pQueryResults doit être DNS_QUERY_RESULTS_VERSION1 et tous les autres membres doivent être NULL. En sortie, les membres restants sont remplis dans le cadre de la requête terminée.

Remarque Pour les requêtes asynchrones, une application ne doit pas libérer cette structure tant que le rappel DNS_QUERY_COMPLETION_ROUTINE n’est pas appelé. Une fois la requête terminée, la structure DNS_QUERY_RESULT contient un pointeur vers une liste de DNS_RECORDS qui doit être libérée à 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.

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

Valeur de retour

La fonction DnsQueryEx a les valeurs de retour possibles suivantes :

Retourner le code Description
ERROR_SUCCESS
 L’appel a réussi.
ERROR_INVALID_PARAMETER
 Les paramètres pQueryRequest ou pQueryResults sont non initialisés ou contiennent la 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 est terminée de façon 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 pQueryRecords membre 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 pour dnsQueryEx et n’utilisent pas le rappel DNS :

  • Le rappel DNS_QUERY_COMPLETION_ROUTINE est omis à partir du membre pQueryCompleteCallback de pQueryRequest .
  • Une requête concerne le nom de l’ordinateur local et A ou AAAA type Resource Records (RR).
  • Un appel à DnsQueryEx interroge une adresse IPv4 ou IPv6.
  • Un appel à DnsQueryEx retourne une erreur.
Si un appel à DnsQueryEx se termine de façon 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_PENDINGet 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é par un appel asynchrone à DnsQueryEx et pQueryContext est valide jusqu’à ce que le rappel DNS DNS_QUERY_COMPLETION_ROUTINE soit appelé.

Remarque Applications sont averties de la saisie semi-automatique asynchrone DnsQueryEx par le biais du rappel DNS_QUERY_COMPLETION_ROUTINE dans le même contexte de processus.
 

Exigences

Exigence Valeur
client minimum pris en charge Windows 8 [applications de bureau uniquement]
serveur minimum pris en charge Windows Server 2012 [applications de bureau uniquement]
plateforme cible Windows
d’en-tête windns.h
bibliothèque Dnsapi.lib
DLL Dnsapi.dll

Voir aussi