CreateLogFile 函式（clfsw32.h）

發行項
11/20/2024

建立或開啟記錄檔。記錄可以是專用或多任務處理，而這取決於記錄檔名稱。使用 CloseHandle 函式來關閉記錄檔。

語法

CLFSUSER_API HANDLE CreateLogFile(
  [in]           LPCWSTR               pszLogFileName,
  [in]           ACCESS_MASK           fDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES psaLogFile,
  [in]           ULONG                 fCreateDisposition,
  [in]           ULONG                 fFlagsAndAttributes
);

參數

[in] pszLogFileName

記錄檔的名稱。

使用 createLogFile 建立記錄檔時，會指定這個名稱。下列範例會識別要使用的格式。

記錄檔：<LogName>[：：<LogStreamName>]

例如：路徑 “LOG：c：\MyDirectory\MyLog” 會建立 “c：\MyDirectory\MyLog.blf” 檔案。路徑 “？？\LOG：\HarddiskVolume1\MyDirectory\MyLog“ 會建立檔案 ”\.\HarddiskVolume1\MyDirectory\MyLog.blf“，路徑 ”\clfs\Device\HarddiskVolume1\MyDirectory\MyLog“。

< LogName> 會對應至文件系統中的有效檔案路徑，<LogStreamName> 是記錄檔中記錄數據流的唯一名稱。如需詳細資訊，請參閱記錄類型。

[in] fDesiredAccess

傳回句柄對記錄物件的存取類型。

價值	意義
GENERIC_READ	指定物件的讀取許可權。
GENERIC_WRITE	指定物件的寫入許可權。
DELETE	指定記錄刪除存取

這些旗標的兩個或多個位 OR 允許讀取、寫入和刪除物件的存取權組合。

注意您必須指定 DELETE 存取權，才能刪除記錄。

Windows Server 2003 R2：此參數必須設定為 GENERIC_WRITE。

[in] dwShareMode

檔案的共用模式。

客戶端無法要求與任何先前開啟要求中指定且具有開啟句柄之模式衝突的共用模式。

如果此參數為零且函式成功，則對象無法共用，而且在句柄關閉之前無法再次開啟。

此參數可以是下列其中一或多個值。

價值	意義
FILE_SHARE_DELETE	在物件上啟用開啟作業，以要求刪除存取權。如果沒有此值，如果要求刪除存取權，其他進程就無法開啟物件。
FILE_SHARE_READ	在物件上啟用開啟作業，以要求讀取存取權。如果沒有這個值，如果要求讀取存取權，其他進程就無法開啟物件。
FILE_SHARE_WRITE	在物件上啟用開啟作業，以要求寫入存取權。如果沒有此值，如果要求寫入存取權，其他進程就無法開啟物件。

[in, optional] psaLogFile

指定記錄檔安全性屬性之 SECURITY_ATTRIBUTES 結構的指標。

它會判斷傳回的句柄是否可以由子進程繼承。如果此參數 NULL，則無法繼承句柄。

SECURITY_ATTRIBUTES 的 lpSecurityDescriptor 成員會為新的記錄句柄指定安全性描述元。如果 psaLogFileNULL，則物件會取得預設的安全性描述元。記錄的預設安全性描述元中的訪問控制清單（ACL）來自建立者的主要或模擬令牌。

[in] fCreateDisposition

要採取的動作。

此參數可以是下列其中一個值。

價值	意義
CREATE_NEW	建立新的檔案，如果檔案已經存在，就會失敗。
OPEN_EXISTING	開啟現有的檔案，如果檔案不存在，就會失敗。
OPEN_ALWAYS	開啟現有的檔案，如果檔案不存在，則建立檔案。

[in] fFlagsAndAttributes

檔案的檔案屬性和旗標。

此參數可以採用下列值。

價值	意義
FILE_ATTRIBUTE_ARCHIVE	此非暫時記錄應該封存。如果未提供此旗標，則不需要封存記錄，而且不會維護封存尾以回收記錄容器。
FILE_FLAG_OVERLAPPED	如果已設定 FILE_FLAG_OVERLAPPED 旗標，則會忽略所有其他旗標值。指定 FILE_FLAG_OVERLAPPED 表示檔案會針對重疊的 I/O 開啟，這可讓記錄句柄上執行多個 I/O 作業。如果在建立記錄檔時設定此旗標，該記錄的所有異步 I/O 呼叫都必須指定重疊的結構，並與呼叫的延遲完成同步處理。

傳回值

如果函式成功，傳回值就是記錄檔的句柄。

如果函式失敗，傳回值會 INVALID_HANDLE_VALUE。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

下列清單會識別可能的錯誤碼：

要求

要求	價值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 R2 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	clfsw32.h
連結庫	Clfsw32.lib
DLL	Clfsw32.dll