Compartir a través de


Estructura ADDRINFOA (ws2def.h)

La función getaddrinfo usa la estructura addrinfo para contener la información de la dirección del host.

Sintaxis

typedef struct addrinfo {
  int             ai_flags;
  int             ai_family;
  int             ai_socktype;
  int             ai_protocol;
  size_t          ai_addrlen;
  char            *ai_canonname;
  struct sockaddr *ai_addr;
  struct addrinfo *ai_next;
} ADDRINFOA, *PADDRINFOA;

Miembros

ai_flags

Tipo: int

Marcas que indican las opciones usadas en la función getaddrinfo .

Los valores admitidos para el miembro ai_flags se definen en el archivo de encabezado Ws2def.h en el Windows SDK para Windows 7 y versiones posteriores. Estos valores se definen en el archivo de encabezado Ws2tcpip.h en el Windows SDK para Windows Server 2008 y Windows Vista. Estos valores se definen en el archivo de encabezado Ws2tcpip.h en platform SDK para Windows Server 2003 y Windows XP. Los valores admitidos para el miembro ai_flags pueden ser una combinación de las siguientes opciones.

Valor Significado
AI_PASSIVE
0x01
La dirección del socket se usará en una llamada a la función bind .
AI_CANONNAME
0x02
El nombre canónico se devuelve en el primer miembro ai_canonname .
AI_NUMERICHOST
0x04
El parámetro nodename pasado a la función getaddrinfo debe ser una cadena numérica.
AI_ALL
0x0100
Si se establece este bit, se realiza una solicitud para las direcciones IPv6 y las direcciones IPv4 con AI_V4MAPPED.

Esta opción se admite en Windows Vista y versiones posteriores.

AI_ADDRCONFIG
0x0400
Getaddrinfo solo se resolverá si se configura una dirección global. La dirección de bucle invertido IPv6 e IPv4 no se considera una dirección global válida.

Esta opción se admite en Windows Vista y versiones posteriores.

AI_V4MAPPED
0x0800
Si se produce un error en la solicitud getaddrinfo para las direcciones IPv6, se realiza una solicitud de servicio de nombre para las direcciones IPv4 y estas direcciones se convierten en formato de dirección IPv4 asignada a IPv6.

Esta opción se admite en Windows Vista y versiones posteriores.

AI_NON_AUTHORITATIVE
0x04000
La información de dirección puede ser de un proveedor de espacios de nombres no autoritativo.

Esta opción solo se admite en Windows Vista y versiones posteriores para el espacio de nombres NS_EMAIL .

AI_SECURE
0x08000
La información de dirección procede de un canal seguro.

Esta opción solo se admite en Windows Vista y versiones posteriores para el espacio de nombres NS_EMAIL .

AI_RETURN_PREFERRED_NAMES
0x010000
La información de dirección es para un nombre preferido para un usuario.

Esta opción solo se admite en Windows Vista y versiones posteriores para el espacio de nombres NS_EMAIL .

AI_FQDN
0x00020000
Si se especifica un nombre plano (etiqueta única), getaddrinfo 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 .

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 getaddrinfo si ambas marcas están presentes con EAI_BADFLAGS.

Esta opción es compatible con Windows 7, Windows Server 2008 R2 y versiones posteriores.

AI_FILESERVER
0x00040000
Sugerencia al proveedor de espacios de nombres que se está consultando el nombre de host se usa en un escenario de recurso compartido de archivos. El proveedor de espacios de nombres puede omitir esta sugerencia.

Esta opción es compatible con Windows 7, Windows Server 2008 R2 y versiones posteriores.

ai_family

Tipo: int

Familia de direcciones. Los valores posibles para la familia de direcciones se definen en el archivo de encabezado Winsock2.h .

En el Windows SDK publicado para Windows Vista y versiones posteriores, la organización de los archivos de encabezado ha cambiado y los valores posibles para la familia de direcciones se definen en el archivo de encabezado Ws2def.h. Tenga en cuenta que el archivo de encabezado Ws2def.h se incluye automáticamente en Winsock2.h y nunca se debe usar directamente.

