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.

One or both of the nodenameor servnameparameters 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 addrinfostructures is returned in the resparameter; the list can be processed by following the pointer provided in the ai_nextmember of each returned addrinfostructure until a NULL pointer is encountered. In each returned addrinfostructure, the ai_family, ai_socktype, and ai_protocolmembers correspond to respective arguments in a socket (Windows Sockets)function call. Also, the ai_addrmember in each returned addrinfostructure points to a filled-in socket address structure, the length of which is specified in its ai_addrlenmember.

Callers of the getaddrinfofunction can provide hints about the type of socket supported through an addrinfostructure pointed to by the hintsparameter. When the hintsparameter is used, rules apply to its associated addrinfostructure. The following list shows the rules that apply:

• A value of PF_UNSPEC for ai_familyindicates the caller will accept any protocol family.
  
  
• A value of zero for ai_socktypeindicates the caller will accept any socket type.
  
  
• A value of zero for ai_protocolindicates the caller will accept any protocol.
  
  
• ai_addrlenmust be zero or a NULL pointer
  
  
• ai_canonnamemust be zero or a NULL pointer
  
  
• ai_addrmust be zero or a NULL pointer
  
  
• ai_nextmust be zero or a NULL pointer
  
  

Other values in the addrinfostructure provided in the hintsparameter indicate specific requirements. For example, if the caller handles only TCP and does not handle UDP, the ai_socktypemember should be set to SOCK_STREAM. For another example, If the caller handles only IPv4 and does not handle IPv6, the ai_familymember should be set to PF_INET.

If the hintsparameter is a NULL pointer, the getaddrinfofunction treats it as if the addrinfostructure in hintswere initialized with its ai_familymember 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_flagsmember of the optional addrinfostructure provided in the hintsparameter.

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 nodenameis 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 sendfunctions for a connectionless protocol. If the nodenameparameter 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 getaddrinfofunction returns success, the ai_canonnamemember in the hintsparameter points to a NULL-terminated string that contains the canonical name of the specified node. Note: The gettaddrinfofunction can return success when the AI_CANNONNAME flag is set, yet the ai_canonnamemember in the associated addrinfostructure is NULL. Therefore, the recommended use of the AI_CANONNAME flag includes testing whether the ai_canonnamemember in the associated addrinfostructure is NULL.
AI_NUMERICHOST	If this flag is set, the nodenameparameter 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 getaddrinfofunction is dynamically allocated.

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