Win32 API 日本語リファレンス
ホームSystem.IO › CancelIoEx

CancelIoEx

関数
指定したオーバーラップI/O操作をキャンセルする。
DLLKERNEL32.dll呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// KERNEL32.dll
#include <windows.h>

BOOL CancelIoEx(
    HANDLE hFile,
    OVERLAPPED* lpOverlapped   // optional
);

パラメーター

名前方向説明
hFileHANDLEinファイルへのハンドルです。
lpOverlappedOVERLAPPED*inoptional

非同期 I/O に使用されるデータを格納する OVERLAPPED データ構造体へのポインターです。

このパラメーターが NULL の場合、hFile パラメーターに対するすべての I/O 要求がキャンセルされます。

このパラメーターが NULL でない場合、指定された lpOverlapped オーバーラップ構造体を使用してそのファイルに対して発行された特定の I/O 要求のみがキャンセル対象としてマークされます。つまり、1 つ以上の要求をキャンセルできます。一方、CancelIo 関数はファイルハンドルに対する未処理の要求をすべてキャンセルします。

戻り値の型: BOOL

公式ドキュメント

指定されたファイルハンドルに対する未処理の I/O 操作をすべてキャンセル対象としてマークします。この関数は、どのスレッドが I/O 操作を作成したかに関係なく、現在のプロセス内の I/O 操作のみをキャンセルします。

戻り値

関数が成功した場合、戻り値は 0 以外になります。指定されたファイルハンドルに対して呼び出し元プロセスが発行した、保留中のすべての I/O 操作に対するキャンセル操作が正常に要求されたことを示します。アプリケーションは、キャンセルされた I/O 操作が完了するまで、それらに関連付けられた OVERLAPPED 構造体を解放したり再利用したりしてはなりません。スレッドは GetOverlappedResult 関数を使用して、I/O 操作自体がいつ完了したかを判断できます。

関数が失敗した場合、戻り値は 0 (ゼロ) になります。拡張エラー情報を取得するには、GetLastError 関数を呼び出します。

この関数がキャンセルする要求を見つけられない場合、戻り値は 0 (ゼロ) になり、GetLastErrorERROR_NOT_FOUND を返します。

解説(Remarks)

CancelIoEx 関数を使用すると、呼び出し元のスレッド以外のスレッドの要求をキャンセルできます。CancelIo 関数は、CancelIo 関数を呼び出したスレッドと同じスレッド内の要求のみをキャンセルします。CancelIoEx はハンドルに対する未処理の I/O のみをキャンセルし、ハンドルの状態は変更しません。つまり、操作が正常に完了したのかキャンセルされたのかを知ることができないため、ハンドルの状態に依存することはできません。

指定されたファイルハンドルに対して進行中の保留中の I/O 操作がある場合、CancelIoEx 関数はそれらをキャンセル対象としてマークします。ほとんどの種類の操作は即座にキャンセルできますが、実際にキャンセルされて呼び出し元に通知される前に完了に向けて処理が継続する操作もあります。CancelIoEx 関数は、キャンセルされたすべての操作が完了するのを待ちません。

ファイルハンドルが完了ポートに関連付けられている場合、同期操作が正常にキャンセルされたときには I/O 完了パケットはポートにキューイングされません。まだ保留中の非同期操作については、キャンセル操作によって I/O 完了パケットがキューイングされます。

キャンセルされる操作は、次の 3 つの状態のいずれかで完了します。完了状態を判断するには、完了ステータスを確認する必要があります。3 つの状態は次のとおりです。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジでサポートされています。
テクノロジ サポート
Server Message Block (SMB) 3.0 プロトコル はい
SMB 3.0 透過的フェールオーバー (TFO) はい
SMB 3.0 スケールアウトファイル共有 (SO) はい
クラスターの共有ボリュームファイルシステム (CsvFS) はい
回復性のあるファイルシステム (ReFS) はい
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll
#include <windows.h>

