CancelIoEx 関数 (ioapiset.h)
指定したファイル ハンドルの未処理の I/O 操作をマークします。 この関数で取り消されるのは、I/O 操作を作成したスレッドに関係なく、現在のプロセスの I/O 操作のみです。
構文
BOOL CancelIoEx(
[in] HANDLE hFile,
[in, optional] LPOVERLAPPED lpOverlapped
);
パラメーター
[in] hFile
ファイルへのハンドル。
[in, optional] lpOverlapped
非同期 I/O に使うデータを格納する OVERLAPPED データ構造体へのポインター。
このパラメーターが NULL の場合、hFile パラメーターに対するすべての I/O 要求は取り消されます。
このパラメーターが NULL でない場合、指定した lpOverlapped オーバーラップ構造体を持つファイルに対して発行された特定の I/O 要求のみが、取り消し済みとマークされます。つまり、1 つ以上の要求を取り消すことができます。また、CancelIo 関数を使ってファイル ハンドルの保留中の要求をすべて取り消すこともできます。
戻り値
関数が成功すると、戻り値は 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 関数は関連するエラー コードを返します。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 Transparent Failover (TFO) | はい |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | はい |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | ioapiset.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |