getaddrinfo

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function provides protocol-independent translation from host name to address.

Syntax

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

Parameters

• nodename
  [in] Pointer to a NULL-terminated 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 hexadecimal address.

• servname
  [in] Pointer to a NULL-terminated string containing either a service name or port number.

• hints
  [in] Pointer to an addrinfo structure that provides hints about the type of socket the caller supports.

• res
  [out] Pointer to a linked list of one or more addrinfo structures containing response information about the host.

Return Value

This function returns zero when successful. The return of a nonzero Windows Sockets error code indicates failure.

Nonzero error codes returned by this function also map to the set of errors outlined by IETF recommendations. The following table shows these error codes and their WSA* equivalents. The following table shows the WSA* error codes. It is recommended that these WSA* error codes be used, as they offer familiar and comprehensive error information for Windows Sockets programmers.

Remarks

One or both of the nodename or servname parameters must point to a NULL-terminated string; generally both are provided.

The maximum number of addresses returned when trying to resolve a name is 15.

Upon success, a linked list of addrinfo structures is returned in the res parameter; the list can be processed by following the pointer provided in the ai_next member of each returned addrinfo structure until a NULL pointer is encountered. In each returned addrinfo structure, the ai_family, ai_socktype, and ai_protocol members correspond to respective arguments in a socket (Windows Sockets) function call. Also, the ai_addr member in each returned addrinfo structure points to a filled-in socket address structure, the length of which is specified in its ai_addrlen member.

Callers of the getaddrinfo function can provide hints about the type of socket supported through an addrinfo structure pointed to by the hints parameter. When the hints parameter is used, rules apply to its associated addrinfo structure. The following list shows the rules that apply:

• A value of PF_UNSPEC for ai_family indicates the caller will accept any protocol family.
• A value of zero for ai_socktype indicates the caller will accept any socket type.
• A value of zero for ai_protocol indicates the caller will accept any protocol.
• ai_addrlen must be zero or a NULL pointer
• ai_canonname must be zero or a NULL pointer
• ai_addr must be zero or a NULL pointer
• ai_next must be zero or a NULL pointer

Other values in the addrinfo structure provided in the hints parameter indicate specific requirements. For example, if the caller handles only TCP and does not handle UDP, the ai_socktype member should be set to SOCK_STREAM. For another example, If the caller handles only IPv4 and does not handle IPv6, the ai_family member should be set to PF_INET.

If the hints parameter is a NULL pointer, the getaddrinfo function treats it as if the addrinfo structure in hints were initialized with its ai_family member set to PF_UNSPEC and all other members set to zero.

Use of ai_flags in the hints parameter

The following table shows flags in the ai_flags member of the optional addrinfo structure provided in the hints parameter.

If neither AI_CANONNAME nor AI_NUMERICHOST is used, the getaddrinfo function attempts resolution. If a literal string is passed getaddrinfo attempts to convert the string, and if a host name is passed the getaddrinfo function attempts to resolve it.

Freeing Address Information from Dynamic Allocation

All information returned by the getaddrinfo function is dynamically allocated, including all addrinfo structures, socket address structures, and canonical host name strings pointed to by addrinfo structures. To return that information to the system, call the freeaddrinfo function.

Requirements

See Also

Reference

bind (Windows Sockets)
connect (Windows Sockets)
send
sendto
socket (Windows Sockets)
addrinfo
freeaddrinfo
WSAGetLastError