GetNameInfoW, fonction (ws2tcpip.h)

Article
08/28/2023

La fonction GetNameInfoW fournit une résolution de noms indépendante du protocole à partir d’une adresse vers un nom d’hôte Unicode et d’un numéro de port au nom du service Unicode.

Syntaxe

INT WSAAPI GetNameInfoW(
  [in]  const SOCKADDR *pSockaddr,
  [in]  socklen_t      SockaddrLength,
  [out] PWCHAR         pNodeBuffer,
  [in]  DWORD          NodeBufferSize,
  [out] PWCHAR         pServiceBuffer,
  [in]  DWORD          ServiceBufferSize,
  [in]  INT            Flags
);

Paramètres

[in] pSockaddr

Pointeur vers une structure d’adresse de socket contenant l’adresse IP et le numéro de port du socket. Pour IPv4, le paramètre pSockaddr pointe vers une structure sockaddr_in . Pour IPv6, le paramètre pSockaddr pointe vers une structure sockaddr_in6 .

[in] SockaddrLength

Longueur, en octets, de la structure pointée vers le paramètre pSockaddr .

[out] pNodeBuffer

Pointeur vers une chaîne Unicode contenant le nom d’hôte. En cas de réussite, un pointeur vers le nom d’hôte Unicode est retourné en tant que nom de domaine complet (FQDN) par défaut. Si le paramètre pNodeBuffer a la valeur NULL, cela indique que l’appelant ne souhaite pas recevoir de chaîne de nom d’hôte.

[in] NodeBufferSize

Nombre de caractères WCHAR dans la mémoire tampon vers laquelle pointe le paramètre pNodeBuffer . L’appelant doit fournir une mémoire tampon suffisamment grande pour contenir le nom d’hôte Unicode, y compris le caractère NULL de fin.

[out] pServiceBuffer

Pointeur vers une chaîne Unicode pour contenir le nom du service. En cas de réussite, un pointeur est retourné à une chaîne Unicode représentant le nom de service associé au numéro de port. Si le paramètre pServiceBuffer a la valeur NULL, cela indique que l’appelant ne souhaite pas recevoir de chaîne de nom de service.

[in] ServiceBufferSize

Nombre de caractères WCHAR dans la mémoire tampon vers laquelle pointe le paramètre pServiceBuffer . L’appelant doit fournir une mémoire tampon suffisamment grande pour contenir le nom du service Unicode, y compris le caractère NULL de fin.

[in] Flags

Valeur utilisée pour personnaliser le traitement de la fonction GetNameInfoW . Consultez la section Notes.

Valeur retournée

En cas de réussite, GetNameInfoW retourne zéro. Toute valeur de retour différente de zéro indique un échec et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Les codes d’erreur non nuls retournés par la fonction GetNameInfoW correspondent également au jeu d’erreurs décrit par les recommandations de l’Internet Engineering Task Force (IETF). Le tableau suivant présente 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	Un ou plusieurs paramètres non valides ont été passés à la fonction GetNameInfoW . Cette erreur est retournée si un nom d’hôte a été demandé, mais que le paramètre NodeBufferSize était égal à zéro ou si un nom de service a été demandé, mais que le paramètre ServiceBufferSize était égal à zéro.
EAI_FAIL	WSANO_RECOVERY	Un échec non récupérable de la résolution de noms s’est produit.
EAI_FAMILY	WSAEAFNOSUPPORT	Le sa_family membre de la structure d’adresse de socket pointé vers le paramètre pSockaddr 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	Un nom de service a été demandé, mais aucun numéro de port n’a été trouvé dans la structure pointée par le paramètre pSockaddr ou aucun nom de service correspondant au numéro de port n’a été trouvé. NI_NAMEREQD est défini et le nom de l’hôte ne peut pas être localisé, ou les paramètres pNodeBuffer et pServiceBuffer étaient NULL.

Vous pouvez utiliser la fonction gai_strerror pour imprimer les messages d’erreur en fonction des codes EAI retournés par la fonction GetNameInfoW . 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.

En outre, les codes d’erreur suivants peuvent être retournés.

Code d'erreur	Signification
WSAEFAULT	Cette erreur est retournée si le paramètre pSockaddr a la valeur NULL ou si le paramètre SockaddrLength est inférieur à la longueur nécessaire pour la taille de sockaddr_in structure pour IPv4 ou la structure sockaddr_in6 pour IPv6.

Remarques

La fonction GetNameInfoW est la version Unicode d’une fonction qui fournit une résolution de noms indépendante du protocole. La fonction GetNameInfoW est utilisée pour traduire le contenu d’une structure d’adresse de socket en nom de nœud et/ou en nom de service.

Pour 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 ou par d’autres mécanismes de nommage. Cette fonction peut être utilisée pour déterminer le nom d’hôte d’une adresse IPv4 ou IPv6, une recherche DNS inversée ou le nom du service pour un numéro de port. La fonction GetNameInfoW peut également être utilisée pour convertir une adresse IP ou un numéro de port dans une structure SOCKADDR en chaîne Unicode. Cette fonction peut également être utilisée pour déterminer l’adresse IP d’un nom d’hôte.

La version ANSI de cette fonction est getnameinfo.

