ADDRINFOEX5 structure (ws2def.h)

The addrinfoex4 structure is used by the GetAddrInfoEx function to hold host address information when a specific network interface has been requested.

Syntax

typedef struct addrinfoex5 {
  int                ai_flags;
  int                ai_family;
  int                ai_socktype;
  int                ai_protocol;
  size_t             ai_addrlen;
  PWSTR              ai_canonname;
  struct sockaddr    *ai_addr;
  void               *ai_blob;
  size_t             ai_bloblen;
  GUID               *ai_provider;
  struct addrinfoex5 *ai_next;
  int                ai_version;
  PWSTR              ai_fqdn;
  int                ai_interfaceindex;
  HANDLE             ai_resolutionhandle;
  unsigned int       ai_ttl;
} ADDRINFOEX5, *PADDRINFOEX5, *LPADDRINFOEX5;

Members

ai_flags

Flags that indicate options used in the GetAddrInfoEx function.

Supported values for the ai_flags member are defined in the Winsock2.h include file and can be a combination of the following options.

Value Meaning
AI_PASSIVE
0x01
The socket address will be used in a call to the bindfunction.
AI_CANONNAME
0x02
The canonical name is returned in the first ai_canonname member.
AI_NUMERICHOST
0x04
The nodename parameter passed to the GetAddrInfoEx function must be a numeric string.
AI_ALL
0x0100
If this bit is set, a request is made for IPv6 addresses and IPv4 addresses with AI_V4MAPPED.

This option is supported on Windows Vista and later.

AI_ADDRCONFIG
0x0400
The GetAddrInfoEx will resolve only if a global address is configured. The IPv6 and IPv4 loopback address is not considered a valid global address.

This option is supported on Windows Vista and later.

AI_V4MAPPED
0x0800
If the GetAddrInfoEx request for an IPv6 addresses fails, a name service request is made for IPv4 addresses and these addresses are converted to IPv4-mapped IPv6 address format.

This option is supported on Windows Vista and later.

AI_NON_AUTHORITATIVE
0x04000
The address information is from non-authoritative results.

When this option is set in the pHints parameter of GetAddrInfoEx, the NS_EMAIL namespace provider returns both authoritative and non-authoritative results. If this option is not set, then only authoritative results are returned.

This option is only supported on Windows Vista and later for the NS_EMAIL namespace.

AI_SECURE
0x08000
The address information is from a secure channel.

If the AI_SECURE bit is set, the NS_EMAIL namespace provider will return results that were obtained with enhanced security to minimize possible spoofing.

When this option is set in the pHints parameter of GetAddrInfoEx, the NS_EMAIL namespace provider returns only results that were obtained with enhanced security to minimize possible spoofing.

This option is only supported on Windows Vista and later for the NS_EMAIL namespace.

AI_RETURN_PREFERRED_NAMES
0x010000
The address information is for a preferred names for publication with a specific namespace.

When this option is set in the pHints parameter of GetAddrInfoEx, no name should be provided in the pName parameter and the NS_EMAIL namespace provider will return preferred names for publication.

This option is only supported on Windows Vista and later for the NS_EMAIL namespace.

AI_FQDN
0x00020000
The fully qualified domain name is returned in the first ai_fqdn member.

When this option is set in the pHints parameter of GetAddrInfoEx and a flat name (single label) is specified in the pName parameter, the fully qualified domain name that the name eventually resolved to will be returned.

This option is supported on Windows 7, Windows Server 2008 R2, and later.

AI_FILESERVER
0x00040000
A hint to the namespace provider that the hostname being queried is being used in a file share scenario. The namespace provider may ignore this hint.

This option is supported on Windows 7, Windows Server 2008 R2, and later.

AI_DISABLE_IDN_ENCODING
0x00080000
Disable the automatic International Domain Name encoding using Punycode in the name resolution functions called by the GetAddrInfoEx function.

This option is supported on Windows 8, Windows Server 2012, and later.

AI_EXTENDED
0x80000000
Indicates that the current object is extended: that is, an addrinfoex2 or greater.

This option is supported on Windows 8.1, Windows Server 2012 R2, and later.

AI_RESOLUTION_HANDLE
0x40000000
A resolution handle is returned in the ai_resolutionhandle member.

This option is supported on Windows 10, Windows Server 2016, and later.

AI_RETURN_TTL
0x0080
The number of seconds for which the DNS record is valid. If this flag is present, the GetAddrInfoEx.ppResult parameter will return a list of addrinfoex5 structures, where the ai_ttl member will contain the individual TTL of the DNS record.

ai_family

The address family.

The possible values for the address family are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

The values currently supported are AF_INET or AF_INET6, which are the Internet address family formats for IPv4 and IPv6. Other options for address family (AF_NETBIOS for use with NetBIOS, for example) are supported if a Windows Sockets service provider for the address family is installed. Note that the values for the AF_ address family and PF_ protocol family constants are identical (for example, AF_INET and PF_INET), so either constant can be used.

The table below lists common values for the address family although many other values are possible.

Value Meaning
AF_UNSPEC
0
The address family is unspecified.
AF_INET
2
The Internet Protocol version 4 (IPv4) address family.
AF_NETBIOS
17
The NetBIOS address family. This address family is only supported if a Windows Sockets provider for NetBIOS is installed.
AF_INET6
23
The Internet Protocol version 6 (IPv6) address family.
AF_IRDA
26
The Infrared Data Association (IrDA) address family. This address family is only supported if the computer has an infrared port and driver installed.
AF_BTH
32
The Bluetooth address family. This address family is only supported if a Bluetooth adapter is installed.

