DeviceIoControl 関数 (ioapiset.h)

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

ドライブ文字の割り当てのサンプルを参照してください。

構文

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、nInBufferSizelpOutBufferおよび nOutBufferSize パラメーターの使用法の詳細を示します。

[in, optional] lpInBuffer

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

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

[in] nInBufferSize

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

[out, optional] lpOutBuffer

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

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

[in] nOutBufferSize

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

[out, optional] lpBytesReturned

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

出力バッファーが小さすぎてデータを受信できない場合、呼び出しは失敗し、 GetLastErrorERROR_INSUFFICIENT_BUFFERを返し、 lpBytesReturned は 0 です。

出力バッファーが小さすぎてすべてのデータを保持できないが、一部のエントリを保持できる場合、一部のドライバーは収まる量のデータを返します。 この場合、呼び出しは失敗し、 GetLastErrorERROR_MORE_DATAを返し、 lpBytesReturned は受信したデータの量を示します。 アプリケーションは、新しい開始点を指定して、同じ操作で DeviceIoControl をもう一度呼び出す必要があります。

lpOverlappedNULL の場合、lpBytesReturnedNULL にすることはできません。 操作が出力データを返せず、 lpOutBufferNULL の場合でも、 DeviceIoControllpBytesReturned を使用します。 このような操作の後、 lpBytesReturned の値は意味がありません。

lpOverlappedNULL でない場合は、lpBytesReturnedNULL を指定できます。 このパラメーターが NULL ではなく、操作がデータを返す場合、重複する操作が完了するまで lpBytesReturned は意味がありません。 返されたバイト数を取得するには、 GetOverlappedResult を呼び出します。 hDevice が I/O 完了ポートに関連付けられている場合は、GetQueuedCompletionStatus を呼び出すことによって返されるバイト数を取得できます。

[in, out, optional] lpOverlapped

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

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

hDeviceFILE_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

関連項目

CreateEvent

CreateFile

デバイス入出力制御 (IOCTL)

GetOverlappedResult

GetQueuedCompletionStatus

オーバー ラップ

ドライブ文字の割り当てサンプル