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

CancelIo

関数
現在のスレッドが発行した保留中のI/Oをキャンセルする。
DLLKERNEL32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

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

BOOL CancelIo(
    HANDLE hFile
);

パラメーター

名前方向説明
hFileHANDLEin

ファイルへのハンドル。

この関数は、このファイルハンドルに対する保留中のすべての I/O 操作をキャンセルします。

戻り値の型: BOOL

公式ドキュメント

呼び出し元スレッドが指定したファイルに対して発行した、保留中のすべての入出力 (I/O) 操作をキャンセルします。

戻り値

関数が成功した場合、戻り値は 0 以外になります。呼び出し元スレッドが指定したファイルハンドルに対して発行した、保留中のすべての I/O 操作のキャンセルが正常に要求されました。スレッドは GetOverlappedResult 関数を使用して、I/O 操作自体がいつ完了したかを判断できます。

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

解説(Remarks)

指定したファイルハンドルに対して進行中の保留中 I/O 操作があり、それらが呼び出し元スレッドによって発行されたものである場合、CancelIo 関数はそれらをキャンセルします。CancelIo はハンドル上の未処理の I/O のみをキャンセルし、ハンドルの状態は変更しません。つまり、操作が正常に完了したのかキャンセルされたのかを知ることはできないため、ハンドルの状態に依存することはできません。

I/O 操作はオーバーラップ I/O として発行する必要があります。そうでない場合、I/O 操作は制御を返さないため、スレッドが CancelIo 関数を呼び出すことができません。FILE_FLAG_OVERLAPPED を指定せずに開いたファイルハンドルで CancelIo 関数を呼び出しても、何も行われません。

キャンセルされたすべての I/O 操作はエラー ERROR_OPERATION_ABORTED で完了し、それらの I/O 操作に対するすべての完了通知は通常どおり行われます。

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

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

lib = Fiddle.dlopen('KERNEL32.dll')
CancelIo = Fiddle::Function.new(
  lib['CancelIo'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
  ],
  Fiddle::TYPE_INT)
#[link(name = "kernel32")]
extern "system" {
    fn CancelIo(
        hFile: *mut core::ffi::c_void  // HANDLE
    ) -> 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 CancelIo(IntPtr hFile);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_CancelIo' -Namespace Win32 -PassThru
# $api::CancelIo(hFile)
#uselib "KERNEL32.dll"
#func global CancelIo "CancelIo" sptr
; CancelIo hFile   ; 戻り値は stat
; hFile : HANDLE -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "KERNEL32.dll"
#cfunc global CancelIo "CancelIo" sptr
; res = CancelIo(hFile)
; hFile : HANDLE -> "sptr"
; BOOL CancelIo(HANDLE hFile)
#uselib "KERNEL32.dll"
#cfunc global CancelIo "CancelIo" intptr
; res = CancelIo(hFile)
; hFile : HANDLE -> "intptr"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procCancelIo = kernel32.NewProc("CancelIo")
)

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

extern "kernel32" fn CancelIo(
    hFile: ?*anyopaque // HANDLE
) callconv(std.os.windows.WINAPI) i32;
proc CancelIo(
    hFile: pointer  # HANDLE
): int32 {.importc: "CancelIo", stdcall, dynlib: "KERNEL32.dll".}
pragma(lib, "kernel32");
extern(Windows)
int CancelIo(
    void* hFile   // HANDLE
);
ccall((:CancelIo, "KERNEL32.dll"), stdcall, Int32,
      (Ptr{Cvoid},),
      hFile)
# hFile : HANDLE -> Ptr{Cvoid}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t CancelIo(
    void* hFile);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.CancelIo(hFile)
-- hFile : HANDLE
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const CancelIo = lib.func('__stdcall', 'CancelIo', 'int32_t', ['void *']);
// CancelIo(hFile)
// hFile : HANDLE -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  CancelIo: { parameters: ["pointer"], result: "i32" },
});
// lib.symbols.CancelIo(hFile)
// hFile : HANDLE -> "pointer"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t CancelIo(
    void* hFile);
C, "KERNEL32.dll");
// $ffi->CancelIo(hFile);
// hFile : HANDLE
// 構造体/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 CancelIo(
        Pointer hFile   // HANDLE
    );
}
@[Link("kernel32")]
lib LibKERNEL32
  fun CancelIo = CancelIo(
    hFile : Void*   # HANDLE
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

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

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

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

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

関連項目

類似 API
公式の関連項目