getaddrinfo function

2022-07-09 10:10:04

The getaddrinfo function provides protocol-independent translation from an ANSI host name to an address.

int getaddrinfo(

  PCSTR      pNodeName,

  PCSTR      pServiceName,

  ADDRINFOA  *pHints,

  PADDRINFOA *ppResult

);

pNodeName [in，可选]
指向NULL终止的ANSI字符串的指针，该字符串包含主机（节点）名称或数字主机地址字符串。对于Internet协议，数字主机地址字符串是点分十进制IPv4地址或IPv6十六进制地址。
pServiceName [in，可选]
指向NULL终止的ANSI字符串的指针，该字符串包含表示为字符串的服务名称或端口号。
服务名称是端口号的字符串别名。例如，“http”是由Internet工程任务组（IETF）定义的端口80的别名，作为Web服务器用于HTTP协议的默认端口。未指定端口号时，pServiceName参数的可能值在以下文件中列出：
％WINDIR％\ system32 \ drivers \ etc \ services
pHints [in，可选]
指向addrinfo结构的指针，提供有关调用程序支持的套接字类型的提示。
由pHints参数指向的addrinfo结构的ai_addrlen，ai_canonname，ai_addr和ai_next成员必须为零或NULL。否则，GetAddrInfoEx函数将失败，并返回WSANO_RECOVERY。
有关详细信息，请参阅备注。
ppResult [out]
指向一个或多个addrinfo结构的链接列表的指针，其中包含有关主机的响应信息。
Return:

成功返回零。失败返回一个非零的Windows Sockets错误代码，在Windows套接字错误代码中找到。
getaddrinfo函数返回的大多数非零错误代码映射到Internet工程任务组（IETF）建议中列出的一组错误。下表列出了这些错误代码及其WSA等效项。建议使用WSA错误代码，因为它们为Winsock程序员提供了熟悉且全面的错误信息。

使用gai_strerror函数根据getaddrinfo函数返回的EAI代码打印错误消息。 gai_strerror函数是为了符合IETF建议而提供的，但它不是线程安全的。因此，建议使用传统的Windows Sockets函数，如WSAGetLastError。

Error code	Meaning
WSA_NOT_ENOUGH_MEMORY	没有足够的内存来执行操作
WSAEAFNOSUPPORT	使用与请求的协议不兼容的地址。如果不支持pHints参数指向的addrinfo结构的ai_family成员，则返回此错误。
WSAEINVAL	提供了无效的参数。如果为pHints参数指向的addrinfo结构的ai_flags成员提供了无效值，则会返回此错误。
WSAESOCKTNOSUPPORT	在此地址系列中不存在对指定套接字类型的支持。如果不支持pHints参数指向的addrinfo结构的ai_socktype成员，则返回此错误。
WSAHOST_NOT_FOUND	没有这样的主机是已知的。如果提供的参数的名称未解析或未提供pNodeName和pServiceName参数，则会返回此错误。
WSANO_DATA	请求的名称有效，但未找到请求类型的数据
WSANO_RECOVERY	在数据库查找期间发生不可恢复的错误。如果发生名称解析中的不可恢复错误，则返回此错误。
WSANOTINITIALISED	在使用此函数之前必须发生成功的WSAStartup调用。
WSATRY_AGAIN	这通常是在主机名解析期间的临时错误，并且意味着本地服务器没有从权威服务器收到响应。当名称解析发生临时故障时，将返回此错误。
WSATYPE_NOT_FOUND	找不到指定的类。对于pHints参数指向的addrinfo结构的指定ai_socktype成员，不支持pServiceName参数。

getaddrinfo函数的调用者可以通过pHints参数指向的addrinfo结构提供关于支持的套接字类型的提示。当使用pHints参数时，以下规则适用于其关联的addrinfo结构：
ai_family的AF_UNSPEC值表示主叫方将只接受AF_INET和AF_INET6地址系列。注意，AF_UNSPEC和PF_UNSPEC是相同的。
ai_socktype的值为零表示调用者将接受任何套接字类型。
ai_protocol的值为零表示调用者将接受任何协议。
ai_addrlen成员必须设置为零。
ai_canonname成员必须设置为NULL。
ai_addr成员必须设置为NULL。
ai_next成员必须设置为NULL。
ai_family的AF_UNSPEC值表示调用者将接受任何协议系列。此值可用于返回pNodeName参数指向的主机名的IPv4和IPv6地址。在Windows Server 2003和Windows XP上，只有在本地计算机上安装了IPv6时才会返回IPv6地址。

