WSALookupServiceNextA 函数 (winsock2.h)

  • 项目

WSALookupServiceNext 函数是在从先前调用 WSALookupServiceBegin 获取句柄后调用的，以检索请求的服务信息。

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

语法

INT WSAAPI WSALookupServiceNextA(
  [in]      HANDLE         hLookup,
  [in]      DWORD          dwControlFlags,
  [in, out] LPDWORD        lpdwBufferLength,
  [out]     LPWSAQUERYSETA lpqsResults
);

参数

[in] hLookup

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

[in] dwControlFlags

控制操作的一组标志。 dwControlFlags 参数中传递给 WSALookupServiceBegin 函数的值确定可能的条件。 在 dwControlFlags 参数中传递到 WSALookupServiceNext 函数的任何值进一步限制服务查找的条件。

目前，LUP_FLUSHPREVIOUS定义为处理太大的结果集的一种手段。 如果应用程序未 (或无法) 提供足够大的缓冲区，则设置 LUP_FLUSHPREVIOUS 指示提供程序放弃上一个结果集（太大），并转到此调用的下一个结果集。

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
 任何可用的别名信息都将在对 WSALookupServiceNext 的连续调用中返回，并且返回的每个别名都将设置RESULT_IS_ALIAS标志。
LUP_RETURN_QUERY_STRING
0x0800
 检索用于请求的查询字符串。
LUP_RETURN_ALL
0x0FF0
 一组标志，用于检索所有LUP_RETURN_* 值。
LUP_FLUSHPREVIOUS
0x1000
 用作 WSALookupServiceNext 中 dwControlFlags 参数的值。 设置此标志指示提供程序放弃最后一个结果集（对于指定的缓冲区太大），并转到下一个结果集。
LUP_FLUSHCACHE
0x2000
 如果提供程序一直在缓存信息，则忽略缓存，并查询命名空间本身。
LUP_RES_SERVICE
0x8000
 这指示主要响应是位于 CSADDR_INFO 结构的远程部分还是本地部分。 在任一情况下，另一部分都需要可用。

[in, out] lpdwBufferLength

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

[out] lpqsResults

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

返回值

如果操作成功，则返回值为零。 否则，将返回值SOCKET_ERROR，并且可以通过调用 WSAGetLastError 检索特定的错误号。

错误代码 含义
WSA_E_CANCELLED
 当此调用仍在处理时，已调用 WSALookupServiceEnd 。 该调用已取消。 lpqsResults 缓冲区中的数据未定义。 在 Windows 套接字版本 2 中，为 WSAECANCELLED (10103) 和 WSA_E_CANCELLED (10111) 定义了冲突错误代码。 错误代码 WSAECANCELLED 将在将来的版本中删除，并且仅保留WSA_E_CANCELLED。 但是，对于 Windows 套接字版本 2，应用程序应同时检查 WSAECANCELLED 和 WSA_E_CANCELLED，以便与使用任一提供程序的命名空间提供程序实现尽可能广泛的兼容性。
WSA_E_NO_MORE
 没有更多可用数据。 在 Windows 套接字版本 2 中，为 WSAENOMORE (10102) 和 WSA_E_NO_MORE (10110) 定义了冲突错误代码。 错误代码 WSAENOMORE 将在将来的版本中删除，并且仅保留WSA_E_NO_MORE。 但是，对于 Windows 套接字版本 2，应用程序应同时为 WSAENOMORE 和 WSA_E_NO_MORE 检查，以便与使用任一名称空间提供程序尽可能广泛的兼容性。
WSAEFAULT
 lpqsResults 缓冲区太小，无法包含 WSAQUERYSET 集。
WSAEINVAL
 一个或多个必需参数无效或缺失。
WSA_INVALID_HANDLE
 指定的查找句柄无效。
WSANOTINITIALIZED
 尚未初始化 WS2_32.DLL。 应用程序必须先调用 WSAStartup， 然后才能调用任何 Windows 套接字函数。
WSANO_DATA
 在数据库中找到了该名称，但找不到与给定限制匹配的数据。
WSA_NOT_ENOUGH_MEMORY
 内存不足，无法执行该操作。

注解

此函数中指定的 dwControlFlags 参数和 WSALookupServiceBegin 时指定的参数被视为组合的限制。 WSALookupServiceBegin 时间的限制与 WSALookupServiceNext 时间的限制组合在一起。 因此， WSALookupServiceNext 中的标志永远不会增加超出 WSALookupServiceBegin 上请求的数据量返回的数据量，尽管指定更多或更少的标志不是错误。 在给定 的 WSALookupServiceNext 中指定的标志仅适用于该调用。

dwControlFlags LUP_FLUSHPREVIOUS和LUP_RES_SERVICE是组合限制规则 (的例外，因为它们是行为标志而不是) 限制标志。 如果在 WSALookupServiceNext 中使用这两个标志中的任何一个，则无论 WSALookupServiceBegin 中的相同标志的设置如何，它们都有其定义的效果。

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

此外，如果 WSALookupServiceBegin 中未指定LUP_RETURN_BLOB，但在 WSALookupServiceNext 中指定，则返回的信息不包括私有数据。 不会生成错误。

如果 WSALookupServiceNext 函数失败并出现 WSAEFAULT 错误，则表示 lpqsResults 参数指向的缓冲区太小，无法包含查询结果。 WSAQUERYSET 的新缓冲区应提供由 lpdwBufferLength 参数指向的值指定的大小。 WSAQUERYSET 的这个新缓冲区需要在再次调用 WSALookupServiceNext 函数之前指定 WSAQUERYSET 的一些成员。 WSAQUERYSET 的 dwSize 成员至少必须设置为缓冲区的新大小。

查询结果

下表介绍了如何在 WSAQUERYSET 结构中表示查询结果。
WSAQUERYSET 成员 结果解释
dwSize 将设置为 sizeof ( WSAQUERYSET) 。 这用作版本控制机制。
dwOutputFlags RESULT_IS_ALIAS标志指示这是别名结果。
lpszServiceInstanceName 引用的字符串包含服务名称。
lpServiceClassId 与服务类对应的 GUID。
lpVersion 引用特定服务实例的版本号。
lpszComment 由服务实例指定的可选注释字符串。
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 结构数组的指针，每个元素中包含一个完整的传输地址。
lpBlob (可选) 这是指向特定于提供程序的实体的指针。
 

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone Store 应用支持 WSALookupServiceNextW 函数。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持 WSALookupServiceNextW 函数。

注意

winsock2.h 标头将 WSALookupServiceNext 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

   
最低受支持的客户端 Windows 8.1、Windows Vista [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 winsock2.h
Library Ws2_32.lib
DLL Ws2_32.dll

另请参阅

蓝牙和 WSALookupServiceNext

WSALookupServiceBegin

WSALookupServiceEnd

WSAQUERYSET

Winsock 函数

Winsock 参考