LookupPersistentTcpPortReservation 함수(iphlpapi.h)

아티클
03/14/2023

LookupPersistentTcpPortReservation 함수는 로컬 컴퓨터에서 연속된 TCP 포트 블록에 대한 영구 TCP 포트 예약에 대한 토큰을 조회합니다.

구문

IPHLPAPI_DLL_LINKAGE ULONG LookupPersistentTcpPortReservation(
  [in]  USHORT   StartPort,
  [in]  USHORT   NumberOfPorts,
  [out] PULONG64 Token
);

매개 변수

[in] StartPort

네트워크 바이트 순서의 시작 TCP 포트 번호입니다.

[in] NumberOfPorts

예약된 TCP 포트 번호의 수입니다.

[out] Token

함수가 성공하면 반환되는 포트 예약 토큰에 대한 포인터입니다.

반환 값

함수가 성공하면 반환 값이 NO_ERROR.

함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.

반환 코드	설명
ERROR_INVALID_PARAMETER	잘못된 매개 변수가 함수에 전달되었습니다. StartPort 또는 NumberOfPorts 매개 변수에 0 이 전달되면 이 오류가 반환됩니다.
ERROR_NOT_FOUND	요소를 찾을 수 없습니다. StartPort 및 NumberOfPorts 매개 변수로 지정된 영구 포트 블록을 찾을 수 없는 경우 이 오류가 반환됩니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

LookupPersistentTcpPortReservation 함수는 Windows Vista 이상에서 정의됩니다.

LookupPersistentTcpPortReservation 함수는 TCP 포트 블록에 대한 영구 예약에 대한 토큰을 조회하는 데 사용됩니다.

TCP 포트 블록에 대한 영구 예약은 CreatePersistentTcpPortReservation 함수를 호출하여 생성됩니다. LookupPersistentTcpPortReservation 함수에 전달된 StartPort 또는 NumberOfPorts 매개 변수는 CreatePersistentTcpPortReservation 함수에서 TCP 포트 블록에 대한 영구 예약을 만들 때 사용되는 값과 일치해야 합니다.

LookupPersistentTcpPortReservation 함수가 성공하면 반환된 토큰 매개 변수는 TCP 포트 블록에 대한 영구 포트 예약에 대한 토큰을 가리킵니다. 시스템이 다시 시작될 때마다 TCP 포트 블록에 대해 지정된 영구 예약에 대한 토큰이 변경될 수 있습니다.

애플리케이션은 TCP 소켓을 연 다음 WSAIoctl 함수를 호출하여 SIO_ASSOCIATE_PORT_RESERVATION IOCTL을 지정하고 소 켓에서 바인딩 함수에 대한 호출을 실행하기 전에 예약 토큰을 전달하여 TCP 포트 예약에서 포트 할당을 요청할 수 있습니다.

예제

다음 예제에서는 영구 TCP 포트 예약을 조회한 다음 소켓을 만들고 포트 예약에서 포트를 할당합니다.

#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 <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

// Need to link with iphlpapi.lib
#pragma comment(lib, "iphlpapi.lib")

// 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
    ULONG64 resToken = {0};
    
    unsigned long status = 0;

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

    SOCKET sock = INVALID_SOCKET;
    int iFamily = AF_INET;
    int iType = SOCK_STREAM;
    int iProtocol = IPPROTO_TCP;

    DWORD bytesReturned = 0;

    // Note that the sockaddr_in struct works only with AF_INET not AF_INET6
    // An application needs to use the sockaddr_in6 for AF_INET6
    sockaddr_in service; 
    sockaddr_in sockName;
    int nameLen = sizeof(sockName);
    
    // Validate the parameters
    if (argc != 3) {
        wprintf(L"usage: %s <Starting Port> <Number of Ports>\n", 
            argv[0]);
        wprintf(L"Look up a persistent TCP port reservation\n");
        wprintf(L"Example usage:\n");
        wprintf(L"   %s 5000 20\n", argv[0]);
        wprintf(L"   where StartPort=5000 NumPorts=20");
        return 1;
    }

    startPort = _wtoi(argv[1]);
    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[2]);
    if (numPorts < 0) {
        wprintf(L"Number of ports must be a positive number\n");
        return 1;
    }    

    status = LookupPersistentTcpPortReservation((USHORT) startPortns, (USHORT) numPorts, &resToken);
    if( status != NO_ERROR )
    {
        wprintf(L"LookupPersistentTcpPortReservation returned error: %ld\n", 
            status);
        return 1;
    }

    wprintf(L"LookupPersistentTcpPortReservation call succeeded\n");
    wprintf(L"  Token = %I64d\n", resToken);  
  
    // Comment out this block if you don't want to create a socket and associate it with the 
    // persistent reservation

    // 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());
    else {
        wprintf(L"socket function succeeded\n");

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

            service.sin_family = AF_INET;
            service.sin_addr.s_addr = INADDR_ANY;
            service.sin_port = 0;

            iResult = bind(sock, (SOCKADDR*) &service, sizeof(service) );
            if (iResult == SOCKET_ERROR)
                wprintf(L"bind failed with error = %d\n", WSAGetLastError());
            else {
                wprintf(L"bind succeeded\n");
                iResult = getsockname(sock, (SOCKADDR*) &sockName, &nameLen);
                if (iResult == SOCKET_ERROR) 
                    wprintf(L"getsockname failed with error = %d\n", WSAGetLastError() );
                else {
                    wprintf(L"getsockname succeeded\n");
                    wprintf(L"Port number allocated = %u\n", ntohs(sockName.sin_port) );
                }
            }                  
        }

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

    return 0;
}

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	iphlpapi.h
라이브러리	Iphlpapi.lib
DLL	Iphlpapi.dll