Structure ADDRINFOA (ws2def.h)
La structure addrinfo est utilisée par la fonction getaddrinfo pour contenir les informations d’adresse de l’hôte.
Syntaxe
typedef struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char *ai_canonname;
struct sockaddr *ai_addr;
struct addrinfo *ai_next;
} ADDRINFOA, *PADDRINFOA;
Membres
ai_flags
Type : int
Indicateurs qui indiquent les options utilisées dans la fonction getaddrinfo .
Les valeurs prises en charge pour le membre ai_flags sont définies dans le fichier d’en-tête Ws2def.h sur le SDK Windows pour Windows 7 et versions ultérieures. Ces valeurs sont définies dans le fichier d’en-tête Ws2tcpip.h sur le SDK Windows pour Windows Server 2008 et Windows Vista. Ces valeurs sont définies 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 valeurs prises en charge pour le membre ai_flags peuvent être une combinaison des options suivantes.
| Valeur | Signification |
|---|---|
|
L’adresse de socket sera utilisée dans un appel à la fonction de liaison . |
|
Le nom canonique est retourné dans le premier membre ai_canonname . |
|
Le paramètre nodename passé à la fonction getaddrinfo doit être une chaîne numérique. |
|
Si ce bit est défini, une requête est effectuée pour les adresses IPv6 et IPv4 avec AI_V4MAPPED.
Cette option est prise en charge sur Windows Vista et versions ultérieures. |
|
Getaddrinfo est résolu uniquement si une adresse globale est configurée. L’adresse de bouclage IPv6 et IPv4 n’est pas considérée comme une adresse globale valide.
Cette option est prise en charge sur Windows Vista et versions ultérieures. |
|
Si la demande getaddrinfo pour les 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.
Cette option est prise en charge sur Windows Vista et versions ultérieures. |
|
Les informations d’adresse peuvent provenir d’un fournisseur d’espaces de noms non faisant autorité.
Cette option est uniquement prise en charge sur Windows Vista et versions ultérieures pour l’espace de noms NS_EMAIL . |
|
Les informations d’adresse proviennent d’un canal sécurisé.
Cette option est uniquement prise en charge sur Windows Vista et versions ultérieures pour l’espace de noms NS_EMAIL . |
|
Les informations d’adresse sont destinées à un nom préféré pour un utilisateur.
Cette option est uniquement prise en charge sur Windows Vista et versions ultérieures pour l’espace de noms NS_EMAIL . |
|
Si un nom plat (étiquette unique) est spécifié, getaddrinfo retourne le nom de domaine complet que le nom a finalement résolu. Le nom de domaine complet est retourné dans le membre ai_canonname .
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. Cette option est prise en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures. |
|
Indique au fournisseur d’espace de noms que le nom d’hôte interrogé est utilisé dans un scénario de partage de fichiers. Le fournisseur d’espaces de noms peut ignorer cet indicateur.
Cette option est prise en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures. |
ai_family
Type : int
Famille d’adresses. Les valeurs possibles pour la famille d’adresses sont définies dans le fichier d’en-tête Winsock2.h .
Sur la SDK Windows publiée pour Windows Vista et versions ultérieures, la organization des fichiers d’en-tête a changé et les valeurs possibles pour la famille d’adresses sont définies dans le fichier d’en-tête Ws2def.h. Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.
Les valeurs actuellement prises en charge sont AF_INET ou AF_INET6, qui sont les formats de famille d’adresses Internet pour IPv4 et IPv6. D’autres options pour la famille d’adresses (AF_NETBIOS à utiliser avec NetBIOS, par exemple) sont prises en charge si un fournisseur de services Windows Sockets pour la famille d’adresses est installé. Notez que les valeurs de la famille d’adresses AF_ et des constantes de famille de protocole PF_ sont identiques (par exemple , AF_UNSPEC et PF_UNSPEC), de sorte que l’une ou l’autre constante peut être utilisée.
Le tableau suivant répertorie les valeurs communes pour la famille d’adresses, bien que de nombreuses autres valeurs soient possibles.
ai_socktype
Type : int
Type de socket. Les valeurs possibles pour le type de socket sont définies dans le fichier d’en-tête Winsock2.h .
Le tableau suivant répertorie les valeurs possibles pour le type de socket pris en charge pour Windows Sockets 2 :
| Valeur | Signification |
|---|---|
|
Fournit des flux d’octets séquencés, fiables, bidirectionnel et basés sur la connexion avec un mécanisme de transmission de données OOB. Utilise le protocole TCP (Transmission Control Protocol) pour la famille d’adresses Internet (AF_INET ou AF_INET6). Si le membre ai_family est AF_IRDA, SOCK_STREAM est le seul type de socket pris en charge. |
|
Prend en charge les datagrammes, qui sont des mémoires tampons sans connexion et peu fiables d’une longueur maximale fixe (généralement petite). Utilise le protocole UDP (User Datagram Protocol) pour la famille d’adresses Internet (AF_INET ou AF_INET6). |
|
Fournit un socket brut qui permet à une application de manipuler l’en-tête de protocole de couche supérieure suivant. Pour manipuler l’en-tête IPv4, l’option de socket IP_HDRINCL doit être définie sur le socket. Pour manipuler l’en-tête IPv6, l’option de socket IPV6_HDRINCL doit être définie sur le socket. |
|
Fournit un datagramme de message fiable. Un exemple de ce type est l’implémentation du protocole de multidiffusion PGM (Pragmatic General Multicast) dans Windows, souvent appelée programmation multidiffusion fiable. |
|
Fournit un paquet de pseudo-flux basé sur des datagrammes. |
Dans les sockets Windows 2, de nouveaux types de sockets ont été introduits. Une application peut découvrir dynamiquement les attributs de chaque protocole de transport disponible via la fonction WSAEnumProtocols . Ainsi, une application peut déterminer le type de socket et les options de protocole possibles pour une famille d’adresses et utiliser ces informations lors de la spécification de ce paramètre. Les définitions de type de socket dans les fichiers d’en-tête Winsock2.h et Ws2def.h seront régulièrement mises à jour à mesure que de nouveaux types de sockets, familles d’adresses et protocoles seront définis.
Dans les sockets Windows 1.1, les seuls types de sockets possibles sont SOCK_DATAGRAM et SOCK_STREAM.
ai_protocol
Type : int
Type de protocole. Les options possibles sont spécifiques à la famille d’adresses et au type de socket spécifiés. Les valeurs possibles pour les ai_protocol sont définies dans les fichiers d’en-tête Winsock2.h et Wsrm.h .
Sur le SDK Windows publié pour Windows Vista et versions ultérieures, le organization des fichiers d’en-tête a changé et ce membre peut être l’une des valeurs du type d’énumération IPPROTO défini dans le fichier d’en-tête Ws2def.h. Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.
Si la valeur 0 est spécifiée pour ai_protocol, l’appelant ne souhaite pas spécifier de protocole et le fournisseur de services choisit le ai_protocol à utiliser. Pour les protocoles autres que IPv4 et IPv6, définissez ai_protocol sur zéro.
Le tableau suivant répertorie les valeurs courantes pour le membre ai_protocol bien que de nombreuses autres valeurs soient possibles.
Si le membre ai_family est AF_IRDA, le ai_protocol doit être 0.
ai_addrlen
Type : size_t
Longueur, en octets, de la mémoire tampon pointée par le membre ai_addr .
ai_canonname
Type : char*
Nom canonique de l’hôte.
ai_addr
Type : struct sockaddr*
Pointeur vers une structure de sockaddr . Le membre ai_addr dans chaque structure addrinfo retournée pointe vers une structure d’adresse de socket remplie. La longueur, en octets, de chaque structure addrinfo retournée est spécifiée dans le membre ai_addrlen .
ai_next
Type : struct addrinfo*
Pointeur vers la structure suivante dans une liste liée. Ce paramètre a la valeur NULL dans la dernière structure addrinfo d’une liste liée.
Remarques
La structure addrinfo est utilisée par la fonction getaddrinfo ANSI pour contenir les informations d’adresse de l’hôte.
La structure addrinfoW est la version de cette structure utilisée par la fonction Unicode GetAddrInfoW .
Les macros du fichier d’en-tête Ws2tcpip.h définissent une structure ADDRINFOT et un nom de fonction à cas mixte de GetAddrInfo. La fonction GetAddrInfo doit être appelée avec les paramètres nodename et servname d’un pointeur de type TCHAR et les paramètres d’indicateurs et de rés d’un pointeur de type ADDRINFOT. Lorsque UNICODE ou _UNICODE n’est pas défini, ADDRINFOT est défini sur la structure addrinfo et GetAddrInfo est défini sur getaddrinfo, la version ANSI de cette fonction. Quand UNICODE ou _UNICODE est défini, ADDRINFOT est défini sur la structure addrinfoW et GetAddrInfo est défini sur GetAddrInfoW, la version Unicode de cette fonction.
En cas d’appel réussi à getaddrinfo, une liste liée de structures addrinfo est retournée dans le paramètre res passé à la fonction getaddrinfo . 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 socket ou WSASocket . En outre, le membre ai_addr dans chaque structure addrinfo retournée pointe vers une structure d’adresse de socket renseignée, dont la longueur est spécifiée dans son ai_addrlen membre.
Prise en charge de getaddrinfo et du struct addrinfo sur les versions antérieures de Windows
La fonction getaddrinfo qui utilise la structure addrinfo a été ajoutée au Ws2_32.dll sur Windows XP et versions ultérieures. La structure addrinfo est définie dans le fichier d’en-tête Ws2tcpip.h inclus avec le KIT de développement logiciel (SDK) de plateforme publié pour Windows XP et versions ultérieures, et les SDK Windows publiés pour Windows Vista et versions ultérieures.Pour exécuter une application qui utilise la fonction getaddrinfo et la structure addrinfo sur des versions antérieures de Windows (Windows 2000), 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 qui utilise la structure addrinfoW est la version Unicode de la fonction getaddrinfo et la structure addrinfo associée. La fonction GetAddrInfoW a été ajoutée au Ws2_32.dll dans Windows XP avec Service Pack 2 (SP2). La fonction GetAddrInfoW et la structure addrinfoW ne peuvent pas être utilisées sur les versions de Windows antérieures à Windows XP avec SP2.
Exemples
L’exemple de code suivant montre l’utilisation de la structure addrinfo .
#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(" 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;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| En-tête | ws2def.h |