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：：stream 名稱，其中 實體記錄檔名稱是保存 數據流記錄之實體記錄的路徑名稱，而 數據流名稱 是) 共用 (或將共用該實體記錄的數據流名稱。

如果您想要建立目前沒有數據流的多任務記錄檔，請使用表單 log：physical log name：：，其中 實體記錄檔名稱 是基礎文件系統上要建立之實體記錄檔的路徑名稱。

下列清單提供一些有效名稱的範例。

  • “Log：c：\myLog” 會建立或開啟專用記錄及其一個數據流。
  • “Log：c：\myCommonLog：：” 會建立尚未有任何數據流的多任務記錄檔。
  • “Log：c：\myCommonLog：：Stream1” 會建立或開啟多任務記錄 (Stream1) 其中一個數據流。

[in] fDesiredAccess

提供用戶端存取類型的 ACCESS_MASK ，會使用 pplfoLog) 中傳回的指標 (至數據流。 如果此參數為零，用戶端可以查詢數據流中的屬性，但無法讀取或寫入數據流。 此參數可以是零或下列旗標的任何組合：

旗標 意義
GENERIC_READ 用戶端具有數據流的讀取許可權。
GENERIC_WRITE 用戶端具有數據流的寫入許可權。
DELETE 用戶端可以將數據流標示為要刪除。

[in] dwShareMode

數據流的共用模式，可以是零 (不共用) 或下列任何旗標的組合：

旗標 意義
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

一組旗標，指定要在建立或開啟數據流時套用的選項。 此參數可以是零或下列旗標的兼容組合：

旗標 意義
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 和建立元件具有標準、一般關聯性。 核心模式元件會使用此值，除非它們屬於此表格中所列的三個其他類別之一。 如果 pvContext 不是 NULL，CLFS 會確認 cbContext 大於零。 否則會忽略 pvContext 和 cbContext 。
CLFS_FLAG_REENTRANT_FILE_SYSTEM 建立元件是提供 CLFS 基礎記憶體的檔案系統。 CLFS 會使用檔案系統來配置容器，而文件系統則使用CLFS資料流。 在此情況下，文件系統可以呼叫CLFS，並讓CLFS在相同線程或不同線程上對文件系統進行回呼。 如果 pvContext 不是 NULL，CLFS 會確認 cbContext 大於零。 否則會忽略 pvContext 和 cbContext 。
CLFS_FLAG_NON_REENTRANT_FILTER 建立元件是文件系統篩選驅動程式，會將其所有CLFS I/O傳送至篩選堆疊上本身下方的指定層級。 此選項可讓篩選驅動程式建立CLFS記錄檔，而不會看到自己的記錄I/O。 呼叫端會在 pvContext 參數中傳遞非 NULL 目標裝置物件，並將 cbContext 設定為適當的大小。 CLFS 會使用 IoCreateFileSpecifyDeviceObjectHint 例程，在裝置物件所指定的 I/O 篩選堆疊中，於目標層級建立容器。
CLFS_FLAG_REENTRANT_FILTER 建立元件是文件系統篩選驅動程式，會將其所有CLFS I/O傳送至篩選堆疊頂端。 篩選條件與 CLFS 具有遞歸關聯性，因為它會在 CLFS 在其容器上執行任何文件系統作業時篩選自己的記錄 I/O。 pvContext 參數提供一種方法，讓篩選條件將可辨識的內容與其 CLFS 容器產生關聯，因為記錄 I/O 會關閉篩選堆棧。 cbContext 參數會以位元組為單位指定不透明內容的大小。
CLFS_FLAG_MINIFILTER_LEVEL 建立元件是文件系統迷你篩選驅動程式，會將其所有CLFS I/O傳送至篩選堆疊上本身下方的指定層級。 此選項可讓迷你篩選建立CLFS記錄檔，而不會看到自己的記錄I/O。 呼叫端會將 pvContext 參數中的非 NULL 迷你篩選內容對象傳遞給適當的大小。 CLFS 會使用 IoCreateFileSpecifyDeviceObjectHint 例程，在篩選管理員的迷你篩選堆疊) 指定的高度 (建立容器。

[in, optional] pvContext

內容的指標。 內容解譯的方式取決於傳遞至 fLogOptionsFlag 的值。

[in] cbContext

pvContext 所指向內容的大小，以位元組為單位。 如果 pvContext 不是 NULL，此參數必須大於零。

傳回值

ClfsCreateLogFile 如果成功，則會傳回STATUS_SUCCESS;否則，它會傳回 Ntstatus.h 中定義的其中一個錯誤碼。

備註

當您建立 CLFS 數據流時，它會受到基礎實體 CLFS 記錄的支援。 基礎記錄可以是專用 (只支援一個數據流) ，或多任務處理 (傳回數個數據流) 。 專用記錄無法轉換成多任務記錄，且多任務記錄無法轉換成專用記錄。

實體 CLFS 記錄名稱不包含 .blf 擴展名。

如需CLFS概念和術語的說明，請參閱 一般記錄檔系統。

規格需求

需求 值
最低支援的用戶端 可在 Windows Server 2003 R2、Windows Vista 和更新版本的 Windows 中使用。
目標平台 桌面
標頭 wdm.h (包含 Wdm.h)
程式庫 Clfs.lib
Dll Clfs.sys
IRQL <= APC_LEVEL

另請參閱

ClfsCloseAndResetLogFile

ClfsCloseLogFileObject

ClfsDeleteLogByPointer

ClfsDeleteLogFile