通过

GetAddressByNameA 函数 （nspapi.h）

  • 项目

[GetAddressByName 不再可用于 Windows 套接字 2。 请改用 Protocol-Independent 名称解析中详述的函数。]

GetAddressByName 函数查询命名空间或一组默认命名空间，以检索指定网络服务的网络地址信息。 此过程称为服务名称解析。 网络服务还可以使用该函数获取可与 绑定 函数一起使用的本地地址信息。

语法

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

参数

[in] dwNameSpace

操作系统应查询网络地址信息的命名空间或默认命名空间集。

使用以下常量之一指定命名空间。

价值 意义
NS_DEFAULT
 一组默认命名空间。 该函数查询此集中的每个命名空间。 默认命名空间集通常包括系统上安装的所有命名空间。 但是，系统管理员可以从集中排除特定命名空间。 这是大多数应用程序应用于 dwNameSpace的值。
NS_DNS
 Internet 中使用的域名系统（DNS）用于主机名解析。
NS_NETBT
 基于 TCP/IP 层的 NetBIOS。 所有操作系统都将其计算机名称注册到 NetBIOS。 此命名空间用于将计算机名称转换为使用此注册的 IP 地址。 请注意，NS_NETBT可以访问 WINS 服务器来执行解析。
NS_SAP
 NetWare 服务广告协议。 如果适用，则可以访问 NetWare bindery。 NS_SAP是一个允许注册服务的动态命名空间。
NS_TCPIP_HOSTS
 <systemroot>\system32\drivers\etc\hosts 文件中的查阅值。
NS_TCPIP_LOCAL
 本地 TCP/IP 名称解析机制，包括与本地主机名进行比较，并在主机缓存中查找主机名和 IP 地址与 IP 地址映射。
 

对 GetAddressByName 的大多数调用都应使用特殊值NS_DEFAULT。 这样一来，客户端就无需了解 Internetwork 上提供哪些命名空间。 系统管理员确定命名空间访问权限。 命名空间可以来去去，而无需客户端知道更改。

[in] lpServiceType

指向指定网络服务类型的全局唯一标识符（GUID）的指针。 Svcguid.h 头文件包括多个 GUID 服务类型的定义，以及用于处理它们的宏。

Winsock2.h 头文件不会自动包含 Svcguid.h 头文件。

[in, optional] lpServiceName

指向唯一表示服务名称的零终止字符串的指针。 例如，“MY SNA SERVER”。

将 lpServiceName 设置为 NULL 等效于 将 dwResolution 设置为 RES_SERVICE。 该函数在其第二种模式下运行，获取指定类型的服务应绑定到的本地地址。 该函数将本地地址存储在存储在 *lpCsaddrBuffer的 CSADDR_INFO 结构的 LocalAddr 成员中。

如果 dwResolution 设置为RES_SERVICE，则函数将忽略 lpServiceName 参数。

如果 dwNameSpace 设置为NS_DNS，*lpServiceName 是主机的名称。

[in, optional] lpiProtocols

指向协议标识符零终止数组的指针。 该函数将名称解析尝试限制为提供这些协议的命名空间提供程序。 这允许调用方限制搜索的范围。

如果 lpiProtocols 设置为 NULL，则该函数将检索所有可用协议的信息。

[in] dwResolution

一组位标志，用于指定服务名称解析过程的各个方面。 定义了以下位标志。

价值 意义
RES_SERVICE
 如果设置，该函数将检索指定类型的服务应绑定到的地址。 这相当于将 lpServiceName 参数设置为 NULL。

如果此标志明确，则会发生正常名称解析。
RES_FIND_MULTIPLE
 如果设置了此标志，则操作系统会对服务的所有命名空间执行广泛的搜索。 它要求每个适当的命名空间解析服务名称。 如果此标志明确，则操作系统在找到服务地址后立即停止查找服务地址。
RES_SOFT_SEARCH
 如果命名空间支持多个级别的搜索，则此标志有效。

如果此标志有效并设置，操作系统将执行命名空间的简单快速搜索。 如果应用程序只需要获取服务的易于查找的地址，这非常有用。

如果此标志有效且清晰，则操作系统将执行更广泛的命名空间搜索。

