LPNSPV2LOOKUPSERVICENEXTEX回调函数 (ws2spi.h)

项目
08/28/2023

从上一次调用 NSPv2LookupServiceBegin 获取句柄后调用 NSPv2LookupServiceNextEx 函数，以便从命名空间版本 2 服务提供程序检索请求的信息。

语法

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

参数

[in] hAsyncCall

从上一次调用 NSPv2LookupServiceBegin 返回的句柄，用于异步调用。

[in] hLookup

从上一次调用 NSPv2LookupServiceBegin 返回的句柄。

[in] dwControlFlags

用于控制下一个操作的标志。目前，只有 LUP_FLUSHPREVIOUS 定义为处理过大的结果集的方法。如果应用程序无法提供足够大的缓冲区，设置 LUP_FLUSHPREVIOUS 会指示提供程序放弃最后一个结果集（太大），并转到此调用的下一个结果集。

[in, out] lpdwBufferLength

lpqsResults 指向的缓冲区中包含的输入大小（以字节为单位）。在输出时，如果函数失败且错误为 WSAEFAULT，则它包含为 lpqsResults 检索记录所传递的最小大小（以字节为单位）。

[out] lpqsResults

指向内存块的指针，该内存块在返回时将包含 WSAQUERYSET2 结构中的一个结果集。

返回值

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

错误代码	含义
WSA_E_CANCELLED	当此调用仍在处理时，已调用 NSPv2LookupServiceEnd 。该调用已取消。 lpqsResults 缓冲区中的数据未定义。在 Windows 套接字 2 中，为 WSAECANCELLED (10103) 和 WSA_E_CANCELLED (10111) 定义了冲突错误代码。将来的版本将删除错误代码 WSAECANCELLED ，并且仅保留WSA_E_CANCELLED。命名空间提供程序应使用 WSA_E_CANCELLED 错误代码来保持与尽可能广泛的应用程序的兼容性。
WSA_E_NO_MORE	没有更多可用数据。在 Windows 套接字 2 中，为 WSAENOMORE (10102) 和 WSA_E_NO_MORE (10110) 定义了冲突错误代码。未来版本中将删除错误代码 WSAENOMORE ，并且仅保留WSA_E_NO_MORE。命名空间提供程序应使用 WSA_E_NO_MORE 错误代码来保持与尽可能广泛的应用程序的兼容性。
WSAEFAULT	lpqsResults 缓冲区太小，无法包含 WSAQUERYSET 集。
WSAEINVAL	此提供程序的一个或多个参数无效或缺失。
WSA_INVALID_HANDLE	指定的查找句柄无效。
WSANO_DATA	在数据库中找到了该名称，但找不到符合给定限制的数据。
WSASERVICE_NOT_FOUND	服务未知。在指定的命名空间中找不到该服务。
WSA_NOT_ENOUGH_MEMORY	没有足够的内存可用于执行此操作。

注解

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

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

提供程序将在 lpqsResults 缓冲区中传递WSAQUERYSET2结构。客户端应调用 NSPv2LookupServiceNextEx 函数，直到返回 WSA_E_NOMORE，指示已返回所有 WSAQUERYSET2 结构。

此函数中指定的 dwControlFlags 和 NSPv2LookupServiceBegin 时指定的 dwControlFlag 作为“限制”进行处理，以便进行组合。 NSPv2LookupServiceBegin 时间的限制与 NSPv2LookupServiceNextEx 时间的限制组合在一起。因此， NSPv2LookupServiceNextEx 上的标志永远不能增加返回的数据量超过 NSPv2LookupServiceBegin 上请求的数据量，尽管指定更多或更少的标志不是错误。在给定 的 NSPv2LookupServiceNextEx 中指定的标志仅适用于该调用。

dwControlFlagsLUP_FLUSHPREVIOUS和LUP_RES_SERVICE是组合限制规则 (的例外情况，因为它们是行为标志，而不是) 的“限制”标志。如果在 NSPv2LookupServiceNextEx 中使用任一标志，则无论 NSPv2LookupServiceBegin 中的相同标志的设置如何，它们都具有定义的效果。

例如，如果在 NSPv2LookupServiceBegin 中指定了LUP_RETURN_VERSION，则服务提供商将检索包括版本在内的记录。如果在 NSPv2LookupServiceNextEx 中未指定LUP_RETURN_VERSION，则返回的信息不包括版本，即使它可用。不会生成错误。

此外，如果在 NSPv2LookupServiceBegin 中未指定LUP_RETURN_BLOB，但在 NSPv2LookupServiceNextEx 中指定，则返回的信息不包括专用数据。不会生成错误。

NSPv2LookupServiceNextEx 函数通常至少调用两次。第一次获取所需缓冲区的大小以接收 lpqsResults 参数指向的WSAQUERYSET2，第二次获取实际查询结果集。在第一次调用时，NSPv2 提供程序应返回 WSAQUERYSET2 结果所需的大小。

返回的 lpqsResults 参数指向的 WSAQUERYSET2 结构仅在同一进程上下文中有用，因为 WSAQUERYSET2 结构中的几个成员包含指向返回的实际数据的指针。如果需要使用 RPC 将查询结果传递给另一个进程 (，例如) ，则必须序列化和封送 lpqsResults 参数指向的WSAQUERYSET2结构中返回的数据，包括WSAQUERYSET2结构中的成员所指向的数据。数据需要以可以跨进程边界传递的形式进行序列化。仅传递 WSAQUERYSET2 结构的副本是不够的，因为只会传递指向数据的指针，而实际数据将不可用于其他进程。

查询结果

下表列出了 WSAQUERYSET2 ，并介绍了如何在 WSAQUERYSET2 结构中表示查询结果。有关详细信息，请参阅与查询相关的数据结构。

WSAQUERYSET2成员名称	结果解释
dwSize	WSAQUERYSET2 结构的大小（以字节为单位）。这用作版本控制机制。
lpszServiceInstanceName	包含服务名称的字符串。
lpVersion	引用特定服务实例的版本号。
lpszComment	服务实例提供的注释字符串。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。
dwNameSpace	在其中找到名称或服务实例的命名空间标识符。
lpNSProviderId	提供此查询结果的特定命名空间提供程序。
lpszContext	服务所在的分层命名空间中的上下文点。
dwNumberOfProtocols	未为结果定义此成员。
lpafpProtocols	未为结果定义此成员。所有必需的协议信息都在 CSADDR_INFO 结构中。
lpszQueryString	当 dwControlFlags 包含 LUP_RETURN_QUERY_STRING时，此成员返回原始查询中指定的 lpszServiceInstanceName 的未解析余数。例如，在通过指定主机名和该主机中的文件路径的分层名称标识服务的命名空间中，返回的地址可能是主机地址，未解析的其余部分可能是文件路径。如果完全分析了 lpszServiceInstanceName，并且使用了“LUP_RETURN_QUERY_STRING”，则此成员为 null 或指向长度为零的字符串。
dwNumberOfCsAddrs	CSADDR_INFO 结构数组中的元素数。
lpcsaBuffer	指向 CSADDR_INFO 结构数组的指针，每个元素中包含一个完整的传输地址。
dwOutputFlags	RESULT_IS_ALIAS 标志指示这是别名结果。
lpBlob	指向提供程序特定的实体的指针。此成员是可选的，具体取决于 NSPv2 服务提供程序的要求。

要求


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