BOOL CancelIoEx(
    HANDLE hFile,
    OVERLAPPED* lpOverlapped   // optional
);
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool CancelIoEx(
    IntPtr hFile,   // HANDLE
    IntPtr lpOverlapped   // OVERLAPPED* optional
);
<DllImport("KERNEL32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CancelIoEx(
    hFile As IntPtr,   ' HANDLE
    lpOverlapped As IntPtr   ' OVERLAPPED* optional
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
' hFile : HANDLE
' lpOverlapped : OVERLAPPED* optional
Declare PtrSafe Function CancelIoEx Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByVal lpOverlapped As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

CancelIoEx = ctypes.windll.kernel32.CancelIoEx
CancelIoEx.restype = wintypes.BOOL
CancelIoEx.argtypes = [
    wintypes.HANDLE,  # hFile : HANDLE
    ctypes.c_void_p,  # lpOverlapped : OVERLAPPED* optional
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
CancelIoEx = Fiddle::Function.new(
  lib['CancelIoEx'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpOverlapped : OVERLAPPED* optional
  ],
  Fiddle::TYPE_INT)
#[link(name = "kernel32")]
extern "system" {
    fn CancelIoEx(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpOverlapped: *mut OVERLAPPED  // OVERLAPPED* optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true)]
public static extern bool CancelIoEx(IntPtr hFile, IntPtr lpOverlapped);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_CancelIoEx' -Namespace Win32 -PassThru
# $api::CancelIoEx(hFile, lpOverlapped)
#uselib "KERNEL32.dll"
#func global CancelIoEx "CancelIoEx" sptr, sptr
; CancelIoEx hFile, varptr(lpOverlapped)   ; 戻り値は stat
; hFile : HANDLE -> "sptr"
; lpOverlapped : OVERLAPPED* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "KERNEL32.dll"
#cfunc global CancelIoEx "CancelIoEx" sptr, var
; res = CancelIoEx(hFile, lpOverlapped)
; hFile : HANDLE -> "sptr"
; lpOverlapped : OVERLAPPED* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; BOOL CancelIoEx(HANDLE hFile, OVERLAPPED* lpOverlapped)
#uselib "KERNEL32.dll"
#cfunc global CancelIoEx "CancelIoEx" intptr, var
; res = CancelIoEx(hFile, lpOverlapped)
; hFile : HANDLE -> "intptr"
; lpOverlapped : OVERLAPPED* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procCancelIoEx = kernel32.NewProc("CancelIoEx")
)

// hFile (HANDLE), lpOverlapped (OVERLAPPED* optional)
r1, _, err := procCancelIoEx.Call(
	uintptr(hFile),
	uintptr(lpOverlapped),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // BOOL
function CancelIoEx(
  hFile: THandle;   // HANDLE
  lpOverlapped: Pointer   // OVERLAPPED* optional
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'CancelIoEx';
result := DllCall("KERNEL32\CancelIoEx"
    , "Ptr", hFile   ; HANDLE
    , "Ptr", lpOverlapped   ; OVERLAPPED* optional
    , "Int")   ; return: BOOL
●CancelIoEx(hFile, lpOverlapped) = DLL("KERNEL32.dll", "bool CancelIoEx(void*, void*)")
# 呼び出し: CancelIoEx(hFile, lpOverlapped)
# hFile : HANDLE -> "void*"
# lpOverlapped : OVERLAPPED* optional -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "kernel32" fn CancelIoEx(
    hFile: ?*anyopaque, // HANDLE
    lpOverlapped: [*c]OVERLAPPED // OVERLAPPED* optional
) callconv(std.os.windows.WINAPI) i32;
proc CancelIoEx(
    hFile: pointer,  # HANDLE
    lpOverlapped: ptr OVERLAPPED  # OVERLAPPED* optional
): int32 {.importc: "CancelIoEx", stdcall, dynlib: "KERNEL32.dll".}
pragma(lib, "kernel32");
extern(Windows)
int CancelIoEx(
    void* hFile,   // HANDLE
    OVERLAPPED* lpOverlapped   // OVERLAPPED* optional
);
ccall((:CancelIoEx, "KERNEL32.dll"), stdcall, Int32,
      (Ptr{Cvoid}, Ptr{OVERLAPPED}),
      hFile, lpOverlapped)
# hFile : HANDLE -> Ptr{Cvoid}
# lpOverlapped : OVERLAPPED* optional -> Ptr{OVERLAPPED}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t CancelIoEx(
    void* hFile,
    void* lpOverlapped);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.CancelIoEx(hFile, lpOverlapped)
-- hFile : HANDLE
-- lpOverlapped : OVERLAPPED* optional
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const CancelIoEx = lib.func('__stdcall', 'CancelIoEx', 'int32_t', ['void *', 'void *']);
// CancelIoEx(hFile, lpOverlapped)
// hFile : HANDLE -> 'void *'
// lpOverlapped : OVERLAPPED* optional -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  CancelIoEx: { parameters: ["pointer", "pointer"], result: "i32" },
});
// lib.symbols.CancelIoEx(hFile, lpOverlapped)
// hFile : HANDLE -> "pointer"
// lpOverlapped : OVERLAPPED* optional -> "pointer"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t CancelIoEx(
    void* hFile,
    void* lpOverlapped);