Los valores admitidos actualmente son AF_INET o AF_INET6, que son los formatos de familia de direcciones de Internet para IPv4 e IPv6. Se admiten otras opciones para la familia de direcciones (AF_NETBIOS para su uso con NetBIOS, por ejemplo) si se instala un proveedor de servicios de Windows Sockets para la familia de direcciones. Tenga en cuenta que los valores de la familia de direcciones AF_ y las constantes de familia de protocolos PF_ son idénticos (por ejemplo, AF_UNSPEC y PF_UNSPEC), por lo que se puede usar cualquier constante.

En la tabla siguiente se enumeran los valores comunes de la familia de direcciones, aunque muchos otros valores son posibles.

Valor Significado
AF_UNSPEC
0
La familia de direcciones no está especificada.
AF_INET
2
Familia de direcciones del Protocolo de Internet versión 4 (IPv4).
AF_NETBIOS
17
Familia de direcciones NetBIOS. Esta familia de direcciones solo se admite si está instalado un proveedor de Windows Sockets para NetBIOS.
AF_INET6
23
Familia de direcciones del Protocolo de Internet versión 6 (IPv6).
AF_IRDA
26
Familia de direcciones de la Asociación de datos infrarrojos (IrDA). Esta familia de direcciones solo se admite si el equipo tiene instalado un puerto infrarrojo y un controlador.
AF_BTH
32
La familia de direcciones Bluetooth. Esta familia de direcciones solo se admite si se instala un adaptador Bluetooth en Windows Server 2003 o posterior.

ai_socktype

Tipo: int

Tipo de socket. Los valores posibles para el tipo de socket se definen en el archivo de encabezado Winsock2.h .

En la tabla siguiente se enumeran los valores posibles para el tipo de socket admitido para Windows Sockets 2:

Valor Significado
SOCK_STREAM
1
Proporciona secuencias de bytes secuenciadas, confiables y bidireccionales basadas en conexiones con un mecanismo de transmisión de datos OOB. Usa el Protocolo de control de transmisión (TCP) para la familia de direcciones de Internet (AF_INET o AF_INET6). Si el miembro ai_family es AF_IRDA, SOCK_STREAM es el único tipo de socket admitido.
SOCK_DGRAM
2
Admite datagramas, que son búferes no confiables sin conexión con una longitud máxima fija (normalmente corta). Usa el Protocolo de datagramas de usuario (UDP) para la familia de direcciones de Internet (AF_INET o AF_INET6).
SOCK_RAW
3
Proporciona un socket sin formato que permite a una aplicación manipular el siguiente encabezado de protocolo de capa superior. Para manipular el encabezado IPv4, la opción de socket IP_HDRINCL debe establecerse en el socket. Para manipular el encabezado IPv6, la opción de socket IPV6_HDRINCL debe establecerse en el socket.
SOCK_RDM
4
Proporciona un datagrama de mensaje confiable. Un ejemplo de este tipo es la implementación del protocolo multidifusión general pragmático (PGM) en Windows, a menudo denominada programación de multidifusión confiable.
SOCK_SEQPACKET
5
Proporciona un paquete de pseudo streaming basado en datagramas.
 

En Windows Sockets 2, se introdujeron nuevos tipos de socket. Una aplicación puede detectar dinámicamente los atributos de cada protocolo de transporte disponible a través de la función WSAEnumProtocols . Por lo tanto, una aplicación puede determinar las posibles opciones de tipo de socket y protocolo para una familia de direcciones y usar esta información al especificar este parámetro. Las definiciones de tipo de socket en los archivos de encabezado Winsock2.h y Ws2def.h se actualizarán periódicamente a medida que se definen nuevos tipos de socket, familias de direcciones y protocolos.

En Windows Sockets 1.1, los únicos tipos de socket posibles son SOCK_DATAGRAM y SOCK_STREAM.

ai_protocol

Tipo: int

Tipo de protocolo. Las opciones posibles son específicas de la familia de direcciones y el tipo de socket especificado. Los valores posibles para el ai_protocol se definen en los archivos de encabezado Winsock2.h y Wsrm.h .

En el Windows SDK publicado para Windows Vista y versiones posteriores, la organización de los archivos de encabezado ha cambiado y este miembro puede ser uno de los valores del tipo de enumeración IPPROTO definido en el archivo de encabezado Ws2def.h. Tenga en cuenta que el archivo de encabezado Ws2def.h se incluye automáticamente en Winsock2.h y nunca se debe usar directamente.

