CreatePersistentUdpPortReservation 関数 (iphlpapi.h)

[アーティクル]
03/14/2023

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

構文

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

パラメーター

[in] StartPort

ネットワークバイト順の開始 UDP ポート番号。

[in] NumberOfPorts

予約する UDP ポート番号の数。

[out] Token

関数が成功した場合に返されるポート予約トークンへのポインター。

戻り値

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

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

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

注釈

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

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

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

これら 2 つのカテゴリは、特定のポート予約要求とワイルドカードポート予約要求に対応しています。特定の予約要求は永続的または実行時である場合があります。一方、ワイルドカードポート予約要求は実行時にのみサポートされます。

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

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

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

永続的な UDP ポート予約が取得されると、アプリケーションは UDP ソケットを開いてから WSAIoctl 関数を呼び出し、 SIO_ASSOCIATE_PORT_RESERVATION IOCTL を指定し、予約トークンを渡してからソケットのバインド関数の呼び出しを発行することで、UDP ポート予約からのポート割り当てを要求できます。

SIO_ACQUIRE_PORT_RESERVATION IOCTL を使用して、TCP または UDP ポートのブロックのランタイム予約を要求できます。ランタイムポート予約の場合、ポートプールでは、予約が許可されたソケット上のプロセスから予約を使用する必要があります。ランタイムポート予約は、 SIO_ACQUIRE_PORT_RESERVATION IOCTL が呼び出されたソケットの有効期間の間だけ続きます。これに対し、 CreatePersistentUdpPortReservation 関数を使用して作成された永続的なポート予約は、永続的な予約を取得できる任意のプロセスで使用できます。

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

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	iphlpapi.h
Library	Iphlpapi.lib
[DLL]	Iphlpapi.dll