Función GetNameInfoW (ws2tcpip.h)

Artículo
11/20/2024

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, un puntero al nombre de host Unicode se devuelve como un 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 del 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 de terminación NULL.

[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 del búfer al que apunta el parámetro de pServiceBuffer. El autor de la llamada debe proporcionar un búfer lo suficientemente grande como para contener el nombre del servicio Unicode, incluido el carácter de terminación NULL.

[in] Flags

Valor que se usa para personalizar el procesamiento de la función getNameInfoW de . 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 pasó 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 parámetros 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 el cumplimiento de 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
WSAEFAULT	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 la estructura de sockaddr_in para IPv4 o la estructura de sockaddr_in6 para IPv6.

Observaciones

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 local hospeda archivo 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 de 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 pueden 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 de GetNameInfo con el pNodeBuffer y parámetros de 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 el host de y parámetros de serv de un puntero de tipo char. Cuando no se define UNICODE o _UNICODE, se define GetNameInfo en la versión ANSI y se llama a getnameinfo con el pNodeBuffer y parámetros pServiceBuffer de un puntero de tipo PWCHAR.

Para simplificar la determinación de los requisitos de búfer para los parámetros de pNodeBuffer y pServiceBuffer, se definen los siguientes valores para la longitud máxima del nombre de host y el nombre máximo del servicio 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 de . Están disponibles las siguientes marcas:

NI_NOFQDN
NI_NUMERICHOST
NI_NAMEREQD
NI_NUMERICSERV
NI_DGRAM

Cuando se establece la marca NI_NAMEREQD, un nombre de host que el DNS no puede resolver produce un error.

Si se establece la marca de NI_NOFQDN, los hosts locales solo tienen su nombre distintivo relativo (RDN) devuelto en el parámetro pNodeBuffer de .

Establecer la marca NI_NUMERICHOST devuelve la forma numérica del nombre de host en lugar de su nombre. También se devuelve la forma numérica del nombre de host 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 dirección IP.

En Windows Vista y versiones posteriores, si no se especifica NI_NUMERICSERV en el parámetro marcas, y el número de puerto incluido en estructura de 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 de 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 las marcas parámetro y el número de puerto contenido en la estructura sockaddr a la que apunta el parámetro sa 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.

Nota La capacidad de realizar búsquedas inversas de DNS mediante la función GetNameInfoW de es conveniente, pero estas búsquedas se consideran intrínsecamente poco confiables y solo se deben usar como sugerencia.

NotaGetNameInfoW no se puede usar para resolver nombres de alias.

Windows Phone 8: Esta función es compatible con las aplicaciones de la Tienda de Windows Phone 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 de

En el ejemplo siguiente se muestra el uso de la función de 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	ws2tcpip.h
biblioteca de	Ws2_32.lib
DLL de	Ws2_32.dll

Consulte también

GetAddrInfoW

WSAGetLastError

funciones winsock

de referencia de Winsock

gai_strerror

getaddrinfo

getnameinfo

sockaddr

Compartir a través de