Structure ADDRINFOW (ws2def.h)

La structure addrinfoW est utilisée par la fonction GetAddrInfoW pour stocker les informations d’adresse de l’hôte.

Syntaxe

typedef struct addrinfoW {
  int              ai_flags;
  int              ai_family;
  int              ai_socktype;
  int              ai_protocol;
  size_t           ai_addrlen;
  PWSTR            ai_canonname;
  struct sockaddr  *ai_addr;
  struct addrinfoW *ai_next;
} ADDRINFOW, *PADDRINFOW;

Membres

ai_flags

Type : int

Indicateurs qui indiquent les options utilisées dans la fonction GetAddrInfoW .

Les valeurs prises en charge pour le membre ai_flags sont définies dans le fichier d’en-tête Winsock2.h et peuvent être une combinaison des options répertoriées dans le tableau suivant.

Valeur Signification
AI_PASSIVE
0x01
L’adresse de socket sera utilisée dans un appel à la fonction de liaison .
AI_CANONNAME
0x02
Le nom canonique est retourné dans le premier membre ai_canonname .
AI_NUMERICHOST
0x04
Le paramètre nodename passé à la fonction GetAddrInfoW doit être une chaîne numérique.
AI_ALL
0x0100
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.

AI_ADDRCONFIG
0x0400
GetAddrInfoW 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.
AI_V4MAPPED
0x0800
Si la demande GetAddrInfoW 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.

AI_NON_AUTHORITATIVE
0x04000
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 .

AI_SECURE
0x08000
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 .

AI_RETURN_PREFERRED_NAMES
0x010000
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 .

AI_FQDN
0x00020000
Si 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 .

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.

Cette option est prise en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.

AI_FILESERVER
0x00040000
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_DISABLE_IDN_ENCODING
0x00080000
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 GetAddrInfoW .

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 d’en-tête 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 suivant répertorie les valeurs communes pour la famille d’adresses, bien que de nombreuses autres valeurs soient possibles.

Valeur Signification
AF_UNSPEC
0
La famille d’adresses n’est pas spécifiée.
AF_INET
2
Famille d’adresses IPv4 (Internet Protocol version 4).
AF_NETBIOS
17
Famille d’adresses NetBIOS. Cette famille d’adresses est uniquement prise en charge si un fournisseur Windows Sockets pour NetBIOS est installé.
AF_INET6
23
Famille d’adresses IPv6 (Internet Protocol version 6).
AF_IRDA
26
L’IrDA (Infrared Data Association) adresse la famille. Cette famille d’adresses est prise en charge uniquement si un port infrarouge et un pilote sont installés sur l’ordinateur.
AF_BTH
32
Famille d’adresses Bluetooth. Cette famille d’adresses est uniquement prise en charge si une carte Bluetooth est installée sur Windows Server 2003 ou version ultérieure.

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
SOCK_STREAM
1
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.
SOCK_DGRAM
2
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).
SOCK_RAW
3
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.
SOCK_RDM
4
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.
SOCK_SEQPACKET
5
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.

Valeur Signification
IPPROTO_TCP
6
Protocole TCP (Transmission Control Protocol). Il s’agit d’une valeur possible lorsque le membre ai_family est AF_INET ou AF_INET6 et que le membre ai_socktype est SOCK_STREAM.
IPPROTO_UDP
17
Protocole UDP (User Datagram Protocol). Il s’agit d’une valeur possible lorsque le membre ai_family est AF_INET ou AF_INET6 et que le paramètre type est SOCK_DGRAM.
IPPROTO_RM
113
Protocole PGM pour une multidiffusion fiable. Il s’agit d’une valeur possible lorsque le membre ai_family est AF_INET et que le membre ai_socktype est SOCK_RDM. Sur la SDK Windows publiée pour Windows Vista et versions ultérieures, cette valeur est également appelée IPPROTO_PGM.
 

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 : PWSTR

Nom canonique de l’hôte.

ai_addr

Type : struct sockaddr*

Pointeur vers une structure sockaddr . Le ai_addr membre dans chaque structure ADDRINFOW retournée pointe vers une structure d’adresse de socket remplie. La longueur, en octets, de chaque structure ADDRINFOW retournée est spécifiée dans le membre ai_addrlen .

ai_next

Type : struct addrinfoW*

Pointeur vers la structure suivante dans une liste liée. Ce paramètre est défini sur NULL dans la dernière structure addrinfoW d’une liste liée.

Remarques

La structure addrinfoW est utilisée par la fonction Unicode GetAddrInfoW pour contenir les informations d’adresse de l’hôte.

La structure addrinfo est la version ANSI de cette structure utilisée par la fonction ANSI getaddrinfo .

Les macros du fichier d’en-tête Ws2tcpip.h définissent une structure ADDRINFOT et un nom de fonction à casse 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 hints et res d’un pointeur de type ADDRINFOT. Lorsque unicode ou _UNICODE est défini, ADDRINFOT est défini pour la structure addrinfoW et GetAddrInfo est défini sur GetAddrInfoW, la version Unicode de cette fonction. Lorsque unicode ou _UNICODE n’est pas défini, ADDRINFOT est défini pour la structure addrinfo et GetAddrInfo est défini sur getaddrinfo, la version ANSI de cette fonction.

En cas d’appel réussi à GetAddrInfoW, une liste liée de structures ADDRINFOW est retournée dans le paramètre ppResult passé à la fonction GetAddrInfoW . 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.

Exemples

L’exemple de code suivant montre comment utiliser la structure addrinfoW .

#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;

    ADDRINFOW *result = NULL;
    ADDRINFOW *ptr = NULL;
    ADDRINFOW hints;

    DWORD dwRetval = 0;
    int i = 1;

    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 GetAddrInfoW with following parameters:\n");
    wprintf(L"\tName = %ws\n", argv[1]);
    wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);

//--------------------------------
// Call GetAddrInfoW(). If the call succeeds,
// the aiList variable will hold a linked list
// of addrinfo structures containing response
// information about the host
    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");
            // 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);
    }

    FreeAddrInfo(result);
    WSACleanup();

    return 0;
}

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista, Windows XP avec SP2 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
En-tête ws2def.h (include Windows Server 2012, Windows 7 Windows Server 2008 R2)

Voir aussi

GetAddrInfoEx

GetAddrInfoW

WSAEnumProtocols

addrinfo

addrinfoex

addrinfoex2

getaddrinfo

sockaddr