Si se especifica un valor de 0 para ai_protocol, el autor de la llamada no desea especificar un protocolo y el proveedor de servicios elegirá el ai_protocol que se va a usar. En el caso de los protocolos distintos de IPv4 e IPv6, establezca ai_protocol en cero.

En la tabla siguiente se enumeran los valores comunes para el miembro ai_protocol , aunque muchos otros valores son posibles.

Valor Significado
IPPROTO_TCP
6
Protocolo de control de transmisión (TCP). Se trata de un valor posible cuando el miembro ai_family es AF_INET o AF_INET6 y el miembro ai_socktype es SOCK_STREAM.
IPPROTO_UDP
17
Protocolo de datagramas de usuario (UDP). Se trata de un valor posible cuando el miembro ai_family es AF_INET o AF_INET6 y el parámetro de tipo se SOCK_DGRAM.
IPPROTO_RM
113
Protocolo PGM para multidifusión confiable. Se trata de un valor posible cuando se AF_INET el miembro ai_family y el miembro ai_socktype es SOCK_RDM. En el Windows SDK publicado para Windows Vista y versiones posteriores, este valor también se denomina IPPROTO_PGM.
 

Si el miembro ai_family es AF_IRDA, el ai_protocol debe ser 0.

ai_addrlen

Tipo: size_t

Longitud, en bytes, del búfer al que apunta el miembro ai_addr .

ai_canonname

Tipo: char*

Nombre canónico del host.

ai_addr

Tipo: struct sockaddr*

Puntero a una estructura sockaddr . El miembro ai_addr de cada estructura addrinfo devuelta apunta a una estructura de direcciones de socket rellenada. La longitud, en bytes, de cada estructura addrinfo devuelta se especifica en el miembro ai_addrlen .

ai_next

Tipo: struct addrinfo*

Puntero a la siguiente estructura de una lista vinculada. Este parámetro se establece en NULL en la última estructura addrinfo de una lista vinculada.

Comentarios

La función getaddrinfo de ANSI usa la estructura addrinfo para contener la información de dirección del host.

La estructura addrinfoW es la versión de esta estructura utilizada por la función GetAddrInfoW unicode.

Las macros del archivo de encabezado Ws2tcpip.h definen una estructura ADDRINFOT y un nombre de función de mayúsculas y minúsculas mixtas de GetAddrInfo. Se debe llamar a la función GetAddrInfo con los parámetros nodename y servname de un puntero de tipo TCHAR y las sugerencias y los parámetros res de un puntero de tipo ADDRINFOT. Cuando no se define UNICODE o _UNICODE, ADDRINFOT se define en la estructura addrinfo y GetAddrInfo se define en getaddrinfo, la versión ANSI de esta función. Cuando se define UNICODE o _UNICODE, ADDRINFOT se define en la estructura addrinfoW y GetAddrInfo se define en GetAddrInfoW, la versión Unicode de esta función.

Tras una llamada correcta a getaddrinfo, se devuelve una lista vinculada de estructuras addrinfo en el parámetro res pasado a la función getaddrinfo . La lista se puede procesar siguiendo el puntero proporcionado en el miembro ai_next de cada estructura addrinfo devuelta hasta que se encuentre un puntero NULL . En cada estructura addrinfo 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 de cada estructura addrinfo devuelta apunta a una estructura de direcciones de socket rellenada, cuya longitud se especifica en su miembro ai_addrlen .

Compatibilidad con getaddrinfo y la estructura addrinfo en versiones anteriores de Windows

La función getaddrinfo que usa la estructura addrinfo se agregó al Ws2_32.dll en Windows XP y versiones posteriores. La estructura addrinfo se define en el archivo de encabezado Ws2tcpip.h incluido con el SDK de plataforma publicado para Windows XP y versiones posteriores y el Windows SDK publicado para Windows Vista y versiones posteriores.

Para ejecutar una aplicación que usa la función getaddrinfo y la estructura addrinfo en versiones anteriores de Windows (Windows 2000), debe incluir los archivos Ws2tcpip.h y Wspiapi.h . Cuando se agrega el archivo de inclusión Wspiapi.h , la función getaddrinfo se define en la función insertada WspiapiGetAddrInfo en el archivo Wspiapi.h . En tiempo de ejecución, la función WspiapiGetAddrInfo se implementa de forma que si el Ws2_32.dll o el Wship6.dll (el archivo que contiene getaddrinfo en la versión preliminar de la tecnología IPv6 para Windows 2000) no incluye getaddrinfo, entonces una versión de getaddrinfo se implementa insertada en función del código en el 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 getaddrinfo .

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 getaddrinfo en versiones de Windows anteriores a Windows XP se limita a controlar la resolución de nombres IPv4.

