getnameinfo, fonction (ws2tcpip.h)

Article
08/28/2023

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

Syntaxe

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

Paramètres

[in] pSockaddr

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

[in] SockaddrLength

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

[out] pNodeBuffer

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

[in] NodeBufferSize

Longueur, en octets, de la mémoire tampon pointée vers le paramètre hôte . L’appelant doit fournir une mémoire tampon suffisamment grande pour contenir le nom d’hôte, y compris le caractère NULL de fin.

[out] pServiceBuffer

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

[in] ServiceBufferSize

Longueur, en octets, de la mémoire tampon pointée vers le paramètre serv . L’appelant doit fournir une mémoire tampon suffisamment grande pour contenir le nom du service, y compris le caractère NULL de fin.

[in] Flags

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

Valeur retournée

En cas de réussite, getnameinfo 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 getnameinfo correspondent également à l’ensemble d’erreurs décrites par les recommandations de l’Internet Engineering Task Force (IETF). Le tableau suivant répertorie 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 getnameinfo . Cette erreur est retournée si un nom d’hôte a été demandé mais que le paramètre hostlen était égal à zéro ou si un nom de service a été demandé, mais que le paramètre servlen était égal à zéro.
EAI_FAIL	WSANO_RECOVERY	Un échec irrécupérable dans 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 sa 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 sa ou aucun nom de service correspondant au numéro de port n’a été trouvé. NI_NAMEREQD est défini et le nom d’hôte ne peut pas être localisé, ou les paramètres host et serv étaient NULL.

Utilisez la fonction gai_strerror pour imprimer les messages d’erreur en fonction des codes EAI retournés par la fonction getnameinfo . La fonction gai_strerror est fournie pour la conformité aux recommandations de l’IETF, mais elle n’est pas thread safe. Par conséquent, l’utilisation de fonctions de sockets Windows 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 sa a la valeur NULL ou si le paramètre salen est inférieur à la longueur requise pour la taille de sockaddr_in structure pour IPv4 ou la structure sockaddr_in6 pour IPv6.

Remarques

La fonction getnameinfo est la version ANSI d’une fonction qui fournit une résolution de noms indépendante du protocole. La fonction getnameinfo 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 déterminer le nom du service pour un numéro de port. La fonction getnameinfo peut également être utilisée pour convertir une adresse IP ou un numéro de port dans une structure sockaddr en chaîne ANSI. Cette fonction peut également être utilisée pour déterminer l’adresse IP d’un nom d’hôte.

Un autre nom qui peut être utilisé pour la fonction getnameinfo est GetNameInfoA. Les macros du fichier d’en-tête Ws2tcpip.h définissent GetNameInfoA sur getnameinfo.

La version Unicode de cette fonction disponible sur Windows XP avec Service Pack 2 (SP2) et versions ultérieures est GetNameInfoW.

Les macros du 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 SP2 et versions ultérieures >(_WIN32_WINNT = 0x0502). Cette fonction GetNameInfo doit être appelée avec les paramètres host et serv d’un pointeur de type TCHAR. 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 host et serv d’un pointeur de type char. Quand UNICODE ou _UNICODE est défini, GetNameInfo est défini sur la version Unicode et GetNameInfoW 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 host et serv , 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 .

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Le paramètre flags peut être utilisé pour personnaliser le traitement de la fonction getnameinfo . 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 DNS génère une erreur.

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

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 résout pas en un service connu, la fonction getnameinfo retourne la forme numérique de l’adresse de service (le 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/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 vers le paramètre sa ne résout pas en service connu, la fonction getnameinfo é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 le service UDP et TCP.

Note La possibilité d’effectuer des recherches DNS inversées à l’aide de la fonction getnameinfo est pratique, mais ces recherches sont considérées comme par nature peu fiables et ne doivent être utilisées qu’à titre d’indication.

Note La fonction getnameinfo ne peut pas être utilisée pour résoudre les noms d’alias.

Exemple de code

L’exemple de code suivant montre comment utiliser la fonction getnameinfo .

#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 = {0};
    int iResult = 0;

    DWORD dwRetval;

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

    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s IPv4 address\n", argv[0]);
        printf("  to return hostname\n");
        printf("       %s 127.0.0.1\n", argv[0]);
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("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 getnameinfo
    dwRetval = getnameinfo((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        printf("getnameinfo failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        printf("getnameinfo returned hostname = %s\n", hostname);
        return 0;
    }
}

Prise en charge de getnameinfo sur les versions antérieures de Windows

La fonction getnameinfo a été ajoutée au Ws2_32.dll sur Windows XP et versions ultérieures. Si vous souhaitez exécuter une application à l’aide de cette fonction sur des versions antérieures de Windows (Windows 2000, Windows NT et Windows Me/98/95), vous devez inclure le fichier Ws2tcpip.h et également inclure le fichier Wspiapi.h . Lorsque le fichier include Wspiapi.h est ajouté, la fonction getnameinfo est définie sur la fonction inline WspiapiGetNameInfo dans le fichier Wspiapi.h . Au moment de l’exécution, la fonction WspiapiGetNameInfo est implémentée de telle sorte que si le Ws2_32.dll ou le Wship6.dll (le fichier contenant getnameinfo dans IPv6 Technology Preview pour Windows 2000) n’inclut pas getnameinfo, une version de getnameinfo 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 getnameinfo 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 getnameinfo sur les versions de Windows antérieures à Windows XP est limitée à la gestion de la résolution de noms IPv4.

La fonction GetNameInfoW est la version Unicode de getnameinfo. La fonction GetNameInfoW a été ajoutée au Ws2_32.dll dans Windows XP avec SP2. La fonction GetNameInfoW ne peut pas être utilisée sur les versions de Windows antérieures à Windows XP avec SP2.

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.

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