SIO_ASSOCIATE_PORT_RESERVATION コントロール コード
説明
SIO_ASSOCIATE_PORT_RESERVATION制御コードは、ポート予約トークンによって識別される TCP または UDP のブロックの永続予約またはランタイム予約にソケットを関連付けます。 ソケットがバインドされる前に、この IOCTL を発行する必要があります。 ソケットがバインドされている場合、それに割り当てられたポートは、指定されたトークンによって識別されるポート予約から選択されます。 指定した予約から使用可能なポートがない場合、 バインド 関数の呼び出しは失敗します。
この操作を実行するには、次のパラメーターを使用して WSAIoctl または WSPIoctl 関数を呼び出します。
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
(LPVOID) lpvInBuffer, // pointer to an INET_PORT_RESERVATION_TOKEN
(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_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
(LPVOID) lpvInBuffer, // pointer to an INET_PORT_RESERVATION_TOKEN
(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.
);
パラメーター
s
ソケットを識別する記述子。
dwIoControlCode
操作の制御コード。 この操作 にはSIO_ASSOCIATE_PORT_RESERVATION を使用します。
lpvInBuffer
入力バッファーへのポインター。 このパラメーターには、ソケットに関連付ける TCP または UDP ポート予約のトークンを持つ INET_PORT_RESERVATION_TOKEN 構造体へのポインターが含まれています。
cbInBuffer
入力バッファーのサイズ (バイト単位)。 このパラメーターは、少なくとも INET_PORT_RESERVATION_TOKEN 構造体のサイズである必要があります。
lpvOutBuffer
出力バッファーへのポインター。 このパラメーターは、この操作では使用されません。
cbOutBuffer
出力バッファーのサイズ (バイト単位)。 このパラメーターは 0 に設定する必要があります。
lpcbBytesReturned
出力バッファーに格納されているデータのサイズをバイト単位で受け取る変数へのポインター。
出力バッファーが小さすぎると、呼び出しは失敗し、 WSAGetLastError はWSAEINVAL を返し、 lpcbBytesReturned パラメーターはDWORD 値 0 を指します。
lpOverlapped が NULL の場合、正常な呼び出しで返される lpcbBytesReturned パラメーターが指す DWORD 値を 0 にすることはできません。
重複するソケットに 対して lpOverlapped パラメーターが NULL でない場合、すぐに完了できない操作が開始され、完了は後で示されます。 返される lpcbBytesReturned パラメーターが指す DWORD 値は、重複する操作が完了するまで格納されているデータのサイズを決定できないため、0 になる場合があります。 最終的な完了状態は、操作が完了したときに適切な完了メソッドが通知されたときに取得できます。
lpvOverlapped
WSAOVERLAPPED 構造体へのポインター。
重複する属性なしでソケット s が作成された場合、 lpOverlapped パラメーターは無視されます。
重複した属性を使用して s を開き、 lpOverlapped パラメーターが NULL でない場合、操作は重複 (非同期) 操作として実行されます。 この場合、 lpOverlapped パラメーターは有効な WSAOVERLAPPED 構造体を指している必要があります。
重複する操作の場合、 WSAIoctl または WSPIoctl 関数は直ちにを返し、操作が完了すると適切な完了メソッドが通知されます。 それ以外の場合、操作が完了するかエラーが発生するまで、関数は を返しません。
lpCompletionRoutine
種類: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
操作が完了したときに呼び出される完了ルーチンへのポインター (重複していないソケットの場合は無視されます)。
lpThreadId
WPUQueueApc への後続の呼び出しでプロバイダーによって使用される WSATHREADID 構造体へのポインター。 プロバイダーは、WPUQueueApc 関数が返されるまで、参照先の WSATHREADID 構造体 (同じへのポインターではない) を格納する必要があります。
メモ このパラメーターは 、WSPIoctl 関数にのみ適用されます。
lpErrno
エラー コードへのポインター。
メモ このパラメーターは 、WSPIoctl 関数にのみ適用されます。
戻り値
操作が正常に完了すると、 WSAIoctl または WSPIoctl 関数は 0 を返します。
操作が失敗した場合、または保留中の場合、 WSAIoctl または WSPIoctl 関数は SOCKET_ERRORを返します。 拡張エラー情報を取得するには、 WSAGetLastError を呼び出します。
| エラー コード | 意味 |
|---|---|
| WSA_IO_PENDING | 重複した I/O 操作が進行中です。 この値は、重複した操作が正常に開始され、完了が後で示される場合に返されます。 |
| WSA_OPERATION_ABORTED | スレッドの終了またはアプリケーションの要求が原因で、I/O 操作が中止されました。 このエラーは、ソケットのクローズまたは SIO_FLUSH IOCTL コマンドの実行により、重複した操作が取り消された場合に返されます。 |
| WSAEACCES | アクセス許可によって禁止されている方法でソケットにアクセスしようとしました。 このエラーは、次のような永続的なポート予約のいくつかの条件下で返されます。ユーザーがローカル コンピューターで必要な管理特権を持っていないか、アプリケーションが組み込みの管理者 (RunAs administrator) として拡張シェルで実行されていません。 |
| WSAEFAULT | 呼び出しでポインター引数を使用しようとしたときに、システムによって無効なポインター アドレスが検出されました。 このエラーは、 lpvInBuffer、 lpvoutBuffer、 lpcbBytesReturned、 lpOverlapped または lpCompletionRoutine パラメーターが、ユーザー アドレス空間の有効な部分に完全に含まれていない場合に返されます。 |
| WSAEINPROGRESS | 現在、ブロック操作を実行中です。 このエラーは、コールバックの進行中に関数が呼び出された場合に返されます。 |
| WSAEINTR | WSACancelBlockingCall の呼び出しによってブロック操作が中断されました。 このエラーは、ブロック操作が中断された場合に返されます。 |
| WSAEINVAL | 無効な引数が指定されました。 このエラーは、 dwIoControlCode パラメーターが有効なコマンドではない場合、または指定した入力パラメーターが受け入れられない場合、または指定されたソケットの型にコマンドが適用されない場合に返されます。 |
| WSAENETDOWN | ソケット操作によりネットワークの停止が検出されました。 このエラーは、ネットワーク サブシステムが失敗した場合に返されます。 |
| WSAENOTSOCK | ソケットではない何かに対して操作が試行されました。 記述子 s がソケットでない場合、このエラーが返されます。 |
| WSAEOPNOTSUPP | 参照されるオブジェクトの種類に対して、試行された操作はサポートされていません。 このエラーは、指定された IOCTL コマンドがサポートされていない場合に返されます。 このエラーは、 SIO_ASSOCIATE_PORT_RESERVATION IOCTL がトランスポート プロバイダーでサポートされていない場合にも返されます。 このエラーは、 SIO_ASSOCIATE_PORT_RESERVATION IOCTL の使用が UDP または TCP 以外のソケットで行われた場合にも返されます。 |
解説
SIO_ASSOCIATE_PORT_RESERVATION IOCTL は、Windows Vista 以降のバージョンのオペレーティング システムでサポートされています。
ポートを予約する必要があるアプリケーションとサービスは、2 つのカテゴリに分類されます。 最初のカテゴリには、操作の一部として特定のポートを必要とするコンポーネントが含まれます。 このようなコンポーネントは、通常、インストール時に必要なポートを指定することを好みます (たとえば、アプリケーション マニフェスト内)。 2 番目のカテゴリには、実行時に使用可能なポートまたはポート ブロックを必要とするコンポーネントが含まれます。 これら 2 つのカテゴリは、特定のポート予約要求とワイルドカード ポート予約要求に対応します。 特定の予約要求は永続的または実行時である場合があります。一方、ワイルドカード ポート予約要求は実行時にのみサポートされます。
SIO_ASSOCIATE_PORT_RESERVATION IOCTL は、TCP または UDP ポート予約を永続予約またはランタイム予約に関連付けるために使用されます。
CreatePersistentTcpPortReservation または CreatePersistentUdpPortReservation 関数は、アプリケーションまたはサービスが TCP または UDP ポートの永続的なブロックを予約する機能を提供します。 永続的なポート予約は、Windows の TCP または UDP モジュールの永続ストアに記録されます。 特定の永続的なポート予約のトークンは、システムが再起動されるたびに変更される可能性があることに注意してください。
永続的な TCP または UDP ポート予約が取得されると、アプリケーションは TCP または UDP ソケットを開き、SIO_ASSOCIATE_PORT_RESERVATION IOCTL を指定して WSAIoctl 関数を呼び出し、予約トークンを渡してからソケットのバインド関数の呼び出しを発行することで、ポート予約からポート割り当てを要求できます。
SIO_ACQUIRE_PORT_RESERVATION IOCTL を使用して、TCP または UDP ポートのブロックのランタイム予約を要求できます。 ランタイム ポート予約の場合、ポート プールでは、予約が許可されたソケット上のプロセスから予約を使用する必要があります。 ランタイム ポート予約は、 SIO_ACQUIRE_PORT_RESERVATION IOCTL が呼び出されたソケットの有効期間に限り続きます。 これに対し、 CreatePersistentTcpPortReservation または CreatePersistentUdpPortReservation 関数を使用して作成された永続的なポート予約は、永続的な予約を取得する機能を持つ任意のプロセスによって使用される場合があります。
ランタイム TCP または UDP ポート予約が取得されると、アプリケーションは TCP または UDP ソケットを開き、SIO_ASSOCIATE_PORT_RESERVATION IOCTL を指定して WSAIoctl 関数を呼び出し、予約トークンを渡してからソケットのバインド関数の呼び出しを発行することで、ポート予約からポート割り当てを要求できます。
lpOverlapped パラメーターと lpCompletionRoutine パラメーターの両方が NULL の場合、この関数のソケットは重複しないソケットとして扱われます。 重複していないソケットの場合、 lpOverlapped パラメーターと lpCompletionRoutine パラメーターは無視されます。ただし、ソケット s がブロック モードの場合、関数はブロックできます。 ソケット s が非ブロッキング モードの場合、この特定の IOCTL では非ブロッキング モードがサポートされていないため、この関数は引き続きブロックされます。
重複するソケットの場合、すぐに完了できない操作が開始され、完了は後で示されます。
サービス プロバイダーの実装によっては、IOCTL が無期限にブロックされる場合があります。 アプリケーションが WSAIoctl 関数呼び出しまたは WSPIoctl 関数呼び出しでブロックを許容できない場合は、特にブロックする可能性が高い IOCTL に対して重複した I/O が推奨されます。
SIO_ASSOCIATE_PORT_RESERVATION IOCTL は、次の場合に WSAEINTR またはWSA_OPERATION_ABORTEDで失敗する可能性があります。
- 要求は I/O マネージャーによって取り消されます。
- ソケットが閉じています。
永続的なポート予約の WSAIoctl または WSPIoctl 関数に渡されるSIO_ASSOCIATE_PORT_RESERVATION IOCTL は、ユーザーが Administrators グループのメンバーとしてログオンしている場合にのみ、アプリケーションで使用できます。
ユーザー が Administrators グループのメンバーでないときにアプリケーションで IOCTL SIO_ASSOCIATE_PORT_RESERVATION使用すると、関数呼び出しは失敗し、 WSAEACCES が返されます。
また、Windows Vista 以降のユーザー アカウント制御 (UAC) により、 SIO_ASSOCIATE_PORT_RESERVATION IOCTL の使用が失敗する可能性があります。
永続的なポート予約でこの IOCTL を使用するアプリケーションが、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしているユーザーによって実行された場合、 要求されたExecutionLevel が requireAdministrator に設定されたマニフェスト ファイルでアプリケーションがマークされていない限り、この呼び出しは失敗します。
アプリケーションにこのマニフェスト ファイルがない場合、組み込みの Administrator 以外の Administrators グループのメンバーとしてログオンしたユーザーは、この関数を成功させるために、拡張シェルで組み込みの Administrator (RunAs administrator) としてアプリケーションを実行する必要があります。
関連項目
CreatePersistentTcpPortReservation
CreatePersistentUdpPortReservation
DeletePersistentTcpPortReservation
DeletePersistentUdpPortReservation
LookupPersistentTcpPortReservation
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示