DeviceIoControl 関数 (ioapiset.h)

[アーティクル]
08/24/2023

コントロールコードを指定したデバイスドライバーに直接送信し、対応するデバイスが対応する操作を実行します。

構文

BOOL DeviceIoControl(
  [in]                HANDLE       hDevice,
  [in]                DWORD        dwIoControlCode,
  [in, optional]      LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out, optional]     LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out, optional]     LPDWORD      lpBytesReturned,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

パラメーター

[in] hDevice

操作を実行するデバイスへのハンドル。通常、デバイスはボリューム、ディレクトリ、ファイル、またはストリームです。デバイスハンドルを取得するには、 CreateFile 関数を使用します。詳細については、「解説」を参照してください。

[in] dwIoControlCode

操作の制御コード。この値は、実行する特定の操作と、実行するデバイスの種類を識別します。

コントロールコードの一覧については、「解説」を参照してください。各コントロールコードのドキュメントでは、lpInBuffer、nInBufferSize、lpOutBuffer、および nOutBufferSize パラメーターの使用方法の詳細を示します。

[in, optional] lpInBuffer

操作の実行に必要なデータを含む入力バッファーへのポインター。このデータの形式は、 dwIoControlCode パラメーターの値によって異なります。

dwIoControlCode で入力データを必要としない操作が指定されている場合、このパラメーターは NULL にすることができます。

[in] nInBufferSize

入力バッファーのサイズ (バイト単位)。

[out, optional] lpOutBuffer

操作によって返されるデータを受け取る出力バッファーへのポインター。このデータの形式は、 dwIoControlCode パラメーターの値によって異なります。

dwIoControlCode でデータを返さない操作が指定されている場合、このパラメーターは NULL にすることができます。

[in] nOutBufferSize

出力バッファーのサイズ (バイト単位)。

[out, optional] lpBytesReturned

出力バッファーに格納されているデータのサイズをバイト単位で受け取る変数へのポインター。

出力バッファーが小さすぎてデータを受信できない場合、呼び出しは失敗し、 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 を呼び出して返されるバイト数を取得できます。

[in, out, optional] lpOverlapped

OVERLAPPED 構造体へのポインター。

FILE_FLAG_OVERLAPPED を指定せずに hDevice を開いた場合、lpOverlapped は無視されます。

hDevice が FILE_FLAG_OVERLAPPED フラグで開かれた場合、操作は重複 (非同期) 操作として実行されます。この場合、lpOverlapped は、イベントオブジェクトへのハンドルを含む有効な OVERLAPPED 構造体を指す必要があります。それ以外の場合、関数は予期しない方法で失敗します。

重複する操作の場合、DeviceIoControl は直ちに戻り、操作が完了するとイベントオブジェクトが通知されます。それ以外の場合、関数は操作が完了するかエラーが発生するまで戻りません。

戻り値

操作が正常に完了すると、戻り値は 0 以外 (TRUE) になります。

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

解説

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

\\.\DeviceName

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

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

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

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

例

DeviceIoControl を使用する例については、「DeviceIoControl の呼び出し」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP
サポートされている最小のサーバー	Windows Server 2003
対象プラットフォーム	Windows
ヘッダー	ioapiset.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

次の方法で共有

DeviceIoControl 関数 (ioapiset.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

その他のリソース