IoCreateFileEx 関数 (ntddk.h)
IoCreateFileEx ルーチンは、新しいファイルまたはディレクトリを作成するか、既存のファイル、デバイス、ディレクトリ、またはボリュームを開き、呼び出し元にファイル オブジェクトのハンドルを提供します。 ファイル システム フィルター ドライバー (レガシ フィルター ドライバー) は、このルーチンを呼び出します。
構文
NTSTATUS IoCreateFileEx(
[out] PHANDLE FileHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in, optional] PLARGE_INTEGER AllocationSize,
[in] ULONG FileAttributes,
[in] ULONG ShareAccess,
[in] ULONG Disposition,
[in] ULONG CreateOptions,
[in, optional] PVOID EaBuffer,
[in] ULONG EaLength,
[in] CREATE_FILE_TYPE CreateFileType,
[in, optional] PVOID InternalParameters,
[in] ULONG Options,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
パラメーター
[out] FileHandle
呼び出しが成功した場合にファイル ハンドルを受け取る変数へのポインター。 ドライバーは、ハンドルが使用されなくなったらすぐに 、ZwClose でハンドルを閉じる必要があります。
[in] DesiredAccess
呼び出し元がファイルまたはディレクトリに対して必要とするアクセスの種類を指定するフラグのビットマスク ( ACCESS_MASK参照)。 このシステム定義の DesiredAccess フラグのセットによって、ファイル オブジェクトに対する次の特定のアクセス権が決定されます。
| DesiredAccess フラグ | 意味 |
|---|---|
| DELETE | ファイルは削除できます。 |
| FILE_READ_DATA | ファイルからデータを読み取ることができます。 |
| FILE_READ_ATTRIBUTES | 以下で説明する FileAttributes フラグを読み取ることができます。 |
| FILE_READ_EA | ファイルに関連付けられている拡張属性 (EA) を読み取ることができます。 |
| READ_CONTROL | ファイルに関連付けられているアクセス制御リスト (ACL) と所有権情報を読み取ることができます。 |
| FILE_WRITE_DATA | ファイルにデータを書き込むことができます。 |
| FILE_WRITE_ATTRIBUTES | FileAttributes フラグを 書き込むことができます。 |
| FILE_WRITE_EA | ファイルに関連付けられている EA を書き込むことができます。 |
| FILE_APPEND_DATA | データはファイルに追加できます。 |
| WRITE_DAC | ファイルに関連付けられている随意アクセス制御リスト (DACL) を書き込むことができます。 |
| WRITE_OWNER | ファイルに関連付けられている所有権情報を書き込むことができます。 |
| SYNCHRONIZE | 呼び出し元は、返された FileHandle が Signaled 状態に設定されるのを待って、I/O 操作の完了を同期できます。 CreateOptions FILE_SYNCHRONOUS_IO_ALERTまたは FILE_SYNCHRONOUS_IO_NONALERT フラグが設定されている場合は、このフラグを設定する必要があります。 |
| FILE_EXECUTE | システム ページング I/O を使用して、ファイルからメモリにデータを読み取ることができます。 |
または、ディレクトリを表さないファイル オブジェクトに対して、次の汎用ACCESS_MASK フラグの 1 つ以上を指定できます。 STANDARD_RIGHTS_XXX フラグは、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です。 これらの汎用フラグを、前の表の追加フラグと組み合わせることもできます。
| ファイル値への必要なアクセス | DesiredAccess フラグにマップします |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ、FILE_READ_DATA、FILE_READ_ATTRIBUTES、FILE_READ_EA、SYNCHRONIZE。 |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE、FILE_WRITE_DATA、FILE_WRITE_ATTRIBUTES、FILE_WRITE_EA、FILE_APPEND_DATA、SYNCHRONIZE。 |
| GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE、SYNCHRONIZE、FILE_READ_ATTRIBUTES、FILE_EXECUTE。 |
ディレクトリ (FILE_DIRECTORY_FILE CreateOptions フラグが設定されている) の場合は、次の 1 つ以上のACCESS_MASK フラグを指定できます。このフラグは、前述の互換性のあるフラグと組み合わせることもできます。
| ディレクトリ値への必要なアクセス | 意味 |
|---|---|
| FILE_LIST_DIRECTORY | ディレクトリ内のファイルを一覧表示できます。 |
| FILE_TRAVERSE | ディレクトリは走査できます。つまり、ファイルのパス名の一部にすることができます。 |
DesiredAccess フラグFILE_READ_DATA、FILE_WRITE_DATA、FILE_EXECUTE、FILE_APPEND_DATAは、ディレクトリ ファイルの作成または開き方と互換性がありません。
[in] ObjectAttributes
InitializeObjectAttributes ルーチンによって既に初期化されているOBJECT_ATTRIBUTES構造体へのポインター。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーターは NULL にすることができます。 それ以外の場合、呼び出し元は InitializeObjectAttributes の呼び出しで OBJ_KERNEL_HANDLE 属性を設定する必要があります。 ファイル オブジェクトのこの構造体のメンバーは次のとおりです。
| メンバー | 値 |
|---|---|
| ULONG の長さ | 指定された ObjectAttributes データの バイト数。 この値は、少なくとも sizeof(OBJECT_ATTRIBUTES)である必要があります。 |
| PUNICODE_STRING ObjectName | 作成または開くファイルの名前を含むバッファー内の Unicode 文字列へのポインター。 RootDirectory で指定されたディレクトリに対するファイルの名前でない限り、この値は完全修飾ファイル仕様である必要があります。 たとえば、"\Device\フロッピー 1\myfile.dat" や "??\B:\myfile.dat" は、フロッピー ディスク ドライブ ドライバーと上にあるファイル システムが既に読み込まれている限り、完全修飾ファイル仕様である可能性があります。 (注: "??" は、Win32 オブジェクト名前空間の名前として "\DosDevices" を置き換えます。"\DosDevices" は引き続き機能しますが、"??" はオブジェクト マネージャーによってより高速に翻訳されます。) |
| HANDLE RootDirectory | IoCreateFileEx の以前の呼び出しによって取得されたディレクトリへの省略可能なハンドル。 この値が NULL の場合、 ObjectName メンバーは、ターゲット ファイルへの完全パスを含む完全修飾ファイル仕様である必要があります。 この値が NULL 以外の場合、 ObjectName メンバーは、このディレクトリに対する相対ファイル名を指定します。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | ファイルに適用されるオプションのセキュリティ記述子。 このようなセキュリティ記述子で指定された ACL は、作成時にのみファイルに適用されます。 ファイルの作成時に値が NULL の 場合、ファイルに配置される ACL はファイル システムに依存します。ほとんどのファイル システムは、そのような ACL の一部を、呼び出し元の既定の ACL と組み合わせた親ディレクトリ ファイルから伝達します。 |
| ULONG 属性 | ファイル オブジェクト属性を制御するフラグのセット。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーターは 0 にすることができます。 それ以外の場合、呼び出し元は OBJ_KERNEL_HANDLE フラグを設定する必要があります。 呼び出し元は、必要に応じて OBJ_CASE_INSENSITIVE フラグを設定することもできます。これは、名前参照コードが完全一致検索を実行する代わりに ObjectName の大文字と小文字を無視する必要があることを示します。 |
[out] IoStatusBlock
最終的な完了状態と要求された操作に 関する情報 を受け取るIO_STATUS_BLOCK型の変数へのポインター。 IoCreateFileEx から返された場合、変数の Information メンバーには次のいずれかの値が含まれます。
FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
必要に応じて、ファイルの初期割り当てサイズをバイト単位で指定します。 ファイルが作成、上書き、または置き換えられる場合を除き、0 以外の値は有効になりません。
[in] FileAttributes
明示的に指定された属性は、ファイルが作成、置き換えられる、または場合によっては上書きされた場合にのみ適用されます。 既定では、この値はFILE_ATTRIBUTE_NORMALです。この値は、他のフラグまたは互換性のあるフラグの組み合わせ (ビットごとの OR 操作を介して) によってオーバーライドできます。 FileAttributes フラグとして使用できるフラグは次のとおりです。
| FileAttributes フラグ | 意味 |
|---|---|
| FILE_ATTRIBUTE_NORMAL | 標準属性を持つファイルを作成する必要があります。 |
| FILE_ATTRIBUTE_READONLY | 読み取り専用ファイルを作成する必要があります。 |
| FILE_ATTRIBUTE_HIDDEN | 隠しファイルを作成する必要があります。 |
| FILE_ATTRIBUTE_SYSTEM | システム ファイルを作成する必要があります。 |
| FILE_ATTRIBUTE_ARCHIVE | アーカイブされるように、ファイルをマークする必要があります。 |
| FILE_ATTRIBUTE_TEMPORARY | 一時ファイルを作成する必要があります。 |
[in] ShareAccess
呼び出し元が必要とするファイルへの共有アクセスの種類を、0 または 1、または次のフラグの組み合わせとして指定します。 排他アクセスを要求するには、このパラメーターを 0 に設定します。 IO_IGNORE_SHARE_ACCESS_CHECK フラグが Options パラメーターで指定されている場合、I/O マネージャーは ShareAccess パラメーターを無視します。 ただし、ファイル システムは引き続きアクセス チェックを実行する可能性があります。 したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、このパラメーターに使用する共有モードを指定することが重要です。 共有違反エラーを回避するには、次のすべての共有アクセス フラグを指定します。
| ShareAccess フラグ | 意味 |
|---|---|
| FILE_SHARE_READ | ファイルは、他のスレッドのファイル作成呼び出しによって読み取りアクセスのために開くことができます。 |
| FILE_SHARE_WRITE | ファイルは、他のスレッドのファイル作成呼び出しによって書き込みアクセスのために開くことができます。 |
| FILE_SHARE_DELETE | ファイルは、他のスレッドのファイル作成呼び出しによって削除アクセスのために開くことができます。 |
通常、デバイス ドライバーと中間ドライバーは ShareAccess を 0 に設定します。これにより、呼び出し元は開いているファイルに排他的にアクセスできます。
[in] Disposition
ファイルが既に存在する場合のファイルの処理方法を決定する値。 処理 には、次のいずれかを指定できます。
| 値 | 意味 |
|---|---|
| FILE_SUPERSEDE | ファイルが既に存在する場合は、指定したファイルに置き換えます。 存在しない場合は、指定されたファイルを作成します。 |
| FILE_CREATE | ファイルが既に存在する場合は、要求を失敗させ、指定されたファイルを作成したり開いたりしないでください。 存在しない場合は、指定されたファイルを作成します。 |
| FILE_OPEN | ファイルが既に存在する場合は、新しいファイルを作成する代わりにファイルを開きます。 存在しない場合は、要求を失敗させ、新しいファイルを作成しないでください。 |
| FILE_OPEN_IF | ファイルが既に存在する場合は、ファイルを開きます。 存在しない場合は、指定されたファイルを作成します。 |
| FILE_OVERWRITE | ファイルが既に存在する場合は、ファイルを開いて上書きします。 存在しない場合は、要求を失敗します。 |
| FILE_OVERWRITE_IF | ファイルが既に存在する場合は、ファイルを開いて上書きします。 存在しない場合は、指定されたファイルを作成します。 |
[in] CreateOptions
ファイルを作成または開くときに適用するオプションを、次のフラグの互換性のある組み合わせとして指定します。
| CreateOptions フラグ | 意味 |
|---|---|
| FILE_DIRECTORY_FILE (0x00000001) | 作成または開いているファイルはディレクトリ ファイルです。 このフラグでは、 Disposition パラメーターをFILE_CREATE、FILE_OPEN、またはFILE_OPEN_IFのいずれかに設定する必要があります。 このフラグと互換性のある CreateOptions フラグは、FILE_SYNCHRONOUS_IO_ALERT、FILE_SYNCHRONOUS_IO_NONALERT、FILE_WRITE_THROUGH、FILE_OPEN_FOR_BACKUP_INTENT、およびFILE_OPEN_BY_FILE_IDです。 |
| FILE_WRITE_THROUGH (0x00000002) | ファイルにデータを書き込むシステム サービス、ファイル システム、ドライバーは、要求された書き込み操作が完了したと見なされる前に、実際にデータをファイルに転送する必要があります。 |
| FILE_SEQUENTIAL_ONLY (0x00000004) | ファイルへのすべてのアクセスはシーケンシャルになります。 |
| FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) | ファイルをキャッシュしたり、ドライバーの内部バッファーにバッファー化したりすることはできません。 このフラグは DesiredAccessFILE_APPEND_DATA フラグと互換性がありません。 |
| FILE_SYNCHRONOUS_IO_ALERT (0x00000010) | ファイルに対するすべての操作が同期的に実行されます。 呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグが設定されている場合は、I/O マネージャーがファイル オブジェクトを同期オブジェクトとして使用するように DesiredAccess SYNCHRONIZE フラグも設定する必要があります。 |
| FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) | ファイルに対するすべての操作が同期的に実行されます。 システムで I/O キューの同期を待機し、完了はアラートの対象になりません。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグが設定されている場合は、I/O マネージャーがファイル オブジェクトを同期オブジェクトとして使用するように DesiredAccess SYNCHRONIZE フラグも設定する必要があります。 |
| FILE_NON_DIRECTORY_FILE (0x00000040) | 開いているファイルがディレクトリ ファイルではないか、この呼び出しが失敗します。 開いているファイル オブジェクトは、データ ファイルを表すことができます。論理デバイス、仮想デバイス、または物理デバイス。またはボリューム。 |
| FILE_CREATE_TREE_CONNECTION (0x00000080) | ネットワーク経由で開くために、このファイルのツリー接続を作成します。 |
| FILE_COMPLETE_IF_OPLOCKED (0x00000100) | 呼び出し元のスレッドをブロックするのではなく、ターゲット ファイルが oplocked の場合は、代替成功コードを使用してすぐにこの操作を完了します。 ファイルが oplocked の場合、別の呼び出し元は既にネットワーク経由でファイルにアクセスできます。 |
| FILE_NO_EA_KNOWLEDGE (0x00000200) | 開かれている既存のファイルの拡張属性が、呼び出し元がファイルを正しく解釈するために拡張属性を理解する必要があることを示している場合、呼び出し元は拡張属性の処理方法を理解していないため、この要求を失敗させます。 |
| FILE_OPEN_REMOTE_INSTANCE (0x00000400) | システムの使用のために予約されています。は使用しません。 |
| FILE_RANDOM_ACCESS (0x00000800) | ファイルへのアクセスはランダムな場合があるため、ファイル システムまたはオペレーティング システムによってファイルに対して順次先読み操作を実行する必要はありません。 |
| FILE_DELETE_ON_CLOSE (0x00001000) | 最後のハンドルが FltClose に渡されたときにファイルを削除します。 |
| FILE_OPEN_BY_FILE_ID (0x00002000) | ファイルは ID で開かれています。 ファイル名には、デバイスの名前と、ファイルを開くために使用する 64 ビット ID が含まれます。 |
| FILE_OPEN_FOR_BACKUP_INTENT (0x000004000) | ファイルはバックアップの目的で開かれています。そのため、システムは特定のアクセス権をチェックし、ファイルのセキュリティ記述子に対して入力 DesiredAccess を確認する前に、呼び出し元にファイルへの適切なアクセス権を付与する必要があります。 |
| FILE_NO_COMPRESSION (0x00008000) | 親ディレクトリからのFILE_ATTRIBUTE_COMPRESSEDの継承を抑制します。 これにより、圧縮されていないファイルを、圧縮済みとマークされたディレクトリに作成できます。 |
| FILE_OPEN_REQUIRING_OPLOCK (0x00010000) | ファイルが開き、ファイルの日和見ロック (oplock) が 1 つのアトミック操作として要求されています。 ファイル システムは、作成操作を実行する前に oplock を確認します。作成操作が既存の oplock を中断した場合、作成操作は戻りコード STATUS_CANNOT_BREAK_OPLOCKで失敗します。 このフラグは、Windows 7、Windows Server 2008 R2 以降の Windows オペレーティング システムで使用できます。 |
| FILE_DISALLOW_EXCLUSIVE (0x00020000) | 既存のファイルを開くときに、FILE_SHARE_READが指定されておらず、ファイル システムのアクセス チェックで呼び出し元にファイルへの書き込みアクセス権が付与されない場合は、STATUS_ACCESS_DENIEDでこのファイルを開けなくなります。 これは Windows 7 より前の既定の動作でした。 |
| FILE_SESSION_AWARE (0x00040000) | ファイルまたはデバイスがセッション認識で開かれています。 このフラグを指定しない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。 このフラグは、セッション 0 に含まれていない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。 このフラグは、Windows Server 2012する前にサポートされていません。 |
| FILE_RESERVE_OPFILTER (0x00100000) | このフラグを使用すると、アプリケーションはフィルターの日和見ロック (oplock) を要求して、他のアプリケーションが共有違反を受け取ることを防ぐことができます。 開いているハンドルが既にある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。 詳細については、「解説」を参照してください。 |
| FILE_OPEN_REPARSE_POINT (0x00200000) | 再解析ポイントを持つファイルを開き、ファイルの通常の再解析ポイント処理をバイパスします。 詳細については、「解説」を参照してください。 |
| FILE_OPEN_NO_RECALL (0x00400000) | オフライン ストレージまたは仮想化を実行するフィルターに対して、このファイルが開かれた結果としてファイルの内容を呼び戻さないよう指示します。 |
| FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) | このフラグは、呼び出し元のスレッドに関連付けられているユーザーをキャプチャするようにファイル システムに指示します。 返されたハンドルを使用して FltQueryVolumeInformation または ZwQueryVolumeInformationFile を後続で呼び出すと、呼び出し元が使用できる空き領域を計算するために、その時点で呼び出し元ユーザーではなく、キャプチャされたユーザーが想定されます。 これは、次の FsInformationClass 値に適用されます。 FileFsSizeInformation、FileFsFullSizeInformation、および FileFsFullSizeInformationEx。 |
[in, optional] EaBuffer
ファイルに適用する拡張属性 (EA) 情報を含む FILE_FULL_EA_INFORMATION 型の呼び出し元から提供される変数へのポインター。 デバイス ドライバーと中間ドライバーの場合、このパラメーターは NULL である必要があります。
[in] EaLength
EaBuffer の長さ (バイト単位)。 デバイス ドライバーと中間ドライバーの場合、このパラメーターは 0 である必要があります。
[in] CreateFileType
ドライバーは、このパラメーターを CreateFileTypeNone に設定する必要があります。
[in, optional] InternalParameters
ドライバーは、このパラメーターを NULL に設定する必要があります。
[in] Options
作成要求の生成中に使用するオプションを指定します。 0 個以上の次のビット フラグ値を使用できます。
| オプション フラグ | 意味 |
|---|---|
| IO_FORCE_ACCESS_CHECK | I/O マネージャーは、ファイルのセキュリティ記述子に対して作成要求をチェックする必要があります。 詳細については、「解説」を参照してください。 |
| IO_IGNORE_SHARE_ACCESS_CHECK | I/O マネージャーは、作成後にファイル オブジェクトに対して共有アクセス チェックを実行しないでください。 ただし、ファイル システムは引き続きこれらのチェックを実行する可能性があります。 |
| IO_STOP_ON_SYMLINK | ファイルを開いたり作成したりするときにジャンクション、シンボリック リンク、またはグローバル再解析ポイントが見つかった場合、I/O マネージャーはSTATUS_STOPPED_ON_SYMLINKを返します。 さらに、REPARSE_DATA_BUFFER構造体は IoStatusBlock-Information> で返されます。 呼び出し元は、 REPARSE_DATA_BUFFER 構造体を解放する役割を担います。 |
| IO_OPEN_TARGET_DIRECTORY | ファイルの親ディレクトリを開きます。 |
[in, optional] DriverContext
IoInitializeDriverCreateContext ルーチンによって以前に初期化されたIO_DRIVER_CREATE_CONTEXT構造体への省略可能なポインター。 IO_DRIVER_CREATE_CONTEXT構造体を使用して、追加のパラメーターを IoCreateFileEx および FltCreateFileEx2 ルーチンに渡すことができます。 詳細については、次の「解説」セクションを参照してください。
戻り値
IoCreateFileEx は 、STATUS_SUCCESSまたは次のいずれかの適切な NTSTATUS 値を返します。
| リターン コード | 説明 |
|---|---|
| STATUS_INVALID_DEVICE_OBJECT_PARAMETER | IoCreateFileEx は、 DriverContext パラメーターが NULL でない場合、および指定されたデバイス オブジェクトがファイルまたはディレクトリ名で指定されたボリュームのファイル システム ドライバー スタックにアタッチされていない場合に、この状態値を返します。 このデバイス オブジェクトは、IO_DRIVER_CREATE_CONTEXT構造体の DeviceObjectHint メンバーによって指定されます。 詳細については、「 IO_DRIVER_CREATE_CONTEXT」を参照してください。 |
| STATUS_MOUNT_POINT_NOT_RESOLVED | DriverContext パラメーターが NULL でない場合、およびファイルまたはディレクトリ名に、指定したデバイス オブジェクトがアタッチされているボリューム以外のボリュームに解決されるマウント ポイントが含まれている場合、IoCreateFileEx は、この状態値を返します。 このデバイス オブジェクトは、IO_DRIVER_CREATE_CONTEXT構造体の DeviceObjectHint メンバーによって指定されます。 詳細については、「 IO_DRIVER_CREATE_CONTEXT」を参照してください。 |
| STATUS_OBJECT_PATH_SYNTAX_BAD | ObjectAttributes パラメーターに RootDirectory メンバーが含まれていなくても、OBJECT_ATTRIBUTES構造体の ObjectName メンバーが空の文字列であるか、OBJECT_NAME_PATH_SEPARATOR文字が含まれていない場合、IoCreateFileEx はこの状態値を返します。 これは、オブジェクト パスの正しくない構文を示します。 |
| STATUS_STOPPED_ON_SYMLINK | IoCreateFileEx は 、Options パラメーター フラグ IO_STOP_ON_SYMLINK が設定され、ファイルの開きまたは作成中にシンボリック リンクが見つかった場合に、この状態値を返します。 |
IoCreateFileEx ルーチンがエラー状態を返した場合、呼び出し元は IoStatusBlock パラメーターを確認することで、エラーの原因に関する追加情報を見つけることができます。
IoCreateFileEx は、STATUS_FILE_LOCK_CONFLICTを戻り値として返すか、IoStatusBlock パラメーターによって指されるIO_STATUS_BLOCK構造体の Status メンバーで返す場合があります。 これは、NTFS ログ ファイルがいっぱいで、 IoCreateFileEx がこの状況を処理しようとしている間にエラーが発生した場合にのみ発生します。
注釈
IoCreateFileEx ルーチンは、IoCreateFile ルーチンと IoCreateFileSpecifyDeviceObjectHint ルーチンの両方に似ていますが、追加の作成パラメーター (ECP)、デバイス オブジェクト ヒント、IoCreateFileEx ルーチンの DriverContext パラメーターを使用したトランザクション情報へのアクセスなど、追加の機能を提供します。 これらの構造体ベースのパラメーターの詳細については、「 IO_DRIVER_CREATE_CONTEXT」を参照してください。
ファイル システム フィルター ドライバーは IoCreateFileEx を呼び出して、指定されたデバイス オブジェクト、その下にアタッチされているフィルター、およびファイル システムにのみ作成要求を送信します。 ドライバー スタック内の指定したデバイス オブジェクトの上にアタッチされたフィルターは、作成要求を受け取りません。 ただし、IO_DRIVER_CREATE_CONTEXT構造体 (DriverContext パラメーターを介して渡される) の DeviceObjectHint メンバーが NULL の場合、要求はスタックの先頭に移動し、すべてのフィルターとファイル システムによって受信されます。
I/O 要求がドライバー スタックの先頭に移動しない場合、つまり DriverContext パラメーターが NULL ではなく、有効なデバイス オブジェクトがIO_DRIVER_CREATE_CONTEXT構造体の DeviceObjectHint メンバーによって指定されている場合は、次の制限が適用されます。
- IoCreateFileEx ルーチンに渡されるファイル名パスにマウント ポイントが含まれている場合、マウント ポイントは、ファイルまたはディレクトリが存在するのと同じボリュームに解決される必要があります。
IoCreateFileEx によって取得されたハンドルは、後続の呼び出しで使用して、ファイル内のデータ、またはファイル オブジェクトの状態または属性を操作できます。 IoCreateFileEx から取得されたハンドルは、最終的に ZwClose を呼び出して解放する必要があります。
IoCreateFileEx を使用して作成または開くファイルの名前を指定するには、次の 2 つの方法があります。
完全修飾パス名として、入力 ObjectAttributes パラメーターの ObjectName メンバーで指定されます。
入力 ObjectAttributes パラメーターの RootDirectory メンバーのハンドルに対する相対パス名。 (このハンドルはディレクトリ ファイルを表すことができます)。
システム プロセス以外のプロセス コンテキストで実行されるドライバー ルーチンは、IoCreateFileEx の ObjectAttributes パラメーターのOBJ_KERNEL_HANDLE属性を設定する必要があります。 これにより、 IoCreateFileEx によって返されるハンドルの使用が、カーネル モードで実行されているプロセスに制限されます。 それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。 ドライバーは InitializeObjectAttributes を呼び出して、OBJ_KERNEL_HANDLE属性を設定できます。
特定の DesiredAccess フラグとフラグの組み合わせには、次の効果があります。
呼び出し元が、返された FileHandle が Signaled 状態に設定されるのを待って I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。 それ以外の場合、デバイスまたは中間ドライバーである呼び出し元は、イベント オブジェクトを使用して I/O 完了を同期する必要があります。
FILE_APPEND_DATAフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元はファイルの末尾にのみ書き込むことができます。ファイルへの書き込みに関するオフセット情報は無視されます。 ただし、この種類の書き込み操作では、必要に応じてファイルが自動的に拡張されます。
ファイルのFILE_WRITE_DATA フラグを設定すると、ファイルの末尾を超える書き込みも行われます。 ファイルは、この種の書き込みでも自動的に拡張されます。
FILE_EXECUTEフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元は、返された FileHandle を使用してファイル内のデータを直接読み取ったり書き込んだりすることはできません。つまり、命令とデータアクセスに応答して、ファイルに対するすべての操作がシステム ポケットベルを介して行われます。 デバイス ドライバーと中間ドライバーでは 、DesiredAccess で FILE_EXECUTE フラグを設定しないでください。
ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。 指定した方法でファイルにアクセスする権限を両方のファイル・オープン機能に持っている場合は、ファイルを正常に開いて共有できます。 IoCreateFileEx の元の呼び出し元がFILE_SHARE_READ、FILE_SHARE_WRITE、またはFILE_SHARE_DELETEを指定していない場合、ファイルに対して他の開いている操作を実行することはできません。つまり、元の呼び出し元にはファイルへの排他的アクセス権が付与されます。
共有ファイルを正常に開くには、ファイルに対して要求された DesiredAccess 値が、ZwClose でまだリリースされていない以前のすべてのオープン要求の DesiredAccess 仕様と ShareAccess 仕様の両方と互換性がある必要があります。 つまり、特定のファイルに対して IoCreateFileEx に指定された DesiredAccess 値は、ファイルの他の opener が許可していないアクセスと競合してはなりません。
Options パラメーターにIO_IGNORE_SHARE_ACCESS_CHECKが指定されている場合、I/O マネージャーは ShareAccess パラメーターを無視します。 ただし、ファイル システムは引き続きアクセス チェックを実行する可能性があります。 したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、 ShareAccess パラメーターに使用する共有モードを指定することが重要です。
Disposition 値FILE_SUPERSEDE、呼び出し元が既存のファイル オブジェクトに対する DELETE アクセス権を持っている必要があります。 その場合、既存のファイルに対する FILE_SUPERSEDE を使用して IoCreateFileEx を正常に呼び出すと、そのファイルが実質的に削除され、再作成されます。 これは、ファイルが既に別のスレッドによって開かれている場合、FILE_SHARE_DELETE フラグが設定された ShareAccess パラメーターを指定して、スレッドによってファイルが開かれたことを意味します。 この種類の処理は、ファイルを上書きする POSIX スタイルと一致していることに注意してください。
Disposition の値FILE_OVERWRITE_IFとFILE_SUPERSEDEは似ています。 IoCreateFileEx が既存のファイルで呼び出され、これらの Disposition 値のいずれかが呼び出されると、ファイルが置き換えられます。
ファイルの上書きは、次の点を除き、意味的には置き換え操作と同じです。
呼び出し元は、削除アクセスではなく、ファイルへの書き込みアクセス権を持っている必要があります。 これは、ファイルが既に別のスレッドによって開かれている場合は、入力 ShareAccess に FILE_SHARE_WRITE フラグを設定してファイルを開くことを意味します。
指定されたファイル属性は、ファイルに既に存在する属性と論理的に ORed です。 これは、ファイルが既に別のスレッドによって開かれている場合、 IoCreateFileEx の後続の呼び出し元は既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。 ファイルを上書きするこのスタイルは、MS-DOS、Windows 3.1、OS/2 と一致していることに注意してください。
CreateOptions FILE_DIRECTORY_FILE値は、作成または開くファイルがディレクトリ ファイルであることを指定します。 ディレクトリ ファイルが作成されると、ファイル システムはディスク上に適切な構造を作成し、その特定のファイル システムのディスク上の構造の空のディレクトリを表します。 このオプションが指定されていて、開く指定されたファイルがディレクトリ ファイルではない場合、または呼び出し元が一貫性のない CreateOptions または Disposition 値を指定した場合、 IoCreateFileEx の呼び出しは失敗します。
CreateOptions FILE_NO_INTERMEDIATE_BUFFERING フラグを指定すると、ファイル システムが呼び出し元に代わって中間バッファリングを実行できなくなります。 この値を指定すると、呼び出し元のパラメーターに特定の制限が Zw に設定されます。ファイル ルーチン(次を含む):
ZwReadFile または ZwWriteFile に渡される任意の ByteOffset は、セクター サイズの整数 (整数倍数) である必要があります。
ZwReadFile または ZwWriteFile に渡される長さは、セクター サイズの整数である必要があります。 長さがセクター サイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有効バイト数が少なくなる可能性があることに注意してください。
バッファーは、基になるデバイスの配置要件に従って配置する必要があります。 この情報を取得するには、 IoCreateFileEx を呼び出して、物理デバイスを表すファイル オブジェクトのハンドルを取得し、そのハンドルを使用して ZwQueryInformationFile を 呼び出します。 システム FILE_XXX_ALIGNMENT 値の一覧については、「 DEVICE_OBJECT」を参照してください。
FileInformationClass パラメーターを FilePositionInformation に設定して ZwSetInformationFile を呼び出すには、セクター サイズの整数であるオフセットを指定する必要があります。
相互に排他的な CreateOptions、FILE_SYNCHRONOUS_IO_ALERT、およびFILE_SYNCHRONOUS_IO_NONALERT フラグは、返される FileHandle によって参照されるファイル オブジェクトを介して行われる限り、ファイルに対するすべての I/O 操作を同期するように指定します。 このようなファイルのすべての I/O は、返されたハンドルを使用して、すべてのスレッドでシリアル化されます。 これらの CreateOptions 値のいずれかを使用して、I/O マネージャーがファイル オブジェクトを同期オブジェクトとして使用するように DesiredAccess SYNCHRONIZE フラグを設定する必要があります。 これらの CreateOptions 値のいずれかが設定されている場合、I/O マネージャーは、ファイル オブジェクトの "ファイル位置コンテキスト" (内部の現在のファイル位置オフセット) を維持します。 このオフセットは、ZwReadFile と ZwWriteFile の呼び出しで使用できます。 その位置は、 ZwQueryInformationFile を呼び出すことによってクエリを実行することも、 ZwSetInformationFile を呼び出して設定することもできます。
CreateOptions FILE_OPEN_REPARSE_POINT フラグが指定されておらず、IoCreateFileEx が再解析ポイントを使用してファイルを開こうとすると、そのファイルに対して通常の再解析ポイント処理が行われます。 一方、FILE_OPEN_REPARSE_POINT フラグが指定されている場合、通常の再解析処理は行 われず 、 IoCreateFileEx は再解析ポイント ファイルを直接開こうとします。 どちらの場合も、開いている操作が成功した場合、 IoCreateFileEx はSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは NTSTATUS エラー コードを返します。 IoCreateFileEx は STATUS_REPARSEを返しません。
CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開いて共有違反を受け取る可能性がある oplock を要求する時間がなくなります。 アプリケーションでは、 IoCreateFileEx で FILE_OPEN_REQUIRING_OPLOCK フラグを使用し、任意の oplock を要求できます。 これにより、oplock 所有者に、共有違反の原因となる後で開いている要求が通知されます。
Windows 7 では、アプリケーションで FILE_OPEN_REQUIRING_OPLOCK フラグを使用するときに、ファイルに他のハンドルが存在する場合、作成操作はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。 この制限は、Windows 8以降は存在しません。
この作成操作によって、ファイルに既に存在する oplock が中断される場合、FILE_OPEN_REQUIRING_OPLOCK フラグを設定すると、作成操作は STATUS_CANNOT_BREAK_OPLOCK で失敗します。 この作成操作では、既存の oplock は破損しません。
このフラグを使用するアプリケーションは、この呼び出しが成功した後に oplock を要求する必要があります。または、一般的な oplock 処理の利点なしに、ファイルを開こうとするすべての試行がブロックされます。 同様に、この呼び出しが成功しても後の oplock 要求が失敗した場合、このフラグを使用するアプリケーションは、oplock 要求が失敗したことを検出した後でハンドルを閉じる必要があります。
FILE_OPEN_REQUIRING_OPLOCK フラグは、Windows 7、Windows Server 2008 R2 以降の Windows オペレーティング システムで使用できます。 このフラグを実装する Microsoft ファイル システムは、NTFS、FAT、exFAT です。
CreateOptions フラグ (FILE_RESERVE_OPFILTER) を使用すると、アプリケーションはレベル 1、バッチ、またはフィルター oplock を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。 ただし、FILE_RESERVE_OPFILTERは、フィルター 操作に対してのみ実用的に役立ちます。 これを使用するには、次の手順に従う必要があります。
CreateOptions of FILE_RESERVE_OPFILTER、DesiredAccess が正確にFILE_READ_ATTRIBUTES、ShareAccess が正確にFILE_SHARE_READで作成要求を発行する |FILE_SHARE_WRITE |FILE_SHARE_DELETE。
既に開いているハンドルがある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗し、次に要求された oplock も失敗します。
より多くのアクセス権またはより少ない共有で開くと、STATUS_OPLOCK_NOT_GRANTEDのエラーも発生します。
作成要求が成功した場合は、oplock を要求します。
ファイルへの別のハンドルを開いて I/O を実行します。
手順 3 では、これはフィルター 操作に対してのみ実用的です。 手順 3 で開いたハンドルには、最大FILE_READ_ATTRIBUTES | を含む DesiredAccess を含めることができます。FILE_WRITE_ATTRIBUTES |FILE_READ_DATA |FILE_READ_EA |FILE_EXECUTE |SYNCHRONIZE |READ_CONTROLし、フィルター oplock を中断しません。 ただし、desiredAccess が FILE_READ_ATTRIBUTES より大きい場合 |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE では、レベル 1 またはバッチ oplock が中断され、FILE_RESERVE_OPFILTER フラグがこれらの oplock 型では役に立たなくなります。
ユーザー モードで発生する作成要求の場合、ドライバーが IoCreateFileExの Options パラメーターにIO_FORCE_ACCESS_CHECKを設定する場合は、ObjectAttributes パラメーターにOBJ_FORCE_ACCESS_CHECKも設定する必要があります。 このフラグの詳細については、OBJECT_ATTRIBUTESの Attributes メンバーを参照してください。
NTFS は、FILE_RESERVE_OPFILTERを実装する唯一の Microsoft ファイル システムです。
IoCreateFileEx を使用して、ボリュームへのハンドルを取得できます。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntddk.h (Ntddk.h、Ntifs.h、FltKernel.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
こちらもご覧ください
FltAllocateExtraCreateParameter
FltAllocateExtraCreateParameterList
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示