Función GetHostNameW (winsock2.h)

  • Artículo

La función GetHostNameW recupera el nombre de host estándar del equipo local como una cadena Unicode.

Sintaxis

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

Parámetros

[out] name

Puntero a un búfer que recibe el nombre de host local como una cadena Unicode terminada en null.

[in] namelen

Longitud, en caracteres anchos, del búfer al que apunta el parámetro name .

Valor devuelto

Si no se produce ningún error, GetHostNameW devuelve cero. De lo contrario, devuelve SOCKET_ERROR y se puede recuperar un código de error específico mediante una llamada a WSAGetLastError.

Código de error Significado
WSAEFAULT
 El parámetro name es un puntero NULL o no es una parte válida del espacio de direcciones del usuario. Este error también se devuelve si el tamaño del búfer especificado por el parámetro namelen es demasiado pequeño para contener el nombre de host completo.
WSANOTINITIALISED
 Debe producirse una llamada WSAStartup correcta antes de usar esta función.
WSAENETDOWN
 Error en el subsistema de red.

Comentarios

La función GetHostNameW devuelve el nombre del host local en el búfer especificado por el parámetro name en Unicode (UTF-16). El nombre de host se devuelve como una cadena Unicode terminada en null. La forma del nombre de host depende del proveedor de Windows Sockets, puede ser un nombre de host simple o puede ser un nombre de dominio completo. Sin embargo, se garantiza que GetAddrInfoW analizará correctamente el nombre devuelto.

Con el crecimiento de Internet, existe una creciente necesidad de identificar los nombres de host de Internet para otros idiomas que no están representados por el juego de caracteres ASCII. Los identificadores que facilitan esta necesidad y permiten representar caracteres no ASCII (Unicode) como cadenas de caracteres ASCII especiales (Punycode) se conocen como nombres de dominio internacionalizados (IDN). Un mecanismo denominado Internacionalización de nombres de dominio en aplicaciones (IDNA) se usa para controlar los IDN de forma estándar. La función GetHostNameW no convierte el nombre de host local entre Punycode y Unicode. La función GetAddrInfoW proporciona compatibilidad con el análisis de nombres de dominio internacionalizados (IDN) y realiza la codificación y conversión punycode/IDN.

Si la función GetHostNameW se usa en un recurso de clúster en Windows Server 2012 y se define la variable de entorno CLUSTER_NETWORK_NAME , el valor de esta variable de entorno invalida el nombre de host real y se devuelve. En un recurso de clúster, la variable de entorno CLUSTER_NETWORK_NAME contiene el nombre del clúster.

La función GetHostNameW consulta proveedores de espacios de nombres para determinar el nombre de host local mediante el GUID de SVCID_HOSTNAME definido en el archivo de encabezado Svgguid.h . Si no responde ningún proveedor de espacios de nombres, la función GetHostNameW devuelve el nombre NetBIOS del equipo local en Unicode.

La longitud máxima, en caracteres anchos, de la cadena devuelta en el búfer al que apunta el parámetro name depende del proveedor de espacios de nombres, pero esta cadena debe tener 256 caracteres anchos o menos. Por lo tanto, si se pasa un búfer de 256 caracteres anchos en el parámetro name y el parámetro namelen se establece en 256, el tamaño del búfer siempre será adecuado.

Nota Si no se ha configurado ningún nombre de host local, GetHostNameW debe realizarse correctamente y devolver un nombre de host de token que GetAddrInfoW pueda resolver.
 

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Requisitos

   
Cliente mínimo compatible Windows 8.1, Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado winsock2.h
Library Ws2_32.lib
Archivo DLL Ws2_32.dll

Consulte también

GetAddrInfoW

Funciones winsock

Referencia de Winsock

gethostname