GetServiceA 函数（nspapi.h）

项目
11/20/2024

GetService 函数在一组默认命名空间或指定命名空间的上下文中检索有关网络服务的信息。网络服务按其类型和名称指定。有关服务的信息作为一组 NS_SERVICE_INFO 数据结构获取。

注释GetService 函数是特定于 Windows 套接字 1.1 规范的Microsoft扩展。此函数已过时。为方便 Windows 套接字 1.1 开发人员，此参考资料已包含在内。

注意Protocol-Independent 名称解析中详述的函数在 Windows 套接字 2 中提供等效的功能。

语法

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

参数

[in] dwNameSpace

该命名空间或一组默认命名空间，操作系统应查询有关指定网络服务的信息。

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

价值	意义
NS_DEFAULT	一组默认命名空间。操作系统查询此集中的每个命名空间。默认命名空间集通常包括系统上安装的所有命名空间。但是，系统管理员可以从集中排除特定命名空间。 NS_DEFAULT是大多数应用程序应用于 dwNameSpace的值。
NS_DNS	Internet 中使用的域名系统用于主机名解析。
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 文件中查找主机名和 IP 地址。
NS_TCPIP_LOCAL	本地 TCP/IP 名称解析机制，包括与本地主机名进行比较，并在主机缓存中查找主机名和 IP 地址与 IP 地址映射。

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

[in] lpGuid

指向指定网络服务类型的全局唯一标识符（GUID）的指针。 Svcguid.h 头文件包括来自 DNS 和 SAP 命名空间中许多已知服务的 GUID 服务类型。

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

[in] lpServiceName

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

[in] dwProperties

一组位标志，用于指定函数检索的服务信息。除PROP_ALL以外的每个位标志常量对应于 SERVICE_INFO 数据结构的特定成员。如果设置了标志，该函数会将信息放入存储在 *lpBuffer中的数据结构的相应成员中。定义了以下位标志。

价值	意义
PROP_COMMENT	如果设置了此标志，函数会将数据存储在存储在 *lpBuffer中的数据结构的 lpComment 成员中。
PROP_LOCALE	如果设置了此标志，函数会将数据存储在存储在 *lpBuffer中的数据结构的 lpLocale 成员中。
PROP_DISPLAY_HINT	如果设置了此标志，函数会将数据存储在存储在 *lpBuffer中的数据结构的 dwDisplayHint 成员中。
PROP_VERSION	如果设置了此标志，函数会将数据存储在存储在 *lpBuffer中的数据结构的 dwVersion 成员中。
PROP_START_TIME	如果设置了此标志，函数会将数据存储在存储在 *lpBuffer中的数据结构的 dwTime 成员中。
PROP_MACHINE	如果设置了此标志，函数会将数据存储在存储在 *lpBuffer中的数据结构的 lpMachineName 成员中。
PROP_ADDRESSES	如果设置了此标志，函数会将数据存储在 lpServiceAddress 存储在 *lpBuffer中的数据结构的成员中。
PROP_SD	如果设置了此标志，函数会将数据存储在 ServiceSpecificInfo 中存储在 *lpBuffer中的数据结构的成员。
PROP_ALL	如果设置了此标志，函数会将数据存储在 *lpBuffer中存储的数据结构的所有成员中。

[out] lpBuffer

指向缓冲区的指针，用于接收 NS_SERVICE_INFO 结构和关联的服务信息的数组。每个 NS_SERVICE_INFO 结构都包含特定命名空间上下文中的服务信息。请注意，如果 dwNameSpace NS_DEFAULT，函数会将多个结构存储在缓冲区中;否则，只存储一个结构。

每个 NS_SERVICE_INFO 结构都包含一个 SERVICE_INFO 结构。这些 SERVICE_INFO 结构的成员将包含基于 dwProperties 参数中设置的位标志的有效数据。如果未在 dwProperties中设置成员的相应位标志，则成员的值是未定义的。

该函数将 NS_SERVICE_INFO 结构存储在连续数组中，从缓冲区的开头开始。包含 SERVICE_INFO 结构中的指针指向存储在 NS_SERVICE_INFO 结构和缓冲区末尾之间的缓冲区中的信息。

[in, out] lpdwBufferSize

指向一个变量的指针，该变量在输入上包含由 lpBuffer指向的缓冲区的大小（以字节为单位）。在输出中，此变量包含存储所请求信息所需的字节数。如果此输出值大于输入值，则函数由于缓冲区大小不足而失败。

[in, optional] lpServiceAsyncInfo

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

返回值

如果函数成功，则返回值是存储在 *lpBuffer中的 NS_SERVICE_INFO 结构的数目。零表示未存储任何结构。

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

错误代码	意义
ERROR_INSUFFICIENT_BUFFER	lpBuffer 指向的缓冲区太小，无法接收所有请求的信息。调用缓冲区至少与 *lpdwBufferSize中返回的值一样大的函数。
ERROR_SERVICE_NOT_FOUND	找不到指定的服务，或者指定的命名空间未使用。在这种情况下，函数返回值为零。

言论

注意

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

要求

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