GetNameInfoW, fonction (ws2tcpip.h)

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.

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.

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.

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

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

Configuration requise

Voir aussi

GetAddrInfoW

WSAGetLastError

Fonctions Winsock

Informations de référence sur Winsock

gai_strerror

getaddrinfo

getnameinfo

sockaddr