C, "KERNEL32.dll");
// $ffi->CancelIoEx(hFile, lpOverlapped);
// hFile : HANDLE
// lpOverlapped : OVERLAPPED* optional
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Kernel32 extends StdCallLibrary {
    Kernel32 INSTANCE = Native.load("kernel32", Kernel32.class);
    boolean CancelIoEx(
        Pointer hFile,   // HANDLE
        Pointer lpOverlapped   // OVERLAPPED* optional
    );
}
@[Link("kernel32")]
lib LibKERNEL32
  fun CancelIoEx = CancelIoEx(
    hFile : Void*,   # HANDLE
    lpOverlapped : OVERLAPPED*   # OVERLAPPED* optional
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef CancelIoExNative = Int32 Function(Pointer<Void>, Pointer<Void>);
typedef CancelIoExDart = int Function(Pointer<Void>, Pointer<Void>);
final CancelIoEx = DynamicLibrary.open('KERNEL32.dll')
    .lookupFunction<CancelIoExNative, CancelIoExDart>('CancelIoEx');
// hFile : HANDLE -> Pointer<Void>
// lpOverlapped : OVERLAPPED* optional -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function CancelIoEx(
  hFile: THandle;   // HANDLE
  lpOverlapped: Pointer   // OVERLAPPED* optional
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'CancelIoEx';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "CancelIoEx"
  c_CancelIoEx :: Ptr () -> Ptr () -> IO CInt
-- hFile : HANDLE -> Ptr ()
-- lpOverlapped : OVERLAPPED* optional -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let cancelioex =
  foreign "CancelIoEx"
    ((ptr void) @-> (ptr void) @-> returning int32_t)
(* hFile : HANDLE -> (ptr void) *)
(* lpOverlapped : OVERLAPPED* optional -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library kernel32 (t "KERNEL32.dll"))
(cffi:use-foreign-library kernel32)

(cffi:defcfun ("CancelIoEx" cancel-io-ex :convention :stdcall) :int32
  (h-file :pointer)   ; HANDLE
  (lp-overlapped :pointer))   ; OVERLAPPED* optional
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $CancelIoEx = Win32::API::More->new('KERNEL32',
    'BOOL CancelIoEx(HANDLE hFile, LPVOID lpOverlapped)');
# my $ret = $CancelIoEx->Call($hFile, $lpOverlapped);
# hFile : HANDLE -> HANDLE
# lpOverlapped : OVERLAPPED* optional -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

類似 API
使用する型