getaddrinfo translates the name of a service location, e.g., hostname 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(
[in, optional] const char *nodename,
[in, optional] const char *servname,
[in, optional] const struct addrinfo *hints,
[out] struct addrinfo **res
);Parameters
[in, optional] 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.
[in, optional] 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.
[in, optional] hints
A pointer to an addrinfo structure that provides hints about the socket type 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 (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 the unsupported values.
[out] res
A pointer to a linked list of one or more addrinfo structures containing response information about the host.
Return Value
If the function succeeds, it returns 0 (zero). If the function fails, it returns a non-zero positive value.
Possible error codes:
|
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 fails. |
|
WSAHOST_NOT_FOUND |
The node or service is unknown. 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 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
Requirements
| Minimum supported version | Header | Library |
|---|---|---|
|
wRTOS 1.0 SDK |
ws2tcpip.h |
RttcpipApi.lib |