Les macros dans le fichier d’en-tête Winsock définissent un nom de fonction à casse mixte de GetNameInfo qui peut être utilisé lorsque l’application est ciblée pour Windows XP avec Service Pack 2 (SP2) et versions ultérieures (_WIN32_WINNT >= 0x0502). Cette fonction GetNameInfo doit être appelée avec les paramètres pNodeBuffer et pServiceBuffer d’un pointeur de type TCHAR. Lorsque unicode ou _UNICODE est défini, GetNameInfo est défini sur la version Unicode et GetNameInfoW est appelé avec les paramètres host et serv d’un pointeur de type char. Lorsque unicode ou _UNICODE n’est pas défini, GetNameInfo est défini sur la version ANSI et getnameinfo est appelé avec les paramètres pNodeBuffer et pServiceBuffer d’un pointeur de type PWCHAR.

Pour simplifier la détermination des exigences de mémoire tampon pour les paramètres pNodeBuffer et pServiceBuffer , les valeurs suivantes pour la longueur maximale du nom d’hôte et le nom de service maximal sont définies dans le fichier d’en-tête Ws2tcpip.h :

#include <windows.h>

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Le paramètre Flags peut être utilisé pour personnaliser le traitement de la fonction GetNameInfoW . Les indicateurs suivants sont disponibles :

NI_NOFQDN
NI_NUMERICHOST
NI_NAMEREQD
NI_NUMERICSERV
NI_DGRAM

Lorsque l’indicateur NI_NAMEREQD est défini, un nom d’hôte qui ne peut pas être résolu par le DNS génère une erreur.

Si vous définissez l’indicateur NI_NOFQDN , les hôtes locaux n’ont que leur nom unique relatif (RDN) retourné dans le paramètre pNodeBuffer .

La définition de l’indicateur NI_NUMERICHOST renvoie la forme numérique du nom d’hôte au lieu de son nom. La forme numérique du nom d’hôte est également retournée si le nom d’hôte ne peut pas être résolu par DNS.

La définition de l’indicateur NI_NUMERICSERV renvoie le numéro de port du service au lieu de son nom. En outre, si un nom d’hôte est introuvable pour une adresse IP (127.0.0.2, par exemple), le nom d’hôte est retourné en tant qu’adresse IP.

Sur Windows Vista et versions ultérieures, si NI_NUMERICSERV n’est pas spécifié dans le paramètre flags et que le numéro de port contenu dans la structure sockaddr pointée par le paramètre sa ne se résout pas en un service bien connu, la fonction GetNameInfoW renvoie la forme numérique de l’adresse de service (numéro de port) sous forme de chaîne numérique. Lorsque NI_NUMERICSERV est spécifié, le numéro de port est retourné sous forme de chaîne numérique. Ce comportement est spécifié dans la section 6.2 de la RFC 3493. Pour plus d’informations, consultez www.ietf.org/rfc/rfc3493.txt

Sur Windows Server 2003 et versions antérieures, si NI_NUMERICSERV n’est pas spécifié dans le paramètre flags et que le numéro de port contenu dans la structure sockaddr pointée par le paramètre sa ne se résout pas en service connu, la fonction GetNameInfoW échoue. Lorsque NI_NUMERICSERV est spécifié, le numéro de port est retourné sous forme de chaîne numérique.

La définition de l’indicateur NI_DGRAM indique que le service est un service de datagramme. Cet indicateur est nécessaire pour les quelques services qui fournissent des numéros de port différents pour les services UDP et TCP.

Note La possibilité d’effectuer des recherches DNS inversées à l’aide de la fonction GetNameInfoW est pratique, mais ces recherches sont considérées comme intrinsèquement peu fiables et ne doivent être utilisées qu’en tant qu’indicateur.

RemarqueGetNameInfoW ne peut pas être utilisé pour résoudre les noms d’alias.

Windows Phone 8 : cette fonction est prise en charge pour les applications 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.

Exemple de code

L’exemple suivant illustre l’utilisation de la fonction GetNameInfoW .

#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")

int __cdecl main(int argc, char **argv)
{

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

    DWORD dwRetval;

    struct sockaddr_in saGNI;
    WCHAR hostname[NI_MAXHOST];
    WCHAR servInfo[NI_MAXSERV];
    u_short port = 27015;

    // Validate the parameters
    if (argc != 2) {
        wprintf(L"usage: %s IPv4 address\n", argv[0]);
        wprintf(L"  to return hostname\n");
        wprintf(L"       %s 127.0.0.1\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;
    }
    //-----------------------------------------
    // Set up sockaddr_in structure which is passed
    // to the getnameinfo function
    saGNI.sin_family = AF_INET;
    saGNI.sin_addr.s_addr = inet_addr(argv[1]);
    saGNI.sin_port = htons(port);

    //-----------------------------------------
    // Call GetNameInfoW
    dwRetval = GetNameInfoW((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        wprintf(L"GetNameInfoW failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        wprintf(L"GetNameInfoW returned hostname = %ws\n", hostname);
        return 0;
    }
}

Notes

L’en-tête ws2tcpip.h définit GetNameInfo comme un 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. Le mélange 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.

Configuration requise

Condition requise	Valeur
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