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 フラグのセットによって、ファイル オブジェクトに対する次の特定のアクセス権が決まります。

IoCreateFileSpecifyDeviceObjectHint の呼び出し元は、ディレクトリ ファイルを表さないファイル オブジェクトに対して、DesiredAccess フラグの前の一覧から互換性のあるフラグを追加する可能性がある次の 1 つまたは組み合わせを指定できます。

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

FILE_DIRECTORY_FILE CreateOptions フラグが設定されている場合、 IoCreateFileSpecifyDeviceObjectHint の呼び出し元は、次の 1 つまたは複数の組み合わせを指定できます。この場合は、DesiredAccess フラグの前のリストから 1 つ以上の互換性のあるフラグを持つ ORed を指定できます。

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構造体のメンバーには、次のようなものがあります。

[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 フラグとして使用できるフラグは次のとおりです。

[in] ShareAccess

呼び出し元が必要とするファイルへの共有アクセスの種類を 0 または 1、または次のフラグの組み合わせとして指定します。 排他アクセスを要求するには、このパラメーターを 0 に設定します。 IO_IGNORE_SHARE_ACCESS_CHECK フラグが Options パラメーターで指定されている場合、I/O マネージャーはこのパラメーターを無視します。 ただし、ファイル システムは引き続きアクセス チェックを実行する可能性があります。 したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、このパラメーターに使用する共有モードを指定することが重要です。 共有違反エラーを回避する可能性が最も高い場合は、次のすべての共有アクセス フラグを指定します。

[in] Disposition

ファイルが既に存在するかどうかに応じて、実行するアクションを決定する値を指定します。 値には、次に説明するもののいずれかを指定できます。

[in] CreateOptions

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

[in, optional] EaBuffer

ファイルに適用される拡張属性 (EA) 情報を含む、呼び出し元が指定した FILE_FULL_EA_INFORMATION構造化バッファーへのポインター。

[in] EaLength

EaBuffer の長さ (バイト単位)。

[in] CreateFileType

ドライバーは、このパラメーターを CreateFileTypeNone に設定する必要があります。

[in, optional] InternalParameters

ドライバーは、このパラメーターを NULL に設定する必要があります。

[in] Options

作成要求の作成時に使用するオプションを指定します。 利用可能なオプションの一覧を次の表に示します。

[in, optional] DeviceObject

作成要求の送信先となるデバイス オブジェクトへのポインター。 デバイス オブジェクトは、ファイルまたはディレクトリが存在するボリュームのファイル システム ドライバー スタック内のフィルターまたはファイル システム デバイス オブジェクトである必要があります。 このパラメーターは省略可能であり、 NULL にすることができます。 このパラメーターが NULL の場合、要求はドライバー スタックの上部にあるデバイス オブジェクトに送信されます。

戻り値

IoCreateFileSpecifyDeviceObjectHint は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

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 つの代替方法があります。

1. 完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。

2. 入力 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は、フィルター 操作ロックに対してのみ実用的に役立ちます。 これを使用するには、次の手順を実行する必要があります。

1. 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のエラーも発生します。

2. 作成要求が成功した場合は、oplock を要求します。

3. ファイルの別のハンドルを開いて 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が返されます。

要件

こちらもご覧ください

ACCESS_MASK

ACL

FILE_FULL_EA_INFORMATION

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoCheckEaBufferValidity

IoCreateFile

IoCreateFileEx

UNICODE_STRING

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile