DeviceIoControl

関数

デバイスドライバに制御コードを送って操作する。

DLLKERNEL32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

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

BOOL DeviceIoControl(
    HANDLE hDevice,
    DWORD dwIoControlCode,
    void* lpInBuffer,   // optional
    DWORD nInBufferSize,
    void* lpOutBuffer,   // optional
    DWORD nOutBufferSize,
    DWORD* lpBytesReturned,   // optional
    OVERLAPPED* lpOverlapped   // optional
);

パラメーター

名前	型	方向	説明
hDevice	HANDLE	in	操作を実行するデバイスへのハンドル。デバイスは通常、ボリューム、ディレクトリ、ファイル、またはストリームです。デバイスハンドルを取得するには、 CreateFile 関数を使用します。詳細については、「Remarks」を参照してください。
dwIoControlCode	DWORD	in	操作の制御コード。この値は、実行する具体的な操作と、それを実行するデバイスの種類を識別します。制御コードの一覧については、「Remarks」を参照してください。各制御コードのドキュメントには、 lpInBuffer、nInBufferSize、 lpOutBuffer、nOutBufferSize の各パラメーターの使用方法の詳細が記載されています。
lpInBuffer	void*	inoptional	操作の実行に必要なデータを格納する入力バッファーへのポインター。このデータの形式は、 dwIoControlCode パラメーターの値によって異なります。 dwIoControlCode が入力データを必要としない操作を指定する場合、このパラメーターは NULL にできます。
nInBufferSize	DWORD	in	入力バッファーのサイズ(バイト単位)。
lpOutBuffer	void*	outoptional	操作によって返されるデータを受け取る出力バッファーへのポインター。このデータの形式は、 dwIoControlCode パラメーターの値によって異なります。 dwIoControlCode がデータを返さない操作を指定する場合、このパラメーターは NULL にできます。
nOutBufferSize	DWORD	in	出力バッファーのサイズ(バイト単位)。
lpBytesReturned	DWORD*	outoptional	出力バッファーに格納されたデータのサイズ(バイト単位)を受け取る変数へのポインター。出力バッファーが小さすぎてデータをまったく受け取れない場合、呼び出しは失敗し、 GetLastError は ERROR_INSUFFICIENT_BUFFER を返し、lpBytesReturned は 0 になります。出力バッファーがすべてのデータを保持するには小さすぎるものの、一部のエントリは保持できる場合、一部のドライバーは収まるだけのデータを返します。この場合、呼び出しは失敗し、 GetLastError は ERROR_MORE_DATA を返し、lpBytesReturned は受け取ったデータ量を示します。アプリケーションは、新しい開始位置を指定して、同じ操作で DeviceIoControl を再度呼び出す必要があります。 lpOverlapped が NULL の場合、 lpBytesReturned を NULL にすることはできません。操作が出力データを返さず lpOutBuffer が NULL である場合でも、 DeviceIoControl は lpBytesReturned を使用します。そのような操作の後、 lpBytesReturned の値は無意味です。 lpOverlapped が NULL でない場合、 lpBytesReturned を NULL にできます。このパラメーターが NULL でなく操作がデータを返す場合、オーバーラップ操作が完了するまで lpBytesReturned は無意味です。返されたバイト数を取得するには、 GetOverlappedResult を呼び出します。 hDevice が I/O 完了ポートに関連付けられている場合は、 GetQueuedCompletionStatus を呼び出すことで返されたバイト数を取得できます。
lpOverlapped	OVERLAPPED*	inoutoptional	OVERLAPPED 構造体へのポインター。 hDevice が FILE_FLAG_OVERLAPPED を指定せずに開かれた場合、 lpOverlapped は無視されます。 hDevice が FILE_FLAG_OVERLAPPED フラグを指定して開かれた場合、操作はオーバーラップ(非同期)操作として実行されます。この場合、 lpOverlapped はイベントオブジェクトへのハンドルを含む有効な OVERLAPPED 構造体を指している必要があります。そうでない場合、関数は予測できない方法で失敗します。オーバーラップ操作の場合、 DeviceIoControl はただちに制御を返し、操作が完了するとイベントオブジェクトがシグナル状態になります。それ以外の場合、関数は操作が完了するかエラーが発生するまで制御を返しません。

戻り値の型: BOOL

公式ドキュメント

指定したデバイスドライバーに制御コードを直接送信し、対応するデバイスに該当の操作を実行させます。

