GetHostNameW, fonction (winsock2.h)

La fonction GetHostNameW récupère le nom d’hôte standard de l’ordinateur local sous la forme d’une chaîne Unicode.

Syntaxe

int WSAAPI GetHostNameW(
  [out] PWSTR name,
  [in]  int   namelen
);

Paramètres

[out] name

Pointeur vers une mémoire tampon qui reçoit le nom d’hôte local sous la forme d’une chaîne Unicode terminée par null.

[in] namelen

Longueur, en caractères larges, de la mémoire tampon pointée vers le paramètre name .

Valeur retournée

Si aucune erreur ne se produit, GetHostNameW retourne zéro. Sinon, il retourne SOCKET_ERROR et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur	Signification
WSAEFAULT	Le paramètre name est un pointeur NULL ou n’est pas une partie valide de l’espace d’adressage utilisateur. Cette erreur est également retournée si la taille de mémoire tampon spécifiée par le paramètre namelen est trop petite pour contenir le nom d’hôte complet.
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSAENETDOWN	Le sous-système réseau a échoué.

Remarques

La fonction GetHostNameW retourne le nom de l’hôte local dans la mémoire tampon spécifiée par le paramètre name dans Unicode (UTF-16). Le nom d’hôte est retourné sous la forme d’une chaîne Unicode terminée par null. La forme du nom d’hôte dépend du fournisseur Windows Sockets: il peut s’agir d’un nom d’hôte simple ou d’un nom de domaine complet. Toutefois, il est garanti que le nom retourné sera correctement analysé par GetAddrInfoW.

Avec la croissance d’Internet, il est de plus en plus nécessaire d’identifier les noms d’hôtes Internet pour d’autres langues qui ne sont pas représentées par le jeu de caractères ASCII. Les identificateurs qui facilitent ce besoin et qui permettent aux caractères non ASCII (Unicode) d’être représentés en tant que chaînes de caractères ASCII spéciales (Punycode) sont appelés noms de domaine internationalisés (IDN). Un mécanisme appelé Internationalizing Domain Names in Applications (IDNA) est utilisé pour gérer les IDN de manière standard. La fonction GetHostNameW ne convertit pas le nom d’hôte local entre Punycode et Unicode. La fonction GetAddrInfoW prend en charge l’analyse idn (Internationalized Domain Name) et effectue l’encodage et la conversion Punycode/IDN.

Si la fonction GetHostNameW est utilisée sur une ressource de cluster sur Windows Server 2012 et que la variable d’environnement CLUSTER_NETWORK_NAME est définie, la valeur de cette variable d’environnement remplace le nom d’hôte réel et est retournée. Sur une ressource de cluster, la variable d’environnement CLUSTER_NETWORK_NAME contient le nom du cluster.

La fonction GetHostNameW interroge les fournisseurs d’espaces de noms pour déterminer le nom d’hôte local à l’aide du GUID SVCID_HOSTNAME défini dans le fichier d’en-tête Svgguid.h . Si aucun fournisseur d’espace de noms ne répond, la fonction GetHostNameW retourne le nom NetBIOS de l’ordinateur local dans Unicode.

La longueur maximale, en caractères larges, de la chaîne renvoyée dans la mémoire tampon pointée par le paramètre name dépend du fournisseur d’espace de noms, mais cette chaîne doit être de 256 caractères larges ou moins. Ainsi, si une mémoire tampon de 256 caractères de large est passée dans le paramètre name et que le paramètre namelen est défini sur 256, la taille de la mémoire tampon sera toujours suffisante.

Note Si aucun nom d’hôte local n’a été configuré, GetHostNameW doit réussir et retourner un nom d’hôte de jeton que GetAddrInfoW peut résoudre.

 

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

Client minimal pris en charge	Windows 8.1, Windows 8 [applications de bureau | Applications UWP]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau | Applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll

Voir aussi

GetAddrInfoW

Fonctions Winsock

Informations de référence sur Winsock

gethostname