SIO_ASSOCIATE_PORT_RESERVATION控制代码

项目
06/13/2023

说明

SIO_ASSOCIATE_PORT_RESERVATION控制代码将套接字与由端口预留令牌标识的 TCP 或 UDP 块的持久性或运行时预留相关联。必须在绑定套接字之前颁发此 IOCTL。如果和当套接字绑定时，将从给定令牌标识的端口预留中选择分配给它的端口。如果指定预留中没有可用的端口，绑定函数调用将失败。

若要执行此操作，请使用以下参数调用 WSAIoctl 或 WSPIoctl 函数。

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the 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_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the 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_ASSOCIATE_PORT_RESERVATION 。

lpvInBuffer

指向输入缓冲区的指针。此参数包含指向 INET_PORT_RESERVATION_TOKEN 结构的指针，其中包含要与套接字关联的 TCP 或 UDP 端口预留的令牌。

cbInBuffer

输入缓冲区的大小（以字节为单位）。此参数必须至少为 INET_PORT_RESERVATION_TOKEN 结构的大小。

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 命令而取消了重叠的操作，则返回此错误。
WSAEACCES	尝试以访问权限禁止的方式访问套接字。对于永久性端口预留，以下几种情况会返回此错误：用户在本地计算机上缺少所需的管理权限，或者应用程序未在增强的 shell 中运行，因为内置管理员 (`RunAs administrator`) 。
WSAEFAULT	系统在尝试在调用中使用指针参数时检测到指针地址无效。此错误返回的 lpvInBuffer、 lpvoutBuffer、 lhttpBytesReturned、 lpOverlapped 或 lpCompletionRoutine 参数未完全包含在用户地址空间的有效部分。
WSAEINPROGRESS	阻止操作当前正在执行。如果在回调正在进行时调用函数，则返回此错误。
WSAEINTR	对 WSACancelBlockingCall 的调用中断了阻止操作。如果阻止操作中断，则返回此错误。
WSAEINVAL	提供了无效的参数。如果 dwIoControlCode 参数不是有效的命令，或者指定的输入参数不可接受，或者命令不适用于指定的套接字类型，则返回此错误。
WSAENETDOWN	套接字操作遇到了一个已死的网络。如果网络子系统发生故障，则返回此错误。
WSAENOTSOCK	尝试对不是套接字的内容执行操作。如果描述符不是套接字，则返回此错误。
WSAEOPNOTSUPP	所引用对象的类型不支持尝试的操作。如果不支持指定的 IOCTL 命令，则返回此错误。如果传输提供程序不支持 SIO_ASSOCIATE_PORT_RESERVATION IOCTL，也会返回此错误。在 UDP 或 TCP 以外的套接字上尝试使用 SIO_ASSOCIATE_PORT_RESERVATION IOCTL 时，也会返回此错误。

备注

SIO_ASSOCIATE_PORT_RESERVATION IOCTL 在 Windows Vista 和更高版本的操作系统上受支持。

需要保留端口的应用程序和服务分为两类。第一个类别包括需要特定端口作为其操作的一部分的组件。此类组件通常倾向于在应用程序清单中 (在安装时指定所需的端口，例如) 。第二个类别包括在运行时需要任何可用端口或端口块的组件。这两个类别对应于特定和通配符端口预留请求。特定预留请求可以是永久性的或运行时的，而通配符端口预留请求仅在运行时受支持。

SIO_ASSOCIATE_PORT_RESERVATION IOCTL 用于将 TCP 或 UDP 端口预留与永久性或运行时预留相关联。

CreatePersistentTcpPortReservation 或 CreatePersistentUdpPortReservation 函数使应用程序或服务能够保留 TCP 或 UDP 端口的永久性块。永久性端口预留记录在 Windows 中的 TCP 或 UDP 模块的持久存储中。请注意，每次重启系统时，给定持久端口预留的令牌可能会更改。

获取永久性 TCP 或 UDP 端口预留后，应用程序可以通过打开 TCP 或 UDP 套接字，然后调用 WSAIoctl 函数，指定 SIO_ASSOCIATE_PORT_RESERVATION IOCTL 并传递预留令牌，然后再对套接字上的绑定函数发出调用，从而从端口预留请求分配。

SIO_ACQUIRE_PORT_RESERVATION IOCTL 可用于请求 TCP 或 UDP 端口块的运行时预留。对于运行时端口预留，端口池要求从向其授予预留的套接字的进程使用预留。运行时端口预留的持续时间仅为调用 SIO_ACQUIRE_PORT_RESERVATION IOCTL 的套接字的生存期。相比之下，使用 CreatePersistentTcpPortReservation 或 CreatePersistentUdpPortReservation 函数创建的永久性端口预留可由能够获取永久性预留的任何进程使用。

获取运行时 TCP 或 UDP 端口预留后，应用程序可以通过打开 TCP 或 UDP 套接字，然后调用 WSAIoctl 函数以指定 SIO_ASSOCIATE_PORT_RESERVATION IOCTL 并传递预留令牌，然后再对套接字上的绑定函数发出调用，从而从端口预留请求分配。

如果 lpOverlapped 和 lpCompletionRoutine 参数均为 NULL，则此函数中的套接字将被视为非重叠套接字。对于非重叠套接字，将忽略 lpOverlapped 和 lpCompletionRoutine 参数，但 当套接字处于 阻止模式时，函数可能会阻止。如果 套接字处于 非阻止模式，此函数仍将阻止，因为此特定 IOCTL 不支持非阻止模式。

对于重叠的套接字，将启动无法立即完成的操作，并在以后指示完成。

任何 IOCTL 都可能无限期阻止，具体取决于服务提供商的实现。如果应用程序不能容忍 WSAIoctl 或 WSPIoctl 函数调用中的阻塞，则会建议对特别可能阻止的 IOCTL 使用重叠 I/O。

在以下情况下 ，SIO_ASSOCIATE_PORT_RESERVATION IOCTL 可能会失败并出现 WSAEINTR 或 WSA_OPERATION_ABORTED ：

I/O 管理器取消请求。
套接字已关闭。

传递给持久端口预留的 WSAIoctl 或 WSPIoctl 函数的SIO_ASSOCIATE_PORT_RESERVATION IOCTL 只能在用户以 Administrators 组成员身份登录时在应用程序中使用。如果用户不是 Administrators 组的成员，则 SIO_ASSOCIATE_PORT_RESERVATION 应用程序中使用 IOCTL，则函数调用将失败并返回 WSAEACCES 。使用 SIO_ASSOCIATE_PORT_RESERVATION IOCTL 也可能失败，因为 Windows Vista 及更高版本上的用户帐户控制 (UAC) 。如果将此 IOCTL 与永久性端口预留一起使用的应用程序由以管理员组成员身份登录（而不是内置管理员）的用户执行，则此调用将失败，除非应用程序已在清单文件中标记为 requestedExecutionLevel 设置为 requireAdministrator。如果应用程序缺少此清单文件，则作为管理员组成员（而不是内置管理员）登录的用户必须在增强的 shell 中执行应用程序，因为内置管理员 (RunAs administrator) 才能使此功能成功。