LPNSPLOOKUPSERVICENEXT 回调函数 (ws2spi.h)

项目
08/28/2023

NSPLookupServiceNext 函数是在从上一次调用 NSPLookupServiceBegin 获取句柄后调用的，以检索请求的服务信息。

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

语法

LPNSPLOOKUPSERVICENEXT Lpnsplookupservicenext;

INT Lpnsplookupservicenext(
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSETW lpqsResults
)
{...}

参数

[in] hLookup

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

[in] dwControlFlags

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

[in, out] lpdwBufferLength

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

[out] lpqsResults

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

返回值

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

错误代码	含义
WSA_E_CANCELLED	当此调用仍在处理时，已调用 NSPLookupServiceEnd 。该调用已取消。 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 错误代码来保持与最广泛的应用程序的兼容性。
WSA_INVALID_HANDLE	指定的查找句柄无效。
WSA_NOT_ENOUGH_MEMORY	没有足够的内存可用于执行此操作。
WSAEFAULT	lpqsResults 缓冲区太小，无法包含 WSAQUERYSET 集。
WSAEINVAL	此提供程序的一个或多个参数无效或缺失。
WSAEOPNOTSUPP	此操作不受支持。如果命名空间提供程序未实现此函数，则返回此错误。
WSANO_DATA	数据库中已找到该名称，但没有找到与给定限制匹配的数据。
WSASERVICE_NOT_FOUND	服务未知。在指定的命名空间中找不到该服务。

注解

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

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

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

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

查询结果

下表列出了 WSAQUERYSET ，并介绍了查询结果在 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 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	ws2spi.h