CreatePersistentUdpPortReservation 関数 (iphlpapi.h)

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

こちらもご覧ください

CreatePersistentTcpPortReservation

DeletePersistentTcpPortReservation

DeletePersistentUdpPortReservation

LookupPersistentTcpPortReservation

LookupPersistentUdpPortReservation

SIO_ACQUIRE_PORT_RESERVATION

SIO_ASSOCIATE_PORT_RESERVATION

SIO_RELEASE_PORT_RESERVATION

WSAIoctl

bind