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 含义
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
任何可用的别名信息都将在对 NSPLookupServiceNext 的连续调用中返回,并且返回的每个别名都将设置 **RESULT_IS_ALIAS** 标志。
LUP_RETURN_QUERY_STRING
0x0800
以 **lpszQueryString** 的形式检索查询字符串。
LUP_RETURN_ALL
0x0ff0
检索信息,包括名称、类型、版本、注释、地址、blob、别名和查询字符串。
LUP_FLUSHCACHE
0x1000
如果提供程序具有缓存的信息,请忽略缓存并查询命名空间本身。
LUP_FLUSHPREVIOUS
0x2000
用作 NSPLookupServiceNextdwControlFlags 参数的值。 设置此标志指示提供程序放弃最后一个结果集(对于提供的缓冲区来说太大),并转到下一个结果集。
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 映射地址) 。

[out] lphLookup

指向句柄的指针,用于对 NSPLookupServiceNext 的后续调用,以便检索结果集。

返回值

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

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

注解

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

某些名称服务提供商可能具有查找容器的其他方法。 例如,容器可以是某种已知类型,也可以是一组已知类型的容器,因此可以创建查询限制来查找它们。 无论服务提供程序使用什么其他方式来查找容器, LUP_CONTAINERSLUP_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

另请参阅

AFPROTOCOLS

NSPLookupServiceEnd

NSPLookupServiceNext

NSP_ROUTINE

WSAQUERYSET

WSASERVICECLASSINFO

WSASetLastError