Función getnameinfo (ws2tcpip.h)
La función getnameinfo proporciona una resolución de nombres independiente del protocolo de una dirección a un nombre de host ANSI y de un número de puerto al nombre del servicio ANSI.
Sintaxis
INT WSAAPI getnameinfo(
[in] const SOCKADDR *pSockaddr,
[in] socklen_t SockaddrLength,
[out] PCHAR pNodeBuffer,
[in] DWORD NodeBufferSize,
[out] PCHAR pServiceBuffer,
[in] DWORD ServiceBufferSize,
[in] INT Flags
);
Parámetros
[in] pSockaddr
Puntero a una estructura de direcciones de socket que contiene la dirección y el número de puerto del socket. Para IPv4, el parámetro sa apunta a una estructura de sockaddr_in . Para IPv6, el parámetro sa apunta a una estructura de sockaddr_in6 .
[in] SockaddrLength
Longitud, en bytes, de la estructura a la que apunta el parámetro sa .
[out] pNodeBuffer
Puntero a una cadena ANSI utilizada para contener el nombre de host. Si se ejecuta correctamente, el nombre de host se devuelve como un nombre de dominio completo (FQDN) de forma predeterminada. Si el parámetro host es NULL, indica que el autor de la llamada no quiere recibir una cadena de nombre de host.
[in] NodeBufferSize
Longitud, en bytes, del búfer al que apunta el parámetro host . El autor de la llamada debe proporcionar un búfer lo suficientemente grande como para contener el nombre de host, incluido el carácter NULL de terminación.
[out] pServiceBuffer
Puntero a una cadena ANSI para contener el nombre del servicio. Si se ejecuta correctamente, se devuelve una cadena ANSI que representa el nombre del servicio asociado al número de puerto. Si el parámetro serv es NULL, indica que el autor de la llamada no quiere recibir una cadena de nombre de servicio.
[in] ServiceBufferSize
Longitud, en bytes, del búfer al que apunta el parámetro serv . El autor de la llamada debe proporcionar un búfer lo suficientemente grande como para contener el nombre del servicio, incluido el carácter NULL de terminación.
[in] Flags
Valor usado para personalizar el procesamiento de la función getnameinfo . Consulte la sección Comentarios.
Valor devuelto
Si se ejecuta correctamente, getnameinfo 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 getnameinfo 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 enumeran 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 errores 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 getnameinfo . Este error se devuelve si se solicitó un nombre de host, pero el parámetro hostlen era cero o si se solicitó un nombre de servicio, pero el parámetro servlen 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 sa . |
| 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 sa 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 de host, o los parámetros host y serv eran NULL. |
Use la función gai_strerror para imprimir mensajes de error en función de los códigos EAI devueltos por la función getnameinfo . 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 sa es NULL o el parámetro salen 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 getnameinfo es la versión ANSI de una función que proporciona resolución de nombres independiente del protocolo. La función getnameinfo se usa para traducir el contenido de una estructura de direcciones de socket a un nombre de nodo o un nombre de servicio.
En el caso de 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 inversa de DNS o determinar el nombre de servicio de un número de puerto. La función getnameinfo también se puede usar para convertir una dirección IP o un número de puerto en una estructura sockaddr en una cadena ANSI. Esta función también se puede usar para determinar la dirección IP de un nombre de host.
Otro nombre que se puede usar para la función getnameinfo es GetNameInfoA. Las macros del archivo de encabezado Ws2tcpip.h definen GetNameInfoA para getnameinfo.
La versión Unicode de esta función disponible en Windows XP con Service Pack 2 (SP2) y versiones posteriores es GetNameInfoW.
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 SP2 y versiones posteriores (_WIN32_WINNT >= 0x0502). Se debe llamar a esta función GetNameInfo con los parámetros host y serv de un puntero de tipo TCHAR. Cuando no se define UNICODE o _UNICODE, GetNameInfo se define en la versión ANSI y se llama a getnameinfo con los parámetros host y serv de un puntero de tipo char. Cuando se define UNICODE o _UNICODE, se define GetNameInfo en la versión Unicode y se llama a GetNameInfoW 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 host y serv , los siguientes valores 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 .
#define NI_MAXSERV 32
#define NI_MAXHOST 1025
El parámetro flags se puede usar para personalizar el procesamiento de la función getnameinfo . Las marcas siguientes están disponibles:
- NI_NOFQDN
- NI_NUMERICHOST
- NI_NAMEREQD
- NI_NUMERICSERV
- NI_DGRAM
Cuando se establece la marca de NI_NAMEREQD , un nombre de host que DNS no puede resolver genera un error.
Al establecer la marca de NI_NOFQDN , los hosts locales solo tienen su nombre distintivo relativo (RDN) devuelto en el parámetro host .
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 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 getnameinfo 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 más información, consulte www.ietf.org/rfc3493.txt
En Windows Server 2003 y versiones anteriores, si NI_NUMERICSERV no se especifica 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 getnameinfo . 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.
Código de ejemplo
En el ejemplo de código siguiente se muestra cómo usar la función getnameinfo .#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 = {0};
int iResult = 0;
DWORD dwRetval;
struct sockaddr_in saGNI;
char hostname[NI_MAXHOST];
char servInfo[NI_MAXSERV];
u_short port = 27015;
// Validate the parameters
if (argc != 2) {
printf("usage: %s IPv4 address\n", argv[0]);
printf(" to return hostname\n");
printf(" %s 127.0.0.1\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("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 getnameinfo
dwRetval = getnameinfo((struct sockaddr *) &saGNI,
sizeof (struct sockaddr),
hostname,
NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);
if (dwRetval != 0) {
printf("getnameinfo failed with error # %ld\n", WSAGetLastError());
return 1;
} else {
printf("getnameinfo returned hostname = %s\n", hostname);
return 0;
}
}
Compatibilidad con getnameinfo en versiones anteriores de Windows
La función getnameinfo se agregó al Ws2_32.dll en Windows XP y versiones posteriores. Si quieres ejecutar una aplicación con esta función en versiones anteriores de Windows (Windows 2000, Windows NT y Windows Me/98/95), debes incluir el archivo Ws2tcpip.h y también incluir el archivo Wspiapi.h . Cuando se agrega el archivo de inclusión Wspiapi.h , la función getnameinfo se define en la función insertada WspiapiGetNameInfo en el archivo Wspiapi.h . En tiempo de ejecución, la función WspiapiGetNameInfo se implementa de forma que, si el Ws2_32.dll o el Wship6.dll (el archivo que contiene getnameinfo en la versión preliminar de tecnología IPv6 para Windows 2000) no incluye getnameinfo, entonces una versión de getnameinfo se implementa insertada en función del código del archivo de encabezado Wspiapi.h . Este código insertado se usará en plataformas de Windows anteriores que no admiten de forma nativa la función getnameinfo .El protocolo IPv6 es compatible con Windows 2000 cuando se instala la versión preliminar de tecnología IPv6 para Windows 2000. De lo contrario, la compatibilidad con getnameinfo en versiones de Windows anteriores a Windows XP se limita a controlar la resolución de nombres IPv4.
La función GetNameInfoW es la versión Unicode de getnameinfo. La función GetNameInfoW se agregó al Ws2_32.dll en Windows XP con SP2. La función GetNameInfoW no se puede usar en versiones de Windows anteriores a Windows XP con SP2.
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
| 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 |