SIO_APPLY_TRANSPORT_SETTING控制代码
说明
SIO_APPLY_TRANSPORT_SETTING控制代码将一个或多个传输设置应用于套接字。
若要执行此操作,请使用以下参数调用 WSAIoctl 或 WSPIoctl 函数。
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
(LPVOID) lpvInBuffer, // pointer to the input buffer
(DWORD) cbInBuffer, // size, in bytes, of the input buffer
(LPVOID) lpvOutBuffer, // pointer to the output buffer
(DWORD) cbOutBuffer, // size, in bytes, of the output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
);
int WSPIoctl(
(socket) s, // descriptor identifying a socket
SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
(LPVOID) lpvInBuffer, // pointer to the input buffer
(DWORD) cbInBuffer, // size, in bytes, of the input buffer
(LPVOID) lpvOutBuffer, // pointer to the output buffer
(DWORD) cbOutBuffer, // size, in bytes, of the output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
(LPWSATHREADID) lpThreadId, // a WSATHREADID structure
(LPINT) lpErrno // a pointer to the error code.
);
参数
S
标识套接字的描述符。
dwIoControlCode
操作的控制代码。 对此操作使用 SIO_APPLY_TRANSPORT_SETTING 。
lpvInBuffer
指向输入缓冲区的指针。 此参数包含指向 结构的指针,其中结构的第一个成员是确定要应用的传输设置 的TRANSPORT_SETTING_ID 结构。
cbInBuffer
输入缓冲区的大小(以字节为单位)。 此参数取决于所应用的传输设置。
lpvOutBuffer
指向输出缓冲区的指针。 此参数取决于所应用的传输设置。
cbOutBuffer
输出缓冲区的大小(以字节为单位)。
lhttpBytesReturned
指向变量的指针,该变量接收输出缓冲区中存储的数据的大小(以字节为单位)。
如果输出缓冲区太小,调用会失败, WSAGetLastError 将返回 WSAEINVAL,并且 lhttpBytesReturned 参数指向 DWORD 值零。
如果 lpOverlapped 为 NULL,则成功调用时返回的lBytesReturned 参数指向的 DWORD 值不能为零。
如果重叠套接字的 lpOverlapped 参数不为 NULL ,则将启动无法立即完成的操作,并在以后指示完成。 返回的lBytesReturned 参数指向的 DWORD 值可能为零,因为在重叠操作完成之前无法确定存储的数据的大小。 当操作完成时发出相应的完成方法信号时,可以检索最终完成状态。
lpvOverlapped
指向 WSAOVERLAPPED 结构的指针。
如果 创建的套接字 没有重叠属性,则忽略 lpOverlapped 参数。
如果使用重叠属性打开了 , 并且 lpOverlapped 参数不为 NULL,则该操作将作为重叠 (异步) 操作执行。 在这种情况下, lpOverlapped 参数必须指向有效的 WSAOVERLAPPED 结构。
对于重叠操作, WSAIoctl 或 WSPIoctl 函数将立即返回,并在操作完成时发出相应的完成方法信号。 否则,在操作完成或发生错误之前,函数不会返回 。
lpCompletionRoutine
类型:_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
指向完成操作时调用的完成例程的指针, (忽略非重叠套接字) 。
lpThreadId
指向 WSATHREADID 结构的指针,供提供程序在后续调用 WPUQueueApc 时使用。 在 WPUQueueApc 函数返回之前,提供程序应存储引用的 WSATHREADID 结构 (而不是指向同一) 的指针。
注意 此参数仅适用于 WSPIoctl 函数。
lpErrno
指向错误代码的指针。
注意 此参数仅适用于 WSPIoctl 函数。
返回值
如果操作成功完成, WSAIoctl 或 WSPIoctl 函数将返回零。
如果操作失败或挂起, WSAIoctl 或 WSPIoctl 函数将返回 SOCKET_ERROR。 若要获取扩展的错误信息,请调用 WSAGetLastError。
错误代码 | 含义 |
---|---|
WSA_IO_PENDING | 重叠 I/O 操作正在进行中。 如果已成功启动重叠操作,并且稍后将指示完成,则返回此值。 |
WSA_OPERATION_ABORTED | 由于发生线程退出或应用程序请求,I/O 操作已中止。 如果由于套接字关闭或执行 SIO_FLUSH IOCTL 命令而取消了重叠的操作,则返回此错误。 |
WSAEFAULT | 系统在尝试在调用中使用指针参数时检测到指针地址无效。 此错误返回的 lpvInBuffer、 lpvoutBuffer、 lhttpBytesReturned、 lpOverlapped 或 lpCompletionRoutine 参数未完全包含在用户地址空间的有效部分。 |
WSAEINPROGRESS | 阻止操作当前正在执行。 如果在回调正在进行时调用函数,则返回此错误。 |
WSAEINTR | 对 WSACancelBlockingCall 的调用中断了阻止操作。 如果阻止操作中断,则返回此错误。 |
WSAEINVAL | 提供了无效的参数。 如果 dwIoControlCode 参数不是有效的命令,或者指定的输入参数不可接受,或者命令不适用于指定的套接字类型,则返回此错误。 |
WSAENETDOWN | 套接字操作遇到了一个已死的网络。 如果网络子系统发生故障,则返回此错误。 |
WSAENOTSOCK | 尝试对不是套接字的内容执行操作。 如果描述符 不是套接字,则返回此错误。 |
WSAEOPNOTSUPP | 所引用对象的类型不支持尝试的操作。 如果不支持指定的 IOCTL 命令,则返回此错误。 如果传输提供程序不支持 SIO_APPLY_TRANSPORT_SETTING IOCTL,也会返回此错误。 在 UDP 或 TCP 以外的套接字上尝试使用 SIO_APPLY_TRANSPORT_SETTING IOCTL 时,也会返回此错误。 |
备注
SIO_APPLY_TRANSPORT_SETTING IOCTL 在操作系统的 Windows 8、Windows Server 2012 及更高版本上受支持。
SIO_APPLY_TRANSPORT_SETTING IOCTL 是用于将传输设置应用于套接字的通用 IOCTL。 正在应用的传输设置基于在 lpvInBuffer 参数中传递的TRANSPORT_SETTING_ID。
从 Windows 8 和 Windows Server 2012 开始,系统会在 TCP 套接字上定义REAL_TIME_NOTIFICATION_CAPABILITY功能。 从Windows 10和Windows Server 2016开始,还定义了ASSOCIATE_NAMERES_CONTEXT。 有关详细信息,请参阅 addrinfoex4 和 ASSOCIATE_NAMERES_CONTEXT_INPUT。
如果 lpvInBuffer 参数中传递 的TRANSPORT_SETTING_ID 的 Guid 成员设置为 REAL_TIME_NOTIFICATION_CAPABILITY,则这是一个请求,用于对 用于 ControlChannelTrigger 的 TCP 套接字应用实时通知设置,以便在 Windows 应用商店应用中接收后台网络通知。 lpvInBuffer 参数应指向REAL_TIME_NOTIFICATION_SETTING_INPUT结构。 此操作未使用 lpvOutBuffer 参数。 此传输设置仅适用于 TCP 套接字。 此传输设置为 WinInet 或类似的网络服务提供了一种方法,用于将给定的 TCP 套接字标记为已启用 ControlChannelTrigger 。 调用此选项时,Windows 将标记相应的 TCP 套接字并配置相应的硬件和软件设置。 Windows 应用商店应用不会直接调用此 IOCTL。