WSALookupServiceBeginA 函数 (winsock2.h)

项目
03/04/2024

WSALookupServiceBegin 函数启动受 WSAQUERYSET 结构中包含的信息约束的客户端查询。 WSALookupServiceBegin 仅返回句柄，后续调用 WSALookupServiceNext 时应使用该句柄来获取实际结果。

语法

INT WSAAPI WSALookupServiceBeginA(
  [in]  LPWSAQUERYSETA lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

参数

[in] lpqsRestrictions

指向搜索条件的指针。有关详细信息，请参见备注。

[in] dwControlFlags

一组控制搜索深度的标志。

dwControlFlags 参数的支持值在 Winsock2.h 头文件中定义，可以是以下选项的组合。

标志	含义
LUP_DEEP 0x0001	查询深度，而不仅仅是第一个级别。
LUP_CONTAINERS 0x0002	仅返回容器。
LUP_NOCONTAINERS 0x0004	不要返回容器。
LUP_NEAREST 0x0008	如果可能，按距离顺序返回结果。距离度量值特定于提供程序。
LUP_RETURN_NAME 0x0010	检索名称为 lpszServiceInstanceName。
LUP_RETURN_TYPE 0x0020	检索类型为 lpServiceClassId。
LUP_RETURN_VERSION 0x0040	以 lpVersion 的形式检索版本。
LUP_RETURN_COMMENT 0x0080	检索注释作为 lpszComment。
LUP_RETURN_ADDR 0x0100	以 lpcsaBuffer 的形式检索地址。
LUP_RETURN_BLOB 0x0200	以 lpBlob 的形式检索私有数据。
LUP_RETURN_ALIASES 0x0400	任何可用的别名信息都将在对 WSALookupServiceNext 的连续调用中返回，并且返回的每个别名都将设置RESULT_IS_ALIAS标志。
LUP_RETURN_QUERY_STRING 0x0800	检索用于请求的查询字符串。
LUP_RETURN_ALL 0x0FF0	一组标志，用于检索所有LUP_RETURN_* 值。
LUP_FLUSHPREVIOUS 0x1000	用作 WSALookupServiceNext 中 dwControlFlags 参数的值。设置此标志指示提供程序放弃最后一个结果集（对于指定的缓冲区太大），并转到下一个结果集。
LUP_FLUSHCACHE 0x2000	如果提供程序一直在缓存信息，则忽略缓存，并查询命名空间本身。
LUP_RES_SERVICE 0x8000	这指示主要响应是位于 CSADDR_INFO 结构的远程部分还是本地部分。在任一情况下，另一部分都需要可用。

[out] lphLookup

调用 WSALookupServiceNext 时要用于开始检索结果集的句柄。

返回值

如果操作成功，则返回值为零。否则，将返回值SOCKET_ERROR，并且可以通过调用 WSAGetLastError 检索特定的错误号。

错误代码	含义
WSA_NOT_ENOUGH_MEMORY	内存不足，无法执行操作。
WSAEINVAL	此提供程序缺少一个或多个参数或参数无效。
WSANO_DATA	在数据库中找到了该名称，但没有找到与给定限制匹配的数据。
WSANOTINITIALIZED	尚未初始化 WS2_32.DLL。应用程序必须先调用 WSAStartup，然后才能调用任何 Windows 套接字函数。
WSASERVICE_NOT_FOUND	无法识别此类服务。在指定的名称空间中找不到该服务。如果未找到远程蓝牙设备，则会为蓝牙服务发现请求返回此错误。

注解

lpqsRestrictions 参数指向包含 WSAQUERYSET 结构的缓冲区。在调用 WSALookupServiceBegin 函数之前，至少必须将 WSAQUERYSET 的 dwSize 成员设置为缓冲区的长度。应用程序可以通过在 WSAQUERYSET 中指定其他成员来限制查询。

在大多数情况下，仅对特定传输协议感兴趣的应用程序应使用 WSAQUERYSET 的 dwNumberOfProtocols 和 lpafpProtocols 成员（而不是指定 dwNameSpace 成员中的命名空间）来限制其查询。

可以使用 EnumProtocols、WSAEnumProtocols、WSCEnumProtocols 或 WSCEnumProtocols32 函数重新获取有关支持的网络传输协议的信息。

还可以将查询限制为单个命名空间。例如，仅需要来自 DNS (而不是来自本地主机文件和其他命名服务的结果的查询) 会将 dwNameSpace 成员设置为 NS_DNS。例如，蓝牙设备发现会将 dwNameSpace 成员设置为 NS_BTH。

应用程序还可以通过在 lpNSProviderId 成员中指定指向提供程序的 GUID 的指针，将查询限制为特定的命名空间提供程序。

可以使用 WSAEnumNameSpaceProviders、WSAEnumNameSpaceProvidersEx、WSCEnumNameSpaceProviders32 或 WSCEnumNameSpaceProvidersEx32 函数检索有关本地计算机上的命名空间提供程序的信息。

如果在调用中指定了LUP_CONTAINERS，应避免使用其他限制值。如果指定了任何限制，则由名称服务提供商决定它是否可以支持对容器的此限制。如果不能，应返回错误。

某些名称服务提供商可以采用其他方法来查找容器。例如，容器可能全部属于某种已知类型，或者属于一组已知类型，因此可以创建查询限制来查找它们。无论服务提供程序的名称用于查找容器的其他含义是什么，LUP_CONTAINERS和LUP_NOCONTAINERS优先。因此，如果给定包含容器的查询限制，则指定LUP_NOCONTAINERS将阻止返回容器项。同样，无论查询限制如何，如果给定LUP_CONTAINERS，则只应返回容器。如果命名空间不支持容器，并且指定了LUP_CONTAINERS，则它应仅返回 WSANO_DATA。

获取另一个容器中的容器的首选方法是调用：

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

此调用后跟必要的 WSALookupServiceNext 调用数。这将返回立即包含在起始上下文中的所有容器;也就是说，它不是深度查询。这样，就可以通过遍历层次结构来映射地址空间结构，或许可以枚举所选容器的内容。 WSALookupServiceBegin 的后续使用使用从上一次调用返回的容器。

如上所述， WSAQUERYSET 结构用作 WSALookupBegin 的输入参数，以便限定查询。下表指示如何使用 WSAQUERYSET 构造查询。当参数标记为 (可选) 可以指定 NULL 指针，指示该参数不会用作搜索条件。有关其他信息，请参阅与查询相关的数据结构部分。

WSAQUERYSET 成员	查询解释
dwSize	必须设置为 sizeof (WSAQUERYSET) 。这是一种版本控制机制。
dwOutputFlags	对于查询，忽略。
lpszServiceInstanceName	(引用的可选) 字符串包含服务名称。字符串中通配符的语义未定义，但某些命名空间提供程序可以支持这些语义。
lpServiceClassId	(必需) 与服务类对应的 GUID。
lpVersion	(可选) 引用所需的版本号，并提供版本比较语义 (，即版本必须完全匹配，或者版本必须不小于) 指定的值。
lpszComment	对于查询，忽略。
dwNameSpace 请参阅后面的重要说明。	要在其中约束搜索的单个命名空间的标识符，或NS_ALL包含所有命名空间。
lpNSProviderId	(可选) 引用特定命名空间提供程序的 GUID，并将查询限制为此提供程序。
lpszContext	(可选) 指定分层命名空间中查询的起点。
dwNumberOfProtocols	协议约束数组的大小可以为零。
lpafpProtocols	(可选) 引用 AFPROTOCOLS 结构的数组。仅返回使用这些协议的服务。
lpszQueryString	(可选) 某些 (命名空间（如 whois++) ）支持包含在简单文本字符串中的类似 SQL 的扩充查询。此参数用于指定该字符串。
dwNumberOfCsAddrs	对于查询，忽略。
lpcsaBuffer	对于查询，忽略。
lpBlob	(可选) 这是指向特定于提供程序的实体的指针。

重要在大多数情况下，仅对特定传输协议感兴趣的应用程序应按地址系列和协议（而不是命名空间）约束其查询。这将允许需要查找 TCP/IP 服务的应用程序（例如，由所有可用的命名空间（如本地主机文件、DNS 和 NIS）处理其查询。

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone Store 应用支持 WSALookupServiceBeginW 函数。

Windows 8.1和Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持 WSALookupServiceBeginW 函数。

注意

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

要求

要求	值
最低受支持的客户端	Windows 8.1、Windows Vista [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	winsock2.h
Library	Ws2_32.lib
DLL	Ws2_32.dll