pHints参数中提供的addrinfo结构中的其他值表示具体要求。例如，如果调用者仅处理IPv4并且不处理IPv6，则ai_family成员应设置为AF_INET。另一个例子，如果调用者仅处理TCP而不处理UDP，则ai_socktype成员应设置为SOCK_STREAM。
如果pHints参数是NULL指针，则getaddrinfo函数将其视为在pHint中的addrinfo结构已使用其ai_family成员设置为AF_UNSPEC并将所有其他成员设置为零的方式进行初始化。
在Windows Vista及更高版本中，当从服务调用getaddrinfo时，如果操作是用户进程调用服务的结果，则服务应模拟用户。这是为了允许正确实施安全。
getaddrinfo函数可以用于将IP地址的文本字符串表示转换为addrinfo结构，该结构包含用于IP地址和其他信息的sockaddr结构。要以这种方式使用，pNodeName参数指向的字符串必须包含IP地址的文本表示，并且pHints参数指向的addrinfo结构必须在ai_flags成员中设置AI_NUMERICHOST标志。

pNodeName参数指向的字符串可能包含IPv4或IPv6地址的文本表示。文本IP地址将转换为ppResult参数指向的addrinfo结构。返回的addrinfo结构包含IP地址的sockaddr结构以及有关IP地址的附加信息。要使此方法在Windows Server 2003和Windows XP上使用IPv6地址字符串，必须在本地计算机上安装IPv6协议。否则，返回WSAHOST_NOT_FOUND错误。
从动态分配释放地址信息
由ppResult参数指向的getaddrinfo函数返回的所有信息都是动态分配的，包括addrinfo结构指向的所有addrinfo结构，套接字地址结构和规范主机名字符串。成功调用此函数所分配的内存必须随后调用freeaddrinfo来释放。

The flag bits can be a combination of the following:

