ホーム › NetworkManagement.IpHelper › CreatePersistentUdpPortReservation

CreatePersistentUdpPortReservation

関数

永続的なUDPポート予約ブロックを作成する。

DLLIPHLPAPI.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// IPHLPAPI.dll
#include <windows.h>

DWORD CreatePersistentUdpPortReservation(
    WORD StartPort,
    WORD NumberOfPorts,
    ULONGLONG* Token
);

パラメーター

名前	型	方向	説明
StartPort	WORD	in	ネットワークバイトオーダーで指定する、開始UDPポート番号。
NumberOfPorts	WORD	in	予約するUDPポート番号の数。
Token	ULONGLONG*	out	関数が成功した場合に返される、ポート予約トークンへのポインター。

戻り値の型: DWORD

公式ドキュメント

ローカルコンピューター上で、連続するUDPポートのブロックに対して永続的なUDPポート予約を作成します。

戻り値

関数が成功した場合、戻り値は NO_ERROR です。

関数が失敗した場合、戻り値は次のいずれかのエラーコードになります。

戻り値	説明
ERROR_ACCESS_DENIED	アクセスが拒否されました。このエラーは、次のような複数の条件下で返されます。すなわち、ユーザーがローカルコンピューター上で必要な管理者権限を持っていない場合、またはアプリケーションが組み込みの Administrator として昇格したシェル(管理者として実行)で実行されていない場合です。
ERROR_INVALID_PARAMETER	無効なパラメーターが関数に渡されました。このエラーは、StartPort または NumberOfPorts パラメーターにゼロが渡された場合に返されます。また、StartPort パラメーターとの関係で NumberOfPorts パラメーターが大きすぎるブロックを指定しており、割り当て可能なポートのブロックが割り当て可能な最大ポートを超えてしまう場合にも返されます。
ERROR_SHARING_VIOLATION	ファイルが別のプロセスによって使用されているため、プロセスはそのファイルにアクセスできません。このエラーは、StartPort および NumberOfPorts パラメーターで指定されたUDPポートのブロック内のUDPポートが既に使用されている場合に返されます。また、StartPort および NumberOfPorts パラメーターで指定されたUDPポートのブロックに対する永続的な予約が、既に作成済みのUDPポートのブロックに対する永続的な予約と一致または重複する場合にも返されます。
その他	返されたエラーのメッセージ文字列を取得するには、 FormatMessage を使用してください。

解説(Remarks)

CreatePersistentUdpPortReservation 関数は、Windows Vista 以降で定義されています。

CreatePersistentUdpPortReservation 関数は、UDPポートのブロックに対する永続的な予約を追加するために使用されます。

ポートを予約する必要があるアプリケーションやサービスは、2つのカテゴリーに分類されます。1つ目のカテゴリーには、その動作の一部として特定のポートを必要とするコンポーネントが含まれます。このようなコンポーネントは一般に、必要なポートをインストール時に(たとえばアプリケーションマニフェスト内で)指定することを好みます。2つ目のカテゴリーには、実行時に利用可能な任意のポートまたはポートのブロックを必要とするコンポーネントが含まれます。

これら2つのカテゴリーは、それぞれ特定(specific)のポート予約要求とワイルドカード(wildcard)のポート予約要求に対応します。特定の予約要求は永続的または実行時のいずれも可能ですが、ワイルドカードのポート予約要求は実行時のみサポートされます。

CreatePersistentUdpPortReservation 関数は、アプリケーションまたはサービスがUDPポートのブロックを永続的に予約する機能を提供します。永続的なTCP予約は、WindowsのUDPモジュール用の永続的なストアに記録されます。

呼び出し元は、必要なポート数と特定の範囲が必要かどうかを指定することで、永続的なポート予約を取得します。要求を満たすことができた場合、CreatePersistentUdpPortReservation 関数は一意で不透明な ULONG64 トークンを返します。このトークンは、以後その予約を識別します。永続的なUDPポート予約は、DeletePersistentUdpPortReservation 関数を呼び出すことで解放できます。なお、特定の永続的なUDPポート予約のトークンは、システムが再起動されるたびに変わる場合があります。

Windowsは、これらの関数を使用して取得した永続的な予約に対して、コンポーネント間のセキュリティを実装していません。これは、あるコンポーネントが永続的なポート予約を取得する権限を与えられている場合、そのコンポーネントは自動的に、システム上の他のコンポーネントに付与された永続的なポート予約を消費する権限も得ることを意味します。実行時の予約に対してはプロセスレベルのセキュリティが適用されますが、そのような制御を、CreatePersistentTcpPortReservation または CreatePersistentUdpPortReservation 関数を使用して作成された永続的な予約にまで拡張することはできません。

永続的なUDPポート予約を取得した後、アプリケーションはUDP socket を開き、次に WSAIoctl 関数を SIO_ASSOCIATE_PORT_RESERVATION IOCTL を指定して呼び出して予約トークンを渡し、その後 socket に対して bind 関数を呼び出すことにより、そのUDPポート予約からのポート割り当てを要求できます。

