Fonction GetAddrInfoW (ws2tcpip.h)

Article
08/28/2023

La fonction GetAddrInfoW fournit une traduction indépendante du protocole d’un nom d’hôte Unicode vers une adresse.

Syntaxe

INT WSAAPI GetAddrInfoW(
  [in, optional] PCWSTR          pNodeName,
  [in, optional] PCWSTR          pServiceName,
  [in, optional] const ADDRINFOW *pHints,
  [out]          PADDRINFOW      *ppResult
);

Paramètres

[in, optional] pNodeName

Pointeur vers une chaîne Unicode terminée par NULL qui contient 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 Unicode 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, optional] pHints

Pointeur vers une structure addrinfoW 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 addrinfoW 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 addrinfoW qui contient des informations de réponse sur l’hôte.

Valeur retournée

Success retourne zéro. 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 GetAddrInfoW correspondent au jeu d’erreurs décrit par les recommandations de l’Internet Engineering Task Force (IETF). Le tableau suivant répertorie 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	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 pNodeName 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 GetAddrInfoW . 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 d’une fonction de sockets Windows traditionnelle, telle 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 addrinfoW pointée par le paramètre hints 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 addrinfoW vers laquelle pointe le paramètre hints .
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 addrinfoW pointée par le paramètre hints n’est pas pris en charge.
WSAHOST_NOT_FOUND	Hôte inconnu. Cette erreur est retournée si le nom n’est pas résolu pour les paramètres fournis ou si les paramètres pNodename 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.
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 addrinfoW pointée par le paramètre hints .

Remarques

La fonction GetAddrInfoW est la version Unicode d’une fonction qui fournit une traduction indépendante du protocole du nom d’hôte à l’adresse. La version ANSI de cette fonction est getaddrinfo.

La fonction GetAddrInfoW retourne des résultats pour l’espace de noms NS_DNS . La fonction GetAddrInfoW agrège toutes les réponses si plusieurs fournisseurs d’espaces de noms retournent des informations. 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 hôte local ou par d’autres mécanismes de nommage pour l’espace de noms NS_DNS .

Les macros dans le fichier d’en-tête Winsock définissent un nom de fonction à casse mixte de GetAddrInfo et une structure ADDRINFOT . Cette fonction GetAddrInfo doit être appelée avec les paramètres pNodeName et pServiceName d’un pointeur de type TCHAR et les paramètres pHints et ppResult d’un pointeur de type ADDRINFOT. Lorsque unicode ou _UNICODE est défini, GetAddrInfo est défini sur GetAddrInfoW, la version Unicode de la fonction, et ADDRINFOT est défini sur la structure addrinfoW . Lorsque unicode ou _UNICODE n’est pas défini, GetAddrInfo est défini sur getaddrinfo, la version ANSI de la fonction, et ADDRINFOT est défini sur la structure addrinfo .

L’un des paramètres pNodeName ou pServiceName ou les deux doivent pointer vers une chaîne Unicode terminée par null ; en général, les deux sont fournis.

En cas de réussite, une liste liée de structures addrinfoW 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 addrinfoW retournée jusqu’à ce qu’un pointeur NULL soit rencontré. Dans chaque structure addrinfoW 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 addrinfoW 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 pNodeName 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 pNodeName pointe vers une chaîne égale à « localhost », toutes les adresses de bouclage sur l’ordinateur local sont retournées.

Si le paramètre pNodeName 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 pNodeName pointe vers une chaîne égale à . localmachine », toutes les adresses inscrites sur l’ordinateur local sont retournées.

Si le paramètre pNodeName 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 unicast 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 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 de Netsh.exe pour la définition de l’attribut SkipAsSource sur une adresse IP. Cela modifie également le comportement de 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 a la valeur 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 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 a la valeur true, l’adresse IP n’est pas inscrite dans DNS. Pour plus d’informations, consultez 2386184 de la Base de connaissances (Ko).

Un correctif logiciel 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 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 a la valeur true, l’adresse IP n’est pas inscrite dans DNS.

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

Une valeur de AF_UNSPEC pour ai_family indique que l’appelant n’acceptera 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 addrinfoW 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 GetAddrInfoW le gère comme si la structure addrinfoW dans pHints avait été initialisée avec son membre ai_family défini sur AF_UNSPEC et tous les autres membres définis sur zéro.

Sur Windows Vista et versions ultérieures, lorsque GetAddrInfoW 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. Il s’agit de permettre à la sécurité d’être correctement appliquée.

La fonction GetAddrInfoW peut être utilisée pour convertir une représentation de chaîne de texte d’une adresse IP en structure addrinfoW qui contient une structure sockaddr pour l’adresse IP et d’autres informations. Pour être utilisée de cette manière, la chaîne pointée vers le paramètre pNodeName doit contenir une représentation textuelle d’une adresse IP et la structure addrinfoW 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 vers par le paramètre pNodeName peut contenir une représentation textuelle d’une adresse IPv4 ou IPv6. L’adresse IP de texte est convertie en une structure addrinfoW pointée vers le paramètre ppResult . La structure addrinfoW retournée contient une structure sockaddr pour l’adresse IP ainsi que des informations supplémentaires sur l’adresse IP. Pour que cette méthode fonctionne avec une chaîne d’adresse IPv6 sur Windows Server 2003 et Windows XP, le protocole IPv6 doit être installé sur l’ordinateur local. Sinon, l’erreur WSAHOST_NOT_FOUND est retournée.

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

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

Exemple de code

L’exemple de code suivant montre comment utiliser la fonction GetAddrInfoW .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

