getaddrinfo

getaddrinfo translates the name of a service location, for instance host name and/or a service name, and returns a set of socket addresses and associated information to be used in creating a socket to which specified service can be addressed.

Syntax

int WSAAPI getaddrinfo(
    const char *nodename,
    const char *servname,
    const struct addrinfo *hints,
    struct addrinfo **res
);

Parameters

nodename

A pointer to a zero terminated ASCII string containing a host (node) name or a numeric host address string. The numeric host address string is a dotted-decimal IPv4 address or an IPv6 hex address. If nodename is not null, the requested service location is named by nodename; otherwise, the requested service location is local to the caller.

servname

A pointer to a zero-terminated ASCII string containing the port number of the service, in decimal form (e.g. "80" for HTTP). This may be NULL if nodename is not NULL.

hints

A pointer to an addrinfo structure that provides hints about the type of socket the caller supports. This may be NULL.

The ai_flags field to which the hints parameter points shall be set to zero or be bitwise-inclusive OR of one or more of the following values:

• If AI_PASSIVE is specified, the returned address information is suitable for use in binding a socket for accepting incoming connections for the specified service (that is, a call to bind). This flag is ignored if the nodename argument is not null.
• If AI_NUMERICHOST is specified, then a non-null nodename string supplied shall be a numeric host address string. Otherwise, an EAI_NONAME error is returned. This flag shall prevent any type of name resolution service (for example, the DNS) from being invoked.
• If AI_NUMERICSERV is specified, then a non-null servname string supplied shall be a port number
• If AI_ADDRCONFIG is specified, IPv4 addresses shall be returned only if an IPv4 address is configured on the local system, and IPv6 addresses shall be returned only if an IPv6 address is configured on the local system

NOTE: See the Remarks section for a list of unsupported values.

res

A pointer to a linked list of one or more addrinfo structures containing response information about the host.

Return Value

0 (zero) if the function succeeds, a non-zero, positive value if the function fails

Error codes returned by getaddrinfo are:

Error Code	Description
WSATRY_AGAIN	The name server returned a temporary failure indication. Try again later.
WSAEINVAL	ai_flags contains invalid flags.
WSAEAFNOSUPPORT	The requested address family is not supported.
WSA_NOT_ENOUGH_MEMORY	Memory allocation failure.
WSAHOST_NOT_FOUND	The node or service is not known. This error is also returned if both node and service are NULL.
WSATYPE_NOT_FOUND	The requested service is not available for the requested socket type. It may be available through another socket type.
WSAESOCKTNOSUPPORT	The requested socket type is not supported.
WSANO_RECOVERY	The name server returned a permanent failure indication.

Remarks

Since the RT-TCP/IP stack does not support DNS protocol, only name-to-address translations, which don’t require dynamic name resolution, are supported.

The ai_family in the hints parameter must be one of the following values:

• AF_INET
• AF_INET6

• AF_UNSPEC

freeaddrinfo must be called when the application finishes using the pointer or a memory leak will occur.

The following values for the ai_flags in the hints parameter are not supported:

• AI_NON_AUTHORITATIVE
• AI_SECURE
• AI_RETURN_PREFERRED_NAMES

• AI_CANONNAME

If the hints parameter is not provided and set to NULL, the following defaults within the hintsparameter are used:

• ai_flags = AI_ADDRCONFIG
• ai_family = AF_UNSPEC
• ai_socktype = 0
• ai_protocol = 0