SIO_ACQUIRE_PORT_RESERVATION IOCTL は、TCPまたはUDPポートのブロックに対する実行時の予約を要求するために使用できます。実行時のポート予約の場合、ポートプールは、予約が付与された socket を持つプロセスから予約が消費されることを要求します。実行時のポート予約は、SIO_ACQUIRE_PORT_RESERVATION IOCTL が呼び出された socket の有効期間中のみ持続します。これに対して、CreatePersistentUdpPortReservation 関数を使用して作成された永続的なポート予約は、永続的な予約を取得する権限を持つ任意のプロセスによって消費される可能性があります。

CreatePersistentUdpPortReservation 関数は、Administrators グループのメンバーとしてログオンしているユーザーのみが呼び出すことができます。Administrators グループのメンバーでないユーザーが CreatePersistentUdpPortReservation を呼び出した場合、関数呼び出しは失敗し、ERROR_ACCESS_DENIED が返されます。この関数は、Windows Vista 以降ではユーザーアカウント制御(UAC)が原因で失敗することもあります。この関数を含むアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーによって実行された場合、そのアプリケーションのマニフェストファイルで requestedExecutionLevel が requireAdministrator に設定されていない限り、この呼び出しは失敗します。アプリケーションにこのマニフェストファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーは、この関数を成功させるために、組み込みの Administrator として昇格したシェル(管理者として実行)でアプリケーションを実行する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// IPHLPAPI.dll
#include <windows.h>

DWORD CreatePersistentUdpPortReservation(
    WORD StartPort,
    WORD NumberOfPorts,
    ULONGLONG* Token
);

[DllImport("IPHLPAPI.dll", ExactSpelling = true)]
static extern uint CreatePersistentUdpPortReservation(
    ushort StartPort,   // WORD
    ushort NumberOfPorts,   // WORD
    out ulong Token   // ULONGLONG* out
);

<DllImport("IPHLPAPI.dll", ExactSpelling:=True)>
Public Shared Function CreatePersistentUdpPortReservation(
    StartPort As UShort,   ' WORD
    NumberOfPorts As UShort,   ' WORD
    <Out> ByRef Token As ULong   ' ULONGLONG* out
) As UInteger
End Function

' StartPort : WORD
' NumberOfPorts : WORD
' Token : ULONGLONG* out
Declare PtrSafe Function CreatePersistentUdpPortReservation Lib "iphlpapi" ( _
    ByVal StartPort As Integer, _
    ByVal NumberOfPorts As Integer, _
    ByRef Token As LongLong) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CreatePersistentUdpPortReservation = ctypes.windll.iphlpapi.CreatePersistentUdpPortReservation
CreatePersistentUdpPortReservation.restype = wintypes.DWORD
CreatePersistentUdpPortReservation.argtypes = [
    ctypes.c_ushort,  # StartPort : WORD
    ctypes.c_ushort,  # NumberOfPorts : WORD
    ctypes.POINTER(ctypes.c_ulonglong),  # Token : ULONGLONG* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('IPHLPAPI.dll')
CreatePersistentUdpPortReservation = Fiddle::Function.new(
  lib['CreatePersistentUdpPortReservation'],
  [
    -Fiddle::TYPE_SHORT,  # StartPort : WORD
    -Fiddle::TYPE_SHORT,  # NumberOfPorts : WORD
    Fiddle::TYPE_VOIDP,  # Token : ULONGLONG* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "iphlpapi")]
extern "system" {
    fn CreatePersistentUdpPortReservation(
        StartPort: u16,  // WORD
        NumberOfPorts: u16,  // WORD
        Token: *mut u64  // ULONGLONG* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("IPHLPAPI.dll")]
public static extern uint CreatePersistentUdpPortReservation(ushort StartPort, ushort NumberOfPorts, out ulong Token);
"@
$api = Add-Type -MemberDefinition $sig -Name 'IPHLPAPI_CreatePersistentUdpPortReservation' -Namespace Win32 -PassThru
# $api::CreatePersistentUdpPortReservation(StartPort, NumberOfPorts, Token)

#uselib "IPHLPAPI.dll"
#func global CreatePersistentUdpPortReservation "CreatePersistentUdpPortReservation" sptr, sptr, sptr
; CreatePersistentUdpPortReservation StartPort, NumberOfPorts, varptr(Token)   ; 戻り値は stat
; StartPort : WORD -> "sptr"
; NumberOfPorts : WORD -> "sptr"
; Token : ULONGLONG* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "IPHLPAPI.dll"
#cfunc global CreatePersistentUdpPortReservation "CreatePersistentUdpPortReservation" int, int, var
; res = CreatePersistentUdpPortReservation(StartPort, NumberOfPorts, Token)
; StartPort : WORD -> "int"
; NumberOfPorts : WORD -> "int"
; Token : ULONGLONG* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "IPHLPAPI.dll"
#cfunc global CreatePersistentUdpPortReservation "CreatePersistentUdpPortReservation" int, int, sptr
; res = CreatePersistentUdpPortReservation(StartPort, NumberOfPorts, varptr(Token))
; StartPort : WORD -> "int"
; NumberOfPorts : WORD -> "int"
; Token : ULONGLONG* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。