// set APPVER=5.02 for WinXP SP2 and later

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

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

    DWORD dwRetval;

    int i = 1;
    
    ADDRINFOW *result = NULL;
    ADDRINFOW *ptr = NULL;
    ADDRINFOW hints;

//    struct sockaddr_in6 *sockaddr_ipv6;
    LPSOCKADDR sockaddr_ip;

    wchar_t ipstringbuffer[46];
    DWORD ipbufferlength = 46;

    // Validate the parameters
    if (argc != 3) {
        wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
        wprintf(L"getaddrinfow provides protocol-independent translation\n");
        wprintf(L"   from an Unicode host name to an IP address\n");
        wprintf(L"%ws example usage\n", argv[0]);
        wprintf(L"   %ws www.contoso.com 0\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;

    wprintf(L"Calling getaddrinfow with following parameters:\n");
    wprintf(L"\tnodename = %ws\n", argv[1]);
    wprintf(L"\tservname (or port) = %ws\n\n", argv[2]);
    

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

    wprintf(L"GetAddrInfoW returned success\n");
    
    // Retrieve each address and print out the hex bytes
    for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {

        wprintf(L"GetAddrInfoW 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");
                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;
                // printf("\tIPv6 address %s\n",
                //    InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstringbuffer, 46) );
                
                // We use WSAAddressToString since it is supported on Windows XP and later
                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);
    }

    FreeAddrInfoW(result);
    WSACleanup();

    return 0;
}

Note Assurez-vous que l’environnement de développement cible la dernière version de Ws2tcpip.h , qui inclut respectivement des définitions de structure et de fonction pour addrinfoW et GetAddrInfoW.

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 en tant que 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 des 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 GetAddrInfoW prend en charge l’analyse IDN (Internationalized Domain Name) appliquée au nom passé dans le paramètre pNodeName . 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 GetAddrInfoW ne prend pas actuellement en charge l’analyse IDN appliquée au nom passé dans le paramètre pNodeName . Winsock n’effectue aucune conversion Punycode/IDN. La fonction GetAddrInfoW n’utilise pas Punycode pour convertir un IDN conformément à la RFC 3490. La fonction GetAddrInfoW 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 les versions ultérieures prennent en charge la conversion d’étiquettes Unicode dans un IDN vers 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 contient des caractères non ASCII. La raison en est la prise en charge des serveurs DNS existants sur Internet, car certains outils dns et serveurs 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 UTF-16 Unicode normale. Pour plus d’informations et des liens vers des projets de normes connexes, consultez Gestion des noms de domaine internationalisés (IDN).

La fonction IdnToAscii peut être utilisée pour convertir un nom IDN au format ASCII. Pour passer ce formulaire ASCII à la fonction GetAddrInfoW , vous pouvez utiliser la fonction MultiByteToWideChar pour convertir la chaîne CHAR en chaîne WCHAR qui peut ensuite être passée dans le paramètre pNodeName à la fonction GetAddrInfoW .

Utilisation de ai_flags dans le paramètre hints

Les indicateurs du membre ai_flags de la structure addrinfoW facultative fournie dans le paramètre pHints 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 Kit de développement logiciel (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 :

Indicateurs bits	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 pNodeName est un pointeur NULL , la partie adresse IP de la structure d’adresse 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 de connexion, d’envoi ou d’envoi pour un protocole sans connexion. Si le paramètre pNodeName 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 GetAddrInfoW tente la résolution. Si une chaîne littérale est transmise GetAddrInfoW tente de convertir la chaîne et si un nom d’hôte est transmis, la fonction GetAddrInfoW tente de résoudre le nom en une adresse ou plusieurs adresses. Lorsque le bit AI_CANONNAME est défini, le paramètre pNodeName ne peut pas avoir la valeur NULL. Sinon, la fonction GetAddrInfoEx échoue avec WSANO_RECOVERY. Lorsque le bit AI_CANONNAME est défini et que la fonction GetAddrInfoW retourne la réussite, le membre ai_canonname dans le paramètre ppResult pointe vers une chaîne null terminée qui contient le nom canonique du nœud spécifié. Note La fonction GetAddrInfoW peut retourner la réussite lorsque l’indicateur AI_CANONNAME est défini, mais le membre ai_canonname dans la structure addrinfoW 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 addrinfoW associée.
AI_NUMERICHOST	Lorsque le bit AI_NUMERICHOST est défini, le paramètre pNodeName doit contenir une chaîne d’adresse 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 Kit de développement logiciel (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 demande 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, GetAddrInfoW ne sera résolu que 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é iPv4. L’indicateur AI_V4MAPPED est défini sur le 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 l’usurpation possible. 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 pNodeName . Le fournisseur d’espaces de noms NS_EMAIL retourne les noms préférés pour 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é, GetAddrInfoW 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 addrinfoW associée. Cela 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 dans lequel le nom plat a été résolu. Un seul des bits AI_FQDN et AI_CANONNAME peut être défini. La fonction GetAddrInfoW échoue si les deux indicateurs sont présents avec EAI_BADFLAGS. Lorsque le bit AI_FQDN est défini, le paramètre pNodeName ne peut pas être NULL. Sinon, la fonction GetAddrInfoEx échoue avec WSANO_RECOVERY. Windows 7 : L’indicateur AI_FQDN est défini sur le 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, il s’agit d’un indicateur pour le fournisseur d’espaces 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 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 de nom de domaine international à l’aide de Punycode dans les fonctions de résolution de noms appelées par la fonction GetAddrInfoW . Windows 8 : L’indicateur AI_DISABLE_IDN_ENCODING est défini sur le 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.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Notes

L’en-tête ws2tcpip.h définit GetAddrInfo en tant qu’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. La combinaison 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.

Spécifications


Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	ws2tcpip.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll