|char * getaddrinfo||(|
|const char * nodeName,|
|const char * serviceName,|
|const struct addrinfo * hintsPtr,|
|struct addrinfo ** resPtrPtr|
Function DescriptionGet a list of IP addresses and port numbers for nodeName and serviceName, as supplied by the primary or secondary DNS server (see tfNgDnsSetServer()). IPv4 and IPv6 addresses are supported. Judicious use of the hintsPtr information will yield address information in resPtrPtr that can be used as input to socket functions socket(), bind(), connect(), sendto(), etc.
Parameter nodeName can be either be the NULL pointer, a fully qualified domain name (e.g. "www.treck.com"), a partial domain name (e.g. "www"), or the string representation of a numeric IPv4 or IPv6 address (e.g. "10.1.2.3" or "2003:db8::17"). Partial domain names are supported only if compile time macro TM_USE_DNS_DOMAIN_SEARCH is uncommented in trsystem.h. Non-global, numeric IPv6 addresses may include interface scope information as defined in RFC 4007, section 11. The scope information may be the name of the interface as specified in your tfAddInterface() call (e.g. "fe80::23%eth0"), or the numeric index that the interface name would return by calling if_nametoindex() (e.g. "fe80::23%2"). (The scope information is often required if you are sending or connecting to a remote host via its link-local IPv6 address.)
Currently, serviceName must either be the NULL pointer or a NUL-terminated string of decimal digits. The number provided is returned as the port number in all resPtrPtr results. If this parameter is NULL, nodeName must not be NULL and vice versa.
Parameter hintsPtr must either be the NULL pointer or a pointer to an address information structure that provides filtering rules for the resPtrPtr results. If hintsPtr is NULL, ai_flags defaults to the combination of flags AI_V4MAPPED and AI_ADDRCONFIG (see description below). By default, both IPv4 and IPv6 addresses are returned (ai_family == AF_UNSPEC). Use ai_family to restrict the results for dual IP systems to IPv4 (AF_INET) or IPv6 (AF_INET6) only.
- Return all IPv4 and IPv6 addresses found.
- Only return IPv4 addresses if no native IPv6 addresses are found. IPv4 addresses will be represented as IPv4-mapped IPv6 addresses.
- Return IPv4 addresses only if IPv4 is configured on this device; return IPv6 only if IPv6 is configured on this device.
- Requests the canonical name of the given host name. When set, the canonical name is returned in the ai_canonname field of the first returned addrinfo structure.
- Don't use name resolution. This flag can be set when passing the ASCII representation of an address to getaddrinfo, which causes it to behave like inet_pton().
- Don't use service resolution. This flag can be set when passing the service name as a port number in decimal string form to getaddrinfo.
- If this flag is not set, the results returned can be used with connect() or sendto() (sin_addr or sin6_addr will be set to the address of the remote host, depending on the address family). If this flag is set, the results returned can be used with bind() to receive from all remote hosts (for IPv4, sin_addr will be set to INADDR_ANY; for IPv6, sin6_addr will be set to in6addr_any).
These flags allow quite a bit of versatility, but here are some common settings for ai_flags and ai_family Only IPv4 addresses: ai_flags = 0; ai_family = AF_INET; Only IPv6 addresses: ai_flags = 0; ai_family = AF_INET6; All addresses (IPv4 and IPv6). IPv4 addresses will be represented as IPv4-mapped IPv6 addresses: ai_flags = AI_ALL; ai_family = AF_INET6; Only return IPv4 addresses if no IPv6 addresses are available. IPv4 addresses will be represented as IPv4-mapped IPv6 addresses: ai_flags = AI_V4MAPPED; ai_flags = AF_INET6;
Like all of the other DNS functions, getaddrinfo() can be used in non-blocking mode by specifying TM_BLOCKING_OFF when tfDnsInit() is called. In non-blocking mode, getaddrinfo() may return TM_EWOULDBLOCK. This indicates that the operation is in progress. Continue to call getaddrinfo() until a value other than TM_EWOULDBLOCK is returned, which indicates that the operation is complete. For example code using getaddrinfo() please see the <examples/txdns.c>.
- String containing nodename to translate. This may be a fully qualified domain name (e.g. "www.treck.com"), a partial domain name (only if compile time macro TM_USE_DNS_DOMAIN_SEARCH is uncommented in trsystem.h), or a numeric IPv4 or IPv6 address. This may be NULL if serviceName is not NULL.
- 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.
- Pointer to structure indicating which types of addresses the caller is interested in.
- Set to a pointer to one or more addrinfo structures containing address information about the specified nodename.
- Address information successfully retrieved.
- Specifying a service name is not supported.
- DNS request failed â requests to DNS server timed out.
- No route to DNS server.
- Indicates that an operation is currently in progress and has not yet completed. Only returned in non-blocking mode. (see above)
- AI_NUMERICHOST was specified but nodeName was not a valid numeric address for the given family type.
- Invalid flags specified in hint structure.
- Invalid protocol family (not PF_INET,PF_INET6 or PF_UNSPEC) in hint structure.
- No addresses (of the given address family) associated with the nodename.
- Not enough memory to allocate addrinfo structure(s) to be returned.
- Error from DNS server: Format error. The name server was unable to interpret the query.
- Error from DNS server: Server failure. The name server was unable to process this query due to a problem with the name server.
- Error from DNS server: Name error. Meaningful only for responses from an authoritative name server, this code signifies that the domain name referenced in the query does not exist.
- Error from DNS server: Not implemented. The name server does not support the requested kind of query.
- Error from DNS server: Refused. The name server refuses to perform the specified operation for policy reasons. For example, a name server may not wish to provide the information to the particular requester, or a name server may not wish to perform a particular operation (e.g., zone transfer) for particular data.
- No answer received from name server (i.e., response packet received, but it did not contain the answer to our query).
- Treck was unable to successfully allocate a socket for the DNS request. This could indicate Treck did not have the resources to allocate another socket. It could also be due to Treck hitting the limit of sockets set by TM_DNS_MAX_SOCKETS_ALLOWED or the tfDnsSetOption() option: TM_DNS_OPTION_MAX_SOCKETS_ALLOWED.