Fonction GetAddrInfoExA (ws2tcpip.h)

La fonction GetAddrInfoEx fournit une résolution de noms indépendante du protocole avec des paramètres supplémentaires pour qualifier les fournisseurs d’espaces de noms qui doivent gérer la requête.

Syntaxe

INT WSAAPI GetAddrInfoExA(
  [in, optional]  PCSTR                              pName,
  [in, optional]  PCSTR                              pServiceName,
  [in]            DWORD                              dwNameSpace,
  [in, optional]  LPGUID                             lpNspId,
  [in, optional]  const ADDRINFOEXA                  *hints,
  [out]           PADDRINFOEXA                       *ppResult,
  [in, optional]  timeval                            *timeout,
  [in, optional]  LPOVERLAPPED                       lpOverlapped,
  [in, optional]  LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
  [out, optional] LPHANDLE                           lpNameHandle
);

Paramètres

[in, optional] pName

Pointeur vers une chaîne terminée par NULL contenant un nom d’hôte (nœud) ou une chaîne d’adresse d’hôte numérique. Pour le protocole Internet, la chaîne d’adresse d’hôte numérique est une adresse IPv4 décimale en pointillés ou une adresse hexadécimale IPv6.

[in, optional] pServiceName

Pointeur vers une chaîne facultative terminée par null qui contient un nom de service ou un numéro de port représenté sous la forme d’une chaîne.

Un nom de service est un alias de chaîne pour un numéro de port. Par exemple, « http » est un alias pour le port 80 défini par l’Internet Engineering Task Force (IETF) comme port par défaut utilisé par les serveurs web pour le protocole HTTP. Les valeurs possibles pour le paramètre pServiceName lorsqu’aucun numéro de port n’est spécifié sont répertoriées dans le fichier suivant :

%WINDIR%\system32\drivers\etc\services

[in] dwNameSpace

Identificateur d’espace de noms facultatif qui détermine les fournisseurs d’espaces de noms qui sont interrogés. La transmission d’un identificateur d’espace de noms spécifique entraîne l’interrogation des fournisseurs d’espaces de noms qui prennent en charge l’espace de noms spécifié. Si vous spécifiez NS_ALL , tous les fournisseurs d’espaces de noms installés et actifs sont interrogés.

Les options du paramètre dwNameSpace sont répertoriées dans le fichier Include Winsock2.h . Plusieurs fournisseurs d’espaces de noms sont ajoutés sur Windows Vista et versions ultérieures. D’autres fournisseurs d’espaces de noms peuvent être installés, de sorte que les valeurs possibles suivantes sont uniquement celles couramment disponibles. De nombreuses autres valeurs sont possibles.

Valeur Signification
NS_ALL
0
Tous les espaces de noms installés et actifs.
NS_DNS
12
Espace de noms de domaine (DNS).
NS_NETBT
13
Espace de noms NetBIOS sur TCP/IP (NETBT).
NS_WINS
14
Espace de noms Windows Internet Naming Service (NS_WINS).
NS_NLA
15
Espace de noms NLA (Network Location Awareness).

Cet identificateur d’espace de noms est pris en charge sur Windows XP et versions ultérieures.

NS_BTH
16
Espace de noms Bluetooth.

Cet identificateur d’espace de noms est pris en charge sur Windows Vista et versions ultérieures.

NS_NTDS
32
Espace de noms des services d’annuaire Windows NT (NS_NTDS).
NS_EMAIL
37
Espace de noms d’e-mail.

Cet identificateur d’espace de noms est pris en charge sur Windows Vista et versions ultérieures.

NS_PNRPNAME
38
Espace de noms d’égal à égal pour un nom d’homologue spécifique.

Cet identificateur d’espace de noms est pris en charge sur Windows Vista et versions ultérieures.

NS_PNRPCLOUD
39
Espace de noms pair à pair pour une collection de noms d’homologues.

Cet identificateur d’espace de noms est pris en charge sur Windows Vista et versions ultérieures.

[in, optional] lpNspId

Pointeur vers un GUID facultatif d’un fournisseur d’espace de noms spécifique à interroger dans le cas où plusieurs fournisseurs d’espaces de noms sont inscrits sous un seul espace de noms, tel que NS_DNS. Le passage du GUID pour un fournisseur d’espaces de noms spécifique entraîne uniquement l’interrogation du fournisseur d’espaces de noms spécifié. La fonction WSAEnumNameSpaceProviders peut être appelée pour récupérer le GUID d’un fournisseur d’espaces de noms.

[in, optional] hints

Pointeur vers une structure addrinfoex qui fournit des conseils sur le type de socket pris en charge par l’appelant.

Les membres ai_addrlen, ai_canonname, ai_addr et ai_next de la structure addrinfoex pointée par le paramètre pHints doivent être zéro ou NULL. Sinon, la fonction GetAddrInfoEx échoue avec WSANO_RECOVERY.

Pour plus d’informations, consultez les remarques.

[out] ppResult

Pointeur vers une liste liée d’une ou plusieurs structures addrinfoex qui contient des informations de réponse sur l’hôte.

[in, optional] timeout

Paramètre facultatif indiquant le temps, en millisecondes, d’attendre une réponse du fournisseur d’espaces de noms avant d’arrêter l’appel.

Ce paramètre est pris en charge uniquement lorsque la macro UNICODE ou _UNICODE a été définie dans les sources avant d’appeler la fonction GetAddrInfoEx . Sinon, ce paramètre est actuellement réservé et doit être défini sur NULL , car aucune option de délai d’expiration n’est prise en charge.

[in, optional] lpOverlapped

Pointeur facultatif vers une structure superposée utilisée pour l’opération asynchrone.

Ce paramètre est pris en charge uniquement lorsque la macro UNICODE ou _UNICODE a été définie dans les sources avant d’appeler la fonction GetAddrInfoEx .

Sur Windows 8 et Windows Server 2012, si aucun paramètre lpCompletionRoutine n’est spécifié, le membre hEvent de la structure OVERLAPPED doit être défini sur un événement de réinitialisation manuelle pour être appelé à la fin d’un appel asynchrone. Si une routine d’achèvement a été spécifiée, le membre hEvent doit être NULL. Lorsque l’événement spécifié par hEvent a été défini, le résultat de l’opération peut être récupéré en appelant la fonction GetAddrInfoExOverlappedResult .

Sur Windows 8 et Windows Server 2012 lorsque la macro UNICODE ou _UNICODE n’est pas définie, ce paramètre est actuellement réservé et doit être défini sur NULL.

Sur Windows 7 et Windows Server 2008 R2 ou version antérieure, ce paramètre est actuellement réservé et doit être défini sur NULL , car les opérations asynchrones ne sont pas prises en charge.

