getaddrinfo, fonction (ws2tcpip.h)
La fonction getaddrinfo fournit une traduction indépendante du protocole d’un nom d’hôte ANSI vers une adresse.
Syntaxe
INT WSAAPI getaddrinfo(
[in, optional] PCSTR pNodeName,
[in, optional] PCSTR pServiceName,
[in, optional] const ADDRINFOA *pHints,
[out] PADDRINFOA *ppResult
);
Paramètres
[in, optional] pNodeName
Pointeur vers une chaîne ANSI 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 ANSI 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 addrinfo 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 addrinfo pointées 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 addrinfo 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 getaddrinfo sont mappés à l’ensemble d’erreurs décrites 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 basés sur les codes EAI retournés par la fonction getaddrinfo . 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 |
|---|---|
| La mémoire était insuffisante pour effectuer l’opération. | |
| Une adresse incompatible avec le protocole demandé a été utilisée. Cette erreur est retournée si le membre ai_family de la structure addrinfo pointée par le paramètre pHints n’est pas pris en charge. | |
| 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 addrinfo vers laquelle pointe le paramètre pHints . | |
| 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 addrinfo pointée par le paramètre pHints n’est pas pris en charge. | |
| 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. | |
| Le nom demandé est valide, mais aucune donnée du type requis n'a été trouvée. | |
| 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. | |
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. | |
| 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. | |
| 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 addrinfo pointée par le paramètre pHints . |
Remarques
La fonction getaddrinfo est la version ANSI d’une fonction qui fournit une traduction indépendante du protocole du nom d’hôte à l’adresse. La version Unicode de cette fonction est GetAddrInfoW. Les développeurs sont encouragés à utiliser la fonction Unicode GetAddrInfoW plutôt que la fonction ANSI getaddrinfo .
La fonction getaddrinfo retourne des résultats pour l’espace de noms NS_DNS . La fonction getaddrinfo 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 .
Un autre nom qui peut être utilisé pour la fonction getaddrinfo est GetAddrInfoA. Les macros du fichier d’en-tête Ws2tcpip.h définissent GetAddrInfoA à getaddrinfo.
Les macros du fichier d’en-tête Ws2tcpip.h 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 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 . 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 .
Les noms de paramètres et les types de paramètres pour la fonction getaddrinfo définis dans le fichier d’en-tête Ws2tcpip.h sur le Kit de développement logiciel (SDK) de plateforme pour Windows Server 2003 et Windows XP étaient différents.
L’un des paramètres pNodeName ou pServiceName ou les deux doivent pointer vers une chaîne ANSI terminée par NULL ; en général, les deux sont fournis.
En cas de réussite, une liste liée de structures addrinfo 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 addrinfo retournée jusqu’à ce qu’un pointeur NULL soit rencontré. Dans chaque structure addrinfo retournée, les membres ai_family, ai_socktype et ai_protocol correspondent aux arguments respectifs dans un appel de fonction de socket ou WSASocket . En outre, le membre ai_addr dans chaque structure addrinfo 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 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 getaddrinfo peuvent fournir des conseils sur le type de socket pris en charge par le biais d’une structure addrinfo pointée par le paramètre pHints . Lorsque le paramètre pHints est utilisé, les règles suivantes s’appliquent à sa structure addrinfo 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.
La valeur AF_UNSPEC pour ai_family indique que l’appelant acceptera n’importe quelle famille de protocoles. Cette valeur peut être utilisée pour renvoyer à la fois les adresses IPv4 et IPv6 pour le nom d’hôte pointé par le paramètre pNodeName . Sur Windows Server 2003 et Windows XP, les adresses IPv6 sont retournées uniquement si IPv6 est installé sur l’ordinateur local.
D’autres valeurs de la structure addrinfo 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 getaddrinfo le traite comme si la structure addrinfo dans pHints était 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 getaddrinfo 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 getaddrinfo peut être utilisée pour convertir une représentation sous forme de chaîne de texte d’une adresse IP en une structure addrinfo 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 pNodeName doit contenir une représentation textuelle d’une adresse IP et la structure addrinfo 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 pNodeName peut contenir une représentation textuelle d’une adresse IPv4 ou IPv6. L’adresse IP de texte est convertie en une structure addrinfo pointée vers le paramètre ppResult . La structure addrinfo 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 getaddrinfo pointée par le paramètre ppResult sont allouées dynamiquement, y compris toutes les structures addrinfo , les structures d’adresses de socket et les chaînes de noms d’hôte canoniques pointées par les structures addrinfo . La mémoire allouée par un appel réussi à cette fonction doit être libérée avec un appel ultérieur à freeaddrinfo.Exemple de code
L’exemple de code suivant montre comment utiliser la fonction getaddrinfo .#undef UNICODE
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// link with Ws2_32.lib
#pragma comment (lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
INT iRetval;
DWORD dwRetval;
int i = 1;
struct addrinfo *result = NULL;
struct addrinfo *ptr = NULL;
struct addrinfo hints;
struct sockaddr_in *sockaddr_ipv4;
// struct sockaddr_in6 *sockaddr_ipv6;
LPSOCKADDR sockaddr_ip;
char ipstringbuffer[46];
DWORD ipbufferlength = 46;
// Validate the parameters
if (argc != 3) {
printf("usage: %s <hostname> <servicename>\n", argv[0]);
printf("getaddrinfo provides protocol-independent translation\n");
printf(" from an ANSI host name to an IP address\n");
printf("%s example usage\n", argv[0]);
printf(" %s www.contoso.com 0\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("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;
printf("Calling getaddrinfo with following parameters:\n");
printf("\tnodename = %s\n", argv[1]);
printf("\tservname (or port) = %s\n\n", argv[2]);
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
dwRetval = getaddrinfo(argv[1], argv[2], &hints, &result);
if ( dwRetval != 0 ) {
printf("getaddrinfo failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
printf("getaddrinfo returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
printf("getaddrinfo response %d\n", i++);
printf("\tFlags: 0x%x\n", ptr->ai_flags);
printf("\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
printf("Unspecified\n");
break;
case AF_INET:
printf("AF_INET (IPv4)\n");
sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
printf("\tIPv4 address %s\n",
inet_ntoa(sockaddr_ipv4->sin_addr) );
break;
case AF_INET6:
printf("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)
printf("WSAAddressToString failed with %u\n", WSAGetLastError() );
else
printf("\tIPv6 address %s\n", ipstringbuffer);
break;
case AF_NETBIOS:
printf("AF_NETBIOS (NetBIOS)\n");
break;
default:
printf("Other %ld\n", ptr->ai_family);
break;
}
printf("\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
printf("Unspecified\n");
break;
case SOCK_STREAM:
printf("SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
printf("SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
printf("SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
printf("SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
printf("Other %ld\n", ptr->ai_socktype);
break;
}
printf("\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
printf("Unspecified\n");
break;
case IPPROTO_TCP:
printf("IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
printf("IPPROTO_UDP (UDP) \n");
break;
default:
printf("Other %ld\n", ptr->ai_protocol);
break;
}
printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
printf("\tCanonical name: %s\n", ptr->ai_canonname);
}
freeaddrinfo(result);
WSACleanup();
return 0;
}
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 getaddrinfo prend en charge l’analyse de nom de domaine international (IDN) 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 getaddrinfo ne fournit pas actuellement l’analyse idn de prise en charge appliquée au nom passé dans le paramètre pNodeName . Winsock n’effectue aucune conversion Punycode/IDN. La version à caractères larges de la fonction GetAddrInfo n’utilise pas Punycode pour convertir un IDN conformément à la norme RFC 3490. La version à caractères larges de la fonction GetAddrInfo 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 au format ASCII qui peut ensuite être passé dans le paramètre pNodeName à la fonction getaddrinfo . Pour transmettre ce nom IDN à la fonction GetAddrInfo 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 pHints
Les indicateurs du ai_flags membre de la structure addrinfo 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 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 sur le 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 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 connect, sendto ou send 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 getaddrinfo tente la résolution. Si une chaîne littérale est passée getaddrinfo tente de convertir la chaîne, et si un nom d’hôte est passé, la fonction getaddrinfo 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 être NULL. Sinon, la fonction getaddrinfo échoue avec WSANO_RECOVERY. Lorsque le bit AI_CANONNAME est défini et que la fonction getaddrinfo 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 getaddrinfo peut retourner success lorsque l’indicateur de 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 addrinfo associée.
|
| AI_NUMERICHOST | Lorsque le bit AI_NUMERICHOST est défini, le paramètre pNodeName 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, getaddrinfo 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é, getaddrinfo retourne le nom de domaine complet vers lequel le nom a finalement été résolu. Le nom de domaine complet est retourné dans le membre ai_canonname dans la structure addrinfo 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 getaddrinfo é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. |
Exemple de code utilisant AI_NUMERICHOST
L’exemple de code suivant montre comment utiliser la fonction getaddrinfo pour convertir une représentation sous forme de chaîne de texte d’une adresse IP en structure addrinfo qui contient une structure sockaddr pour l’adresse IP et d’autres informations.#undef UNICODE
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// link with Ws2_32.lib
#pragma comment (lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
DWORD dwRetval;
int i = 1;
struct addrinfo *result = NULL;
struct addrinfo *ptr = NULL;
struct addrinfo hints;
// Validate the parameters
if (argc != 2) {
printf("usage: %s <IP Address String>\n", argv[0]);
printf(" getaddrinfo determines the IP binary network address\n");
printf(" %s 207.46.197.32\n", argv[0]); /* www.contoso.com */
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("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_flags = AI_NUMERICHOST;
hints.ai_family = AF_UNSPEC;
// hints.ai_socktype = SOCK_STREAM;
// hints.ai_protocol = IPPROTO_TCP;
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
dwRetval = getaddrinfo(argv[1], NULL, &hints, &result);
if ( dwRetval != 0 ) {
printf("getaddrinfo failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
printf("getaddrinfo returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
printf("getaddrinfo response %d\n", i++);
printf("\tFlags: 0x%x\n", ptr->ai_flags);
printf("\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
printf("Unspecified\n");
break;
case AF_INET:
printf("AF_INET (IPv4)\n");
break;
case AF_INET6:
printf("AF_INET6 (IPv6)\n");
break;
case AF_NETBIOS:
printf("AF_NETBIOS (NetBIOS)\n");
break;
default:
printf("Other %ld\n", ptr->ai_family);
break;
}
printf("\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
printf("Unspecified\n");
break;
case SOCK_STREAM:
printf("SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
printf("SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
printf("SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
printf("SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
printf("Other %ld\n", ptr->ai_socktype);
break;
}
printf("\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
printf("Unspecified\n");
break;
case IPPROTO_TCP:
printf("IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
printf("IPPROTO_UDP (UDP) \n");
break;
default:
printf("Other %ld\n", ptr->ai_protocol);
break;
}
printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
printf("\tCanonical name: %s\n", ptr->ai_canonname);
}
freeaddrinfo(result);
WSACleanup();
return 0;
}
Prise en charge de getaddrinfo sur Windows 2000 et versions antérieures
La fonction getaddrinfo a été ajoutée au Ws2_32.dll sur Windows XP et versions ultérieures. Pour exécuter une application qui utilise cette fonction sur des versions antérieures de Windows, vous devez inclure les fichiers Ws2tcpip.h et Wspiapi.h . Lorsque le fichier include Wspiapi.h est ajouté, la fonction getaddrinfo est définie sur la fonction inline WspiapiGetAddrInfo dans le fichier Wspiapi.h . Au moment de l’exécution, la fonction WspiapiGetAddrInfo est implémentée de telle sorte que si le Ws2_32.dll ou le Wship6.dll (le fichier contenant getaddrinfo dans IPv6 Technology Preview pour Windows 2000) n’inclut pas getaddrinfo, une version de getaddrinfo est implémentée inline en fonction du code dans le fichier d’en-tête Wspiapi.h. Ce code inline sera utilisé sur les plateformes Windows plus anciennes qui ne prennent pas en charge la fonction getaddrinfo en mode natif.Le protocole IPv6 est pris en charge sur Windows 2000 lorsque la préversion de la technologie IPv6 pour Windows 2000 est installée. Sinon, la prise en charge de getaddrinfo sur les versions de Windows antérieures à Windows XP est limitée à la gestion de la résolution de noms IPv4.
La fonction GetAddrInfoW est la version Unicode de getaddrinfo. La fonction GetAddrInfoW a été ajoutée au Ws2_32.dll dans Windows XP avec Service Pack 2 (SP2). La fonction GetAddrInfoW ne peut pas être utilisée sur les versions de Windows antérieures à Windows XP avec SP2.
Windows Phone 8 : Cette fonction est prise en charge pour les applications du Windows Phone Store sur Windows Phone 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP, Windows 8.1 [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 |