CancelIoEx 関数
指定したファイル ハンドルの未処理の I/O 操作をマークします。 関数は、I/O 操作を作成したスレッドに関係なく、現在のプロセスの I/O 操作のみを取り消します。
構文
BOOL WINAPI CancelIoEx(
_In_ HANDLE hFile,
_In_opt_ LPOVERLAPPED lpOverlapped
);
パラメーター
-
hFile [in]
-
ファイルへのハンドル。
-
lpOverlapped [in, optional]
-
非同期 I/O に使用されるデータを含む OVERLAPPED データ構造へのポインター。
このパラメーターが NULL の場合、 hFile パラメーターに対するすべての I/O 要求が取り消されます。
このパラメーターが NULL でない場合は、指定された lpOverlapped 重複構造を持つファイルに対して発行された特定の I/O 要求のみが取り消し済みとしてマークされます。つまり、 CancelIo 関数はファイル ハンドルのすべての未処理の要求を取り消しながら、1 つ以上の要求を取り消すことができます。
戻り値
関数が成功すると、戻り値は 0 以外になります。 指定されたファイル ハンドルの呼び出しプロセスによって発行されたすべての保留中の I/O 操作の取り消し操作が正常に要求されました。 アプリケーションは、取り消された I/O 操作に関連付けられている OVERLAPPED 構造体を、完了するまで解放したり再利用したりしてはなりません。 スレッドは GetOverlappedResult 関数を使用して、I/O 操作自体がいつ完了したかを判断できます。
関数が失敗した場合、戻り値は 0 (ゼロ) になります。 拡張エラー情報を取得するには、 GetLastError 関数を呼び出します。
この関数で取り消す要求が見つからない場合、戻り値は 0 (ゼロ) になり、GetLastError はERROR_NOT_FOUNDを返します。
解説
CancelIoEx 関数を使用すると、呼び出し元スレッド以外のスレッドで要求を取り消すことができます。 CancelIo 関数は、 CancelIo 関数を呼び出したのと同じスレッド内の要求のみを 取り消 します。 CancelIoEx は 、ハンドルの未処理の I/O のみを取り消します。ハンドルの状態は変更されません。つまり、操作が正常に完了したか取り消されたかを把握できないため、ハンドルの状態に依存できません。
指定したファイル ハンドルに対して保留中の I/O 操作が進行中の場合、 CancelIoEx 関数によって取り消しがマークされます。 ほとんどの種類の操作は直ちに取り消すことができます。他の操作は、実際に取り消され、呼び出し元に通知される前に、完了に向けて続行できます。 CancelIoEx 関数は、取り消されたすべての操作が完了するまで待機しません。
ファイル ハンドルが完了ポートに関連付けられている場合、同期操作が正常に取り消された場合、I/O 完了パケットはポートにキューに登録されません。 非同期操作がまだ保留中の場合、取り消し操作は I/O 完了パケットをキューに入れます。
取り消される操作は、3 つの状態のいずれかで完了します。完了状態を確認するには、完了状態をチェックする必要があります。 次の 3 つの状態があります。
- 操作は正常に完了しました。 これは、操作を取り消すために取り消し要求が時間内に送信されていない可能性があるため、操作が取り消された場合でも発生する可能性があります。
- 操作は取り消されました。 GetLastError 関数は、ERROR_OPERATION_ABORTEDを返します。
- 操作が別のエラーで失敗しました。 GetLastError 関数は、関連するエラー コードを返します。
Windows 8とWindows Server 2012では、この関数は次のテクノロジでサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル |
はい |
| SMB 3.0 Transparent Failover (TFO) |
はい |
| スケールアウト ファイル共有を含む SMB 3.0 (SO) |
はい |
| クラスター共有ボリューム ファイル システム (CsvFS) |
はい |
| Resilient File System (ReFS) |
はい |
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント |
Windows Vista [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー |
Windows Server 2008 [デスクトップ アプリ |UWP アプリ] |
| Header |
|
| ライブラリ |
|
| [DLL] |
|