[in, optional] lpCompletionRoutine

Pointeur facultatif vers une fonction à appeler en cas de réussite des opérations asynchrones.

Ce paramètre est pris en charge uniquement lorsque la macro UNICODE ou _UNICODE a été définie dans les sources avant d’appeler la fonction GetAddrInfoEx .

Si ce paramètre est spécifié, il doit s’agir d’un pointeur vers une fonction avec la signature suivante :

typedef   
void   
(CALLBACK * LPLOOKUPSERVICE_COMPLETION_ROUTINE)(   
    __in      DWORD    dwError,   
    __in      DWORD    dwBytes,   
    __in      LPWSAOVERLAPPED lpOverlapped   
    );   

Une fois l’opération asynchrone terminée, la routine d’achèvement est appelée avec le paramètre lpOverlapped défini sur la valeur du paramètre lpOverlapped passée à GetAddrInfoEx. Le membre Pointeur de la structure OVERLAPPED est défini sur la valeur du paramètre ppResult de l’appel d’origine. Si le membre Pointeur pointe vers un pointeur non NULL vers la structure addrinfoex , il incombe à l’appelant d’appeler FreeAddrInfoEx pour libérer la structure addrinfoex . Le paramètre dwError passé à la routine d’achèvement est défini sur un code d’erreur Winsock. Le paramètre dwBytes est réservé pour une utilisation ultérieure et doit être ignoré.

Sur Windows 8 et Windows Server 2012 lorsque la macro UNICODE ou _UNICODE n’est pas définie, ce paramètre est actuellement réservé et doit être défini sur NULL.

Sur Windows 7 et Windows Server 2008 R2 ou version antérieure, ce paramètre est actuellement réservé et doit être défini sur NULL , car les opérations asynchrones ne sont pas prises en charge.

[out, optional] lpNameHandle

Pointeur facultatif utilisé uniquement pour les opérations asynchrones.

Ce paramètre est pris en charge uniquement lorsque la macro UNICODE ou _UNICODE a été définie dans les sources avant d’appeler la fonction GetAddrInfoEx .

Sur Windows 8 et Windows Server 2012, si la fonction GetAddrInfoEx se termine de manière asynchrone, le pointeur retourné dans ce champ peut être utilisé avec la fonction GetAddrInfoExCancel . Le handle retourné est valide lorsque GetAddrInfoEx est retourné jusqu’à ce que la routine d’achèvement soit appelée, que l’événement soit déclenché ou que la fonction GetAddrInfoExCancel soit appelée avec ce handle.

Sur Windows 8 et Windows Server 2012 lorsque la macro UNICODE ou _UNICODE n’est pas définie, ce paramètre est actuellement réservé et doit être défini sur NULL.

Sur Windows 7 et Windows Server 2008 R2 ou version antérieure, ce paramètre est actuellement réservé et doit être défini sur NULL , car les opérations asynchrones ne sont pas prises en charge.

Valeur retournée

En cas de réussite, GetAddrInfoEx retourne NO_ERROR (0). L’échec retourne un code d’erreur Windows Sockets différent de zéro, comme indiqué dans les codes d’erreur des sockets Windows.

La plupart des codes d’erreur non nuls retournés par la fonction GetAddrInfoEx correspondent au jeu d’erreurs décrit par les recommandations de l’Internet Engineering Task Force (IETF). Le tableau suivant présente ces codes d’erreur et leurs équivalents WSA. Il est recommandé d’utiliser les codes d’erreur WSA, car ils offrent des informations familières et complètes sur les erreurs pour les programmeurs Winsock.

Valeur d’erreur Équivalent WSA Description
EAI_AGAIN WSATRY_AGAIN Un échec temporaire de la résolution de noms s’est produit.
EAI_BADFLAGS WSAEINVAL Un paramètre non valide a été fourni. Cette erreur est retournée si l’un des paramètres réservés n’est pas NULL. Cette erreur est également retournée si une valeur non valide a été fournie pour le membre ai_flags du paramètre pHints .
EAI_FAIL WSANO_RECOVERY Un échec non récupérable de la résolution de noms s’est produit.
EAI_FAMILY WSAEAFNOSUPPORT Le membre ai_family du paramètre pHints n’est pas pris en charge.
EAI_MEMORY WSA_NOT_ENOUGH_MEMORY Un échec d’allocation de mémoire s’est produit.
EAI_NONAME WSAHOST_NOT_FOUND Le nom ne se résout pas pour les paramètres fournis ou les paramètres pName et pServiceName n’ont pas été fournis.
EAI_SERVICE WSATYPE_NOT_FOUND Le paramètre pServiceName n’est pas pris en charge pour le membre ai_socktype spécifié du paramètre pHints .
EAI_SOCKTYPE WSAESOCKTNOSUPPORT Le ai_socktype membre du paramètre pHints n’est pas pris en charge.
 

Utilisez la fonction gai_strerror pour imprimer les messages d’erreur en fonction des codes EAI retournés par la fonction GetAddrInfoEx . La fonction gai_strerror est fournie pour la conformité avec les recommandations de l’IETF, mais elle n’est pas thread-safe. Par conséquent, l’utilisation de fonctions windows sockets traditionnelles telles que WSAGetLastError est recommandée.

Code d'erreur Signification
WSA_NOT_ENOUGH_MEMORY
La mémoire était insuffisante pour effectuer l’opération.
WSAEAFNOSUPPORT
Une adresse incompatible avec le protocole demandé a été utilisée. Cette erreur est retournée si le membre ai_family de la structure addrinfoex pointée par le paramètre pHints n’est pas pris en charge.
WSAEINVAL
Argument non valide fourni. Cette erreur est retournée si une valeur non valide a été fournie pour le membre ai_flags de la structure addrinfoex pointée vers par le paramètre pHints . Cette erreur est également retournée lorsque le paramètre dwNameSpace est NS_PNRPNAME ou NS_PNRPCLOUD et que le service de nom d’égal à égal ne fonctionne pas.
WSAESOCKTNOSUPPORT
La prise en charge du type de socket spécifié n'existe pas dans cette famille d'adresses. Cette erreur est retournée si le membre ai_socktype de la structure addrinfoex pointée par le paramètre pHints n’est pas pris en charge.
WSAHOST_NOT_FOUND
Hôte inconnu. Cette erreur est retournée si le nom ne se résout pas pour les paramètres fournis ou si les paramètres pName et pServiceName n’ont pas été fournis.
WSANO_DATA
Le nom demandé est valide, mais aucune donnée du type requis n'a été trouvée.
WSANO_RECOVERY
Une erreur irrécupérable s’est produite pendant une recherche de base de données. Cette erreur est retournée si une erreur irrécupérable dans la résolution de noms s’est produite.
WSANOTINITIALISED
Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSASERVICE_NOT_FOUND
Aucun service de ce type n’est connu. Le service est introuvable dans l’espace de nom spécifié. Cette erreur est retournée si le paramètre pName ou pServiceName est introuvable pour l’espace de noms spécifié dans le paramètre dwNameSpace ou si l’espace de noms spécifié dans le paramètre dwNameSpace n’est pas installé.
WSATRY_AGAIN
Il s'agit habituellement d'une erreur temporaire qui se produit durant la résolution du nom d'hôte et qui signifie que le serveur local n'a pas reçu de réponse d'un serveur de référence. Cette erreur est retournée lorsqu’un échec temporaire de la résolution de noms s’est produit.
WSATYPE_NOT_FOUND
La classe spécifiée est introuvable. Le paramètre pServiceName n’est pas pris en charge pour le membre ai_socktype spécifié de la structure addrinfoex pointée par le paramètre pHints .

Remarques

La fonction GetAddrInfoEx fournit une traduction indépendante du protocole du nom d’hôte à l’adresse et du nom du service au numéro de port. La fonction GetAddrInfoEx est une version améliorée des fonctions getaddrinfo et GetAddrInfoW . La fonction GetAddrInfoEx permet de spécifier le fournisseur d’espaces de noms pour résoudre la requête.

La fonction GetAddrInfoEx agrège et retourne les résultats de plusieurs fournisseurs d’espaces de noms, sauf si un fournisseur d’espaces de noms spécifique est spécifié. Pour une utilisation avec les protocoles IPv6 et IPv4, la résolution de noms peut être effectuée par le système DNS (Domain Name System), un fichier d’hôtes local, un fournisseur de messagerie ( l’espace de noms NS_EMAIL ) ou par d’autres mécanismes de nommage.

Quand UNICODE ou _UNICODE est défini, GetAddrInfoEx est défini sur GetAddrInfoExW, la version Unicode de cette fonction. Les paramètres de chaîne sont définis sur le type de données PWSTR et la structure ADDRINFOEXW est utilisée. Sur Windows 8 et Windows Server 2012, les paramètres timeout, lpOverlapped, lpCompletionRoutine et lpNameHandle peuvent être utilisés pour appeler la fonction GetAddrInfoEx afin qu’elle puisse se terminer de manière asynchrone.

Quand UNICODE ou _UNICODE n’est pas défini, GetAddrInfoEx est défini sur GetAddrInfoExA, la version ANSI de cette fonction. Les paramètres de chaîne sont du type de données PCSTR et la structure ADDRINFOEXA est utilisée. Les paramètres timeout, lpOverlapped, lpCompletionRoutine et lpNameHandle doivent être définis sur NULL.

Un ou les deux paramètres pName ou pServiceName doivent pointer vers une chaîne terminée par NULL. En général, les deux sont fournis.

En cas de réussite, une liste liée de structures addrinfoex est retournée dans le paramètre ppResult . La liste peut être traitée en suivant le pointeur fourni dans le ai_next membre de chaque structure addrinfoex retournée jusqu’à ce qu’un pointeur NULL soit rencontré. Dans chaque structure addrinfoex retournée, les membres ai_family, ai_socktype et ai_protocol correspondent aux arguments respectifs d’un socket ou d’un appel de fonction WSASocket . En outre, le membre ai_addr dans chaque structure addrinfoex retournée pointe vers une structure d’adresse de socket remplie, dont la longueur est spécifiée dans son ai_addrlen membre.

Si le paramètre pName pointe vers un nom d’ordinateur, toutes les adresses permanentes de l’ordinateur qui peuvent être utilisées comme adresse source sont retournées. Sur Windows Vista et versions ultérieures, ces adresses incluent toutes les adresses IP de monodiffusion retournées par les fonctions GetUnicastIpAddressTable ou GetUnicastIpAddressEntry dans lesquelles le membre SkipAsSource est défini sur false dans la structure MIB_UNICASTIPADDRESS_ROW .

Si le paramètre pName pointe vers une chaîne égale à « localhost », toutes les adresses de bouclage sur l’ordinateur local sont retournées.

Si le paramètre pName contient une chaîne vide, toutes les adresses inscrites sur l’ordinateur local sont retournées.

Sur Windows Server 2003 et versions ultérieures si le paramètre pName pointe vers une chaîne égale à . localmachine », toutes les adresses inscrites sur l’ordinateur local sont retournées.

Si le paramètre pName fait référence à un nom de serveur virtuel de cluster, seules les adresses de serveur virtuel sont retournées. Sur Windows Vista et versions ultérieures, ces adresses incluent toutes les adresses IP de monodiffusion retournées par les fonctions GetUnicastIpAddressTable ou GetUnicastIpAddressEntry dans lesquelles le membre SkipAsSource est défini sur true dans la structure MIB_UNICASTIPADDRESS_ROW . Pour plus d’informations sur le clustering, consultez Clustering Windows .

Windows 7 avec Service Pack 1 (SP1) et Windows Server 2008 R2 avec Service Pack 1 (SP1) ajoutent la prise en charge à Netsh.exe pour la définition de l’attribut SkipAsSource sur une adresse IP. Cela modifie également le comportement de telle sorte que si le membre SkipAsSource dans la structure MIB_UNICASTIPADDRESS_ROW a la valeur false, l’adresse IP est inscrite dans DNS. Si le membre SkipAsSource est défini sur true, l’adresse IP n’est pas inscrite dans DNS.

Un correctif logiciel est disponible pour Windows 7 et Windows Server 2008 R2 qui ajoute la prise en charge de Netsh.exe pour la définition de l’attribut SkipAsSource sur une adresse IP. Ce correctif logiciel modifie également le comportement de telle sorte que si le membre SkipAsSource dans la structure MIB_UNICASTIPADDRESS_ROW est défini sur false, l’adresse IP est inscrite dans DNS. Si le membre SkipAsSource est défini sur true, l’adresse IP n’est pas inscrite dans DNS. Pour plus d’informations, consultez 2386184 base de connaissances (Ko).

Un correctif similaire est également disponible pour Windows Vista avec Service Pack 2 (SP2) et Windows Server 2008 avec Service Pack 2 (SP2) qui ajoute la prise en charge de Netsh.exe pour la définition de l’attribut SkipAsSource sur une adresse IP. Ce correctif logiciel modifie également le comportement de telle sorte que si le membre SkipAsSource dans la structure MIB_UNICASTIPADDRESS_ROW est défini sur false, l’adresse IP est inscrite dans DNS. Si le membre SkipAsSource est défini sur true, l’adresse IP n’est pas inscrite dans DNS.

