getaddrinfo
This function provides protocol-independent translation from host name to address.
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 Values
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.
| Error code | WSA* equivalent | Description |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | Temporary failure in name resolution. |
| EAI_BADFLAGS | WSAEINVAL | Invalid value for ai_flags. |
| EAI_FAIL | WSANO_RECOVERY | Nonrecoverable failure in name resolution. |
| EAI_FAMILY | WSAEAFNOSUPPORT | The ai_family member is not supported. |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Memory allocation failure. |
| EAI_NODATA | WSANO_DATA | No address associated with nodename. |
| EAI_NONAME | WSAHOST_NOT_FOUND | Neither nodename nor servname provided, or not known. |
| EAI_SERVICE | WSATYPE_NOT_FOUND | The servname parameter is not supported for ai_socktype. |
Remarks
One or both of the nodename or servname parameters must point to a NULL-terminated string; generally both are provided.
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.
| Flag | Description |
|---|---|
| AI_PASSIVE | If set, this flag indicates the caller intends to use the returned socket address structure in a call to the bind (Windows Sockets) function. If this flag is set and nodename is a NULL pointer, the IP address portion of the of the socket address structure is set to INADDR_ANY for IPv4 addresses and IN6ADDR_ANY_INIT for IPv6 addresses.
If this flag is not set, the returned socket address structure is ready for a call to the connect (Windows Sockets) function for a connection-oriented protocol, or ready for a call to either the connect (Windows Sockets), sendto, or send functions for a connectionless protocol. If the nodename parameter is a NULL pointer in this case, the IP address portion of the socket address structure is set to the loopback address. |
| AI_CANONNAME | If this flag is set and the getaddrinfo function returns success, the ai_canonname member in the hints parameter points to a NULL-terminated string that contains the canonical name of the specified node.
Note The gettaddrinfo function can return success when the AI_CANNONNAME flag is set, yet the ai_canonname member in the associated addrinfo structure is NULL. Therefore, the recommended use of the AI_CANONNAME flag includes testing whether the ai_canonname member in the associated addrinfo structure is NULL. |
| AI_NUMERICHOST | If this flag is set, the nodename parameter must contain a non-NULL numeric host address string, otherwise the EAI_NONAME error is returned. This prevents a name resolution service from being called; all information returned by the getaddrinfo function is dynamically allocated. |
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
OS Versions: Windows CE .NET 4.1 and later.
Header: Ws2tcpip.h.
Link Library: Ws2.lib.
See Also
bind (Windows Sockets) | connect (Windows Sockets) | send | sendto | socket (Windows Sockets) | addrinfo | freeaddrinfo | WSAGetLastError
Last updated on Saturday, April 10, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.