LPNSPIOCTL 回调函数 (ws2spi.h)
NSPIoctl 函数将 IOCTL 发送到命名空间服务提供程序。
语法
LPNSPIOCTL Lpnspioctl;
INT Lpnspioctl(
[in] HANDLE hLookup,
[in] DWORD dwControlCode,
[in] LPVOID lpvInBuffer,
[in, out] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSACOMPLETION lpCompletion,
[in] LPWSATHREADID lpThreadId
)
{...}
参数
[in] hLookup
从上一次调用 NSPLookupServiceBegin 函数返回的查找句柄。
[in] dwControlCode
要执行的操作的控制代码。
可用于 dwControlCode 参数的值由命名空间提供程序确定。
以下值受多个 Microsoft 命名空间提供程序的支持，包括网络位置感知 (NS_NLA) 命名空间提供程序。 此 IOCTL 在 Winsock2.h 头文件中定义。
| Value | 含义 |
|---|---|
|
此操作检查使用 hLookup 参数的先前调用返回的结果是否仍然有效。 前面的这些调用包括对 NSPLookupServiceBegin 函数的初始调用，以检索 hLookup 参数。 之前的这些调用还可能包括使用 hLookup 参数对 NSPLookupServiceNext 函数的调用。 |
[in] lpvInBuffer
指向输入缓冲区的指针。
[in, out] cbInBuffer
输入缓冲区的大小（以字节为单位）。
[out] lpvOutBuffer
指向输出缓冲区的指针。
[in] cbOutBuffer
输出缓冲区的大小（以字节为单位）。
[out] lpcbBytesReturned
指向返回的字节数的指针。
[in] lpCompletion
指向 WSACOMPLETION 结构的指针，用于异步处理。 将 lpCompletion 设置为 NULL 以强制阻塞 (同步) 执行。
[in] lpThreadId
指向 WSATHREADID 结构的指针，供提供程序在后续调用 WPUQueueApc 时使用。 在 WPUQueueApc 函数返回之前，提供程序应存储引用的 WSATHREADID 结构 (而不是指针) 。
返回值
如果未发生错误并且操作已立即完成， 则 NSPIoctl 函数应返回 NO_ERROR (零) 。 请注意，在这种情况下，完成例程（如果指定）已排队。
如果例程失败， NSPIoctl 函数应返回 SOCKET_ERROR (即 1) ，并且必须使用 WSASetLastError 设置相应的错误代码。
错误代码WSA_IO_PENDING指示已成功启动重叠操作，稍后将指示完成。 任何其他错误代码指示未启动重叠的操作，并且不会发生完成指示。
| 错误代码 | 说明 |
|---|---|
| hLookup 参数不是 NSPLookupServiceBegin 返回的有效查询句柄。 | |
| 已成功启动重叠操作，稍后将指示完成。 | |
| lpvInBuffer、cbInBuffer、lpvOutBuffer、cbOutBuffer 或 lpCompletion 参数并不完全包含在用户地址空间的有效部分。 或者， cbInBuffer 或 cbOutBuffer 参数太小，并修改参数以反映所需的分配大小。 | |
| 提供的参数不可接受，或者当操作对指定操作没有意义时，该操作会不恰当地返回来自多个命名空间的结果。 | |
| 网络子系统失败。 | |
| 此操作不受支持。 如果命名空间提供程序未实现此函数，则返回此错误。 如果指定的 dwControlCode 是无法识别的命令，也可能会返回此错误。 | |
|
资源暂时不可用。 套接字未使用重叠 I/O (异步处理) ，但 lpCompletion 参数为非 NULL。
当 lpCompletion 参数为 NULL (轮询) 指示查询集仍然有效时，此错误用作SIO_NSP_NOTIFY_CHANGE IOCTL 的特殊通知。 |
注解
NSPIoctl 函数用于将 I/O 控制代码发送到命名空间提供程序，以便设置或检索与查询句柄关联的操作参数。 hLookup 参数是 NSPLookupServiceBegin 函数先前返回的命名空间提供程序查询的句柄， (不是) 的套接字句柄。
发送到命名空间提供程序的任何 IOCTL 都可能会无限期阻塞，具体取决于命名空间的实现。 如果应用程序不能容忍 在 NSPIoctl 函数调用中阻塞，则应使用重叠 I/O，并且 lpCompletion 参数应指向 WSACOMPLETION 结构。 若要使 NSPIoctl 函数调用非阻止并立即返回，请将 WSACOMPLETION 结构的 Type 成员设置为NSP_NOTIFY_IMMEDIATELY。
如果 lpCompletion 为 NULL，则 NSPIoctl 函数将作为阻止调用执行。 命名空间提供程序应立即返回，不应阻止。 但每个命名空间提供程序都负责强制实施此行为。
多个 Microsoft 命名空间提供程序支持以下 IOCTL 代码：
支持此 IOCTL 的 Microsoft 命名空间提供程序包括：
- NS_NLA - 网络位置感知 (NLA) 命名空间提供程序。
- NS_PNRPNAME - PNRP) 命名空间提供程序 (对等名称解析协议。
- NS_PNRPCLOUD - 云命名空间提供程序 (PNRP) 对等名称解析协议。
可能安装了其他也支持此 IOCTL 的非 Microsoft 命名空间提供程序。
当 lpCompletion 参数为 NULL 时，此 IOCTL 将实现特殊行为。 如果此 IOCTL 的 lpCompletion 参数为 NULL ，则此操作为轮询并立即返回。 如果查询集仍然有效，则 WSAEWOULDBLOCK 将作为通知返回，指示查询集仍然有效。 如果查询集已更改且无效，则返回 NO_ERROR ，指示查询集无效轮询成功。
如果 lpCompletion 参数不为 NULL 且指向 WSACOMPLETION 结构，则 NSPIoctl 函数返回 WSA_IO_PENDING 如果重叠的操作已成功启动，并且稍后将指示完成。 WSACOMPLETION 结构中指定的方法用于通知应用程序查询集是否仍然有效。
并非所有名称解析协议都能支持此功能，因此，此函数调用可能会失败并显示 WSAEOPNOTSUPP。 包含来自多个提供程序的数据的查询无法调用此 IOCTL，并将返回 WSAEINVAL。
Microsoft 命名空间提供程序当前忽略 lpvInBuffer、 cbInBuffer、 lpvOutBuffer 和 cbOutBuffer 参数。
对于单线程应用程序，使用 NSPIoctl 函数的典型方法如下所示。 在每次调用 NSPLookupServiceNext 函数后， (将 lpCompletion 参数设置为 NULL) 的 dwControlCode 参数设置为 SIO_NSP_NOTIFY_CHANGE调用 NSPIoctl 函数，以确保查询数据仍然有效。 如果数据无效，请调用 NSPLookupServiceEnd 函数以关闭查询句柄。 调用 NSPLookupServiceBegin 函数以检索新的查询句柄并再次开始查询。
对于多线程应用程序，使用 NSPIoctl 函数的典型方法如下所示。 在初始调用 NSPLookupServiceBegin 函数后，使用完成例程调用 dwControlCode 参数设置为 SIO_NSP_NOTIFY_CHANGE调用 NSPIoctl 函数。 应用程序将使用完成例程中指定的通知机制，以便在数据不再有效时收到通知。 一种常见机制是使用完成例程中指定的事件。 如果数据无效，请调用 NSPLookupServiceEnd 函数以关闭查询句柄。 调用 NSPLookupServiceBegin 和 NSPIoctl 函数以检索新的查询句柄并再次开始查询。
某些协议可能只是在本地缓存信息，并在一段时间后使其失效，在这种情况下，可能会发出通知以指示本地缓存已失效。
对于不经常更改的名称解析协议，命名空间提供程序可能会指示可能不适用于请求和发出更改通知的查询的全局更改事件。
即时轮询操作的资源消耗通常要小得多，因为它们不需要通知对象。 在大多数情况下，这是作为简单布尔变量检查实现的。 但是，异步通知可能需要创建专用的工作线程和/或进程间信道，具体取决于命名空间提供程序服务的实现，并且会产生与向更改事件发出信号所涉及的通知对象相关的处理开销。
若要取消异步通知请求，请在受影响的查询句柄上调用 NSPLookupServiceEnd 函数，以结束原始查询。 取消LUP_NOTIFY_HWND的异步通知不会发布任何消息，但是，将完成重叠的操作，并发送通知并 WSA_OPERATION_ABORTED错误。
要求
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | ws2spi.h |