ClfsCreateLogFile 関数 (wdm.h)
ClfsCreateLogFile ルーチンは、CLFS ストリームを作成または開きます。 必要に応じて、 ClfsCreateLogFile は、ストリームのレコードを保持する基になる物理ログも作成します。
構文
CLFSUSER_API NTSTATUS ClfsCreateLogFile(
[out] PPLOG_FILE_OBJECT pplfoLog,
[in] PUNICODE_STRING puszLogFileName,
[in] ACCESS_MASK fDesiredAccess,
[in] ULONG dwShareMode,
[in, optional] PSECURITY_DESCRIPTOR psdLogFile,
[in] ULONG fCreateDisposition,
[in] ULONG fCreateOptions,
[in] ULONG fFlagsAndAttributes,
[in] ULONG fLogOptionFlag,
[in, optional] PVOID pvContext,
[in] ULONG cbContext
);
パラメーター
[out] pplfoLog
ストリームの開いているインスタンスを表す LOG_FILE_OBJECT 構造体へのポインターを受け取る変数へのポインター。
[in] puszLogFileName
ストリームまたは基になる物理ログの名前を提供する UNICODE_STRING 構造体へのポインター。
ストリームが既に存在し、専用ログの唯一のストリームである場合、名前の形式は log:physical log name です。 ここで、物理ログ名 は、ストリームのレコードを含む既存の物理ログのパス名 (基になるファイル システム上) です。
ストリームがまだ存在せず、(まだ存在しない) 専用ログの唯一のストリームになる場合、名前には log:physical log name という形式があります。 ここで、物理ログ名 は、ストリームのレコードを保持するために作成される物理ログの、基になるファイル システム上のパス名です。
ストリームが多重化されたログのストリームの 1 つである (またはになる) 場合、名前の形式は log:physical log name::stream name です。 ここで、物理ログ名 は、基になるファイル システム上の、ストリームのレコードを保持する物理ログのパス名であり、 ストリーム名 はその物理ログを共有する (または共有する) ストリームの名前です。
ストリームがない多重化ログを作成する場合は、log:physical log name::という形式の名前を使用します。 ここで、物理ログ名 は、作成する物理ログの、基になるファイル システム上のパス名です。
次の一覧では、有効な名前の例をいくつか示します。
- "Log:c:\myLog" は、専用ログとその 1 つのストリームを作成または開きます。
- "Log:c:\myCommonLog::" は、ストリームがまだない多重化されたログを作成します。
- "Log:c:\myCommonLog::Stream1" は、多重化されたログのストリーム (Stream1) の 1 つを作成または開きます。
[in] fDesiredAccess
(pplfoLog で返されるポインターを使用して) クライアントがストリームに持つアクセスの種類を提供するACCESS_MASK。 このパラメーターが 0 の場合、クライアントはストリームに対して属性のクエリを実行できますが、ストリームから読み取ったり、ストリームに書き込んだりすることはできません。 このパラメーターには、0 または次のフラグの任意の組み合わせを指定できます。
| フラグ | 説明 |
|---|---|
| GENERIC_READ | クライアントはストリームへの読み取りアクセス権を持っています。 |
| GENERIC_WRITE | クライアントはストリームへの書き込みアクセス権を持っています。 |
| DELETE | クライアントはストリームに削除のマークを付けることができます。 |
[in] dwShareMode
ストリームの共有モード。0 (共有されていない) または次のフラグの任意の組み合わせにすることができます。
| フラグ | 説明 |
|---|---|
| FILE_SHARE_DELETE | 削除アクセス権を持つストリームを開く後続の要求は成功します。 |
| FILE_SHARE_READ | 読み取りアクセス権を持つストリームを開く後続の要求は成功します。 |
| FILE_SHARE_WRITE | 書き込みアクセス権を持つストリームを開く後続の要求は成功します。 |
[in, optional] psdLogFile
ストリームのセキュリティ属性を提供する SECURITY_DESCRIPTOR 構造体へのポインター。 このパラメーターは、NULL でもかまいません。
[in] fCreateDisposition
ストリームが既に存在するかどうかによって異なる、実行するアクション。 このパラメーターは、次のいずれかの値に設定する必要があります。
| 値 | 意味 |
|---|---|
| CREATE_NEW | ストリームがまだ終了していない場合は、新しいストリームを作成します。 ストリームが既に存在する場合は失敗します。 |
| OPEN_EXISTING | 既存のストリームを開きます。 ストリームがまだ存在しない場合は失敗します。 |
| OPEN_ALWAYS | 既存のストリームを開きます。 まだ存在しない場合は、ストリームを作成します。 |
[in] fCreateOptions
ストリームを作成または開くときに適用するオプションを指定するフラグのセット。 このパラメーターには、0 または次のフラグの互換性のある組み合わせを指定できます。
| フラグ | 説明 |
|---|---|
| FILE_NO_INTERMEDIATE_BUFFERING | ストリームのレコードをドライバーの内部バッファーにキャッシュすることはできません。 |
| FILE_SYNCHRONOUS_IO_ALERT | ストリームに対するすべての操作は同期的に実行されます。 呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。 このフラグが設定されている場合は、FILE_SYNCHRONOUS_IO_NONALERT フラグをクリアする必要があります。 |
| FILE_SYNCHRONOUS_IO_NONALERT | ストリームに対するすべての操作は同期的に実行されます。 I/O キューと完了を同期するシステムでの待機は、アラートの対象になりません。 このフラグが設定されている場合は、FILE_SYNCHRONOUS_IO_ALERT フラグをクリアする必要があります。 |
[in] fFlagsAndAttributes
ストリームを通常のアクセス用または読み取り専用アクセス用に開くかどうかを示す 値です。 このパラメーターは、次のいずれかに設定する必要があります。
FILE_ATTRIBUTE_NORMALまたはFILE_ATTRIBUTE_READONLY。
[in] fLogOptionFlag
CLFS と、ストリームを作成または開くコンポーネントとの関係に関するヒント。 このパラメーターは、次のいずれかの値に設定する必要があります。
| 値 | 意味 |
|---|---|
| CLFS_FLAG_NO_FLAGS | CLFS と作成コンポーネントには、標準の通常のリレーションシップがあります。 カーネル モード コンポーネントは、この表に記載されている他の 3 つのカテゴリのいずれかに分類されない限り、この値を使用します。 pvContext が NULL でない場合、CLFS は cbContext が 0 より大きいことが確認されます。 それ以外の場合、 pvContext と cbContext は無視されます。 |
| CLFS_FLAG_REENTRANT_FILE_SYSTEM | 作成コンポーネントは、CLFS の基になるストレージを提供するファイル システムです。 CLFS はコンテナーの割り当てにファイル システムを使用し、ファイル システムは CLFS ストリームを使用します。 この場合、ファイル・システムが CLFS を呼び出し、CLFS が同じスレッドまたは異なるスレッド上のファイル・システムに呼び出しを戻す可能性があります。 pvContext が NULL でない場合、CLFS は cbContext が 0 より大きいことが確認されます。 それ以外の場合、 pvContext と cbContext は無視されます。 |
| CLFS_FLAG_NON_REENTRANT_FILTER | 作成コンポーネントは、すべての CLFS I/O をフィルター スタック上のそれ自体より下の指定したレベルに送信するファイル システム フィルター ドライバーです。 このオプションを使用すると、フィルター ドライバーは独自のログ I/O を表示せずに CLFS ログを作成できます。 呼び出し元は、cbContext が適切なサイズに設定された pvContext パラメーター内の NULL 以外のターゲット デバイス オブジェクトを渡します。 CLFS は IoCreateFileSpecifyDeviceObjectHint ルーチンを使用して、デバイス オブジェクトによって指定された I/O フィルター スタック内のターゲット レベルでコンテナーを作成します。 |
| CLFS_FLAG_REENTRANT_FILTER | 作成コンポーネントは、すべての CLFS I/O をフィルター スタックの先頭に送信するファイル システム フィルター ドライバーです。 CLFS は、CLFS がコンテナーに対してファイル システム操作を実行するときに独自のログ I/O をフィルター処理するため、CLFS との再帰的な関係があります。 pvContext パラメーターは、ログ I/O がフィルター スタックの下に来ると、認識可能なコンテキストを CLFS コンテナーに関連付けるフィルターの手段を提供します。 cbContext パラメーターは、不透明なコンテキストのサイズをバイト単位で指定します。 |
| CLFS_FLAG_MINIFILTER_LEVEL | 作成コンポーネントは、すべての CLFS I/O をフィルター スタック上のそれ自体より下の指定したレベルに送信するファイル システム ミニフィルター ドライバーです。 このオプションを使用すると、ミニフィルターは、独自のログ記録 I/O を表示せずに CLFS ログを作成できます。 呼び出し元は、cbContext が適切なサイズに設定された pvContext パラメーター内の NULL 以外のミニフィルター コンテキスト オブジェクトを渡します。 CLFS は IoCreateFileSpecifyDeviceObjectHint ルーチンを使用して、フィルター マネージャーのミニフィルター スタック内の高度 (ミニフィルター コンテキスト内で指定) にコンテナーを作成します。 |
[in, optional] pvContext
コンテキストへのポインター。 コンテキストの解釈方法は、 fLogOptionsFlag に渡される値によって異なります。
[in] cbContext
pvContext が指すコンテキストのサイズ (バイト単位)。 pvContext が NULL でない場合、このパラメーターは 0 より大きくする必要があります。
戻り値
ClfsCreateLogFile は 、成功した場合STATUS_SUCCESSを返します。それ以外の場合は、Ntstatus.h で定義されているエラー コードのいずれかを返します。
注釈
CLFS ストリームを作成すると、基になる物理 CLFS ログによってサポートされます。 基になるログは、専用 (1 つのストリームのみをバック) または多重化 (複数のストリームをバック) にすることができます。 専用ログは多重化ログに変換できず、多重化ログは専用ログに変換できません。
物理 CLFS ログ名には、.blf 拡張子は含まれません。
CLFS の概念と用語の詳細については、「 共通ログ ファイル システム」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Server 2003 R2、Windows Vista、およびそれ以降のバージョンの Windows で使用できます。 |
| 対象プラットフォーム | デスクトップ |
| Header | wdm.h (Wdm.h を含む) |
| Library | Clfs.lib |
| [DLL] | Clfs.sys |
| IRQL | <= APC_LEVEL |