getAddressByNameA 函数 (nspapi.h)

  • 项目

[从 Windows 套接字 2 开始，GetAddressByName 不再可供使用。 请改用 独立于协议的名称解析中详述的函数。]

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

语法

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 绑定。 NS_SAP是允许注册服务的动态命名空间。
NS_TCPIP_HOSTS
 systemroot>\system32\drivers\etc\hosts 文件中的<查找值。
NS_TCPIP_LOCAL
 本地 TCP/IP 名称解析机制，包括与本地主机名的比较，以及查找主机到 IP 地址映射缓存中的主机名和 IP 地址。
 

对 GetAddressByName 的大多数调用应使用特殊值NS_DEFAULT。 这使客户端无需了解 Internet 上可用的命名空间即可获取。 系统管理员确定命名空间访问权限。 命名空间可以来来去去，客户端无需知道更改。

[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 的输出值是所需的最小缓冲区大小。

如果 lpAliasBuffer 为 NULL， 则 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 [仅限桌面应用]
目标平台 Windows
标头 nspapi.h
Library Mswsock.lib
DLL Mswsock.dll

另请参阅

CSADDR_INFO

Winsock 函数

Winsock 参考

getaddrinfo

gethostbyname