Compartir a través de


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
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 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.

Nota La capacidad de realizar búsquedas inversas de DNS mediante la función GetNameInfoW 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 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

Consulte también

GetAddrInfoW

WSAGetLastError

Funciones winsock

Referencia de Winsock

gai_strerror

getaddrinfo

getnameinfo

sockaddr