Flag Bits	Description
AI_PASSIVE	设置AI_PASSIVE标志表示调用者打算在调用bind函数时使用返回的套接字地址结构。当设置AI_PASSIVE标志并且pNodeName是NULL指针时，套接字地址结构的IP地址部分对于IPv4地址设置为INADDR_ANY，对于IPv6地址设置为IN6ADDR_ANY_INIT。当未设置AI_PASSIVE标志时，返回的套接字地址结构已准备好用于面向连接的协议的connect函数的调用，或者准备好对无连接协议的connect，sendto或send函数的调用。如果在这种情况下pNodeName参数是NULL指针，则套接字地址结构的IP地址部分将设置为环回地址。
AI_CANONNAME	如果既不使用AI_CANONNAME，也不使用AI_NUMERICHOST，则getaddrinfo函数尝试解析。如果传递的是字符串getaddrinfo尝试转换字符串，并且如果传递主机名，getaddrinfo函数会尝试将该名称解析为一个地址或多个地址。当设置AI_CANONNAME位时，pNodeName参数不能为NULL。否则，getaddrinfo函数将失败，并返回WSANO_RECOVERY。当AI_CANONNAME位置1且getaddrinfo函数返回成功时，ppResult参数中的ai_canonname成员指向包含指定节点的规范名称的以NULL结尾的字符串。注意当设置AI_CANONNAME标志时，getaddrinfo函数可以返回成功，但关联的addrinfo结构中的ai_canonname成员为NULL。因此，建议使用AI_CANONNAME标志包括测试关联addrinfo结构中的ai_canonname成员是否为NULL。
AI_NUMERICHOST	当AI_NUMERICHOST位置1时，pNodeName参数必须包含非NULL数字主机地址字符串，否则返回EAI_NONAME错误。此标志阻止调用名称解析服务。
AI_NUMERICSERV	当设置了AI_NUMERICSERV位时，pServiceName参数必须包含非NULL数字端口号，否则返回EAI_NONAME错误。此标志阻止调用名称解析服务。 AI_NUMERICSERV标志在Windows Vista及更高版本的Windows SDK上定义。 Microsoft提供程序不支持AI_NUMERICSERV标志。
AI_ALL	如果设置了AI_ALL位，则会通过AI_V4MAPPED请求IPv6地址和IPv4地址。 AI_ALL标志在Windows Vista及更高版本的Windows SDK上定义。 Windows Vista及更高版本支持AI_ALL标志。
AI_ADDRCONFIG	如果设置了AI_ADDRCONFIG位，则仅当配置了全局地址时，getaddrinfo才会解析。如果指定了AI_ADDRCONFIG标志，则只有在本地系统上配置了IPv4地址时才会返回IPv4地址，并且只有在本地系统上配置了IPv6地址时才会返回IPv6地址。 IPv4或IPv6环回地址不被认为是有效的全局地址。 AI_ADDRCONFIG标志在Windows Vista及更高版本的Windows SDK上定义。 Windows Vista及更高版本支持AI_ADDRCONFIG标志。
AI_V4MAPPED	如果设置了AI_V4MAPPED位，并且对IPv6地址的请求失败，则对IPv4地址进行名称服务请求，这些地址将转换为IPv4映射IPv6地址格式。 AI_V4MAPPED标志在Windows Vista及更高版本的Windows SDK上定义。 Windows Vista及更高版本支持AI_V4MAPPED标志。
AI_NON_AUTHORITATIVE	如果设置了AI_NON_AUTHORITATIVE位，则NS_EMAIL命名空间提供程序返回权威和非权威结果。如果未设置AI_NON_AUTHORITATIVE位，则NS_EMAIL命名空间提供程序仅返回权威性结果。 AI_NON_AUTHORITATIVE标志在Windows Vista及更高版本的Windows SDK上定义。 AI_NON_AUTHORITATIVE标志在Windows Vista及更高版本上受支持，并且仅适用于NS_EMAIL命名空间。
AI_SECURE	如果设置了AI_SECURE位，NS_EMAIL命名空间提供程序将返回通过增强的安全性获得的结果，以尽可能减少可能的欺骗。 AI_SECURE标志在Windows Vista及更高版本的Windows SDK上定义。在Windows Vista和更高版本上支持AI_SECURE标志，并且仅适用于NS_EMAIL命名空间。
AI_RETURN_PREFERRED_NAMES	如果设置了AI_RETURN_PREFERRED_NAMES，则pNodeName参数中不应提供任何名称。 NS_EMAIL命名空间提供程序将返回用于发布的首选名称。 AI_RETURN_PREFERRED_NAMES标志在Windows Vista及更高版本的Windows SDK上定义。 AI_RETURN_PREFERRED_NAMES标志在Windows Vista及更高版本上受支持，并且仅适用于NS_EMAIL命名空间。
AI_FQDN	如果设置了AI_FQDN并且指定了平面名称（单个标签），getaddrinfo将返回名称最终解析为的完全限定域名。完全限定域名在关联addrinfo结构中的ai_canonname成员中返回。这与AI_CANONNAME位标记不同，后者返回在DNS中注册的规范名称，该名称可能与平面名称解析为的完全限定域名不同。只能设置AI_FQDN和AI_CANONNAME位中的一个。如果EAI_BADFLAGS同时存在这两个标志，getaddrinfo函数将失败。当AI_FQDN位置1时，pNodeName参数不能为NULL。否则，GetAddrInfoEx函数将失败，并返回WSANO_RECOVERY。 Windows 7：AI_FQDN标志在Windows 7和更高版本的Windows SDK上定义。 Windows 7及更高版本支持AI_FQDN标志。
AI_FILESERVER	如果设置了AI_FILESERVER，则这是命名空间提供程序的一个提示，即正在查询的主机名正在文件共享方案中使用。命名空间提供程序可以忽略此提示。 Windows 7：AI_FILESERVER标志在Windows 7和更高版本的Windows SDK上定义。 Windows 7及更高版本支持AI_FILESERVER标志。

注意确保开发环境目标为Ws2tcpip.h的最新版本，它们分别包括addrinfo和getaddrinfo的结构和函数定义。

具体参考：https://msdn.microsoft.com/zh-cn/library/windows/desktop/ms738520(v=vs.85).aspx

码农公寓

相关文章