NtCreateFile 関数 (winternl.h)

  • [アーティクル]

新しいファイルまたはディレクトリを作成するか、既存のファイル、デバイス、ディレクトリ、またはボリュームを開きます。

 

この関数は、Windows Driver Kit (WDK) に記載されている ZwCreateFile 関数と同等のユーザー モードです。

構文

__kernel_entry NTSTATUS NtCreateFile(
  [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              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in]           PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

パラメーター

[out] FileHandle

呼び出しが成功した場合にファイル ハンドルを受け取る変数へのポインター。

[in] DesiredAccess

呼び出し元がファイルまたはディレクトリに対して必要とするアクセスの種類を表す ACCESS_MASK 値。 DesiredAccess フラグ システム定義のセットによって、ファイル オブジェクトに対する次の特定のアクセス権が決まります。

価値 意味
DELETE を する
 ファイルは削除できます。
FILE_READ_DATA
 ファイルからデータを読み取ることができます。
FILE_READ_ATTRIBUTES
 FileAttributes フラグは、後で説明しますが、読み取ることができます。
FILE_READ_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 は、I/O 操作の完了との同期を待機できます。 FileHandle 同期 I/O 用に開かれていた場合、この値は無視されます。
FILE_EXECUTE
 システム ページング I/O を使用して、ファイルからメモリにデータを読み取ることができます。 このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
 

ディレクトリを作成または開くときに、FILE_READ_DATA、FILE_WRITE_DATA、FILE_APPEND_DATA、または FILE_EXECUTE は指定しないでください。

NtCreateFile の呼び出し元は、ディレクトリ ファイルを表さないファイル オブジェクトに対して、ビットごとの OR と、前述の DesiredAccess フラグ リストからの互換性のあるフラグを追加で使用して、次の 1 つまたは複数の組み合わせを指定できます。

価値 意味
FILE_GENERIC_READ
 STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE
FILE_GENERIC_WRITE
 STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
FILE_GENERIC_EXECUTE
 STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE
 

FILE_GENERIC_EXECUTE 値は、デバイスドライバーと中間ドライバーには関係ありません。

STANDARD_RIGHTS_XXX は、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です。

CreateOptions パラメーターで示されているように、ディレクトリ ファイルを開いたり作成したりするには、NtCreateFile の呼び出し元は、ビットごとの OR と、前述の DesiredAccess フラグ リストの 1 つ以上の互換性のあるフラグを使用して、次の 1 つまたは複数の組み合わせを指定できます。

価値 意味
FILE_LIST_DIRECTORY
 ディレクトリ内のファイルを一覧表示できます。
FILE_TRAVERSE
 ディレクトリは走査できます。つまり、ファイルのパス名の一部にすることができます。

[in] ObjectAttributes

InitializeObjectAttributesで既 初期化されている構造体へのポインター。 ファイル オブジェクトのこの構造体のメンバーは、次のとおりです。

価値 意味
ULONG の長さの を する
 指定されたデータ ObjectAttributes バイト数を指定します。 この値は、少なくとも sizeof(OBJECT_ATTRIBUTES) である必要があります。
HANDLE RootDirectory
 必要に応じて、NtCreateFileの前の呼び出しによって取得されたディレクトリへのハンドルを指定します。 この値が NULL場合、ObjectName メンバーは、ターゲット ファイルへの完全なパスを含む完全修飾ファイル仕様である必要があります。 この値が NULL以外の場合、ObjectName メンバーは、このディレクトリに対する相対ファイル名を指定します。
PUNICODE_STRING ObjectName
 作成または開くファイルの名前を指定するバッファー内の Unicode 文字列を指します。 この値は、rootDirectoryで指定されたディレクトリに対する相対ファイル名でない限り、完全修飾ファイル指定またはデバイス オブジェクトの名前 必要があります。 たとえば、\Device\フロッピー 1\myfile.datまたは \??フロッピー ドライバーと上にあるファイル システムが既に読み込まれている場合は、\B:\myfile.dat が完全修飾ファイル仕様である可能性があります。 詳細については、「ファイル名、パス、および名前空間の」を参照してください。
ULONG 属性 を する
 ファイル オブジェクト属性を制御するフラグのセットです。 この値は 0 または OBJ_CASE_INSENSITIVEにすることができます。これは、名前参照コードが完全一致検索を実行するのではなく、ObjectName メンバーの大文字と小文字を無視する必要があることを示します。 OBJ_INHERIT 値は、デバイスドライバーと中間ドライバーとは無関係です。
PSECURITY_DESCRIPTOR SecurityDescriptor
 必要に応じて、ファイルに適用するセキュリティ記述子を指定します。 このようなセキュリティ記述子で指定された ACL は、作成時にのみファイルに適用されます。 ファイルの作成時に値が null 場合、ファイルに配置される ACL はファイル システムに依存します。ほとんどのファイル システムは、そのような ACL の一部を親ディレクトリ ファイルから、呼び出し元の既定の ACL と組み合わせて伝達します。 デバイス ドライバーと中間ドライバーは、このメンバーを NULL設定できます。
PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService
 サーバーがクライアントのセキュリティ コンテキストに与える必要があるアクセス権を指定します。 この値は、保護されたサーバーへの接続が確立された場合にのみ、NULL です。これにより、呼び出し元は、呼び出し元のセキュリティ コンテキストのどの部分をサーバーで使用できるか、およびサーバーが呼び出し元の偽装を許可されるかどうかを制御できます。

[out] IoStatusBlock

最終的な完了状態と要求された操作に関する情報を受け取る変数へのポインター。 NtCreateFileから戻った場合、Information メンバーには次のいずれかの値が含まれます。

  • FILE_CREATED
  • FILE_OPENED
  • FILE_OVERWRITTEN
  • FILE_SUPERSEDED
  • FILE_EXISTS
  • FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

ファイルの初期割り当てサイズ (バイト単位)。 0 以外の値は、ファイルが作成、上書き、または置き換えられている場合を除き、効果はありません。

[in] FileAttributes

ファイル属性。 明示的に指定された属性は、ファイルが作成、置き換えられる、または場合によっては上書きされる場合にのみ適用されます。 既定では、この値は FILE_ATTRIBUTE_NORMALであり、Wdm.h および NtDdk.h で定義されている 1 つ以上の FILE_ATTRIBUTE_xxxx フラグの ORed の組み合わせによってオーバーライドできます。 NtCreateFileで使用できるフラグの一覧については、「CreateFile参照してください。

[in] ShareAccess

呼び出し元がファイルで使用する共有アクセスの種類。0、または次の値の 1 つまたは組み合わせとして使用します。

価値 意味
FILE_SHARE_READ
 NtCreateFileへの他のスレッドの呼び出しによって、ファイルを読み取りアクセス 開くことができます。
FILE_SHARE_WRITE
 このファイルは、NtCreateFileへの他のスレッドの呼び出しによって書き込みアクセス 開くことができます。
FILE_SHARE_DELETE
 このファイルは、NtCreateFileを する他のスレッドの呼び出しによって、削除アクセス用に開くことができます。
 

詳細については、Windows SDK を参照してください。

[in] CreateDisposition

ファイルが既に存在するかどうかに応じて、次のいずれかの値として実行する処理を指定します。

価値 意味
FILE_SUPERSEDE
 ファイルが既に存在する場合は、指定されたファイルに置き換えます。 そうでない場合は、指定されたファイルを作成します。
FILE_CREATE
 ファイルが既に存在する場合は、要求を失敗させ、指定されたファイルを作成したり開いたりしないでください。 そうでない場合は、指定されたファイルを作成します。
FILE_OPEN
 ファイルが既に存在する場合は、新しいファイルを作成する代わりに開きます。 そうでない場合は、要求を失敗させ、新しいファイルを作成しません。
FILE_OPEN_IF
 ファイルが既に存在する場合は、ファイルを開きます。 そうでない場合は、指定されたファイルを作成します。
FILE_OVERWRITE
 ファイルが既に存在する場合は、ファイルを開いて上書きします。 そうでない場合は、要求を失敗します。
FILE_OVERWRITE_IF
 ファイルが既に存在する場合は、ファイルを開いて上書きします。 そうでない場合は、指定されたファイルを作成します。

[in] CreateOptions

次のフラグの互換性のある組み合わせとして、ファイルを作成または開くときに適用するオプション。

価値 意味
FILE_DIRECTORY_FILE
 作成または開いているファイルはディレクトリ ファイルです。 このフラグでは、CreateDisposition パラメーターを 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
 ファイルにデータを書き込むアプリケーションは、要求された書き込み操作が完了したと見なされる前に、実際にデータをファイルに転送する必要があります。 このフラグは、CreateOptions フラグ FILE_NO_INTERMEDIATE _BUFFERING が設定されている場合に自動的に設定されます。
FILE_SEQUENTIAL_ONLY
 ファイルへのすべてのアクセスはシーケンシャルです。
FILE_RANDOM_ACCESS
 ファイルへのアクセスはランダムな場合があるため、FSD またはシステムによってファイルに対して順次先読み操作を実行する必要はありません。
FILE_NO_INTERMEDIATE_BUFFERING
 ファイルは、ドライバーの内部バッファーにキャッシュまたはバッファーすることはできません。 このフラグは、DesiredAccessFILE_APPEND_DATA フラグと互換性がありません。
FILE_SYNCHRONOUS_IO_ALERT
 ファイルに対するすべての操作は同期的に実行されます。 呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグを設定する場合は、DesiredAccessSYNCHRONIZE フラグも設定する必要があります。
FILE_SYNCHRONOUS_IO_NONALERT
 ファイルに対するすべての操作は同期的に実行されます。 システムで I/O キューの同期を待機し、完了はアラートの対象になりません。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグを設定する場合は、DesiredAccessSYNCHRONIZE フラグも設定する必要があります。
FILE_CREATE_TREE_CONNECTION
 ネットワーク経由で開くために、このファイルのツリー接続を作成します。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。
FILE_NO_EA_KNOWLEDGE
 開いている既存のファイルの拡張属性が、呼び出し元がファイルを正しく解釈するために EA を理解する必要があることを示している場合、呼び出し元は EA の処理方法を理解していないため、この要求を失敗します。 このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
FILE_OPEN_REPARSE_POINT
 再解析ポイントを使用してファイルを開き、ファイルの通常の再解析ポイント処理をバイパスします。 詳細については、「解説」セクションを参照してください。
FILE_DELETE_ON_CLOSE
 NtCloseに最後のハンドルが渡されたときに、ファイルを削除します。 このフラグが設定されている場合は、DesiredAccess パラメーターで DELETE フラグを設定する必要があります。
FILE_OPEN_BY_FILE_ID
 ObjectAttributes パラメーターで指定されたファイル名には、ファイルの 8 バイトのファイル参照番号が含まれます。 この番号は、特定のファイル システムによって割り当てられ、特定のファイル システムに固有です。 ファイルが再解析ポイントの場合、ファイル名にはデバイスの名前も含まれます。 FAT ファイル システムでは、このフラグはサポートされないことに注意してください。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。
FILE_OPEN_FOR_BACKUP_INTENT
 ファイルがバックアップインテント用に開かれています。 したがって、システムは、ファイルのセキュリティ記述子に対して desiredAccess パラメーター チェックする前に、特定のアクセス権を確認し、呼び出し元にファイルへの適切なアクセス権を付与する必要があります。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。
FILE_RESERVE_OPFILTER
このフラグを使用すると、アプリケーションはフィルターの日和見ロック (oplock) を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。 既に開いているハンドルがある場合、作成要求は STATUS_OPLOCK_NOT_GRANTEDで失敗します。 詳細については、「解説」セクションを参照してください。
FILE_OPEN_REQUIRING_OPLOCK
 ファイルが開き、ファイルの日和見ロック (oplock) が 1 つのアトミック操作として要求されています。 ファイル システムは、作成操作を実行する前に oplock をチェックし、結果が既存の oplock を中断する場合は、STATUS_CANNOT_BREAK_OPLOCK のリターン コードで作成に失敗します。 詳細については、「解説」セクションを参照してください。Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: このフラグはサポートされていません。

このフラグは、NTFS、FAT、exFAT のファイル システムでサポートされています。
FILE_COMPLETE_IF_OPLOCKED
 呼び出し元のスレッドをブロックするのではなく、ターゲット ファイルが操作されている場合は、STATUS_OPLOCK_BREAK_IN_PROGRESS の代替成功コードを使用して、この操作をすぐに完了します。 ファイルが oplocked場合、別の呼び出し元は既にファイルにアクセスできます。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。

[in] EaBuffer

拡張属性を渡すために使用される EA バッファーへのポインター。

注 一部のファイル システムでは EA バッファーがサポートされない場合があります。
 

[in] EaLength

EA バッファーの長さ。

戻り値

NtCreateFile は、STATUS_SUCCESS または適切なエラー状態を返します。 エラー状態が返された場合、呼び出し元は IoStatusBlockを確認することで、エラーの原因に関する詳細情報を見つけることができます。 このチェックを簡略化するために、アプリケーションでは、NT_SUCCESS、NT_ERROR、および NT_WARNING マクロを使用できます。

備考

NtCreateFileによって指定されたハンドルは、後続の呼び出しでファイル内のデータまたはファイル オブジェクトの状態または属性を操作するために使用できます。

NtCreateFileを使用して作成または開くファイルの名前 指定するには、次の 2 つの方法があります。

  • 完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。
  • 入力 ObjectAttributes の RootDirectory メンバー内のハンドルによって表されるディレクトリ ファイルに対する相対パス名として
特定の DesiredAccess フラグとフラグの組み合わせには、次の効果があります。
  • 呼び出し元が返された FileHandleを待機して I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。
  • DesiredFlags に 0 を渡すことは無効です。
  • FILE_APPEND_DATA と SYNCHRONIZE フラグのみが設定されている場合、呼び出し元はファイルの末尾にのみ書き込むことができます。ファイルへの書き込みに関するオフセット情報は無視されます。 ただし、この種類の書き込み操作では、必要に応じてファイルが自動的に拡張されます。
  • ファイルの FILE_WRITE_DATA フラグを設定すると、ファイルの末尾を超える書き込みも行われます。 ファイルは、この種類の書き込み用にも自動的に拡張されます。
  • FILE_EXECUTE と SYNCHRONIZE フラグのみが設定されている場合、呼び出し元は、返された FileHandleを使用してファイル内のデータを直接読み書きすることはできません。つまり、命令とデータ アクセスに応答して、ファイルに対するすべての操作がシステム ページャーを介して実行されます。
ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。 指定した方法でファイルにアクセスする権限を両方のファイルオーナーに付与すれば、ファイルを正常に開いて共有できます。 NtCreateFile の元の呼び出し元が FILE_SHARE_READ、FILE_SHARE_WRITE、または FILE_SHARE_DELETEを指定していない場合は、ファイルに対して他の開いている操作を実行できません。つまり、元の呼び出し元には、ファイルへの排他的アクセス権が付与されます。

共有ファイルを正常に開くには、ファイルに対して要求された DesiredAccess パラメーターが、の DesiredAccessと、NtCloseでまだリリースされていない前述のすべてのオープンの ShareAccess 仕様の両方と互換性がある必要があります。 つまり、特定のファイルの NtCreateFile を するために指定された DesiredAccess パラメーターは、ファイルの他のオープナーが許可していないアクセスと競合してはなりません。

CreateDisposition 値 FILE_SUPERSEDE、呼び出し元が既存のファイル オブジェクトに対する DELETE アクセス 必要があります。 その場合、既存のファイルの FILE_SUPERSEDE を使用して NtCreateFile を 正常に呼び出すと、そのファイルが実質的に削除され、再作成されます。 これは、ファイルが既に別のスレッドによって開かれている場合は、FILE_SHARE_DELETE フラグを設定して ShareAccess パラメーターを指定してファイルを開くことを意味します。 この種類の処理は、ファイルを上書きする POSIX スタイルと一致することに注意してください。 CreateDisposition の値 FILE_OVERWRITE_IF と FILE_SUPERSEDE は似ています。 ZwCreateFile が既存のファイルで呼び出され、これらの CreateDisposition 値のいずれかで呼び出された場合、ファイルは置き換えられます。

ファイルの上書きは、次を除き、置き換え操作と意味的に同等です。

  • 呼び出し元は、削除アクセスではなく、ファイルへの書き込みアクセス権を持っている必要があります。 これは、ファイルが既に別のスレッドによって開かれている場合、ShareAccess パラメーターの入力 FILE_SHARE_WRITE フラグを設定してファイルを開くことを意味します。
  • 指定されたファイル属性は、論理的には ORed であり、ファイルに既に存在します。 これは、ファイルが既に別のスレッドによって開かれている場合、NtCreateFile の後続の呼び出し元は、既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。 このファイルの上書きスタイルは、MS-DOS、Windows 3.1、OS/2 オペレーティング システムと一致することに注意してください。
CreateOptionsFILE_DIRECTORY_FILE 値は、作成または開くファイルがディレクトリ ファイルであることを指定します。 ディレクトリ ファイルが作成されると、ファイル システムはディスク上に適切な構造を作成し、その特定のファイル システムのディスク上構造の空のディレクトリを表します。 このオプションが指定されていて、開く指定されたファイルがディレクトリ ファイルでない場合、または呼び出し元が CreateOptions または CreateDisposition 値 不整合 指定した場合、NtCreateFile の呼び出しは失敗します。

CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING フラグを指定すると、ファイル システムは呼び出し元に代わって中間バッファリングを実行できなくなります。 この値を指定すると、呼び出し元のパラメーターが、次のような他の NtXXXFile ルーチンに制限されます。

  • オプションの ByteOffset、NtReadFile または ntWriteFile 関数 に渡される場合は、セクター サイズの整数である必要があります。
  • NtReadFile または ntWriteFileに渡される 長 は、セクター サイズの整数である必要があります。 長さがセクター サイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有効バイト数が少なくなる可能性があることに注意してください。
  • バッファーは、基になるデバイスの配置要件に従って調整する必要があります。 この情報を取得するには、NtCreateFile を呼び出して、物理デバイスを表すファイル オブジェクトのハンドルを取得し、そのハンドルで NtQueryInformationFile を呼び出します。 XXX_ALIGNMENT 値 FILE_システムの一覧については、Windows SDK のドキュメントを参照してください。
  • FileInformationClass パラメーターを filePositionInformation に設定して ntSetInformationFile を する呼び出しでは、セクター サイズの整数であるオフセットを指定する必要があります。
CreateOptionsFILE_SYNCHRONOUS_IO_ALERT フラグと FILE_SYNCHRONOUS_IO_NONALERT フラグは、名前が示すとおりに相互に排他的であり、返された FileHandleによって参照されるファイル オブジェクトを介して行われる限り、ファイルに対するすべての I/O 操作が同期的であることを指定します。 このようなファイルのすべての I/O は、返されたハンドルを使用して、すべてのスレッドでシリアル化されます。 これらの CreateOptionsでは、I/O マネージャーがファイル オブジェクトを同期オブジェクトとして使用するように、DesiredAccessSYNCHRONIZE フラグを設定する必要があります。 これらの CreateOptions セットでは、I/O マネージャーは、ファイル オブジェクトの "ファイル位置コンテキスト" (内部の現在のファイル位置オフセット) を維持します。 このオフセットは、NtReadFile を し、NtWriteFileを する呼び出しで使用できます。 その位置は、NtQueryInformationFile および NtSetInformationFileを使用してクエリまたは設定することもできます。

CreateOptions パラメーターが FILE_OPEN_REPARSE_POINT フラグを指定し、NtCreateFile が再解析ポイントを持つファイルを開く 場合、通常の再解析処理は行われず、NtCreateFile は再解析ポイント ファイルを直接開こうとします。 FILE_OPEN_REPARSE_POINT フラグが指定されていない場合は、ファイルに対して通常の再解析ポイント処理が行われます。 いずれの場合も、開いている操作が成功した場合、NtCreateFile は STATUS_SUCCESSを返します。それ以外の場合はエラー コード。 NtCreateFile 関数は、STATUS_REPARSEを返しません。

CreateOptions パラメーターの FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開くことができる可能性がある oplock を要求してから、共有違反が発生する可能性がある時間が短縮されます。 アプリケーションは、ntCreateFile FILE_OPEN_REQUIRING_OPLOCK フラグを使用して、任意の oplock を要求できます。 これにより、共有違反の原因となる後続のオープン要求が oplock 所有者に通知されます。

Windows 7 では、アプリケーションがこのフラグを使用するときにファイルに他のハンドルが存在する場合、作成操作は 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 以降のオペレーティング システムで使用できます:NTFS、FAT、exFAT。
 

CreateOptions パラメーターの FILE_RESERVE_OPFILTER フラグを使用すると、アプリケーションはレベル 1、バッチ、またはフィルター 操作を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。 ただし、実際的には、FILE_RESERVE_OPFILTER はフィルター 操作に対してのみ役立ちます。 これを使用するには、次の手順を実行する必要があります。

  1. CreateOptions FILE_RESERVE_OPFILTER、DesiredAccess の正確な FILE_READ_ATTRIBUTES、および正確に の ShareAccess を して作成要求を発行します。 考えられるエラーは次のとおりです。
    • 既に開いているハンドルがある場合、作成要求は STATUS_OPLOCK_NOT_GRANTEDで失敗し、次に要求された oplock も失敗します。
    • FILE_READ_ATTRIBUTES より多くのアクセス権を持つか、(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)よりも少ない共有で開くと、要求は STATUS_OPLOCK_NOT_GRANTEDで失敗します。
  2. 作成要求が成功した場合は、oplock を要求します。
  3. ファイルへの別のハンドルを開いて I/O を実行します。
手順 3 では、これはフィルター 操作ロックに対してのみ実用的です。 手順 3 で開いたハンドルには、最大 (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) を含み、フィルター 操作を中断しない DesiredAccess を含めることができます。 ただし、DesiredAccess より大きい場合は、レベル 1 または Batch のオペロックが解除され、FILE_RESERVE_OPFILTER フラグはそれらの oplock 型では使用できなくなります。

NTFS は、FILE_RESERVE_OPFILTERを実装する唯一の Microsoft ファイル システムです。

oplock の詳細については、「Oplock Semantics」を参照してください。

WDK ヘッダー ファイル NtDef.h は、多くの定数定義と、InitializeObjectAttributes マクロに必要であることに注意してください。 LoadLibrary と GetProcAddress 関数を して、NtDll.dllに動的にリンクすることもできます。

必要条件

要件 価値
ターゲット プラットフォーム の ウィンドウズ
ヘッダー winternl.h
ライブラリ ntdll.lib
DLL ntdll.dll