LPNSPV2LOOKUPSERVICENEXTEX回调函数（ws2spi.h）

项目
07/16/2024

NSPv2LookupServiceNextEx 函数是在从上一次调用 NSPv2LookupServiceBegin 获取句柄后调用的，以便从命名空间版本 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（零）。如果例程失败并且必须使用 WSASetLastError设置适当的错误代码，则它应返回 SOCKET_ERROR（即 1）。

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

言论

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

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

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

此函数中指定的 dwControlFlags，NSPv2LookupServiceBegin 中指定的将作为“限制”进行处理，以便进行组合。限制在 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** 结构中表示查询结果。有关详细信息，请参阅 Query-Related 数据结构。

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 [仅限桌面应用]
目标平台	窗户
标头	ws2spi.h