Les appelants de la fonction GetAddrInfoEx peuvent fournir des conseils sur le type de socket pris en charge par le biais d’une structure addrinfoex pointée vers le paramètre pHints . Lorsque le paramètre pHints est utilisé, les règles suivantes s’appliquent à sa structure addrinfoex associée :

  • La valeur AF_UNSPEC pour ai_family indique que l’appelant n’accepte que les familles d’adresses AF_INET et AF_INET6 . Notez que AF_UNSPEC et PF_UNSPEC sont identiques.
  • La valeur zéro pour ai_socktype indique que l’appelant acceptera n’importe quel type de socket.
  • La valeur zéro pour ai_protocol indique que l’appelant acceptera n’importe quel protocole.
  • Le membre ai_addrlen doit être défini sur zéro.
  • Le membre ai_canonname doit avoir la valeur NULL.
  • Le membre ai_addr doit avoir la valeur NULL.
  • Le membre ai_next doit avoir la valeur NULL.

D’autres valeurs de la structure addrinfoex fournie dans le paramètre pHints indiquent des exigences spécifiques. Par exemple, si l’appelant gère uniquement IPv4 et ne gère pas IPv6, le membre ai_family doit être défini sur AF_INET. Pour un autre exemple, si l’appelant gère uniquement TCP et ne gère pas UDP, le membre ai_socktype doit être défini sur SOCK_STREAM.

Si le paramètre pHints est un pointeur NULL , la fonction GetAddrInfoEx le traite comme si la structure addrinfoex dans pHints était initialisée avec son membre ai_family défini sur AF_UNSPEC et tous les autres membres définis sur NULL ou zéro.

Lorsque GetAddrInfoEx est appelé à partir d’un service, si l’opération est le résultat d’un processus utilisateur appelant le service, le service doit emprunter l’identité de l’utilisateur. Cela permet d’appliquer correctement la sécurité.

La fonction GetAddrInfoEx peut être utilisée pour convertir une représentation sous forme de chaîne de texte d’une adresse IP en une structure addrinfoex qui contient une structure sockaddr pour l’adresse IP et d’autres informations. Pour être utilisée de cette façon, la chaîne pointée par le paramètre pName doit contenir une représentation textuelle d’une adresse IP et la structure addrinfoex pointée par le paramètre pHints doit avoir l’indicateur AI_NUMERICHOST défini dans le membre ai_flags . La chaîne pointée par le paramètre pName peut contenir une représentation textuelle d’une adresse IPv4 ou IPv6. L’adresse IP de texte est convertie en structure addrinfoex pointée vers le paramètre ppResult . La structure addrinfoex retournée contient une structure sockaddr pour l’adresse IP, ainsi que des informations supplémentaires sur l’adresse IP.

Plusieurs fournisseurs d’espaces de noms peuvent être installés sur un ordinateur local pour le même espace de noms. Par exemple, le logiciel de mise en réseau TCP/IP Windows de base s’inscrit pour l’espace de noms NS_DNS. Microsoft Forefront Threat Management Gateway (TMG) et l’ancien serveur Microsoft Internet Security and Acceleration (ISA) incluent un logiciel client de pare-feu qui s’inscrit également pour l’espace de noms NS_DNS. Lorsque le paramètre dwNameSpace est défini sur une valeur (NS_DNS, par exemple) et que le paramètre lpNspId a la valeur NULL, les résultats retournés par la fonction GetAddrInfoEx sont les résultats fusionnés de tous les fournisseurs d’espaces de noms qui s’inscrivent pour l’espace de noms spécifié avec les résultats en double éliminés. Le paramètre lpNspId doit être défini sur le GUID du fournisseur d’espaces de noms spécifique si un seul fournisseur d’espaces de noms doit être interrogé.

Si le paramètre pNameSpace est défini sur NS_ALL, les résultats de l’interrogation de tous les fournisseurs d’espaces de noms sont fusionnés et retournés. Dans ce cas, les réponses en double peuvent être retournées dans les résultats pointés vers le paramètre ppResult si plusieurs fournisseurs d’espaces de noms retournent les mêmes informations.

Sur Windows 8 et Windows Server 2012, si la fonction GetAddrInfoEx se termine de manière asynchrone, le pointeur retourné dans le paramètre lpNameHandle peut être utilisé avec la fonction GetAddrInfoExCancel . Le handle retourné est valide lorsque GetAddrInfoEx est retourné jusqu’à ce que la routine d’achèvement soit appelée, que l’événement soit déclenché ou que la fonction GetAddrInfoExCancel soit appelée avec ce handle.

Libération des informations d’adresse de l’allocation dynamique

Toutes les informations retournées par la fonction GetAddrInfoEx pointée vers le paramètre ppResult sont allouées dynamiquement, y compris toutes les structures addrinfoex , les structures d’adresses de socket et les chaînes de noms d’hôte canoniques pointées par les structures addrinfoex . La mémoire allouée par un appel réussi à cette fonction doit être libérée avec un appel ultérieur à FreeAddrInfoEx.

Exemple de code

L’exemple suivant illustre l’utilisation de la fonction GetAddrInfoEx .
#ifndef UNICODE
#define UNICODE
#endif

#include <winsock2.h>
#include <ws2tcpip.h>
#include <objbase.h>
#include <stdio.h>

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")

// Need to link with Ole32.lib to print GUID
#pragma comment(lib, "ole32.lib")

