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.
| 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 |
|---|---|
| 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.
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 |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour