Función GetNameInfoW (ws2tcpip.h)
La función GetNameInfoW proporciona una resolución de nombres independiente del protocolo de una dirección a un nombre de host Unicode y de un número de puerto al nombre del servicio Unicode.
Sintaxis
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
);
Parámetros
[in] pSockaddr
Puntero a una estructura de direcciones de socket que contiene la dirección IP y el número de puerto del socket. Para IPv4, el parámetro pSockaddr apunta a una estructura de sockaddr_in . Para IPv6, el parámetro pSockaddr apunta a una estructura de sockaddr_in6 .
[in] SockaddrLength
Longitud, en bytes, de la estructura a la que apunta el parámetro pSockaddr .
[out] pNodeBuffer
Puntero a una cadena Unicode que contiene el nombre de host. Si se ejecuta correctamente, se devuelve un puntero al nombre de host Unicode como nombre de dominio completo (FQDN) de forma predeterminada. Si el parámetro pNodeBuffer es NULL, indica que el autor de la llamada no quiere recibir una cadena de nombre de host.
[in] NodeBufferSize
Número de caracteres WCHAR en el búfer al que apunta el parámetro pNodeBuffer . El autor de la llamada debe proporcionar un búfer lo suficientemente grande como para contener el nombre de host Unicode, incluido el carácter NULL de terminación.
[out] pServiceBuffer
Puntero a una cadena Unicode que contiene el nombre del servicio. Si se ejecuta correctamente, se devuelve un puntero a una cadena Unicode que representa el nombre del servicio asociado al número de puerto. Si el parámetro pServiceBuffer es NULL, indica que el autor de la llamada no quiere recibir una cadena de nombre de servicio.
[in] ServiceBufferSize
Número de caracteres WCHAR en el búfer al que apunta el parámetro pServiceBuffer . El llamador debe proporcionar un búfer lo suficientemente grande como para contener el nombre del servicio Unicode, incluido el carácter NULL de terminación.
[in] Flags
Valor que se usa para personalizar el procesamiento de la función GetNameInfoW . Consulte la sección Comentarios.
Valor devuelto
Si se ejecuta correctamente, GetNameInfoW devuelve cero. Cualquier valor devuelto distinto de cero indica un error y se puede recuperar un código de error específico llamando a WSAGetLastError.
Los códigos de error distintos de cero devueltos por la función GetNameInfoW también se asignan al conjunto de errores descritos por las recomendaciones del Grupo de tareas de ingeniería de Internet (IETF). En la tabla siguiente se muestran estos códigos de error y sus equivalentes de WSA. Se recomienda usar los códigos de error de WSA, ya que ofrecen información de error familiar y completa para los programadores de Winsock.
| Valor de error | WSA equivalente | Descripción |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | Error temporal en la resolución de nombres. |
| EAI_BADFLAGS | WSAEINVAL | Se pasaron uno o varios parámetros no válidos a la función GetNameInfoW . Este error se devuelve si se solicitó un nombre de host pero el parámetro NodeBufferSize era cero o si se solicitó un nombre de servicio pero el parámetro ServiceBufferSize era cero. |
| EAI_FAIL | WSANO_RECOVERY | Error irrecuperable en la resolución de nombres. |
| EAI_FAMILY | WSAEAFNOSUPPORT | No se admite el miembro sa_family de la estructura de direcciones de socket a la que apunta el parámetro pSockaddr . |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Error de asignación de memoria. |
| EAI_NONAME | WSAHOST_NOT_FOUND | Se solicitó un nombre de servicio, pero no se encontró ningún número de puerto en la estructura a la que apunta el parámetro pSockaddr o no se encontró ningún nombre de servicio que coincida con el número de puerto. NI_NAMEREQD se establece y no se puede encontrar el nombre del host, o los parámetros pNodeBuffer y pServiceBuffer eran NULL. |
Puede usar la función gai_strerror para imprimir mensajes de error en función de los códigos EAI devueltos por la función GetNameInfoW . La función gai_strerror se proporciona para cumplir las recomendaciones de IETF, pero no es segura para subprocesos. Por lo tanto, se recomienda el uso de funciones tradicionales de Windows Sockets, como WSAGetLastError .
Además, se pueden devolver los siguientes códigos de error.
| Código de error | Significado |
|---|---|
| Este error se devuelve si el parámetro pSockaddr es NULL o el parámetro SockaddrLength es menor que la longitud necesaria para el tamaño de sockaddr_in estructura para IPv4 o la estructura de sockaddr_in6 para IPv6. |
Comentarios
La función GetNameInfoW es la versión Unicode de una función que proporciona resolución de nombres independiente del protocolo. La función GetNameInfoW se usa para traducir el contenido de una estructura de direcciones de socket a un nombre de nodo o a un nombre de servicio.
Para los protocolos IPv6 e IPv4, la resolución de nombres puede ser por el Sistema de nombres de dominio (DNS), un archivo de hosts local o por otros mecanismos de nomenclatura. Esta función se puede usar para determinar el nombre de host de una dirección IPv4 o IPv6, una búsqueda de DNS inversa o determinar el nombre del servicio para un número de puerto. La función GetNameInfoW también se puede usar para convertir una dirección IP o un número de puerto en una estructura SOCKADDR en una cadena Unicode. Esta función también se puede usar para determinar la dirección IP de un nombre de host.
La versión ANSI de esta función es getnameinfo.
Las macros del archivo de encabezado Winsock definen un nombre de función de mayúsculas y minúsculas mixtas de GetNameInfo que se puede usar cuando la aplicación está destinada a Windows XP con Service Pack 2 (SP2) y versiones posteriores (_WIN32_WINNT >= 0x0502). Se debe llamar a esta función GetNameInfo con los parámetros pNodeBuffer y pServiceBuffer de un puntero de tipo TCHAR. Cuando se define UNICODE o _UNICODE, GetNameInfo se define en la versión Unicode y se llama a GetNameInfoW con los parámetros host y serv de un puntero de tipo char. Cuando no se define UNICODE o _UNICODE, GetNameInfo se define en la versión ANSI y se llama a getnameinfo con los parámetros pNodeBuffer y pServiceBuffer de un puntero de tipo PWCHAR.
Para simplificar la determinación de los requisitos de búfer para los parámetros pNodeBuffer y pServiceBuffer , los valores siguientes para la longitud máxima del nombre de host y el nombre máximo del servicio se definen en el archivo de encabezado Ws2tcpip.h :
#include <windows.h>
#define NI_MAXSERV 32
#define NI_MAXHOST 1025
El parámetro Flags se puede usar para personalizar el procesamiento de la función GetNameInfoW . Están disponibles las marcas siguientes:
- NI_NOFQDN
- NI_NUMERICHOST
- NI_NAMEREQD
- NI_NUMERICSERV
- NI_DGRAM
Cuando se establece la marca NI_NAMEREQD , un nombre de host que no puede resolver el DNS produce un error.
Si se establece la marca NI_NOFQDN , los hosts locales solo tienen su nombre distintivo relativo (RDN) devuelto en el parámetro pNodeBuffer .
Al establecer la marca NI_NUMERICHOST , se devuelve la forma numérica del nombre de host en lugar de su nombre. La forma numérica del nombre de host también se devuelve si DNS no puede resolver el nombre de host.
Al establecer la marca NI_NUMERICSERV , se devuelve el número de puerto del servicio en lugar de su nombre. Además, si no se encuentra un nombre de host para una dirección IP (127.0.0.2, por ejemplo), el nombre de host se devuelve como la dirección IP.
En Windows Vista y versiones posteriores, si no se especifica NI_NUMERICSERV en el parámetro flags y el número de puerto contenido en la estructura sockaddr a la que apunta el parámetro sa no se resuelve en un servicio conocido, la función GetNameInfoW devuelve la forma numérica de la dirección del servicio (el número de puerto) como una cadena numérica. Cuando se especifica NI_NUMERICSERV , el número de puerto se devuelve como una cadena numérica. Este comportamiento se especifica en la sección 6.2 de RFC 3493. Para obtener más información, consulte www.ietf.org/rfc/rfc3493.txt
En Windows Server 2003 y versiones anteriores, si no se especifica NI_NUMERICSERV en el parámetro flags y el número de puerto contenido en la estructura sockaddr a la que apunta el parámetro sa no se resuelve en un servicio conocido, se produce un error en la función GetNameInfoW . Cuando se especifica NI_NUMERICSERV , el número de puerto se devuelve como una cadena numérica.
Establecer la marca NI_DGRAM indica que el servicio es un servicio de datagramas. Esta marca es necesaria para los pocos servicios que proporcionan números de puerto diferentes para el servicio UDP y TCP.
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.
Código de ejemplo
En el ejemplo siguiente se muestra el uso de la función 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;
}
}
Nota
El encabezado ws2tcpip.h define GetNameInfo como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 8.1, Windows Vista [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | ws2tcpip.h |
| Library | Ws2_32.lib |
| Archivo DLL | Ws2_32.dll |