Función GetAddrInfoW (ws2tcpip.h)
La función GetAddrInfoW proporciona una traducción independiente del protocolo de un nombre de host Unicode a una dirección.
Sintaxis
INT WSAAPI GetAddrInfoW(
[in, optional] PCWSTR pNodeName,
[in, optional] PCWSTR pServiceName,
[in, optional] const ADDRINFOW *pHints,
[out] PADDRINFOW *ppResult
);
Parámetros
[in, optional] pNodeName
Puntero a una cadena Unicode terminada en NULL que contiene un nombre de host (nodo) o una cadena de dirección de host numérica. Para el protocolo de Internet, la cadena de dirección de host numérica es una dirección IPv4 decimal con puntos o una dirección hexadecimal IPv6.
[in, optional] pServiceName
Puntero a una cadena Unicode terminada en NULL que contiene un nombre de servicio o un número de puerto representado como una cadena.
Un nombre de servicio es un alias de cadena para un número de puerto. Por ejemplo, "http" es un alias para el puerto 80 definido por el Grupo de tareas de ingeniería de Internet (IETF) como el puerto predeterminado que usan los servidores web para el protocolo HTTP. Los valores posibles para el parámetro pServiceName cuando no se especifica un número de puerto se muestran en el siguiente archivo:
%WINDIR%\system32\drivers\etc\services
[in, optional] pHints
Puntero a una estructura addrinfoW que proporciona sugerencias sobre el tipo de socket que admite el llamador.
Los miembros ai_addrlen, ai_canonname, ai_addr y ai_next de la estructura addrinfoW a la que apunta el parámetro pHints deben ser cero o NULL. De lo contrario, se producirá un error en la función GetAddrInfoEx con WSANO_RECOVERY.
Consulte los comentarios para obtener más detalles.
[out] ppResult
Puntero a una lista vinculada de una o varias estructuras addrinfoW que contiene información de respuesta sobre el host.
Valor devuelto
Success devuelve cero. Error devuelve un código de error de Windows Sockets distinto de cero, como se encuentra en los códigos de error de Windows Sockets.
La mayoría de los códigos de error distintos de cero devueltos por la función GetAddrInfoW 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 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 proporcionó un valor no válido para el miembro ai_flags del parámetro pHints . |
| EAI_FAIL | WSANO_RECOVERY | Error irrecuperable en la resolución de nombres. |
| EAI_FAMILY | WSAEAFNOSUPPORT | No se admite el miembro ai_family del parámetro pHints . |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Error de asignación de memoria. |
| EAI_NONAME | WSAHOST_NOT_FOUND | El nombre no se resuelve para los parámetros proporcionados o no se proporcionaron los parámetros pNodeName y pServiceName . |
| EAI_SERVICE | WSATYPE_NOT_FOUND | El parámetro pServiceName no se admite para el miembro ai_socktype especificado del parámetro pHints . |
| EAI_SOCKTYPE | WSAESOCKTNOSUPPORT | No se admite el miembro ai_socktype del parámetro pHints . |
Use la función gai_strerror para imprimir mensajes de error basados en los códigos EAI_* devueltos por la función GetAddrInfoW . 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 una función tradicional de Windows Sockets, como WSAGetLastError.
| Código de error | Significado |
|---|---|
| No había memoria suficiente para realizar la operación. | |
| Se ha usado una dirección incompatible con el protocolo solicitado. Este error se devuelve si no se admite el ai_family miembro de la estructura addrinfoW a la que apunta el parámetro hints . | |
| Se ha proporcionado un argumento no válido. Este error se devuelve si se proporcionó un valor no válido para el miembro ai_flags de la estructura addrinfoW a la que apunta el parámetro hints . | |
| Esta familia de direcciones no es compatible con el tipo de socket especificado. Este error se devuelve si no se admite el ai_socktype miembro de la estructura addrinfoW a la que apunta el parámetro hints . | |
| Se desconoce el host. Este error se devuelve si el nombre no se resuelve para los parámetros proporcionados o no se proporcionaron los parámetros pNodename y pServicename . | |
| El nombre solicitado es válido, pero no se ha encontrado ningún dato del tipo solicitado. | |
| Se produjo un error no recuperable durante una búsqueda de base de datos. Este error se devuelve si se produjo un error irrecuperable en la resolución de nombres. | |
| Debe producirse una llamada WSAStartup correcta antes de usar esta función. | |
| Éste es normalmente un error temporal durante la resolución de nombres de host y significa que el servidor local no recibió una respuesta de un servidor autorizado. Este error se devuelve cuando se produjo un error temporal en la resolución de nombres. | |
| No se encontró la clase especificada. El parámetro pServiceName no se admite para el miembro de ai_socktype especificado de la estructura addrinfoW a la que apunta el parámetro hints . |
Comentarios
La función GetAddrInfoW es la versión Unicode de una función que proporciona traducción independiente del protocolo del nombre de host a la dirección. La versión ANSI de esta función es getaddrinfo.
La función GetAddrInfoW devuelve resultados para el espacio de nombres NS_DNS. La función GetAddrInfoW agrega todas las respuestas si más de un proveedor de espacios de nombres devuelve información. Para su uso con el protocolo 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 para el espacio de nombres NS_DNS .
Las macros del archivo de encabezado Winsock definen un nombre de función de mayúsculas y minúsculas mixtas de GetAddrInfo y una estructura ADDRINFOT . Se debe llamar a esta función GetAddrInfo con los parámetros pNodeName y pServiceName de un puntero de tipo TCHAR y los parámetros pHints y ppResult de un puntero de tipo ADDRINFOT. Cuando se define UNICODE o _UNICODE, GetAddrInfo se define en GetAddrInfoW, la versión Unicode de la función y ADDRINFOT se define en la estructura addrinfoW . Cuando no se define UNICODE o _UNICODE, GetAddrInfo se define en getaddrinfo, la versión ANSI de la función y ADDRINFOT se define en la estructura addrinfo .
Uno o ambos parámetros pNodeName o pServiceName deben apuntar a una cadena Unicode terminada en NULL; por lo general, ambos se proporcionan.
Tras la operación correcta, se devuelve una lista vinculada de estructuras addrinfoW en el parámetro ppResult . La lista se puede procesar siguiendo el puntero proporcionado en el miembro ai_next de cada estructura addrinfoW devuelta hasta que se encuentre un puntero NULL . En cada estructura addrinfoW devuelta, los miembros ai_family, ai_socktype y ai_protocol corresponden a argumentos respectivos en una llamada de función WSASocket o socket. Además, el miembro ai_addr en cada estructura addrinfoW devuelta apunta a una estructura de direcciones de socket rellenada, cuya longitud se especifica en su miembro ai_addrlen .
Si el parámetro pNodeName apunta a un nombre de equipo, se devuelven todas las direcciones permanentes del equipo que se pueden usar como dirección de origen. En Windows Vista y versiones posteriores, estas direcciones incluirían todas las direcciones IP de unidifusión devueltas por las funciones GetUnicastIpAddressTable o GetUnicastIpAddressEntry en las que el miembro SkipAsSource se establece en false en la estructura MIB_UNICASTIPADDRESS_ROW .
Si el parámetro pNodeName apunta a una cadena igual a "localhost", se devuelven todas las direcciones de bucle invertido en el equipo local.
Si el parámetro pNodeName contiene una cadena vacía, se devuelven todas las direcciones registradas en el equipo local.
En Windows Server 2003 y versiones posteriores, si el parámetro pNodeName apunta a una cadena igual a ".. localmachine", se devuelven todas las direcciones registradas del equipo local.
Si el parámetro pNodeName hace referencia a un nombre de servidor virtual de clúster, solo se devuelven las direcciones del servidor virtual. En Windows Vista y versiones posteriores, estas direcciones incluirían todas las direcciones IP de unidifusión devueltas por las funciones GetUnicastIpAddressTable o GetUnicastIpAddressEntry en las que el miembro SkipAsSource se establece en true en la estructura MIB_UNICASTIPADDRESS_ROW . Consulte Clústeres de Windows para obtener más información sobre la agrupación en clústeres.
Windows 7 con Service Pack 1 (SP1) y Windows Server 2008 R2 con Service Pack 1 (SP1) agregan compatibilidad a Netsh.exe para establecer el atributo SkipAsSource en una dirección IP. Esto también cambia el comportamiento de modo que si el miembro SkipAsSource de la estructura MIB_UNICASTIPADDRESS_ROW está establecido en false, la dirección IP se registrará en DNS. Si el miembro SkipAsSource se establece en true, la dirección IP no se registra en DNS.
Hay disponible una revisión para Windows 7 y Windows Server 2008 R2 que agrega compatibilidad a Netsh.exe para establecer el atributo SkipAsSource en una dirección IP. Esta revisión también cambia el comportamiento de modo que si el miembro SkipAsSource de la estructura MIB_UNICASTIPADDRESS_ROW está establecido en false, la dirección IP se registrará en DNS. Si el miembro SkipAsSource se establece en true, la dirección IP no se registra en DNS. Para obtener más información, vea Knowledge Base (KB) 2386184.
También hay disponible una revisión similar para Windows Vista con Service Pack 2 (SP2) y Windows Server 2008 con Service Pack 2 (SP2) que agrega compatibilidad a Netsh.exe para establecer el atributo SkipAsSource en una dirección IP. Esta revisión también cambia el comportamiento de modo que si el miembro SkipAsSource de la estructura MIB_UNICASTIPADDRESS_ROW está establecido en false, la dirección IP se registrará en DNS. Si el miembro SkipAsSource se establece en true, la dirección IP no se registra en DNS.
Los autores de llamadas de la función GetAddrInfoW pueden proporcionar sugerencias sobre el tipo de socket admitido a través de una estructura addrinfoW a la que apunta el parámetro pHints . Cuando se usa el parámetro pHints , las siguientes reglas se aplican a su estructura addrinfoW asociada:
- Un valor de AF_UNSPEC para ai_family indica que el autor de la llamada solo aceptará el AF_INET y las familias de direcciones AF_INET6 . Tenga en cuenta que AF_UNSPEC y PF_UNSPEC son los mismos.
- Un valor de cero para ai_socktype indica que el autor de la llamada aceptará cualquier tipo de socket.
- Un valor de cero para ai_protocol indica que el autor de la llamada aceptará cualquier protocolo.
- El miembro ai_addrlen debe establecerse en cero.
- El miembro ai_canonname debe establecerse en NULL.
- El miembro ai_addr debe establecerse en NULL.
- El miembro ai_next debe establecerse en NULL.
Otros valores de la estructura addrinfoW proporcionada en el parámetro pHints indican requisitos específicos. Por ejemplo, si el autor de la llamada solo controla IPv4 y no controla IPv6, el miembro ai_family debe establecerse en AF_INET. Por otro ejemplo, si el autor de la llamada solo controla TCP y no controla UDP, el miembro ai_socktype debe establecerse en SOCK_STREAM.
Si el parámetro pHints es un puntero NULL , la función GetAddrInfoW la controla como si la estructura addrinfoW de pHints se inicializara con su miembro ai_family establecido en AF_UNSPEC y todos los demás miembros establecidos en cero.
En Windows Vista y versiones posteriores cuando se llama a GetAddrInfoW desde un servicio, si la operación es el resultado de un proceso de usuario que llama al servicio, el servicio debe suplantar al usuario. Esto es para permitir que la seguridad se aplique correctamente.
La función GetAddrInfoW se puede usar para convertir una representación de cadena de texto de una dirección IP en una estructura addrinfoW que contiene una estructura sockaddr para la dirección IP y otra información. Para usarlo de esta manera, la cadena a la que apunta el parámetro pNodeName debe contener una representación de texto de una dirección IP y la estructura addrinfoW a la que apunta el parámetro pHints debe tener la marca AI_NUMERICHOST establecida en el miembro ai_flags . La cadena a la que apunta el parámetro pNodeName puede contener una representación de texto de una dirección IPv4 o IPv6. La dirección IP de texto se convierte en una estructura addrinfoW a la que apunta el parámetro ppResult . La estructura addrinfoW devuelta contiene una estructura sockaddr para la dirección IP junto con información adicional sobre la dirección IP. Para que este método funcione con una cadena de dirección IPv6 en Windows Server 2003 y Windows XP, el protocolo IPv6 debe estar instalado en el equipo local. De lo contrario, se devuelve el error WSAHOST_NOT_FOUND .
Liberar información de direcciones de la asignación dinámica
Toda la información devuelta por la función GetAddrInfoW a la que apunta el parámetro ppResult se asigna dinámicamente, incluidas todas las estructuras addrinfoW , las estructuras de dirección de socket y las cadenas de nombre de host canónicas a las que apuntan las estructuras addrinfoW . La memoria asignada por una llamada correcta a esta función debe liberarse con una llamada posterior a FreeAddrInfoW.Código de ejemplo
En el ejemplo de código siguiente se muestra cómo usar la función GetAddrInfoW .#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")
// set APPVER=5.02 for WinXP SP2 and later
int __cdecl wmain(int argc, wchar_t **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
INT iRetval;
DWORD dwRetval;
int i = 1;
ADDRINFOW *result = NULL;
ADDRINFOW *ptr = NULL;
ADDRINFOW hints;
// struct sockaddr_in6 *sockaddr_ipv6;
LPSOCKADDR sockaddr_ip;
wchar_t ipstringbuffer[46];
DWORD ipbufferlength = 46;
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
wprintf(L"getaddrinfow provides protocol-independent translation\n");
wprintf(L" from an Unicode host name to an IP address\n");
wprintf(L"%ws example usage\n", argv[0]);
wprintf(L" %ws www.contoso.com 0\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;
}
//--------------------------------
// Setup the hints address info structure
// which is passed to the getaddrinfo() function
ZeroMemory( &hints, sizeof(hints) );
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
wprintf(L"Calling getaddrinfow with following parameters:\n");
wprintf(L"\tnodename = %ws\n", argv[1]);
wprintf(L"\tservname (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrinfoW(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfow structures containing response
// information
dwRetval = GetAddrInfoW(argv[1], argv[2], &hints, &result);
if ( dwRetval != 0 ) {
wprintf(L"GetAddrInfoW failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
wprintf(L"GetAddrInfoW returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
wprintf(L"GetAddrInfoW response %d\n", i++);
wprintf(L"\tFlags: 0x%x\n", ptr->ai_flags);
wprintf(L"\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
wprintf(L"Unspecified\n");
break;
case AF_INET:
wprintf(L"AF_INET (IPv4)\n");
sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
// The buffer length is changed by each call to WSAAddresstoString
// So we need to set it for each iteration through the loop for safety
ipbufferlength = 46;
iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL,
ipstringbuffer, &ipbufferlength );
if (iRetval)
wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
else
wprintf(L"\tIPv4 address %ws\n", ipstringbuffer);
break;
case AF_INET6:
wprintf(L"AF_INET6 (IPv6)\n");
// the InetNtop function is available on Windows Vista and later
// sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
// printf("\tIPv6 address %s\n",
// InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstringbuffer, 46) );
// We use WSAAddressToString since it is supported on Windows XP and later
sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
// The buffer length is changed by each call to WSAAddresstoString
// So we need to set it for each iteration through the loop for safety
ipbufferlength = 46;
iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL,
ipstringbuffer, &ipbufferlength );
if (iRetval)
wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
else
wprintf(L"\tIPv6 address %ws\n", ipstringbuffer);
break;
default:
wprintf(L"Other %ld\n", ptr->ai_family);
break;
}
wprintf(L"\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
wprintf(L"Unspecified\n");
break;
case SOCK_STREAM:
wprintf(L"SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
wprintf(L"SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
wprintf(L"SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
wprintf(L"SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
wprintf(L"SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_socktype);
break;
}
wprintf(L"\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
wprintf(L"Unspecified\n");
break;
case IPPROTO_TCP:
wprintf(L"IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
wprintf(L"IPPROTO_UDP (UDP) \n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_protocol);
break;
}
wprintf(L"\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
wprintf(L"\tCanonical name: %s\n", ptr->ai_canonname);
}
FreeAddrInfoW(result);
WSACleanup();
return 0;
}
Nombres de dominio internacionalizados
Los nombres de host de Internet normalmente constan de un conjunto de caracteres muy restringido:- Letras ASCII mayúsculas y minúsculas del alfabeto inglés.
- Dígitos del 0 al 9.
- Caracteres de guion ASCII.
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 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. Las especificaciones de IDN e IDNA se documentan en RFC 3490, RTF 5890 y RFC 6365 publicada por el Grupo de tareas de ingeniería de Internet (IETF).
En Windows 8 y Windows Server 2012, la función GetAddrInfoW proporciona compatibilidad con el análisis de nombres de dominio internacionalizados (IDN) aplicado al nombre pasado en el parámetro pNodeName . Winsock realiza la codificación punycode/IDN y la conversión. Este comportamiento se puede deshabilitar mediante la marca AI_DISABLE_IDN_ENCODING que se describe a continuación.
En Windows 7 y Windows Server 2008 R2 o versiones anteriores, la función GetAddrInfoW no proporciona actualmente compatibilidad con el análisis de IDN aplicado al nombre pasado en el parámetro pNodeName . Winsock no realiza ninguna conversión punycode/IDN. La función GetAddrInfoW no usa Punycode para convertir un IDN según RFC 3490. La función GetAddrInfoW al consultar DNS codifica el nombre Unicode en formato UTF-8, el formato usado por los servidores DNS de Microsoft en un entorno empresarial.
Varias funciones de Windows Vista y versiones posteriores admiten la conversión entre etiquetas Unicode en un IDN a sus equivalentes ASCII. La representación resultante de cada etiqueta Unicode contiene solo caracteres ASCII y comienza con el prefijo xn-- si la etiqueta Unicode contenía caracteres no ASCII. El motivo es admitir servidores DNS existentes en Internet, ya que algunas herramientas y servidores DNS solo admiten caracteres ASCII (consulte RFC 3490).
La función IdnToAscii usa Punycode para convertir un IDN en la representación ASCII de la cadena Unicode original mediante el algoritmo estándar definido en RFC 3490. La función IdnToUnicode convierte la forma ASCII de un IDN en la sintaxis de codificación UTF-16 normal de Unicode. Para obtener más información y vínculos a estándares de borrador relacionados, consulte Control de nombres de dominio internacionalizados (IDN).
La función IdnToAscii se puede usar para convertir un nombre IDN en el formulario ASCII. Para pasar este formulario ASCII a la función GetAddrInfoW , puede usar la función MultiByteToWideChar para convertir la cadena CHAR en una cadena WCHAR que, a continuación, se puede pasar en el parámetro pNodeName a la función GetAddrInfoW .
Uso de ai_flags en el parámetro hints
Las marcas del miembro ai_flags de la estructura opcional addrinfoW proporcionada en el parámetro pHints modifican el comportamiento de la función.
Estos bits de marca se definen en el archivo de encabezado Ws2def.h en el Kit de desarrollo de software (SDK) de Microsoft Windows para Windows 7. Estos bits de marca se definen en el archivo de encabezado Ws2tcpip.h en Windows SDK para Windows Server 2008 y Windows Vista. Estos bits de marca se definen en el archivo de encabezado Ws2tcpip.h en el Kit de desarrollo de software de plataforma (SDK) para Windows Server 2003 y Windows XP.
Los bits de marca pueden ser una combinación de lo siguiente:
| Bits de marca | Descripción |
|---|---|
| AI_PASSIVE |
Establecer la marca AI_PASSIVE indica que el autor de la llamada pretende usar la estructura de direcciones de socket devuelta en una llamada a la función bind . Cuando se establece la marca AI_PASSIVE y pNodeName es un puntero NULL , la parte de dirección IP de la estructura de direcciones de socket se establece en INADDR_ANY para las direcciones IPv4 y IN6ADDR_ANY_INIT para las direcciones IPv6.
Cuando no se establece la marca de AI_PASSIVE , la estructura de direcciones de socket devuelta está lista para una llamada a la función connect para un protocolo orientado a la conexión o lista para una llamada a las funciones connect, sendto o send para un protocolo sin conexión. Si el parámetro pNodeName es un puntero NULL en este caso, la parte de la dirección IP de la estructura de direcciones de socket se establece en la dirección de bucle invertido. |
| AI_CANONNAME |
Si no se usa AI_CANONNAME ni AI_NUMERICHOST , la función GetAddrInfoW intenta la resolución. Si se pasa una cadena literal GetAddrInfoW intenta convertir la cadena y, si se pasa un nombre de host, la función GetAddrInfoW intenta resolver el nombre en una dirección o en varias direcciones.
Cuando se establece el bit de AI_CANONNAME , el parámetro pNodeName no puede ser NULL. De lo contrario, se producirá un error en la función GetAddrInfoEx con WSANO_RECOVERY. Cuando se establece el bit de AI_CANONNAME y la función GetAddrInfoW devuelve éxito, el miembro ai_canonname del parámetro ppResult apunta a una cadena terminada en NULL que contiene el nombre canónico del nodo especificado. Nota La función GetAddrInfoW puede devolver éxito cuando se establece la marca AI_CANONNAME , pero el miembro ai_canonname de la estructura addrinfoW asociada es NULL. Por lo tanto, el uso recomendado de la marca AI_CANONNAME incluye probar si el miembro de ai_canonname en la estructura addrinfoW asociada es NULL.
|
| AI_NUMERICHOST | Cuando se establece el bit de AI_NUMERICHOST , el parámetro pNodeName debe contener una cadena de dirección de host numérico no NULL ; de lo contrario, se devuelve el error EAI_NONAME . Esta marca impide que se llame a un servicio de resolución de nombres. |
| AI_NUMERICSERV |
Cuando se establece el bit de AI_NUMERICSERV , el parámetro pServiceName debe contener un número de puerto numérico distinto de NULL ; de lo contrario, se devuelve el error EAI_NONAME . Esta marca impide que se llame a un servicio de resolución de nombres.
La marca AI_NUMERICSERV se define en Windows SDK para Windows Vista y versiones posteriores. Los proveedores de Microsoft no admiten la marca AI_NUMERICSERV . |
| AI_ALL |
Si se establece el bit de AI_ALL , se realiza una solicitud para las direcciones IPv6 e IPv4 con AI_V4MAPPED.
La marca AI_ALL se define en Windows SDK para Windows Vista y versiones posteriores. La marca AI_ALL se admite en Windows Vista y versiones posteriores. |
| AI_ADDRCONFIG |
Si se establece el bit de AI_ADDRCONFIG , GetAddrInfoW solo se resolverá si se configura una dirección global. Si se especifica AI_ADDRCONFIG marca, las direcciones IPv4 solo se devolverán si se configura una dirección IPv4 en el sistema local y las direcciones IPv6 solo se devolverán si se configura una dirección IPv6 en el sistema local. La dirección de bucle invertido IPv4 o IPv6 no se considera una dirección global válida.
La marca AI_ADDRCONFIG se define en Windows SDK para Windows Vista y versiones posteriores. La marca AI_ADDRCONFIG se admite en Windows Vista y versiones posteriores. |
| AI_V4MAPPED |
Si se establece el bit de AI_V4MAPPED y se produce un error en una solicitud de direcciones IPv6, se realiza una solicitud de servicio de nombre para las direcciones IPv4 y estas direcciones se convierten en formato de dirección IPv6 asignado a IPv4.
La marca AI_V4MAPPED se define en Windows SDK para Windows Vista y versiones posteriores. La marca AI_V4MAPPED se admite en Windows Vista y versiones posteriores. |
| AI_NON_AUTHORITATIVE |
Si se establece el bit de AI_NON_AUTHORITATIVE , el proveedor de espacio de nombres NS_EMAIL devuelve resultados autoritativos y no autoritativos. Si no se establece el bit de AI_NON_AUTHORITATIVE , el proveedor de espacio de nombres NS_EMAIL devuelve solo los resultados autoritativos.
La marca AI_NON_AUTHORITATIVE se define en Windows SDK para Windows Vista y versiones posteriores. La marca AI_NON_AUTHORITATIVE se admite en Windows Vista y versiones posteriores y solo se aplica al espacio de nombres NS_EMAIL . |
| AI_SECURE |
Si se establece el bit de AI_SECURE , el proveedor de espacio de nombres NS_EMAIL devolverá los resultados obtenidos con seguridad mejorada para minimizar la posible suplantación de identidad.
La marca AI_SECURE se define en Windows SDK para Windows Vista y versiones posteriores. La marca AI_SECURE se admite en Windows Vista y versiones posteriores y solo se aplica al espacio de nombres NS_EMAIL . |
| AI_RETURN_PREFERRED_NAMES |
Si se establece el AI_RETURN_PREFERRED_NAMES , no se debe proporcionar ningún nombre en el parámetro pNodeName . El proveedor de espacio de nombres NS_EMAIL devolverá nombres preferidos para la publicación.
La marca AI_RETURN_PREFERRED_NAMES se define en Windows SDK para Windows Vista y versiones posteriores. La marca AI_RETURN_PREFERRED_NAMES se admite en Windows Vista y versiones posteriores y solo se aplica al espacio de nombres NS_EMAIL . |
| AI_FQDN |
Si se establece el AI_FQDN y se especifica un nombre plano (etiqueta única), GetAddrInfoW devolverá el nombre de dominio completo al que finalmente se resolvió el nombre. El nombre de dominio completo se devuelve en el miembro ai_canonname en la estructura addrinfoW asociada. Esto es diferente de AI_CANONNAME marca de bits que devuelve el nombre canónico registrado en DNS, que puede ser diferente del nombre de dominio completo al que se resolvió el nombre plano. Solo se puede establecer uno de los bits de AI_FQDN y AI_CANONNAME . Se producirá un error en la función GetAddrInfoW si ambas marcas están presentes con EAI_BADFLAGS.
Cuando se establece el bit de AI_FQDN , el parámetro pNodeName no puede ser NULL. De lo contrario, se producirá un error en la función GetAddrInfoEx con WSANO_RECOVERY. Windows 7: La marca AI_FQDN se define en Windows SDK para Windows 7 y versiones posteriores. La marca AI_FQDN se admite en Windows 7 y versiones posteriores. |
| AI_FILESERVER |
Si se establece el AI_FILESERVER , se trata de una sugerencia para el proveedor de espacios de nombres que se está consultando el nombre de host que se está consultando en el escenario del recurso compartido de archivos. El proveedor de espacios de nombres puede omitir esta sugerencia.
Windows 7: La marca AI_FILESERVER se define en Windows SDK para Windows 7 y versiones posteriores. La marca AI_FILESERVER se admite en Windows 7 y versiones posteriores. |
| AI_DISABLE_IDN_ENCODING |
Si se establece el AI_DISABLE_IDN_ENCODING , se deshabilita la codificación automática de nombres de dominio internacionales mediante Punycode en las funciones de resolución de nombres a las que llama la función GetAddrInfoW .
Windows 8: La marca AI_DISABLE_IDN_ENCODING se define en Windows SDK para Windows 8 y versiones posteriores. La marca AI_DISABLE_IDN_ENCODING se admite en Windows 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.
Nota
El encabezado ws2tcpip.h define GetAddrInfo 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 XP, Windows 8.1 [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 |