次の方法で共有


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 です。

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

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

lpOverlappedNULL でない場合、lpBytesReturned には NULL を指定できます。 このパラメーターが 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

OVERLAPPED

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