SIO_APPLY_TRANSPORT_SETTING控制代码

说明

SIO_APPLY_TRANSPORT_SETTING控制代码将一个或多个传输设置应用于套接字。

若要执行此操作,请使用以下参数调用 WSAIoctlWSPIoctl 函数。

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 值零。

如果 lpOverlappedNULL,则成功调用时返回的lBytesReturned 参数指向的 DWORD 值不能为零。

如果重叠套接字的 lpOverlapped 参数不为 NULL ,则将启动无法立即完成的操作,并在以后指示完成。 返回的lBytesReturned 参数指向的 DWORD 值可能为零,因为在重叠操作完成之前无法确定存储的数据的大小。 当操作完成时发出相应的完成方法信号时,可以检索最终完成状态。

lpvOverlapped

指向 WSAOVERLAPPED 结构的指针。

如果 创建的套接字 没有重叠属性,则忽略 lpOverlapped 参数。

如果使用重叠属性打开了 并且 lpOverlapped 参数不为 NULL,则该操作将作为重叠 (异步) 操作执行。 在这种情况下, lpOverlapped 参数必须指向有效的 WSAOVERLAPPED 结构。

对于重叠操作, WSAIoctlWSPIoctl 函数将立即返回,并在操作完成时发出相应的完成方法信号。 否则,在操作完成或发生错误之前,函数不会返回 。

lpCompletionRoutine

类型:_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

指向完成操作时调用的完成例程的指针, (忽略非重叠套接字) 。

lpThreadId

指向 WSATHREADID 结构的指针,供提供程序在后续调用 WPUQueueApc 时使用。 在 WPUQueueApc 函数返回之前,提供程序应存储引用的 WSATHREADID 结构 (而不是指向同一) 的指针。

注意 此参数仅适用于 WSPIoctl 函数。

lpErrno

指向错误代码的指针。

注意 此参数仅适用于 WSPIoctl 函数。

返回值

如果操作成功完成, WSAIoctlWSPIoctl 函数将返回零。

如果操作失败或挂起, WSAIoctlWSPIoctl 函数将返回 SOCKET_ERROR。 若要获取扩展的错误信息,请调用 WSAGetLastError

错误代码 含义
WSA_IO_PENDING 重叠 I/O 操作正在进行中。 如果已成功启动重叠操作,并且稍后将指示完成,则返回此值。
WSA_OPERATION_ABORTED 由于发生线程退出或应用程序请求,I/O 操作已中止。 如果由于套接字关闭或执行 SIO_FLUSH IOCTL 命令而取消了重叠的操作,则返回此错误。
WSAEFAULT 系统在尝试在调用中使用指针参数时检测到指针地址无效。 此错误返回的 lpvInBufferlpvoutBufferlhttpBytesReturnedlpOverlappedlpCompletionRoutine 参数未完全包含在用户地址空间的有效部分。
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。 有关详细信息,请参阅 addrinfoex4ASSOCIATE_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。

另请参阅

ControlChannelTrigger

socket

SIO_QUERY_TRANSPORT_SETTING

TRANSPORT_SETTING_ID

WSAGetLastError

WSAGetOverlappedResult

WSAIoctl

WSAOVERLAPPED

WSASocketA

WSASocketW