La función GetAddrInfoW que usa la estructura addrinfoW es la versión Unicode de la función getaddrinfo y la estructura addrinfo asociada. La función GetAddrInfoW se agregó al Ws2_32.dll en Windows XP con Service Pack 2 (SP2). La función GetAddrInfoW y la estructura addrinfoW no se pueden usar en versiones de Windows anteriores a Windows XP con SP2.

Ejemplos

En el ejemplo de código siguiente se muestra el uso de la estructura addrinfo .


#undef UNICODE

#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;
    INT iRetval;

    DWORD dwRetval;

    int i = 1;
    
    struct addrinfo *result = NULL;
    struct addrinfo *ptr = NULL;
    struct addrinfo hints;

    struct sockaddr_in  *sockaddr_ipv4;
//    struct sockaddr_in6 *sockaddr_ipv6;
    LPSOCKADDR sockaddr_ip;

    char ipstringbuffer[46];
    DWORD ipbufferlength = 46;

    // Validate the parameters
    if (argc != 3) {
        printf("usage: %s <hostname> <servicename>\n", argv[0]);
        printf("       provides protocol-independent translation\n");
        printf("       from an ANSI host name to an IP address\n");
        printf("%s example usage\n", argv[0]);
        printf("   %s www.contoso.com 0\n", argv[0]);
        return 1;
    }

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("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;

    printf("Calling getaddrinfo with following parameters:\n");
    printf("\tnodename = %s\n", argv[1]);
    printf("\tservname (or port) = %s\n\n", argv[2]);
    
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
    dwRetval = getaddrinfo(argv[1], argv[2], &hints, &result);
    if ( dwRetval != 0 ) {
        printf("getaddrinfo failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }

    printf("getaddrinfo returned success\n");
    
    // Retrieve each address and print out the hex bytes
    for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {

        printf("getaddrinfo response %d\n", i++);
        printf("\tFlags: 0x%x\n", ptr->ai_flags);
        printf("\tFamily: ");
        switch (ptr->ai_family) {
            case AF_UNSPEC:
                printf("Unspecified\n");
                break;
            case AF_INET:
                printf("AF_INET (IPv4)\n");
                sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
                printf("\tIPv4 address %s\n",
                    inet_ntoa(sockaddr_ipv4->sin_addr) );
                break;
            case AF_INET6:
                printf("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)
                    printf("WSAAddressToString failed with %u\n", WSAGetLastError() );
                else    
                    printf("\tIPv6 address %s\n", ipstringbuffer);
                break;
            case AF_NETBIOS:
                printf("AF_NETBIOS (NetBIOS)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_family);
                break;
        }
        printf("\tSocket type: ");
        switch (ptr->ai_socktype) {
            case 0:
                printf("Unspecified\n");
                break;
            case SOCK_STREAM:
                printf("SOCK_STREAM (stream)\n");
                break;
            case SOCK_DGRAM:
                printf("SOCK_DGRAM (datagram) \n");
                break;
            case SOCK_RAW:
                printf("SOCK_RAW (raw) \n");
                break;
            case SOCK_RDM:
                printf("SOCK_RDM (reliable message datagram)\n");
                break;
            case SOCK_SEQPACKET:
                printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_socktype);
                break;
        }
        printf("\tProtocol: ");
        switch (ptr->ai_protocol) {
            case 0:
                printf("Unspecified\n");
                break;
            case IPPROTO_TCP:
                printf("IPPROTO_TCP (TCP)\n");
                break;
            case IPPROTO_UDP:
                printf("IPPROTO_UDP (UDP) \n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_protocol);
                break;
        }
        printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
        printf("\tCanonical name: %s\n", ptr->ai_canonname);
    }

    freeaddrinfo(result);
    WSACleanup();

    return 0;
}

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado ws2def.h

Consulte también

GetAddrInfoW

WSAEnumProtocols

addrinfoW

bind

getaddrinfo

sockaddr