ai_socktype

The socket type. Possible values for the socket type are defined in the Winsock2.h include file.

The following table lists the possible values for the socket type supported for Windows Sockets 2:

Value Meaning
SOCK_STREAM
1
Provides sequenced, reliable, two-way, connection-based byte streams with an OOB data transmission mechanism. Uses the Transmission Control Protocol (TCP) for the Internet address family (AF_INET or AF_INET6). If the ai_family member is AF_IRDA, then SOCK_STREAM is the only supported socket type.
SOCK_DGRAM
2
Supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. Uses the User Datagram Protocol (UDP) for the Internet address family (AF_INET or AF_INET6).
SOCK_RAW
3
Provides a raw socket that allows an application to manipulate the next upper-layer protocol header. To manipulate the IPv4 header, the IP_HDRINCL socket option must be set on the socket. To manipulate the IPv6 header, the IPV6_HDRINCL socket option must be set on the socket.
SOCK_RDM
4
Provides a reliable message datagram. An example of this type is the Pragmatic General Multicast (PGM) multicast protocol implementation in Windows, often referred to as reliable multicast programming.
SOCK_SEQPACKET
5
Provides a pseudo-stream packet based on datagrams.
 

In Windows Sockets 2, new socket types were introduced. An application can dynamically discover the attributes of each available transport protocol through the WSAEnumProtocols function. So an application can determine the possible socket type and protocol options for an address family and use this information when specifying this parameter. Socket type definitions in the Winsock2.h and Ws2def.h header files will be periodically updated as new socket types, address families, and protocols are defined.

In Windows Sockets 1.1, the only possible socket types are SOCK_DATAGRAM and SOCK_STREAM.

ai_protocol

The protocol type. The possible options are specific to the address family and socket type specified. Possible values for the ai_protocol are defined in Winsock2.h and the Wsrm.h header files.

On the Windows SDK released for Windows Vista and later,, the organization of header files has changed and this member can be one of the values from the IPPROTO enumeration type defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

If a value of 0 is specified for ai_protocol, the caller does not wish to specify a protocol and the service provider will choose the ai_protocol to use. For protocols other than IPv4 and IPv6, set ai_protocol to zero.

The following table lists common values for the ai_protocol member although many other values are possible.

Value Meaning
IPPROTO_TCP
6
The Transmission Control Protocol (TCP). This is a possible value when the ai_family member is AF_INET or AF_INET6 and the ai_socktype member is SOCK_STREAM.
IPPROTO_UDP
17
The User Datagram Protocol (UDP). This is a possible value when the ai_family member is AF_INET or AF_INET6 and the type parameter is SOCK_DGRAM.
IPPROTO_RM
113
The PGM protocol for reliable multicast. This is a possible value when the ai_family member is AF_INET and the ai_socktype member is SOCK_RDM. On the Windows SDK released for Windows Vista and later, this value is also called IPPROTO_PGM.
 

If the ai_family member is AF_IRDA, then the ai_protocol must be 0.

ai_addrlen

The length, in bytes, of the buffer pointed to by the ai_addr member.

ai_canonname

The canonical name for the host.

ai_addr

A pointer to a sockaddr structure. The ai_addr member in each returned addrinfoex4 structure points to a filled-in socket address structure. The length, in bytes, of each returned addrinfoex4 structure is specified in the ai_addrlen member.

ai_blob

A pointer to data that is used to return provider-specific namespace information that is associated with the name beyond a list of addresses. The length, in bytes, of the buffer pointed to by ai_blob must be specified in the ai_bloblen member.

ai_bloblen

The length, in bytes, of the ai_blob member.

ai_provider

A pointer to the GUID of a specific namespace provider.

ai_next

A pointer to the next structure in a linked list. This parameter is set to NULL in the last addrinfoex4 structure of a linked list.

ai_version

The version number of this structure. The value currently used for this version of the structure is 4.

ai_fqdn

The fully qualified domain name for the host.

ai_interfaceindex

The interface index, as defined by the IP_ADAPTER_ADDRESSES.IfIndex property returned in GetAdaptersAddresses.

ai_resolutionhandle

Handle pointing to the fully qualified domain name for the host.

ai_ttl

Number of seconds for which this DNS record is valid.

Remarks

The ADDRINFOEX5 structure is used by the GetAddrInfoExW function to hold host address information when the AI_EXTENDED or AI_RETURN_TTL bits are set in the ai_flags member passed in through the GetAddrInfoExW hints parameter.

The ADDRINFOEX5 structure is an extension of the ADDRINFOEX4 structure. In addition to all fields from the ADDRINFOEX4 structure, it also holds in the ai_ttl member the individual DNS TTL for each returned IP address.

If the AI_RETURN_TTL bit is set in the ai_flags member passed in through the GetAddrInfoEx hints parameter, the GetAddrInfoExW ppResult parameter will return a list of ADDRINFOEX5 structures. Each node in this list will contain in the ai_ttl member the individual DNS TTL for the IP address present in the sockaddr member.

Examples

See example code in the ADDRINFOEX4 structure topic.

Requirements

Requirement Value
Minimum supported client Windows 10 Build 20348
Minimum supported server Windows 10 Build 20348
Header ws2def.h

See also

GetAddrInfoEx

addrinfo

addrinfoW

addrinfoex

addrinfoex3