LPNSPLOOKUPSERVICEBEGIN 回调函数 (ws2spi.h)
NSPLookupServiceBegin 函数启动名称服务提供程序的客户端查询，该查询受 WSAQUERYSET 结构中包含的信息的约束。
NSPLookupServiceBegin 仅返回句柄，后续调用 NSPLookupServiceNext 时应使用该句柄来获取实际结果。 由于此操作无法取消，因此应实现此操作以快速执行。 虽然启动网络查询是可以接受的，但此函数不应要求响应成功返回。
语法
LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;
INT Lpnsplookupservicebegin(
[in] LPGUID lpProviderId,
[in] LPWSAQUERYSETW lpqsRestrictions,
[in] LPWSASERVICECLASSINFOW lpServiceClassInfo,
[in] DWORD dwControlFlags,
[out] LPHANDLE lphLookup
)
{...}
参数
[in] lpProviderId
指向要查询的名称服务提供程序标识符的指针。
[in] lpqsRestrictions
指向搜索条件的指针。 请参阅“备注”。
[in] lpServiceClassInfo
指向 WSASERVICECLASSINFO 结构的指针，该结构包含服务的架构信息。
[in] dwControlFlags
一个值，该值控制搜索的深度。
| Value | 含义 |
|---|---|
|
查询提供程序的层次结构，而不仅仅是第一个级别。 |
|
仅返回容器。 |
|
不返回任何容器。 |
|
如果可能，按距离顺序返回结果。 距离度量值特定于提供程序。 |
|
检索名称为 **lpszServiceInstanceName**。 |
|
检索类型为 **lpServiceClassId**。 |
|
检索版本为 **lpVersion**。 |
|
检索注释为 **lpszComment**。 |
|
以 **lpcsaBuffer** 的形式检索地址。 |
|
以 **lpBlob** 的形式检索私有数据。 |
|
任何可用的别名信息都将在对 NSPLookupServiceNext 的连续调用中返回，并且返回的每个别名都将设置 **RESULT_IS_ALIAS** 标志。 |
|
以 **lpszQueryString** 的形式检索查询字符串。 |
|
检索信息，包括名称、类型、版本、注释、地址、blob、别名和查询字符串。 |
|
如果提供程序具有缓存的信息，请忽略缓存并查询命名空间本身。 |
|
用作 NSPLookupServiceNext 中 dwControlFlags 参数的值。 设置此标志指示提供程序放弃最后一个结果集（对于提供的缓冲区来说太大），并转到下一个结果集。 |
|
指示命名空间提供程序应包含名称的非权威结果。 |
|
指示主要响应位于 CSADDR_INFO 结构的远程部分还是本地部分。 另一部分在任一情况下都必须可用。 此选项仅适用于服务实例请求。 |
|
指示命名空间提供程序应使用安全查询。 此选项仅适用于名称查询请求。 |
|
指示命名空间提供程序应仅返回首选名称。 |
|
指示命名空间提供程序应返回地址配置。 |
|
指示命名空间提供程序应返回双地址。 此选项仅适用于双模式套接字 (IPv6 和 IPv4 映射地址) 。 |
[out] lphLookup
指向句柄的指针，用于对 NSPLookupServiceNext 的后续调用，以便检索结果集。
返回值
如果例程成功 ， 函数应返回NO_ERROR (零) 。 如果例程失败，它应返回 SOCKET_ERROR (-1) ，并且必须使用 WSASetLastError 设置相应的错误代码。
| 错误代码 | 含义 |
|---|---|
| 没有足够的内存可用于执行此操作。 | |
| 此提供程序的一个或多个参数无效或缺失。 | |
| 此操作不受支持。 如果命名空间提供程序未实现此函数，则返回此错误。 | |
| 已在数据库中找到该名称，但它没有为其解析的正确关联数据。 | |
| 服务未知。 在指定的命名空间中找不到该服务。 |
注解
如果在调用中指定 了LUP_CONTAINERS ，请避免使用所有其他限制值。 如果提供了任何限制，则名称服务提供商必须决定它是否可以支持对容器的此限制。 否则，它应返回错误。
某些名称服务提供商可能具有查找容器的其他方法。 例如，容器可以是某种已知类型，也可以是一组已知类型的容器，因此可以创建查询限制来查找它们。 无论服务提供程序使用什么其他方式来查找容器， LUP_CONTAINERS 和 LUP_NOCONTAINERS 优先。 因此，如果给定包含容器的查询限制，则指定 LUP_NOCONTAINERS 将阻止返回容器项。 同样，无论查询限制如何，如果给定 LUP_CONTAINERS ，则只应返回容器。 如果命名空间不支持容器并且指定 了LUP_CONTAINERS ，则它应返回 WSANO_DATA。
获取另一个容器中的容器的首选方法是调用：
dwStatus = NSPLookupServiceBegin(
lpqsRestrictions,
LUP_CONTAINERS,
lphLookup);
后跟必要的 NSPLookupServiceNext 调用数。 这将返回立即包含在起始上下文中的所有容器;也就是说，它不是深度查询。 这样，就可以通过遍历层次结构来映射地址空间结构，或许可以枚举所选容器的内容。 NSPLookupServiceBegin 的后续使用使用上一次调用返回的容器。
形成查询
如前所述， WSAQUERYSET 结构用作 NSPLookupServiceBegin 的输入参数来限定查询。 下表列出了 WSAQUERYSET 成员名称，并介绍了如何使用 WSAQUERYSET 构造查询。 当成员标记为 (Optional) 可以提供空指针，指示参数不会用作搜索条件。 有关详细信息，请参阅 与查询相关的数据结构。
| WSAQUERYSET 成员名称 | 查询解释 |
|---|---|
| **dwSize** | 将设置为 sizeof (WSAQUERYSET) 。 这是一种版本控制机制。 |
| dwOutputFlags | 对于查询，忽略。 |
| **lpszServiceInstanceName** | 可选。 引用的字符串包含服务名称。 字符串中通配符的语义未定义，但某些命名空间提供程序可以支持这些语义。 |
| **lpServiceClassId** | 必需。 对应于服务类的 GUID。 |
| **lpVersion** | 可选。 引用所需的版本号并提供版本比较语义 (即版本必须完全匹配，或者版本必须不小于) 提供的值。 |
| **lpszComment** | 对于查询，忽略。 |
| dwNameSpace | 要在其中限制搜索的单个命名空间的标识符，或 **NS_ALL** 以包含所有命名空间。 |
| **lpNSProviderId** | 可选。 引用特定命名空间提供程序的 GUID，并将查询限制为仅此提供程序。 |
| **lpszContext** | 可选。 指定分层命名空间中查询的起点。 |
| **dwNumberOfProtocols** | 协议约束数组中条目数的大小（以字节为单位）可以为零。 |
| **lpafpProtocols** | 可选。 对 AFPROTOCOLS 结构数组的引用。 仅返回使用这些协议的服务。 允许值 **AF_UNSPEC** 显示为协议系列值，表示通配符。 无论地址系列如何，命名空间提供程序都可以提供有关使用相应协议的任何服务的信息。 |
| **lpszQueryString** | 可选。 某些 (命名空间（如 whois++) ）支持包含在简单文本字符串中的类似 SQL 的丰富查询。 此参数用于指定该字符串。 |
| **dwNumberOfCsAddrs** | 对于查询，忽略。 |
| **lpcsaBuffer** | 对于查询，忽略。 |
| **lpBlob** | 可选。 指向提供程序特定的实体的指针。 |
要求
| 最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
| 最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | ws2spi.h |