[in, optional] lpServiceAsyncInfo

保留供将来使用;必须设置为 NULL。

[out] lpCsaddrBuffer

指向缓冲区的指针，用于接收一个或多个 CSADDR_INFO 数据结构。 写入缓冲区的结构数取决于解析尝试中找到的信息量。 应假定将写入多个结构，但在许多情况下，只有一个结构。

[in, out] lpdwBufferLength

指向变量的指针，该变量在输入时指定由 lpCsaddrBuffer指向的缓冲区的大小（以字节为单位）。

输出后，此变量包含存储 CSADDR_INFO 结构数组所需的字节总数。 如果此值小于或等于 *lpdwBufferLength的输入值，并且函数成功，则这是实际存储在缓冲区中的字节数。 如果此值大于 *lpdwBufferLength的输入值，则缓冲区太小，并且 *lpdwBufferLength 的输出值是所需的最小缓冲区大小。

[in, out] lpAliasBuffer

指向缓冲区的指针，用于接收网络服务的别名信息。

如果命名空间支持别名，函数会将零终止名称字符串的数组存储在由 lpAliasBuffer指向的缓冲区中。 列表末尾有一个双零终止符。 数组中的第一个名称是服务的主名称。 后面的名称是别名。 支持别名的命名空间示例是 DNS。

如果命名空间不支持别名，则会将双零终止符存储在缓冲区中。

此参数是可选的，可以设置为 NULL。

[in, out] lpdwAliasBufferLength

指向变量的指针，该变量在输入时指定由 lpAliasBuffer指向的缓冲区的大小（字符）。

输出后，此变量包含存储名称字符串数组所需的元素（字符）总数。 如果此值小于或等于 *lpdwAliasBufferLength的输入值，并且函数成功，则这是实际存储在缓冲区中的元素数。 如果此值大于 *lpdwAliasBufferLength的输入值，则缓冲区太小，并且 *lpdwAliasBufferLength 的输出值是所需的最小缓冲区大小。

如果 lpAliasBufferNULL，则 lpdwAliasBufferLength 毫无意义，也可以 NULL。

返回值

如果函数成功，则返回值是写入 lpCsaddrBuffer指向的缓冲区 CSADDR_INFO 数据结构的数目。

如果函数失败，则返回值SOCKET_ERROR（–1）。 若要获取扩展错误信息，请调用 GetLastError，这将返回以下扩展错误值。

错误代码 意义
ERROR_INSUFFICIENT_BUFFER
 lpCsaddrBuffer 指向的缓冲区太小，无法接收所有相关 CSADDR_INFO 结构。 调用缓冲区至少与 *lpdwBufferLength中返回的值一样大的函数。

言论

此函数是 gethostbyname 函数的更强大的版本。 GetAddressByName 函数适用于多个名称服务。

注释 引入 getaddrinfo 函数，已弃用 gethostbyname 函数。 敦促创建 Windows 套接字 2 应用程序的开发人员使用 getaddrinfo 函数，而不是 gethostbyname。
 

GetAddressByName 函数允许客户端获取网络服务的 Windows 套接字地址。 客户端按服务类型和服务名称指定感兴趣的服务。

许多名称服务都支持名称服务提供商在解析服务名称时考虑的默认前缀或后缀。 例如，在 DNS 命名空间中，如果域名为“nt.microsoft.com”，并且提供“ftp millikan”作为输入，则 DNS 软件无法解析“millikan”，但成功解析“millikan.nt.microsoft.com”。

请注意，GetAddressByName 函数可以通过两种方式搜索服务地址：在特定命名空间中或一组默认命名空间中。 使用默认命名空间时，管理员可以指定仅当按名称指定时，才会搜索某些命名空间的服务地址。 管理员或命名空间 - 安装程序还可以控制命名空间搜索的顺序。

注意

nspapi.h 标头将 GetAddressByName 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows 2000 Professional [仅限桌面应用]
支持的最低服务器 Windows 2000 Server [仅限桌面应用]
目标平台 窗户
标头 nspapi.h
库 Mswsock.lib
DLL Mswsock.dll

另请参阅

CSADDR_INFO

Winsock 函数

Winsock 参考

getaddrinfo

gethostbyname