getServiceA 函数 (nspapi.h)

项目
02/29/2024

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

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

注意独立于协议的名称解析中详述的函数在 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 绑定（如果适用）。 NS_SAP 是允许注册服务的动态命名空间。
NS_TCPIP_HOSTS	在 <systemroot>\system32\drivers\etc\hosts 文件中查找主机名和 IP 地址。
NS_TCPIP_LOCAL	本地 TCP/IP 名称解析机制，包括与本地主机名的比较，以及查找主机到 IP 地址映射缓存中的主机名和 IP 地址。

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

[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	如果设置了此标志，函数会将数据存储在 *lpBuffer 中存储的数据结构的 lpServiceAddress 成员中。
PROP_SD	如果设置了此标志，函数会将数据存储在 *lpBuffer 中存储的数据结构的 ServiceSpecificInfo 成员中。
PROP_ALL	如果设置了此标志，函数会将数据存储在 *lpBuffer 中存储的所有数据结构成员中。

[out] lpBuffer

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

每个 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 [仅限桌面应用]
目标平台	Windows
标头	nspapi.h
Library	Mswsock.lib
DLL	Mswsock.dll

另请参阅

通过

getServiceA 函数 (nspapi.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源