戻り値

操作が正常に完了した場合、戻り値は 0 以外(TRUE)です。

操作が失敗または保留中の場合、戻り値は 0 です。拡張エラー情報を取得するには、 GetLastError を呼び出します。

解説(Remarks)

デバイスへのハンドルを取得するには、デバイスの名前またはデバイスに関連付けられたドライバーの名前のいずれかを指定して、 CreateFile 関数を呼び出す必要があります。デバイス名を指定するには、次の形式を使用します。

\\.\DeviceName

DeviceIoControl は特定のデバイスへのハンドルを受け取ることができます。たとえば、CreateFile で論理ドライブ A: へのハンドルを開くには、 \\.\a: を指定します。あるいは、\\.\PhysicalDrive0、\\.\PhysicalDrive1 のような名前を使用して、システム上の物理ドライブへのハンドルを開くこともできます。

デバイスドライバーへのハンドルを開くために CreateFile を呼び出すときは、 FILE_SHARE_READ および FILE_SHARE_WRITE アクセスフラグを指定する必要があります。ただし、シリアルポートなどの通信リソースを開くときは、排他アクセスを指定する必要があります。デバイスハンドルを開くときは、その他の CreateFile パラメーターを次のように使用します。

fdwCreate パラメーターには OPEN_EXISTING を指定する必要があります。
hTemplateFile パラメーターは NULL である必要があります。
返されるハンドルをオーバーラップ(非同期)I/O 操作で使用できることを示すため、 fdwAttrsAndFlags パラメーターには FILE_FLAG_OVERLAPPED を指定できます。

サポートされている制御コードの一覧については、次のトピックを参照してください。

Examples

DeviceIoControl を使用する例については、Calling DeviceIoControl を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

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

