getnameinfo, fonction (ws2tcpip.h)
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 |
|---|---|
| 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.
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 |
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