IoCreateFileSpecifyDeviceObjectHint 関数 (ntddk.h)
IoCreateFileSpecifyDeviceObjectHint ルーチンは、指定されたデバイス オブジェクトの下のフィルターとファイル システムにのみ作成要求を送信するために、ファイル システム フィルター ドライバーによって使用されます。
構文
NTSTATUS IoCreateFileSpecifyDeviceObjectHint(
[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] PVOID DeviceObject
);
パラメーター
[out] FileHandle
この呼び出しが成功した場合にファイル オブジェクトのハンドルを受け取る変数へのポインター。
[in] DesiredAccess
呼び出し元がファイルまたはディレクトリに対して必要とするアクセスの種類を指定するフラグのビットマスク。 システム定義の 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 | ファイルに関連付けられている拡張属性を書き込むことができます。 |
| 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 を使用して、ファイルからメモリにデータを読み取ることができます。 |
IoCreateFileSpecifyDeviceObjectHint の呼び出し元は、ディレクトリ ファイルを表さないファイル オブジェクトに対して、DesiredAccess フラグの前の一覧から互換性のあるフラグを追加する可能性がある次の 1 つまたは組み合わせを指定できます。
| DesiredAccess to file values | 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。 |
STANDARD_RIGHTS_XXX は、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です。
FILE_DIRECTORY_FILE CreateOptions フラグが設定されている場合、 IoCreateFileSpecifyDeviceObjectHint の呼び出し元は、次の 1 つまたは複数の組み合わせを指定できます。この場合は、DesiredAccess フラグの前のリストから 1 つ以上の互換性のあるフラグを持つ ORed を指定できます。
| DesiredAccess to directory values | 意味 |
|---|---|
| FILE_LIST_DIRECTORY | ディレクトリ内のファイルを一覧表示できます。 |
| FILE_TRAVERSE | ディレクトリは走査できます。つまり、ファイルのパス名の一部にすることができます。 |
DesiredAccess フラグFILE_READ_DATA、FILE_WRITE_DATA、FILE_EXECUTE、FILE_APPEND_DATAは、ディレクトリ ファイルの作成または開き方と互換性がありません。
[in] ObjectAttributes
InitializeObjectAttributes ルーチンによって既に初期化されているOBJECT_ATTRIBUTES構造体へのポインター。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーター (ObjectAttributes) は NULL にすることができます。 それ以外の場合、呼び出し元は InitializeObjectAttributes ルーチンの呼び出しでOBJ_KERNEL_HANDLE属性を設定する必要があります。 ファイル オブジェクトのOBJECT_ATTRIBUTES構造体のメンバーには、次のようなものがあります。
| メンバー | 値 |
|---|---|
| ULONGLength | 指定された ObjectAttributes データのバイト数を指定します。 この値は、少なくとも sizeof(OBJECT_ATTRIBUTES) である必要があります。 |
| PUNICODE_STRING ObjectName | 作成または開くファイルに名前を付ける、バッファー内の Unicode 文字列へのポインター。 RootDirectory で指定されたディレクトリに対するファイルの名前でない限り、この値は完全修飾ファイル仕様である必要があります。 たとえば、\Device\フロッピー 1\myfile.datや \??フロッピー ドライバーと上にあるファイル システムが既に読み込まれている場合は、\B:\myfile.dat が完全修飾ファイル仕様である可能性があります。 (\?? は、Win32 オブジェクト名前空間の名前として \DosDevices を置き換えます。\DosDevices は引き続き機能しますが、\?? はオブジェクト マネージャーによってより高速に変換されます。 |
| HANDLERootDirectory | 必要に応じて、 IoCreateFileSpecifyDeviceObjectHint の前の呼び出しによって取得されたディレクトリへのハンドルを指定します。 この値が NULL の場合、 ObjectName メンバーは、ターゲット ファイルへの完全パスを含む完全修飾ファイル仕様である必要があります。 この値が NULL 以外の場合、 ObjectName メンバーは、このディレクトリに対する相対ファイル名を指定します。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | 必要に応じて、ファイルに適用するセキュリティ記述子を指定します。 このようなセキュリティ記述子で指定された ACL は、作成時にのみファイルに適用されます。 ファイルの作成時に値が NULL の 場合、ファイルに配置される ACL はファイル システムに依存します。ほとんどのファイル システムは、そのような ACL の一部を、呼び出し元の既定の ACL と組み合わせた親ディレクトリ ファイルから伝達します。 |
| ULONGAttributes | ファイル オブジェクト属性を制御するフラグのセット。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーターは 0 にすることができます。 それ以外の場合、呼び出し元はOBJ_KERNEL_HANDLE フラグを設定する必要があります。 呼び出し元は必要に応じて、OBJ_CASE_INSENSITIVE フラグを設定することもできます。これは、名前参照コードが完全一致検索を実行するのではなく 、ObjectName の大文字と小文字を無視する必要があることを示します。 |
[out] IoStatusBlock
最終的 な完了 状態と要求された操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 IoCreateFileSpecifyDeviceObjectHint から返された場合、Information メンバーには次のいずれかの値が含まれます。
FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
必要に応じて、ファイルの初期割り当てサイズをバイト単位で指定します。 ファイルが作成、上書き、または置き換えられる場合を除き、0 以外の値は有効になりません。
[in] FileAttributes
明示的に指定された属性は、ファイルが作成、置き換えられる、または場合によっては上書きされた場合にのみ適用されます。 既定では、この値はFILE_ATTRIBUTE_NORMAL。他のフラグまたは互換性のあるフラグの ORed の組み合わせによってオーバーライドできます。 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 マネージャーはこのパラメーターを無視します。 ただし、ファイル システムは引き続きアクセス チェックを実行する可能性があります。 したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、このパラメーターに使用する共有モードを指定することが重要です。 共有違反エラーを回避する可能性が最も高い場合は、次のすべての共有アクセス フラグを指定します。
| ShareAccess フラグ | 意味 |
|---|---|
| FILE_SHARE_READ | ファイルは、他のスレッドが読み取りアクセスできるように開くことができます。 |
| FILE_SHARE_WRITE | ファイルは、他のスレッドによる書き込みアクセス用に開くことができます。 |
| FILE_SHARE_DELETE | ファイルは、他のスレッドによる削除アクセスのために開くことができます。 |
[in] Disposition
ファイルが既に存在するかどうかに応じて、実行するアクションを決定する値を指定します。 値には、次に説明するもののいずれかを指定できます。
| 廃棄値 | 意味 |
|---|---|
| FILE_SUPERSEDE | ファイルが既に存在する場合は、指定したファイルに置き換えます。 そうでない場合は、指定されたファイルを作成します。 |
| FILE_CREATE | ファイルが既に存在する場合は、要求に失敗し、指定されたファイルを作成または開かないでください。 そうでない場合は、指定されたファイルを作成します。 |
| FILE_OPEN | ファイルが既に存在する場合は、新しいファイルを作成する代わりに開きます。 そうでない場合は、要求に失敗し、新しいファイルを作成しません。 |
| FILE_OPEN_IF | ファイルが既に存在する場合は、ファイルを開きます。 そうでない場合は、指定されたファイルを作成します。 |
| FILE_OVERWRITE | ファイルが既に存在する場合は、ファイルを開いて上書きします。 そうでない場合は、要求に失敗します。 |
| FILE_OVERWRITE_IF | ファイルが既に存在する場合は、ファイルを開いて上書きします。 そうでない場合は、指定されたファイルを作成します。 |
[in] CreateOptions
ファイルを作成または開くときに適用するオプションを指定します。 これらのオプションは、次のフラグの互換性のある組み合わせとして指定されます。
| CreateOptions フラグ | 意味 |
|---|---|
| FILE_DIRECTORY_FILE | 作成または開いているファイルはディレクトリ ファイルです。 このフラグが設定されている場合、 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_NON_DIRECTORY_FILE | 開いているファイルをディレクトリ ファイルにすることはできません。または、この呼び出しは失敗します。 開いているファイル オブジェクトは、データ ファイルを表す必要があります。 |
| FILE_WRITE_THROUGH | ファイルにデータを書き込むシステム サービス、FSD、ドライバーは、要求された書き込み操作が完了したと見なされる前に、実際にデータをファイルに転送する必要があります。 |
| FILE_SEQUENTIAL_ONLY | ファイルへのアクセスはすべて順次行われます。 |
| FILE_RANDOM_ACCESS | ファイルへのアクセスはランダムにできるため、FSD またはシステムによってファイルに対して順次先読み操作を実行する必要はありません。 |
| FILE_NO_INTERMEDIATE_BUFFERING | ファイルは、ドライバーの内部バッファーにキャッシュまたはバッファーすることはできません。 このフラグは DesiredAccess FILE_APPEND_DATA フラグと互換性がありません。 |
| FILE_SYNCHRONOUS_IO_ALERT | ファイルに対するすべての操作は同期的に実行されます。 呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグを設定する場合は、 DesiredAccess SYNCHRONIZE フラグも設定する必要があります。 |
| FILE_SYNCHRONOUS_IO_NONALERT | ファイルに対するすべての操作は同期的に実行されます。 I/O キューと完了を同期するためにシステムに存在する待機は、アラートの対象になりません。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグを設定する場合は、 DesiredAccess SYNCHRONIZE フラグも設定する必要があります。 |
| FILE_CREATE_TREE_CONNECTION | ネットワーク経由で開くために、このファイルのツリー接続を作成します。 |
| FILE_COMPLETE_IF_OPLOCKED | 呼び出し元のスレッドをブロックするのではなく、ターゲット ファイルが操作されている場合は、代替成功コードを使用してすぐにこの操作を完了します。 ファイルが oplocked の場合、別の呼び出し元は既にネットワーク経由でファイルにアクセスできます。 |
| FILE_NO_EA_KNOWLEDGE | 開かれている既存のファイルの拡張属性が、呼び出し元がファイルを正しく解釈するために EA を理解する必要があることを示している場合は、呼び出し元が EA の処理方法を理解していないため、この要求を失敗させます。 |
| FILE_OPEN_REPARSE_POINT | 再解析ポイントを持つファイルを開き、ファイルの通常の再解析ポイント処理をバイパスします。 詳細については、以下の 「解説 」セクションを参照してください。 |
| FILE_DELETE_ON_CLOSE | 最後のハンドルが ZwClose に渡されたときにファイルを削除します。 |
| FILE_OPEN_BY_FILE_ID | ObjectAttributes パラメーターで指定されたファイル名には、ファイルの 8 バイトのファイル参照番号が含まれています。 この番号はファイル システムによって割り当てられ、ファイル システム固有です。 ファイルが再解析ポイントの場合、ファイル名にはデバイスの名前も含まれます。 注: FAT ファイル システムでは、FILE_OPEN_BY_FILE_IDはサポートされていません。 |
| FILE_OPEN_FOR_BACKUP_INTENT | ファイルはバックアップの目的で開かれているため、システムは特定のアクセス権をチェックし、ファイルのセキュリティ記述子に対して DesiredAccess という入力を確認する前に、呼び出し元にファイルへの適切なアクセス権を付与する必要があります。 |
| FILE_OPEN_REQUIRING_OPLOCK | ファイルが開き、ファイルの日和見ロック (oplock) が 1 つのアトミック操作として要求されています。 ファイル システムは、作成操作を実行する前に oplock を確認し、作成が既存の oplock を中断する場合、STATUS_CANNOT_BREAK_OPLOCKの戻りコードで作成操作が失敗します。 |
| FILE_RESERVE_OPFILTER | このフラグを使用すると、アプリケーションはフィルターの日和見ロック (oplock) を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。 既に開いているハンドルがある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。 詳細については、「解説」を参照してください。 |
[in, optional] EaBuffer
ファイルに適用される拡張属性 (EA) 情報を含む、呼び出し元が指定した FILE_FULL_EA_INFORMATION構造化バッファーへのポインター。
[in] EaLength
EaBuffer の長さ (バイト単位)。
[in] CreateFileType
ドライバーは、このパラメーターを CreateFileTypeNone に設定する必要があります。
[in, optional] InternalParameters
ドライバーは、このパラメーターを NULL に設定する必要があります。
[in] Options
作成要求の作成時に使用するオプションを指定します。 利用可能なオプションの一覧を次の表に示します。
| オプション フラグ | 意味 |
|---|---|
| IO_FORCE_ACCESS_CHECK | I/O マネージャーがファイルのセキュリティ記述子に対して作成要求をチェックする必要があることを示します。 |
| IO_IGNORE_SHARE_ACCESS_CHECK | I/O マネージャーが作成された後、ファイル オブジェクトに対して共有アクセス チェックを実行しないことを示します。 ただし、ファイル システムは引き続きこれらのチェックを実行する可能性があります。 |
[in, optional] DeviceObject
作成要求の送信先となるデバイス オブジェクトへのポインター。 デバイス オブジェクトは、ファイルまたはディレクトリが存在するボリュームのファイル システム ドライバー スタック内のフィルターまたはファイル システム デバイス オブジェクトである必要があります。 このパラメーターは省略可能であり、 NULL にすることができます。 このパラメーターが NULL の場合、要求はドライバー スタックの上部にあるデバイス オブジェクトに送信されます。
戻り値
IoCreateFileSpecifyDeviceObjectHint は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。
| リターン コード | 説明 |
|---|---|
| STATUS_INVALID_DEVICE_OBJECT_PARAMETER | 指定された DeviceObject は、ファイル名またはディレクトリ名で指定されたボリュームのファイル システム ドライバー スタックにアタッチされません。 このエラーは、名前にマウント ポイント以外の再解析ポイントが含まれている場合にも発生する可能性があります。 |
| STATUS_MOUNT_POINT_NOT_RESOLVED | ファイルまたはディレクトリ名には、指定した DeviceObject がアタッチされているボリューム以外のボリュームに解決されるマウント ポイントが含まれています。 |
| STATUS_OBJECT_PATH_SYNTAX_BAD |
IoCreateFileSpecifyDeviceObjectHint は、STATUS_FILE_LOCK_CONFLICTを戻り値として返すか、IoStatusBlock パラメーターによって指されるIO_STATUS_BLOCK構造体の Status メンバーで返される場合があります。 これは、NTFS ログ ファイルがいっぱいで、 IoCreateFileSpecifyDeviceObjectHint がこの状況を処理しようとしたときにエラーが発生した場合にのみ発生します。
注釈
このルーチンは、指定したデバイス オブジェクトの下のフィルターとファイル システムにのみ作成要求を送信するファイル システム フィルター ドライバーによって使用されます。 ドライバー スタック内の指定したデバイス オブジェクトの上にアタッチされているフィルターは、作成要求を受け取りません。
Windows Vista IoCreateFileEx ルーチンは IoCreateFileSpecifyDeviceObjectHint ルーチンに似ていますが、追加の create パラメーター (ECP) やトランザクション情報へのアクセスなど、 IoCreateFileSpecifyDeviceObjectHint ルーチンよりも大きな機能を提供します。
IoCreateFileSpecifyDeviceObjectHint ルーチンの代わりに IoCreateFileEx ルーチンを使用する場合は、IoCreateFileSpecifyDeviceObjectHint ルーチンの DriverContext パラメーターが、IO_DRIVER_CREATE_CONTEXT構造体の DeviceObjectHint メンバーに移動されていることに注意してください。 IO_DRIVER_CREATE_CONTEXT構造体は、DriverContext パラメーターを使用して IoCreateFileEx ルーチンに渡されます。
ファイル システム フィルター ドライバーは IoCreateFileSpecifyDeviceObjectHint を呼び出して、指定されたデバイス オブジェクト、その下にアタッチされているフィルター、およびファイル システムにのみ作成要求を送信します。 ドライバー スタック内の指定したデバイス オブジェクトの上にアタッチされたフィルターは、作成要求を受け取りません。 IoCreateFileSpecifyDeviceObjectHint によって作成されたファイル オブジェクトに対するクリーンアップ要求またはクローズ要求についても同様です。
IoCreateFileSpecifyDeviceObjectHint を使用して作成または開くファイルの名前を指定するには、2 つの代替方法があります。
完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。
入力 ObjectAttributes の RootDirectory メンバーのハンドルによって表されるディレクトリ ファイルに対する相対パス名として
IoCreateFileSpecifyDeviceObjectHint から取得されたハンドルは、最終的に ZwClose を呼び出して解放する必要があります。
システム プロセス以外のプロセス コンテキストで実行されるドライバー ルーチンは、IoCreateFileSpecifyDeviceObjectHintの ObjectAttributes パラメーターのOBJ_KERNEL_HANDLE属性を設定する必要があります。 これにより、 IoCreateFileSpecifyDeviceObjectHint によって返されるハンドルの使用が、カーネル モードで実行されているプロセスに制限されます。 それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。
特定の DesiredAccess フラグとフラグの組み合わせには、次の効果があります。
呼び出し元が、返された FileHandle が Signaled 状態に設定されるのを待って I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。
FILE_APPEND_DATAフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元はファイルの末尾にのみ書き込むことができます。ファイルへの書き込みに関するオフセット情報は無視されます。 ただし、この種類の書き込み操作では、必要に応じてファイルが自動的に拡張されます。
ファイルのFILE_WRITE_DATA フラグを設定すると、ファイルの末尾を超える書き込みも実行できます。 ファイルは、この種類の書き込み用にも自動的に拡張されます。
FILE_EXECUTEフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元は、返された FileHandle を使用してファイル内のデータを直接読み取ったり書き込んだりすることはできません。つまり、ファイルに対するすべての操作は、命令とデータ アクセスに応答してシステム ポケットベルを介して実行されます。
ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。 指定した方法でファイルにアクセスする権限を両方のファイルオープン者が持っている場合は、ファイルを正常に開いて共有できます。 IoCreateFileSpecifyDeviceObjectHint の元の呼び出し元がFILE_SHARE_READ、FILE_SHARE_WRITE、またはFILE_SHARE_DELETEを指定していない場合、ファイルに対して他の開いている操作を実行することはできません。つまり、元の呼び出し元にはファイルへの排他的アクセス権が付与されます。
共有ファイルを正常に開くには、ファイルに対して要求された DesiredAccess が、ZwClose でまだリリースされていない上記のすべてのオープンの DesiredAccess 仕様と ShareAccess 仕様の両方と互換性がある必要があります。 つまり、特定のファイルに対して IoCreateFileSpecifyDeviceObjectHint に指定された DesiredAccess は、ファイルの他のオープン者が許可していないアクセスと競合してはなりません。
Options パラメーターにIO_IGNORE_SHARE_ACCESS_CHECKが指定されている場合、I/O マネージャーは ShareAccess パラメーターを無視します。 ただし、ファイル システムは引き続きアクセス チェックを実行する可能性があります。 したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、 ShareAccess パラメーターに使用する共有モードを指定することが重要です。
Disposition 値FILE_SUPERSEDEでは、呼び出し元が既存のファイル オブジェクトに対する DELETE アクセス権を持っている必要があります。 その場合、既存のファイルに対する FILE_SUPERSEDE を使用して IoCreateFileSpecifyDeviceObjectHint を正常に呼び出すと、そのファイルが実質的に削除され、再作成されます。 これは、ファイルが既に別のスレッドによって開かれている場合、FILE_SHARE_DELETE フラグが設定された ShareAccess パラメーターを指定してファイルを開くことを意味します。 この種類の処理は、ファイルを上書きする POSIX スタイルと一致することに注意してください。
Disposition の値FILE_OVERWRITE_IFとFILE_SUPERSEDEは似ています。 IoCreateFileSpecifyDeviceObjectHint が既存のファイルで呼び出され、これらの Disposition 値のいずれかが呼び出されると、ファイルが置き換えられます。
ファイルの上書きは、次の点を除き、意味的には置き換え操作と同じです。
呼び出し元は、アクセスを削除するのではなく、ファイルへの書き込みアクセス権を持っている必要があります。 これは、ファイルが既に別のスレッドによって開かれている場合は、入力 ShareAccess に FILE_SHARE_WRITE フラグを設定してファイルを開くことを意味します。
指定されたファイル属性は、ファイルに既に存在する属性と論理的に ORed です。 これは、ファイルが既に別のスレッドによって開かれている場合、 IoCreateFileSpecifyDeviceObjectHint の後続の呼び出し元は既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。
CreateOptions FILE_DIRECTORY_FILE値は、作成または開くファイルがディレクトリ ファイルであることを指定します。 ディレクトリ ファイルが作成されると、ファイル システムはディスク上に適切な構造を作成し、その特定のファイル システムのディスク上の構造の空のディレクトリを表します。 このオプションが指定されていて、開く指定されたファイルがディレクトリ ファイルではない場合、または呼び出し元が一貫性のない CreateOptions または Disposition 値を指定した場合、 IoCreateFileSpecifyDeviceObjectHint の呼び出しは失敗します。
CreateOptions FILE_NO_INTERMEDIATE_BUFFERING フラグを指定すると、ファイル システムが呼び出し元に代わって中間バッファリングを実行できなくなります。 この値を指定すると、呼び出し元のパラメーターに特定の制限が他の Zw に設定されます。ファイル ルーチン(次を含む):
ZwReadFile または ZwWriteFile に渡されるバイト オフセット値は、基になるデバイスのセクター サイズの倍数である必要があります。
ZwReadFile または ZwWriteFile に渡される長さは、セクター サイズの倍数である必要があります。 長さがセクター サイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有効バイト数が少なくなる可能性があることに注意してください。
バッファーは、基になるデバイスの配置要件に従って配置する必要があります。 この情報を取得するには、 IoCreateFileSpecifyDeviceObjectHint を呼び出して、物理デバイスを表すファイル オブジェクトのハンドルを取得し、そのハンドルで 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 フラグが指定されておらず、IoCreateFileSpecifyDeviceObjectHint が再解析ポイントを使用してファイルを開こうとすると、ファイルに対して通常の再解析ポイント処理が行われます。 一方、FILE_OPEN_REPARSE_POINT フラグが指定されている場合、通常の再解析処理は行われず、 IoCreateFileSpecifyDeviceObjectHint は再解析ポイント ファイルを直接開こうとします。 どちらの場合も、開いている操作が成功した場合、 IoCreateFileSpecifyDeviceObjectHint はSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは NTSTATUS エラー コードを返します。 IoCreateFileSpecifyDeviceObjectHint は STATUS_REPARSEを返しません。
CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開いて共有違反を受け取る可能性がある oplock を要求する時間がなくなります。 アプリケーションでは、 IoCreateFileSpecifyDeviceObjectHint で 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 オペレーティング システムで使用できます。 Windows 7 でこのフラグを実装する Microsoft ファイル システムは、NTFS、FAT、exFAT です。
CreateOptions フラグ FILE_RESERVE_OPFILTERを使用すると、アプリケーションはレベル 1、バッチ、またはフィルター oplock を要求して、他のアプリケーションで共有違反が発生しないようにすることができます。 ただし、FILE_RESERVE_OPFILTERは、フィルター 操作ロックに対してのみ実用的に役立ちます。 これを使用するには、次の手順を実行する必要があります。
CreateOptions が 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し、フィルター 操作ロックを中断しません。 ただし、 desiredAccess が FILE_READ_ATTRIBUTES より大きい場合 |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE では、レベル 1 またはバッチ oplock が中断され、FILE_RESERVE_OPFILTER フラグは、これらの oplock 型では使用できなくなります。
NTFS は、FILE_RESERVE_OPFILTERを実装する唯一の Microsoft ファイル システムです。
IoCreateFileSpecifyDeviceObjectHint を使用してボリュームへのハンドルを取得することはできません。
IoCreateFileSpecifyDeviceObjectHint に渡されるファイル名パスに再解析ポイントが含まれている場合、再解析ポイントは、ファイルまたはディレクトリが存在するのと同じボリュームに解決される必要があります。 そうでない場合は、エラー STATUS_INVALID_DEVICE_OBJECT_PARAMETERまたはSTATUS_MOUNT_POINT_NOT_RESOLVEDが返されます。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntddk.h (Ntddk.h、Ntifs.h、FltKernel.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示