int __cdecl wmain(int argc, wchar_t ** argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    DWORD dwRetval;

    int i = 1;

    DWORD dwNamespace = NS_ALL;
    LPGUID lpNspid = NULL;

    ADDRINFOEX *result = NULL;
    ADDRINFOEX *ptr = NULL;
    ADDRINFOEX hints;

    // LPSOCKADDR sockaddr_ip;
    struct sockaddr_in *sockaddr_ipv4;
    struct sockaddr_in6 *sockaddr_ipv6;

    // DWORD ipbufferlength = 46;
    wchar_t ipstringbuffer[46];

    // variables needed to print namespace provider GUID
    int iRet = 0;
    WCHAR GuidString[40] = { 0 };

    // Validate the parameters
    if (argc != 4) {
        wprintf(L"usage: %ws <hostname> <servicename> <namespace>\n", argv[0]);
        wprintf(L"getaddrinfoex provides protocol-independent translation\n");
        wprintf(L"   from a host name to an IP address\n");
        wprintf(L"%ws example usage\n", argv[0]);
        wprintf(L"   %ws www.contoso.com 0 12\n", argv[0]);
        wprintf(L"   looks up the www.contoso.com in the NS_DNS namespace\n",
                argv[0]);
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed: %d\n", iResult);
        return 1;
    }
    //--------------------------------
    // Setup the hints address info structure
    // which is passed to the getaddrinfo() function
    ZeroMemory(&hints, sizeof (hints));
    hints.ai_family = AF_UNSPEC;
    hints.ai_socktype = SOCK_STREAM;
    hints.ai_protocol = IPPROTO_TCP;

    dwNamespace = (DWORD) _wtoi(argv[3]);

    wprintf(L"Calling GetAddrInfoEx with following parameters:\n");
    wprintf(L"\tName = %ws\n", argv[1]);
    wprintf(L"\tServiceName (or port) = %ws\n", argv[2]);
    wprintf(L"\tNamespace = %s (", argv[3]);
    switch (dwNamespace) {
    case NS_ALL:
        wprintf(L"(NS_ALL)\n");
        break;
    case NS_DNS:
        wprintf(L"(NS_DNS)\n");
        break;
    case NS_NETBT:
        wprintf(L"NS_NETBT");
        break;
    case NS_WINS:
        wprintf(L"NS_WINS");
        break;
    case NS_NLA:
        wprintf(L"NS_NLA");
        break;
    case NS_BTH:
        wprintf(L"NS_BTH");
        break;
    case NS_NTDS:
        wprintf(L"NS_NTDS");
        break;
    case NS_EMAIL:
        wprintf(L"NS_EMAIL");
        break;
    case NS_PNRPNAME:
        wprintf(L"NS_PNRPNAME");
        break;
    case NS_PNRPCLOUD:
        wprintf(L"NS_PNRPCLOUD");
        break;
    default:
        wprintf(L"Other");
        break;
    }
    wprintf(L")\n\n");

//--------------------------------
// Call getaddrinfoex(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
    dwRetval =
        GetAddrInfoEx(argv[1], argv[2], dwNamespace, lpNspid, &hints, &result,
                      NULL, NULL, NULL, NULL);
    if (dwRetval != 0) {
        wprintf(L"GetAddrInfoEx failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }

    wprintf(L"GetAddrInfoEx returned success\n");

    // Retrieve each address and print out the hex bytes
    for (ptr = result; ptr != NULL; ptr = ptr->ai_next) {

        wprintf(L"GetAddrInfoEx response %d\n", i++);
        wprintf(L"\tFlags: 0x%x\n", ptr->ai_flags);
        wprintf(L"\tFamily: ");
        switch (ptr->ai_family) {
        case AF_UNSPEC:
            wprintf(L"Unspecified\n");
            break;
        case AF_INET:
            wprintf(L"AF_INET (IPv4)\n");
            // the InetNtop function is available on Windows Vista and later
            sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
            wprintf(L"\tIPv4 address %ws\n",
                    InetNtop(AF_INET, &sockaddr_ipv4->sin_addr, ipstringbuffer,
                             46));

            // We could also use the WSAAddressToString function
            // sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
            // The buffer length is changed by each call to WSAAddresstoString
            // So we need to set it for each iteration through the loop for safety
            // ipbufferlength = 46;
            // iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL, 
            //    ipstringbuffer, &ipbufferlength );
            // if (iRetval)
            //    wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
            // else    
            //    wprintf(L"\tIPv4 address %ws\n", ipstringbuffer);
            break;
        case AF_INET6:
            wprintf(L"AF_INET6 (IPv6)\n");
            // the InetNtop function is available on Windows Vista and later
            sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
            wprintf(L"\tIPv6 address %ws\n",
                    InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr,
                             ipstringbuffer, 46));

            // We could also use WSAAddressToString which also returns the scope ID
            // sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
            // The buffer length is changed by each call to WSAAddresstoString
            // So we need to set it for each iteration through the loop for safety
            // ipbufferlength = 46;
            //iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL, 
            //    ipstringbuffer, &ipbufferlength );
            //if (iRetval)
            //    wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
            //else    
            //    wprintf(L"\tIPv6 address %ws\n", ipstringbuffer);
            break;
        default:
            wprintf(L"Other %ld\n", ptr->ai_family);
            break;
        }
        wprintf(L"\tSocket type: ");
        switch (ptr->ai_socktype) {
        case 0:
            wprintf(L"Unspecified\n");
            break;
        case SOCK_STREAM:
            wprintf(L"SOCK_STREAM (stream)\n");
            break;
        case SOCK_DGRAM:
            wprintf(L"SOCK_DGRAM (datagram) \n");
            break;
        case SOCK_RAW:
            wprintf(L"SOCK_RAW (raw) \n");
            break;
        case SOCK_RDM:
            wprintf(L"SOCK_RDM (reliable message datagram)\n");
            break;
        case SOCK_SEQPACKET:
            wprintf(L"SOCK_SEQPACKET (pseudo-stream packet)\n");
            break;
        default:
            wprintf(L"Other %ld\n", ptr->ai_socktype);
            break;
        }
        wprintf(L"\tProtocol: ");
        switch (ptr->ai_protocol) {
        case 0:
            wprintf(L"Unspecified\n");
            break;
        case IPPROTO_TCP:
            wprintf(L"IPPROTO_TCP (TCP)\n");
            break;
        case IPPROTO_UDP:
            wprintf(L"IPPROTO_UDP (UDP) \n");
            break;
        default:
            wprintf(L"Other %ld\n", ptr->ai_protocol);
            break;
        }
        wprintf(L"\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
        wprintf(L"\tCanonical name: %s\n", ptr->ai_canonname);

        if (ptr->ai_blob == NULL)
            wprintf(L"\tBlob: (null)\n");
        else    
            wprintf(L"\tLength of the blob: %u\n",
                    (DWORD) ptr->ai_bloblen);

        if (ptr->ai_provider == NULL)
            wprintf(L"\tNamespace provider GUID: (null)\n");
        else {
            iRet =
                StringFromGUID2(*(ptr->ai_provider), (LPOLESTR) & GuidString,
                                39);
            // For c rather than C++ source code, the above line needs to be
            // iRet = StringFromGUID2(&ptr.ai_provider, (LPOLESTR) &GuidString, 39); 
            if (iRet == 0)
                wprintf(L"StringFromGUID2 failed\n");
            else {
                wprintf(L"\tNamespace provider: %ws\n", GuidString);
            }
        }
    }

    FreeAddrInfoEx(result);
    WSACleanup();

    return 0;
}


L’exemple suivant montre comment utiliser la fonction GetAddrInfoEx asynchrone pour résoudre un nom en adresse IP.

//
//    This sample demonstrates how to use asynchronous GetAddrInfoEx to
//    resolve a name to an IP address.
//
//    ResolveName <QueryName>
//

#ifndef UNICODE
#define UNICODE
#endif

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#include <stdlib.h>

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")

#define MAX_ADDRESS_STRING_LENGTH   64

//
//  Asynchronous query context structure.
//

typedef struct _QueryContext
{
    OVERLAPPED      QueryOverlapped;
    PADDRINFOEX     QueryResults;
    HANDLE          CompleteEvent;
}QUERY_CONTEXT, *PQUERY_CONTEXT;

VOID
WINAPI
QueryCompleteCallback(
    _In_ DWORD Error,
    _In_ DWORD Bytes,
    _In_ LPOVERLAPPED Overlapped
    );

int
__cdecl
wmain(
    _In_ int Argc, PWCHAR Argv[]
    )
{
    INT                 Error = ERROR_SUCCESS;
    WSADATA             wsaData;
    BOOL                IsWSAStartupCalled = FALSE;
    ADDRINFOEX          Hints;
    QUERY_CONTEXT       QueryContext;
    HANDLE              CancelHandle = NULL;
    DWORD               QueryTimeout = 5 * 1000; // 5 seconds

    ZeroMemory(&QueryContext, sizeof(QueryContext));

    //
    //  Validate the parameters
    //

    if (Argc != 2)
    {
        wprintf(L"Usage: ResolveName <QueryName>\n");
        goto exit;
    }

    //
    //  All Winsock functions require WSAStartup() to be called first
    //

    Error = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (Error != 0)
    {
        wprintf(L"WSAStartup failed with %d\n", Error);
        goto exit;
    }

    IsWSAStartupCalled = TRUE;

    ZeroMemory(&Hints, sizeof(Hints));
    Hints.ai_family = AF_UNSPEC;

    //
    //  Note that this is a simple sample that waits/cancels a single
    //  asynchronous query. The reader may extend this to support
    //  multiple asynchronous queries.
    //

    QueryContext.CompleteEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

    if (QueryContext.CompleteEvent == NULL)
    {
        Error = GetLastError();
        wprintf(L"Failed to create completion event: Error %d\n",  Error);
        goto exit;
    }

    //
    //  Initiate asynchronous GetAddrInfoExW.
    //
    //  Note GetAddrInfoEx can also be invoked asynchronously using an event
    //  in the overlapped object (Just set hEvent in the Overlapped object
    //  and set NULL as completion callback.)
    //
    //  This sample uses the completion callback method.
    //

    Error = GetAddrInfoExW(Argv[1],
                           NULL,
                           NS_DNS,
                           NULL,
                           &Hints,
                           &QueryContext.QueryResults,
                           NULL,
                           &QueryContext.QueryOverlapped,
                           QueryCompleteCallback,
                           &CancelHandle);

    //
    //  If GetAddrInfoExW() returns  WSA_IO_PENDING, GetAddrInfoExW will invoke
    //  the completion routine. If GetAddrInfoExW returned anything else we must
    //  invoke the completion directly.
    //

    if (Error != WSA_IO_PENDING)
    {
        QueryCompleteCallback(Error, 0, &QueryContext.QueryOverlapped);
        goto exit;
    }

    //
    //  Wait for query completion for 5 seconds and cancel the query if it has
    //  not yet completed.
    //

    if (WaitForSingleObject(QueryContext.CompleteEvent,
                            QueryTimeout)  == WAIT_TIMEOUT )
    {

        //
        //  Cancel the query: Note that the GetAddrInfoExCancelcancel call does
        //  not block, so we must wait for the completion routine to be invoked.
        //  If we fail to wait, WSACleanup() could be called while an
        //  asynchronous query is still in progress, possibly causing a crash.
        //

        wprintf(L"The query took longer than %d seconds to complete; "
                L"cancelling the query...\n", QueryTimeout/1000);

        GetAddrInfoExCancel(&CancelHandle);

        WaitForSingleObject(QueryContext.CompleteEvent,
                            INFINITE);
    }

exit:

    if (IsWSAStartupCalled)
    {
        WSACleanup();
    }

    if (QueryContext.CompleteEvent)
    {
        CloseHandle(QueryContext.CompleteEvent);
    }

    return Error;
}

//
// Callback function called by Winsock as part of asynchronous query complete
//

VOID
WINAPI
QueryCompleteCallback(
    _In_ DWORD Error,
    _In_ DWORD Bytes,
    _In_ LPOVERLAPPED Overlapped
    )
{
    PQUERY_CONTEXT  QueryContext = NULL;
    PADDRINFOEX     QueryResults = NULL;
    WCHAR           AddrString[MAX_ADDRESS_STRING_LENGTH];
    DWORD           AddressStringLength;

    UNREFERENCED_PARAMETER(Bytes);

    QueryContext = CONTAINING_RECORD(Overlapped,
                                     QUERY_CONTEXT,
                                     QueryOverlapped);

    if (Error != ERROR_SUCCESS)
    {
        wprintf(L"ResolveName failed with %d\n", Error);
        goto exit;
    }

    wprintf(L"ResolveName succeeded. Query Results:\n");

    QueryResults = QueryContext->QueryResults;

    while(QueryResults)
    {
        AddressStringLength = MAX_ADDRESS_STRING_LENGTH;

        WSAAddressToString(QueryResults->ai_addr,
                           (DWORD)QueryResults->ai_addrlen,
                           NULL,
                           AddrString,
                           &AddressStringLength);

        wprintf(L"Ip Address: %s\n", AddrString);
        QueryResults = QueryResults->ai_next;
    }

exit:

    if (QueryContext->QueryResults)
    {
        FreeAddrInfoEx(QueryContext->QueryResults);
    }

    //
    //  Notify caller that the query completed
    //

    SetEvent(QueryContext->CompleteEvent);
    return;
}

Note Vérifiez que l’environnement de développement cible la version la plus récente de Ws2tcpip.h , qui inclut des définitions de structure et de fonction pour addrinfoex et GetAddrInfoEx, respectivement.
 

Noms de domaine internationalisés

Les noms d’hôtes Internet se composent généralement d’un ensemble très restreint de caractères :
  • Lettres ASCII minuscules et majuscules de l’alphabet anglais.
  • Chiffres de 0 à 9.
  • Caractères de trait d’union ASCII.

Avec la croissance d’Internet, il est de plus en plus nécessaire d’identifier les noms d’hôtes Internet pour d’autres langues qui ne sont pas représentées par le jeu de caractères ASCII. Les identificateurs qui facilitent ce besoin et permettent aux caractères non-ASCII (Unicode) d’être représentés sous forme de chaînes de caractères ASCII spéciales sont appelés noms de domaine internationalisés (IDN). Un mécanisme appelé Internationalizing Domain Names in Applications (IDNA) est utilisé pour gérer les IDN de manière standard. Les spécifications pour les IDN et IDNA sont documentées dans RFC 3490, RTF 5890 et RFC 6365 publiées par l’Internet Engineering Task Force (IETF).

Sur Windows 8 et Windows Server 2012, la fonction GetAddrInfoEx prend en charge l’analyse idn (Internationalized Domain Name) appliquée au nom passé dans le paramètre pName . Winsock effectue l’encodage et la conversion Punycode/IDN. Ce comportement peut être désactivé à l’aide de l’indicateur AI_DISABLE_IDN_ENCODING décrit ci-dessous.

Sur Windows 7 et Windows Server 2008 R2 ou version antérieure, la fonction GetAddrInfoEx ne prend actuellement pas en charge l’analyse IDN appliquée au nom passé dans le paramètre pName . La version à caractères larges de la fonction GetAddrInfoEx n’utilise pas Punycode pour convertir un format IDN Punycode conformément à la norme RFC 3490. La version à caractères larges de la fonction GetAddrInfoEx lors de l’interrogation dns encode le nom Unicode au format UTF-8, le format utilisé par les serveurs DNS Microsoft dans un environnement d’entreprise.

Plusieurs fonctions sur Windows Vista et ultérieurement prennent en charge la conversion entre les étiquettes Unicode dans un IDN en leurs équivalents ASCII. La représentation résultante de chaque étiquette Unicode contient uniquement des caractères ASCII et commence par le préfixe xn-- si l’étiquette Unicode contenait des caractères non-ASCII. Cela s’explique par la prise en charge des serveurs DNS existants sur Internet, car certains outils et serveurs DNS prennent uniquement en charge les caractères ASCII (voir RFC 3490).

La fonction IdnToAscii utilise Punycode pour convertir un IDN en représentation ASCII de la chaîne Unicode d’origine à l’aide de l’algorithme standard défini dans RFC 3490. La fonction IdnToUnicode convertit la forme ASCII d’un IDN en syntaxe d’encodage Unicode UTF-16 normale. Pour plus d’informations et des liens vers des ébauches de normes connexes, consultez Gestion des noms de domaine internationalisés (IDN).

La fonction IdnToAscii peut être utilisée pour convertir un nom IDN en un formulaire ASCII qui peut ensuite être transmis dans le paramètre pName à la fonction GetAddrInfoEx lorsque la version ASCII de cette fonction est utilisée (lorsque unicode et _UNICODE ne sont pas définis). Pour passer ce nom IDN à la fonction GetAddrInfoEx lorsque la version à caractères larges de cette fonction est utilisée (lorsque unicode ou _UNICODE est défini), vous pouvez utiliser la fonction MultiByteToWideChar pour convertir la chaîne CHAR en chaîne WCHAR .

Utilisation de ai_flags dans le paramètre hints

Les indicateurs dans le ai_flags membre de la structure addrinfoex facultative fournie dans le paramètre hints modifient le comportement de la fonction.

Ces bits d’indicateur sont définis dans le fichier d’en-tête Ws2def.h du Kit de développement logiciel (SDK) Microsoft Windows pour Windows 7. Ces bits d’indicateur sont définis dans le fichier d’en-tête Ws2tcpip.h sur le SDK Windows pour Windows Server 2008 et Windows Vista. Ces bits d’indicateur sont définis dans le fichier d’en-tête Ws2tcpip.h du Kit de développement logiciel (SDK) de plateforme pour Windows Server 2003 et Windows XP.

Les bits d’indicateur peuvent être une combinaison des éléments suivants :

Bits d’indicateur Description
AI_PASSIVE La définition de l’indicateur AI_PASSIVE indique que l’appelant a l’intention d’utiliser la structure d’adresse de socket retournée dans un appel à la fonction de liaison . Lorsque l’indicateur AI_PASSIVE est défini et que pName est un pointeur NULL , la partie adresse IP de la structure d’adresses de socket est définie sur INADDR_ANY pour les adresses IPv4 et IN6ADDR_ANY_INIT pour les adresses IPv6.

Lorsque l’indicateur AI_PASSIVE n’est pas défini, la structure d’adresse de socket retournée est prête pour un appel à la fonction de connexion pour un protocole orienté connexion, ou prête pour un appel aux fonctions connect, sendto ou send pour un protocole sans connexion. Si le paramètre pName est un pointeur NULL dans ce cas, la partie adresse IP de la structure d’adresse de socket est définie sur l’adresse de bouclage.

AI_CANONNAME Si ni AI_CANONNAME ni AI_NUMERICHOST n’est utilisé, la fonction GetAddrInfoEx tente la résolution. Si une chaîne littérale est passée , GetAddrInfoEx tente de convertir la chaîne, et si un nom d’hôte est transmis, la fonction GetAddrInfoEx tente de résoudre le nom en une adresse ou plusieurs adresses.

Lorsque le bit AI_CANONNAME est défini, le paramètre pName ne peut pas être NULL. Sinon, la fonction GetAddrInfoEx échoue avec WSANO_RECOVERY.

Lorsque le bit AI_CANONNAME est défini et que la fonction GetAddrInfoEx retourne la réussite, le membre ai_canonname dans le paramètre ppResult pointe vers une chaîne terminée par NULL qui contient le nom canonique du nœud spécifié.

Note La fonction GetAddrInfoEx peut retourner success lorsque l’indicateur AI_CANONNAME est défini, mais le membre ai_canonname dans la structure addrinfo associée est NULL. Par conséquent, l’utilisation recommandée de l’indicateur AI_CANONNAME inclut le test de la valeur NULL du membre ai_canonname dans la structure addrinfoex associée.
 
AI_NUMERICHOST Lorsque le bit AI_NUMERICHOST est défini, le paramètre pName doit contenir une chaîne d’adresse d’hôte numérique non NULL , sinon l’erreur EAI_NONAME est retournée. Cet indicateur empêche l’appel d’un service de résolution de noms.
AI_NUMERICSERV Lorsque le bit AI_NUMERICSERV est défini, le paramètre pServiceName doit contenir un numéro de port numérique non NULL , sinon l’erreur EAI_NONAME est retournée. Cet indicateur empêche l’appel d’un service de résolution de noms.

L’indicateur AI_NUMERICSERV est défini sur le SDK Windows pour Windows Vista et versions ultérieures. L’indicateur AI_NUMERICSERV n’est pas pris en charge par les fournisseurs Microsoft.

AI_ALL Si le bit AI_ALL est défini, une requête est effectuée pour les adresses IPv6 et IPv4 avec AI_V4MAPPED.

L’indicateur AI_ALL est défini sur le SDK Windows pour Windows Vista et versions ultérieures. L’indicateur AI_ALL est pris en charge sur Windows Vista et versions ultérieures.

AI_ADDRCONFIG Si le bit AI_ADDRCONFIG est défini, GetAddrInfoEx est résolu uniquement si une adresse globale est configurée. Si AI_ADDRCONFIG indicateur est spécifié, les adresses IPv4 sont retournées uniquement si une adresse IPv4 est configurée sur le système local, et les adresses IPv6 sont retournées uniquement si une adresse IPv6 est configurée sur le système local. L’adresse de bouclage IPv4 ou IPv6 n’est pas considérée comme une adresse globale valide.

L’indicateur AI_ADDRCONFIG est défini sur le Kit de développement logiciel (SDK) Windows pour Windows Vista et versions ultérieures. L’indicateur AI_ADDRCONFIG est pris en charge sur Windows Vista et versions ultérieures.

AI_V4MAPPED Si le bit AI_V4MAPPED est défini et qu’une demande d’adresses IPv6 échoue, une demande de service de nom est effectuée pour les adresses IPv4 et ces adresses sont converties au format d’adresse IPv6 mappée.

L’indicateur AI_V4MAPPED est défini sur le Kit de développement logiciel (SDK) Windows pour Windows Vista et versions ultérieures. L’indicateur AI_V4MAPPED est pris en charge sur Windows Vista et versions ultérieures.

AI_NON_AUTHORITATIVE Si le bit AI_NON_AUTHORITATIVE est défini, le fournisseur d’espace de noms NS_EMAIL retourne des résultats faisant autorité et non faisant autorité. Si le bit AI_NON_AUTHORITATIVE n’est pas défini, le fournisseur d’espace de noms NS_EMAIL retourne uniquement les résultats faisant autorité.

L’indicateur AI_NON_AUTHORITATIVE est défini sur le Kit de développement logiciel (SDK) Windows pour Windows Vista et versions ultérieures. L’indicateur AI_NON_AUTHORITATIVE est pris en charge sur Windows Vista et versions ultérieures et s’applique uniquement à l’espace de noms NS_EMAIL.

AI_SECURE Si le bit AI_SECURE est défini, le fournisseur d’espace de noms NS_EMAIL retourne les résultats obtenus avec une sécurité renforcée pour réduire les usurpations d’identité possibles.

L’indicateur AI_SECURE est défini sur le Kit de développement logiciel (SDK) Windows pour Windows Vista et versions ultérieures. L’indicateur AI_SECURE est pris en charge sur Windows Vista et versions ultérieures et s’applique uniquement à l’espace de noms NS_EMAIL.

AI_RETURN_PREFERRED_NAMES Si le AI_RETURN_PREFERRED_NAMES est défini, aucun nom ne doit être fourni dans le paramètre pName . Le fournisseur d’espace de noms NS_EMAIL retourne les noms préférés pour la publication.

L’indicateur AI_RETURN_PREFERRED_NAMES est défini sur le Kit de développement logiciel (SDK) Windows pour Windows Vista et versions ultérieures. L’indicateur AI_RETURN_PREFERRED_NAMES est pris en charge sur Windows Vista et versions ultérieures et s’applique uniquement à l’espace de noms NS_EMAIL.

AI_FQDN Si le AI_FQDN est défini et qu’un nom plat (étiquette unique) est spécifié, GetAddrInfoEx retourne le nom de domaine complet auquel le nom a finalement été résolu. Le nom de domaine complet est retourné dans le membre ai_canonname dans la structure addrinfoex associée. Il est différent de AI_CANONNAME indicateur de bits qui retourne le nom canonique inscrit dans DNS qui peut être différent du nom de domaine complet auquel le nom plat a été résolu.

Lorsque le bit AI_FQDN est défini, le paramètre pName ne peut pas avoir la valeur NULL. Sinon, la fonction GetAddrInfoEx échoue avec WSANO_RECOVERY.

Sur Windows 8 et Windows Server 2012, les bits AI_FQDN et AI_CANONNAME peuvent être définis. Si la fonction GetAddrInfoEx est appelée avec les bits AI_FQDN et AI_CANONNAME , le paramètre ppResult renvoie un pointeur vers une structure addrinfoex2 , et non une structure addrinfoex .

Sur Windows 7 et Windows Server 2008 R2, un seul des bits AI_FQDN et AI_CANONNAME peut être défini. La fonction GetAddrInfoEx échoue si les deux indicateurs sont présents avec EAI_BADFLAGS.

Windows 7 : L’indicateur AI_FQDN est défini sur le Kit de développement logiciel (SDK) Windows pour Windows 7 et versions ultérieures. L’indicateur AI_FQDN est pris en charge sur Windows 7 et versions ultérieures.

AI_FILESERVER Si le AI_FILESERVER est défini, cela indique au fournisseur d’espace de noms que le nom d’hôte interrogé est utilisé dans le scénario de partage de fichiers. Le fournisseur d’espaces de noms peut ignorer cet indicateur.

Windows 7 : L’indicateur AI_FILESERVER est défini sur le Kit de développement logiciel (SDK) Windows pour Windows 7 et versions ultérieures. L’indicateur AI_FILESERVER est pris en charge sur Windows 7 et versions ultérieures.

AI_DISABLE_IDN_ENCODING Si le AI_DISABLE_IDN_ENCODING est défini, cela désactive l’encodage automatique des noms de domaine internationaux à l’aide de Punycode dans les fonctions de résolution de noms appelées par la fonction GetAddrInfoEx .

Windows 8 : L’indicateur AI_DISABLE_IDN_ENCODING est défini sur le Kit de développement logiciel (SDK) Windows pour Windows 8 et versions ultérieures. L’indicateur AI_DISABLE_IDN_ENCODING est pris en charge sur Windows 8 et versions ultérieures.

 

Notes

L’en-tête ws2tcpip.h définit GetAddrInfoEx comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête ws2tcpip.h
Bibliothèque Ws2_32.lib
DLL Ws2_32.dll

Voir aussi

FreeAddrInfoEx

GetAddrInfoExCancel

GetAddrInfoExOverlappedResult

GetAddrInfoW

IdnToAscii

IdnToUnicode

WSAEnumNameSpaceProviders

WSAGetLastError

Codes d’erreur des sockets Windows

addrinfoex

addrinfoex2

gai_strerror

getaddrinfo