BOOL DeviceIoControl(
    HANDLE hDevice,
    DWORD dwIoControlCode,
    void* lpInBuffer,   // optional
    DWORD nInBufferSize,
    void* lpOutBuffer,   // optional
    DWORD nOutBufferSize,
    DWORD* lpBytesReturned,   // optional
    OVERLAPPED* lpOverlapped   // optional
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool DeviceIoControl(
    IntPtr hDevice,   // HANDLE
    uint dwIoControlCode,   // DWORD
    IntPtr lpInBuffer,   // void* optional
    uint nInBufferSize,   // DWORD
    IntPtr lpOutBuffer,   // void* optional, out
    uint nOutBufferSize,   // DWORD
    IntPtr lpBytesReturned,   // DWORD* optional, out
    IntPtr lpOverlapped   // OVERLAPPED* optional, in/out
);

<DllImport("KERNEL32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function DeviceIoControl(
    hDevice As IntPtr,   ' HANDLE
    dwIoControlCode As UInteger,   ' DWORD
    lpInBuffer As IntPtr,   ' void* optional
    nInBufferSize As UInteger,   ' DWORD
    lpOutBuffer As IntPtr,   ' void* optional, out
    nOutBufferSize As UInteger,   ' DWORD
    lpBytesReturned As IntPtr,   ' DWORD* optional, out
    lpOverlapped As IntPtr   ' OVERLAPPED* optional, in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' hDevice : HANDLE
' dwIoControlCode : DWORD
' lpInBuffer : void* optional
' nInBufferSize : DWORD
' lpOutBuffer : void* optional, out
' nOutBufferSize : DWORD
' lpBytesReturned : DWORD* optional, out
' lpOverlapped : OVERLAPPED* optional, in/out
Declare PtrSafe Function DeviceIoControl Lib "kernel32" ( _
    ByVal hDevice As LongPtr, _
    ByVal dwIoControlCode As Long, _
    ByVal lpInBuffer As LongPtr, _
    ByVal nInBufferSize As Long, _
    ByVal lpOutBuffer As LongPtr, _
    ByVal nOutBufferSize As Long, _
    ByVal lpBytesReturned 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

DeviceIoControl = ctypes.windll.kernel32.DeviceIoControl
DeviceIoControl.restype = wintypes.BOOL
DeviceIoControl.argtypes = [
    wintypes.HANDLE,  # hDevice : HANDLE
    wintypes.DWORD,  # dwIoControlCode : DWORD
    ctypes.POINTER(None),  # lpInBuffer : void* optional
    wintypes.DWORD,  # nInBufferSize : DWORD
    ctypes.POINTER(None),  # lpOutBuffer : void* optional, out
    wintypes.DWORD,  # nOutBufferSize : DWORD
    ctypes.POINTER(wintypes.DWORD),  # lpBytesReturned : DWORD* optional, out
    ctypes.c_void_p,  # lpOverlapped : OVERLAPPED* optional, in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
DeviceIoControl = Fiddle::Function.new(
  lib['DeviceIoControl'],
  [
    Fiddle::TYPE_VOIDP,  # hDevice : HANDLE
    -Fiddle::TYPE_INT,  # dwIoControlCode : DWORD
    Fiddle::TYPE_VOIDP,  # lpInBuffer : void* optional
    -Fiddle::TYPE_INT,  # nInBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # lpOutBuffer : void* optional, out
    -Fiddle::TYPE_INT,  # nOutBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # lpBytesReturned : DWORD* optional, out
    Fiddle::TYPE_VOIDP,  # lpOverlapped : OVERLAPPED* optional, in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn DeviceIoControl(
        hDevice: *mut core::ffi::c_void,  // HANDLE
        dwIoControlCode: u32,  // DWORD
        lpInBuffer: *mut (),  // void* optional
        nInBufferSize: u32,  // DWORD
        lpOutBuffer: *mut (),  // void* optional, out
        nOutBufferSize: u32,  // DWORD
        lpBytesReturned: *mut u32,  // DWORD* optional, out
        lpOverlapped: *mut OVERLAPPED  // OVERLAPPED* optional, in/out
    ) -> 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 DeviceIoControl(IntPtr hDevice, uint dwIoControlCode, IntPtr lpInBuffer, uint nInBufferSize, IntPtr lpOutBuffer, uint nOutBufferSize, IntPtr lpBytesReturned, IntPtr lpOverlapped);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_DeviceIoControl' -Namespace Win32 -PassThru
# $api::DeviceIoControl(hDevice, dwIoControlCode, lpInBuffer, nInBufferSize, lpOutBuffer, nOutBufferSize, lpBytesReturned, lpOverlapped)

#uselib "KERNEL32.dll"
#func global DeviceIoControl "DeviceIoControl" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; DeviceIoControl hDevice, dwIoControlCode, lpInBuffer, nInBufferSize, lpOutBuffer, nOutBufferSize, varptr(lpBytesReturned), varptr(lpOverlapped)   ; 戻り値は stat
; hDevice : HANDLE -> "sptr"
; dwIoControlCode : DWORD -> "sptr"
; lpInBuffer : void* optional -> "sptr"
; nInBufferSize : DWORD -> "sptr"
; lpOutBuffer : void* optional, out -> "sptr"
; nOutBufferSize : DWORD -> "sptr"
; lpBytesReturned : DWORD* optional, out -> "sptr"
; lpOverlapped : OVERLAPPED* optional, in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global DeviceIoControl "DeviceIoControl" sptr, int, sptr, int, sptr, int, var, var
; res = DeviceIoControl(hDevice, dwIoControlCode, lpInBuffer, nInBufferSize, lpOutBuffer, nOutBufferSize, lpBytesReturned, lpOverlapped)
; hDevice : HANDLE -> "sptr"
; dwIoControlCode : DWORD -> "int"
; lpInBuffer : void* optional -> "sptr"
; nInBufferSize : DWORD -> "int"
; lpOutBuffer : void* optional, out -> "sptr"
; nOutBufferSize : DWORD -> "int"
; lpBytesReturned : DWORD* optional, out -> "var"
; lpOverlapped : OVERLAPPED* optional, in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global DeviceIoControl "DeviceIoControl" sptr, int, sptr, int, sptr, int, sptr, sptr
; res = DeviceIoControl(hDevice, dwIoControlCode, lpInBuffer, nInBufferSize, lpOutBuffer, nOutBufferSize, varptr(lpBytesReturned), varptr(lpOverlapped))
; hDevice : HANDLE -> "sptr"
; dwIoControlCode : DWORD -> "int"
; lpInBuffer : void* optional -> "sptr"
; nInBufferSize : DWORD -> "int"
; lpOutBuffer : void* optional, out -> "sptr"
; nOutBufferSize : DWORD -> "int"
; lpBytesReturned : DWORD* optional, out -> "sptr"
; lpOverlapped : OVERLAPPED* optional, in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。