LPNSPV2LOOKUPSERVICEBEGIN回调函数 (ws2spi.h)

项目
03/04/2024

NSPv2LookupServiceBegin 函数启动命名空间版本 2 服务提供程序的客户端查询，该提供程序受WSAQUERYSET2结构中包含的信息的约束。

语法

LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;

INT Lpnspv2lookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSET2W lpqsRestrictions,
  [in]  DWORD dwControlFlags,
  [out] LPVOID lpvClientSessionArg,
  [out] LPHANDLE lphLookup
)
{...}

参数

[in] lpProviderId

指向要查询的命名空间服务提供程序的标识符的指针。

[in] lpqsRestrictions

指向搜索条件的指针。请参阅“备注”。

[in] 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	将在对 NSPv2LookupServiceNextEx 的连续调用中返回任何可用的别名信息，并且返回的每个别名都将设置 “RESULT_IS_ALIAS” 标志。
LUP_RETURN_QUERY_STRING 0x0800	检索查询字符串作为 lpszQueryString。
LUP_RETURN_ALL 0x0ff0	检索信息，包括名称、类型、版本、注释、地址、blob、别名和查询字符串。
LUP_FLUSHCACHE 0x1000	如果提供程序已缓存信息，请忽略缓存并查询命名空间本身。
LUP_FLUSHPREVIOUS 0x2000	用作 NSPv2LookupServiceNextEx 中的 dwControlFlags 参数的值。设置此标志会指示提供程序放弃最后一个结果集（对于提供的缓冲区太大），并转到下一个结果集。
LUP_NON_AUTHORITATIVE 0x4000	指示命名空间提供程序应包含名称的非权威结果。
LUP_RES_RESERVICE 0x8000	指示主要响应是位于 CSADDR_INFO 结构的远程部分还是本地部分。在任一情况下，另一部分都必须可用。此选项仅适用于服务实例请求。
LUP_SECURE 0x8000	指示命名空间提供程序应使用安全查询。此选项仅适用于名称查询请求。
LUP_RETURN_PREFERRED_NAMES 0x10000	指示命名空间提供程序应仅返回首选名称。
LUP_ADDRCONFIG 0x100000	指示命名空间提供程序应返回地址配置。
LUP_DUAL_ADDR 0x200000	指示命名空间提供程序应返回双地址。此选项仅适用于 (IPv6 和 IPv4 映射地址) 的双模式套接字。
LUP_DISABLE_IDN_ENCODING 0x800000	指示命名空间提供程序应禁用自动国际域名编码。 Windows 8 和 Windows Server 2012 支持此值

[out] lpvClientSessionArg

指向客户端会话的指针。

[out] lphLookup

指向句柄的指针，用于后续调用 NSPv2LookupServiceNextEx 以检索结果集。

返回值

如果例程成功，函数应返回NO_ERROR (零) 。如果例程失败，它应返回 SOCKET_ERROR (即 1) ，并且必须使用 WSASetLastError 设置相应的错误代码。

错误代码	含义
WSAEINVAL	此提供程序的一个或多个参数无效或缺失。
WSANO_DATA	该名称是在数据库中找到的，但它没有为其解析的正确关联数据。
WSASERVICE_NOT_FOUND	服务未知。在指定的命名空间中找不到该服务。
WSA_NOT_ENOUGH_MEMORY	没有足够的内存可用于执行此操作。

注解

NSPv2LookupServiceBegin 函数用作命名空间服务提供程序版本 2 的一部分， (Windows Vista 及更高版本上提供的 NSPv2) 体系结构。

在 Windows Vista 和 Windows Server 2008 上， NSPv2LookupServiceBegin 函数只能用于NS_EMAIL命名空间提供程序上的操作。

NSPv2LookupServiceBegin 函数仅返回句柄，后续调用 NSPv2LookupServiceNextEx 时应使用该句柄来获取实际结果。由于无法取消此操作，因此应实现此操作以快速执行。虽然可以接受启动网络查询，但此函数不应要求响应即可成功返回。

每次新客户端进程开始使用命名空间提供程序时，都会调用 NSPv2Startup 函数。提供程序可以使用 ppvClientSessionArg 参数指向的客户端会话参数来存储有关此会话的信息。如果在对 NSPv2Startup 函数的调用中为客户端会话参数指定了值，则此相同的客户端会话参数将在 lpvClientSessionArg 参数中传递到 NSPv2LookupServiceBegin 函数。

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

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

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

dwStatus = NSPv2LookupServiceBegin(
    lpProviderId,
    lpqsRestrictions,
    LUP_CONTAINERS,
    lpClientSession,
    lphLookup);

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

形成查询

WSAQUERYSET2 结构用作 NSPv2LookupServiceBegin 的输入参数，以限定查询。下表列出了 “WSAQUERYSET2” 成员名称，并介绍了如何使用 **WSAQUERYSET2** 构造查询。标记为可选且依赖于 NSPv2 提供程序要求的成员在命名空间提供程序未用作搜索条件时，可能会作为 **NULL** 指针提供。有关详细信息，请参阅与查询相关的数据结构。

WSAQUERYSET2成员名称	查询解释
dwSize	将设置为 sizeof (WSAQUERYSET2) 。这是一种版本控制机制。
lpszServiceInstanceName	包含服务名称的字符串。字符串中通配符的语义未定义，但可由某些命名空间提供程序支持。此成员是可选的，具体取决于 NSPv2 服务提供商的要求。
lpVersion	提供版本比较语义的所需版本号 (即版本必须完全匹配，或者版本必须不小于) 提供的值。此成员是可选的，具体取决于 NSPv2 服务提供商的要求。
lpszComment	对于查询，将忽略此成员。
dwNameSpace	要在其中约束搜索的单个命名空间的标识符，或 “NS_ALL” 以包含所有命名空间。
lpNSProviderId	特定命名空间提供程序的 GUID，将查询限制为仅此提供程序。此成员是可选的，具体取决于 NSPv2 服务提供商的要求。
lpszContext	分层命名空间中查询的起点。此成员是可选的，具体取决于 NSPv2 服务提供商的要求。
dwNumberOfProtocols	协议约束数组中条目数的大小（以字节为单位）。此成员可以为零。
lpafpProtocols	AFPROTOCOLS 结构的数组。仅返回使用这些协议的服务。允许值 “AF_UNSPEC” 显示为协议系列值，表示通配符。命名空间提供程序可能会提供有关使用相应协议的任何服务的信息，而不考虑地址系列。此成员是可选的，具体取决于 NSPv2 服务提供商的要求。
lpszQueryString	某些 (命名空间（如 whois++) ）支持简单文本字符串中包含的类似 SQL 的丰富查询。此参数用于指定该字符串。此成员是可选的，具体取决于 NSPv2 服务提供商的要求。
dwNumberOfCsAddrs	对于查询，将忽略此成员。
lpcsaBuffer	对于查询，将忽略此成员。
dwOutputFlags	对于查询，将忽略此成员。
lpBlob	指向提供程序特定的实体的指针。此成员是可选的，具体取决于 NSPv2 服务提供商的要求。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	ws2spi.h