Structure ADDRINFOEXA (ws2def.h)
La structure addrinfoex est utilisée par la fonction GetAddrInfoEx pour contenir les informations d’adresse de l’hôte.
Syntaxe
typedef struct addrinfoexA {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char *ai_canonname;
struct sockaddr *ai_addr;
void *ai_blob;
size_t ai_bloblen;
LPGUID ai_provider;
struct addrinfoexA *ai_next;
} ADDRINFOEXA, *PADDRINFOEXA, *LPADDRINFOEXA;
Membres
ai_flags
Type : int
Indicateurs qui indiquent les options utilisées dans la fonction GetAddrInfoEx .
Les valeurs prises en charge pour le membre ai_flags sont définies dans le fichier Include Winsock2.h et 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 .
Lorsque les bits AI_CANONNAME et AI_FQDN sont définis, une structure addrinfoex2 est retournée et non la structure addrinfoex . |
|
Le paramètre nodename passé à la fonction GetAddrInfoEx 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. |
|
L’objet GetAddrInfoEx 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 uniquement prise en charge sur Windows Vista et versions ultérieures. |
|
Si la demande GetAddrInfoEx pour une adresse 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 proviennent de résultats qui ne font pas autorité.
Lorsque cette option est définie dans le paramètre pHints de GetAddrInfoEx, le fournisseur d’espaces de noms NS_EMAIL retourne des résultats faisant autorité et non faisant autorité. Si cette option n’est pas définie, seuls les résultats faisant autorité sont retournés. Dans le paramètre ppResults retourné par GetAddrInfoEx, cet indicateur est défini dans le ai_flags membre de la structure addrinfoex pour les résultats qui ne font pas 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é. 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.
Lorsque cette option est définie dans le paramètre pHints de GetAddrInfoEx, le fournisseur d’espaces de noms NS_EMAIL retourne uniquement les résultats obtenus avec une sécurité renforcée pour réduire l’usurpation possible. Dans le paramètre ppResults retourné par GetAddrInfoEx, cet indicateur est défini dans le ai_flags membre de la structure addrinfoex pour les résultats retournés avec une sécurité renforcée afin de réduire l’usurpation possible. 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 concernent les noms préférés pour la publication avec un espace de noms spécifique.
Lorsque cette option est définie dans le paramètre pHints de GetAddrInfoEx, aucun nom ne doit être fourni dans le paramètre pName et le NS_EMAIL fournisseur d’espaces de noms retourne les noms préférés pour publication. Dans le paramètre ppResults retourné par GetAddrInfoEx, cet indicateur est défini dans le ai_flags membre de la structure addrinfoex pour les résultats retournés pour les noms préférés pour la publication. Cette option est uniquement prise en charge sur Windows Vista et versions ultérieures pour l’espace de noms NS_EMAIL . |
|
Le nom de domaine complet est retourné dans le premier membre ai_canonicalname .
Lorsque cette option est définie dans le paramètre pHints de GetAddrInfoEx et qu’un nom plat (étiquette unique) est spécifié dans le paramètre pName , le nom de domaine complet dont le nom a finalement été résolu est retourné. Lorsque les bits AI_CANONNAME et AI_FQDN sont définis, une structure addrinfoex2 est retournée et non la structure addrinfoex . 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. |
|
Désactivez 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 GetAddrInfoEx .
Cette option est prise en charge sur Windows 8, Windows Server 2012 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 Include Winsock2.h .
Sur le SDK Windows publié 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 ci-dessous répertorie les valeurs courantes 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 Include 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 non fiables et sans connexion 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 général pragmatique (PGM) dans Windows, souvent appelée programmation de multidiffusion fiable. |
|
Fournit un paquet de pseudo-flux basé sur des datagrammes. |
Dans Windows Sockets 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 sont régulièrement mises à jour à mesure que de nouveaux types de sockets, familles d’adresses et protocoles sont définis.
Dans Windows Sockets 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 le ai_protocol sont définies dans winsock2.h et les fichiers d’en-tête Wsrm.h .
Sur le SDK Windows publié pour Windows Vista et versions ultérieures, la 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 communes 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 : PCTSTR
Nom canonique de l’hôte.
ai_addr
Type : struct sockaddr*
Pointeur vers une structure sockaddr . Le membre ai_addr dans chaque structure addrinfoex retournée pointe vers une structure d’adresse de socket remplie. La longueur, en octets, de chaque structure addrinfoex retournée est spécifiée dans le membre ai_addrlen .
ai_blob
Type : void*
Pointeur vers des données utilisées pour retourner des informations d’espace de noms spécifiques au fournisseur associées au nom au-delà d’une liste d’adresses. La longueur, en octets, de la mémoire tampon pointée par ai_blob doit être spécifiée dans le membre ai_bloblen .
ai_bloblen
Type : size_t
Longueur, en octets, du membre ai_blob .
ai_provider
Type : LPGUID
Pointeur vers le GUID d’un fournisseur d’espace de noms spécifique.
ai_next
Type : struct addrinfoex*
Pointeur vers la structure suivante dans une liste liée. Ce paramètre est défini sur NULL dans la dernière structure addrinfoex d’une liste liée.
Remarques
La structure addrinfoex est utilisée par la fonction GetAddrInfoEx pour contenir les informations d’adresse de l’hôte. La structure addrinfoex est une version améliorée des structures addrinfo et addrinfoW . Les membres de structure supplémentaires sont pour les données blob et le GUID pour le fournisseur d’espaces de noms. Les données d’objet blob sont utilisées pour retourner des informations d’espace de noms supplémentaires spécifiques au fournisseur associées à un nom. Le format des données dans le membre ai_blob est spécifique à un fournisseur d’espaces de noms particulier. Actuellement, les données blob sont utilisées par le fournisseur d’espace de noms NS_EMAIL pour fournir des informations supplémentaires.
La structure addrinfoex est une version améliorée de la structure addrinfo et addrinfoW utilisée avec la fonction GetAddrInfoEx . La fonction GetAddrInfoEx permet de spécifier le fournisseur d’espaces de noms pour résoudre la requête. 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.
Lorsque unicode ou _UNICODE est défini, addrinfoex est défini sur addrinfoexW, la version Unicode de cette structure. Les paramètres de chaîne sont définis sur le type de données PWSTR et la structure addrinfoexW est utilisée.
Lorsque unicode ou _UNICODE n’est pas défini, addrinfoex est défini sur addrinfoexA, la version ANSI de cette structure. Les paramètres de chaîne sont du type de données PCSTR et la structure addrinfoexA est utilisée.
Lors d’un appel réussi à GetAddrInfoEx, une liste liée de structures addrinfoex est retournée dans le paramètre ppResult passé à la fonction GetAddrInfoEx . 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.
Exemples
L’exemple suivant illustre l’utilisation de la structure addrinfoex .
#ifndef UNICODE
#define UNICODE
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#pragma comment(lib, "Ws2_32.lib")
int __cdecl wmain(int argc, wchar_t ** argv)
{
//--------------------------------
// Declare and initialize variables.
WSADATA wsaData;
int iResult;
ADDRINFOEX *result = NULL;
ADDRINFOEX *ptr = NULL;
ADDRINFOEX hints;
DWORD dwRetval = 0;
int i = 1;
DWORD dwNamespace = NS_DNS;
LPGUID lpNspid = NULL;
struct sockaddr_in *sockaddr_ipv4;
struct sockaddr_in6 *sockaddr_ipv6;
// LPSOCKADDR sockaddr_ip;
wchar_t ipstringbuffer[46];
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
wprintf(L" 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\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 GetAddrInfoW() function
memset(&hints, 0, sizeof (hints));
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
wprintf(L"Calling GetAddrInfoEx with following parameters:\n");
wprintf(L"\tName = %ws\n", argv[1]);
wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrInfoEx(). If the call succeeds,
// the aiList variable will hold a linked list
// of ADDRINFOEX structures containing response
// information about the host
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);
}
FreeAddrInfoEx(result);
WSACleanup();
return 0;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| En-tête | ws2def.h (include Windows Server 2012, Windows 7 Windows Server 2008 R2) |