WSANSPIoctl 函数 (winsock2.h)

  • 项目

Windows 套接字 WSANSPIoctl 函数使开发人员能够对已注册的命名空间进行 I/O 控件调用。

语法

INT WSAAPI WSANSPIoctl(
  [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] hLookup

从上一次调用 WSALookupServiceBegin 函数返回的查找句柄。

[in] dwControlCode

要执行的操作的控制代码。

可用于 dwControlCode 参数的值由命名空间提供程序确定。

多个 Microsoft 命名空间提供程序支持以下值，包括网络位置感知 (NS_NLA) 命名空间提供程序。 此 IOCTL 在 Winsock2.h 头文件中定义。

值 含义
SIO_NSP_NOTIFY_CHANGE
 此操作检查使用 hLookup 参数的先前调用返回的结果是否仍然有效。 之前的这些调用包括对 WSALookupServiceBegin 函数的初始调用，以检索 hLookup 参数。 之前的这些调用还可能包括使用 hLookup 参数对 WSALookupServiceNext 函数的调用。

[in] lpvInBuffer

指向输入缓冲区的指针。

[in, out] cbInBuffer

输入缓冲区的大小（以字节为单位）。

[out] lpvOutBuffer

指向输出缓冲区的指针。

[in] cbOutBuffer

输出缓冲区的大小（以字节为单位）。

[out] lpcbBytesReturned

指向返回的字节数的指针。

[in] lpCompletion

指向 WSACOMPLETION 结构的指针，用于异步处理。 将 lpCompletion 设置为 NULL 以强制阻止 (同步) 执行。

返回值

成功返回NO_ERROR。 失败返回SOCKET_ERROR，可以通过调用 WSAGetLastError 函数来检索特定的错误代码。 下表描述了错误代码。

错误代码 说明
WSA_INVALID_HANDLE
 hLookup 参数不是 WSALookupServiceBegin 返回的有效查询句柄。
WSA_IO_PENDING
 已成功启动重叠操作，稍后将指示完成。
WSAEFAULT
 lpvInBuffer、cbInBuffer、lpvOutBuffer、cbOutBuffer 或 lpCompletion 参数未完全包含在用户地址空间的有效部分。 或者， cbInBuffer 或 cbOutBuffer 参数太小，并修改参数以反映所需的分配大小。
WSAEINVAL
 提供的参数不可接受，或者当操作对指定操作没有意义时，操作会不恰当地返回来自多个命名空间的结果。
WSAENETDOWN
 网络子系统发生故障。
WSAEOPNOTSUPP
 此操作不受支持。 如果命名空间提供程序未实现此函数，则返回此错误。 如果指定的 dwControlCode 是无法识别的命令，则也可能返回此错误。
WSAEWOULDBLOCK
 套接字未使用重叠 I/O (异步处理) ，但 lpCompletion 参数为非 NULL。

当 lpCompletion 参数为 NULL (轮询) 指示查询集仍然有效时，此错误将用作SIO_NSP_NOTIFY_CHANGE IOCTL 的特殊通知。

注解

WSANSPIoctl 函数用于设置或检索与命名空间提供程序的查询句柄关联的操作参数。 hLookup 参数是先前由 WSALookupServiceBegin 函数返回的命名空间提供程序查询的句柄 (而不是套接字句柄) 。

发送到命名空间提供程序的任何 IOCTL 可能会无限期阻止，具体取决于命名空间的实现。 如果应用程序不能容忍 WSANSPIoctl 函数调用中的阻塞，则应使用重叠的 I/O，并且 lpCompletion 参数应指向 WSACOMPLETION 结构。 若要使 WSANSPIoctl 函数调用非阻止并立即返回，请将 WSACOMPLETION 结构的 Type 成员设置为NSP_NOTIFY_IMMEDIATELY。

如果 lpCompletion 为 NULL， 则 WSANSPIoctl 函数将作为阻止调用执行。 命名空间提供程序应立即返回，不应阻止。 但每个命名空间都负责强制实施此行为。

多个 Microsoft 名称空间提供程序支持以下 IOCTL 代码：

SIO_NSP_NOTIFY_CHANGE
此操作检查使用 hLookup 参数的先前调用返回的结果是否仍然有效。 之前的这些调用包括对 WSALookupServiceBegin 函数的初始调用，以检索 hLookup 参数。 之前的这些调用还可能包括使用 hLookup 参数对 WSALookupServiceNext 函数的调用。

支持此 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 结构，则 WSANSPIoctl 函数返回 WSA_IO_PENDING 如果已成功启动重叠的操作并且稍后将指示完成。 WSACOMPLETION 结构中指定的方法用于在查询集仍然有效时通知应用程序。

并非所有名称解析协议都支持此功能，因此，此函数调用可能会失败并出现 WSAEOPNOTSUPP。 包含来自多个提供程序的数据的查询无法调用此 IOCTL，并且将返回 WSAEINVAL。

Microsoft 命名空间提供程序当前忽略 lpvInBuffer、 cbInBuffer、 lpvOutBuffer 和 cbOutBuffer 参数。

对于单线程应用程序，使用 WSANSPIoctl 函数的典型方法如下所示。 每次调用 WSALookupServiceNext 函数后，调用 wSANSPIoctl 函数，其中 dwControlCode 参数设置为 SIO_NSP_NOTIFY_CHANGE 没有完成例程， (lpCompletion 参数设置为 NULL) ，以确保查询数据仍然有效。 如果数据无效，请调用 WSALookupServiceEnd 函数以关闭查询句柄。 调用 WSALookupServiceBegin 函数以检索新的查询句柄并再次开始查询。

对于多线程应用程序，使用 WSANSPIoctl 函数的典型方法如下所示。 在初始调用 WSALookupServiceBegin 函数后，使用完成例程调用 dwControlCode 参数设置为 SIO_NSP_NOTIFY_CHANGEWSANSPIoctl 函数。 应用程序将使用在完成例程中指定的通知机制，以便在数据不再有效时收到通知。 一种常见机制是使用完成例程中指定的事件。 如果数据无效，请调用 WSALookupServiceEnd 函数以关闭查询句柄。 调用 WSALookupServiceBegin 和 WSANSPIoctl 函数以检索新的查询句柄并再次开始查询。

某些协议可能只是在本地缓存信息，并在一段时间后使其失效，在这种情况下，可能会发出通知以指示本地缓存已失效。

对于不经常更改的名称解析协议，命名空间提供程序可以指示一个全局更改事件，该事件可能不适用于请求和发出更改通知的查询。

即时轮询操作通常成本更低，因为它们不需要通知对象。 在大多数情况下，这是作为一个简单的布尔变量检查实现的。 但是，异步通知可能需要创建专用的工作线程和/或进程间通信通道，具体取决于命名空间提供程序服务的实现，并且将产生与向更改事件发出信号所涉及的通知对象相关的处理开销。

若要取消异步通知请求，请在受影响的查询句柄上使用 WSALookupServiceEnd 函数调用结束原始查询。 取消LUP_NOTIFY_HWND的异步通知不会发布任何消息，但是，将完成重叠操作，并发送带有错误 WSA_OPERATION_ABORTED的通知。

注意 当给定线程退出时，将取消由给定线程启动的所有 I/O。 对于重叠套接字，如果在操作完成之前关闭线程，挂起的异步操作可能会失败。 有关详细信息 ，请参阅 ExitThread 。
 
Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone 应用商店应用支持此函数。

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

要求

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

另请参阅

ExitThread

WSACOMPLETION

WSAGetLastError

WSALookupServiceBegin

WSALookupServiceEnd

WSALookupServiceNext

Winsock 函数