SIO_RELEASE_PORT_RESERVATION控制代码

项目
06/13/2023

说明

SIO_RELEASE_PORT_RESERVATION控制代码为 TCP 或 UDP 端口块释放运行时预留。必须已使用 IOCTL SIO_ACQUIRE_PORT_RESERVATION 从颁发进程获取要释放的运行时预留。

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_RELEASE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to a INET_PORT_RESERVATION_TOKEN structure
  (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_RELEASE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to a INET_PORT_RESERVATION_TOKEN structure
  (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.
);

parameters

S

标识套接字的描述符。

dwIoControlCode

操作的控制代码。对此操作使用 SIO_RELEASE_PORT_RESERVATION 。

lpvInBuffer

指向输入缓冲区的指针。此参数包含指向 INET_PORT_RESERVATION_TOKEN 结构的指针，其中包含要发布的 TCP 或 UDP 端口预留的令牌。

cbInBuffer

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

lpvOutBuffer

指向输出缓冲区的指针。此参数未用于此操作。

cbOutBuffer

输出缓冲区的大小（以字节为单位）。该参数必须设置为零。

lpcbBytesReturned

指向变量的指针，该变量接收存储在输出缓冲区中的数据的大小（以字节为单位）。

如果输出缓冲区太小，则调用失败， WSAGetLastError 返回 WSAEINVAL， lBytesReturned 参数指向 DWORD 值零。

如果 lpOverlapped 为 NULL，则成功调用时返回的 lpcbBytesReturned 参数指向的 DWORD 值不能为零。

如果对于重叠套接字， lpOverlapped 参数不是 NULL ，则将启动无法立即完成的操作，并在以后的时间指示完成。返回的 lpcbBytesReturned 参数指向的 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	系统在尝试在调用中使用指针参数时检测到指针地址无效。此错误返回 lpOverlapped 或 lpCompletionRoutine 参数未完全包含在用户地址空间的有效部分。
WSAEINPROGRESS	阻止操作当前正在执行。如果在回调正在进行时调用函数，则返回此错误。
WSAEINTR	调用 WSACancelBlockingCall 中断了阻止操作。如果阻止操作中断，则返回此错误。
WSAEINVAL	提供了无效的参数。如果 dwIoControlCode 参数不是有效的命令，或者指定的输入参数不可接受，或者命令不适用于指定的套接字类型，则返回此错误。
WSAENETDOWN	套接字操作遇到了一个已死的网络。如果网络子系统发生故障，则返回此错误。
WSAENOTSOCK	尝试对不是套接字的内容执行操作。如果描述符不是套接字，则返回此错误。
WSAEOPNOTSUPP	引用的对象类型不支持尝试的操作。如果不支持指定的 IOCTL 命令，则返回此错误。如果传输提供程序不支持 SIO_RELEASE_PORT_RESERVATION IOCTL，也会返回此错误。在 UDP 或 TCP 以外的套接字上尝试使用 IOCTL SIO_RELEASE_PORT_RESERVATION 时，也会返回此错误。

备注

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

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

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

SIO_RELEASE_PORT_RESERVATION IOCTL 用于释放 TCP 或 UDP 端口块的运行时预留。

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

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

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

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

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

示例

以下示例获取运行时端口预留，然后释放运行时端口预留。

#ifndef UNICODE
#define UNICODE
#endif

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <Windows.h.>
#include <winsock2.h>
#include <mstcpip.h>
#include <ws2ipdef.h>
#include <stdio.h>
#include <stdlib.h>

// Need to link with Ws2_32.lib for Winsock functions
#pragma comment(lib, "ws2_32.lib")

int wmain(int argc, WCHAR ** argv)
{

    // Declare and initialize variables

    int startPort = 0;          // host byte order
    int numPorts = 0;
    USHORT startPortns = 0;     // Network byte order

    INET_PORT_RANGE portRange = { 0 };
    INET_PORT_RESERVATION_INSTANCE portRes = { 0 };

    unsigned long status = 0;

    WSADATA wsaData = { 0 };
    int iResult = 0;

    SOCKET sock = INVALID_SOCKET;
    int iFamily = AF_INET;
    int iType = 0;
    int iProtocol = 0;

    SOCKET sockRes = INVALID_SOCKET;

    DWORD bytesReturned = 0;

    // Validate the parameters
    if (argc != 6) {
        wprintf
            (L"usage: %s <addressfamily> <type> <protocol> <StartingPort> <NumberOfPorts>\n",
             argv[0]);
        wprintf(L"Opens a socket for the specified family, type, & protocol\n");
        wprintf
            (L"and then acquires a runtime port reservation for the protocol specified\n");
        wprintf(L"%ws example usage\n", argv[0]);
        wprintf(L"   %ws 2 2 17 5000 20\n", argv[0]);
        wprintf(L"   where AF_INET=2 SOCK_DGRAM=2 IPPROTO_UDP=17 StartPort=5000 NumPorts=20", argv[0]);

        return 1;
    }

    iFamily = _wtoi(argv[1]);
    iType = _wtoi(argv[2]);
    iProtocol = _wtoi(argv[3]);

    startPort = _wtoi(argv[4]);
    if (startPort < 0 || startPort > 65535) {
        wprintf(L"Starting point must be either 0 or between 1 and 65,535\n");
        return 1;
    }
    startPortns = htons((USHORT) startPort);

    numPorts = _wtoi(argv[5]);
    if (numPorts < 0) {
        wprintf(L"Number of ports must be a positive number\n");
        return 1;
    }

    portRange.StartPort = startPortns;
    portRange.NumberOfPorts = (USHORT) numPorts;

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed with error = %d\n", iResult);
        return 1;
    }

    sock = socket(iFamily, iType, iProtocol);
    if (sock == INVALID_SOCKET) {
        wprintf(L"socket function failed with error = %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    } else {
        wprintf(L"socket function succeeded\n");

        iResult =
            WSAIoctl(sock, SIO_ACQUIRE_PORT_RESERVATION, (LPVOID) & portRange,
                     sizeof (INET_PORT_RANGE), (LPVOID) & portRes,
                     sizeof (INET_PORT_RESERVATION_INSTANCE), &bytesReturned, NULL, NULL);
        if (iResult != 0) {
            wprintf(L"WSAIoctl(SIO_ACQUIRE_PORT_RESERVATION) failed with error = %d\n",
                    WSAGetLastError());
            closesocket(sock);
            WSACleanup();
            return 1;
        } else {
            wprintf
                (L"WSAIoctl(SIO_ACQUIRE_PORT_RESERVATION) succeeded, bytesReturned = %u\n",
                 bytesReturned);
            wprintf(L"  Starting port=%d,  Number of Ports=%d, Token=%I64d\n",
                    htons(portRes.Reservation.StartPort),
                    portRes.Reservation.NumberOfPorts, portRes.Token);

            iResult =
                WSAIoctl(sock, SIO_RELEASE_PORT_RESERVATION, (LPVOID) & portRes.Token,
                         sizeof (ULONG64), NULL, 0, &bytesReturned, NULL, NULL);
            if (iResult != 0) {
                wprintf
                    (L"WSAIoctl(SIO_RELEASE_PORT_RESERVATION) failed with error = %d\n",
                     WSAGetLastError());
            } else {
                wprintf
                    (L"WSAIoctl(SIO_RELEASE_PORT_RESERVATION) succeeded, bytesReturned = %u\n",
                     bytesReturned);
            }
        }

        if (sock != INVALID_SOCKET) {
            iResult = closesocket(sock);
            if (iResult == SOCKET_ERROR) {
                wprintf(L"closesocket for first socket failed with error = %d\n",
                        WSAGetLastError());
            }
        }
    }

    WSACleanup();

    return 0;
}