pdhOpenLogA 函式 (pdh.h)

發行項
03/01/2024

開啟指定的記錄檔以供讀取或寫入。

語法

PDH_FUNCTION PdhOpenLogA(
  [in]  LPCSTR     szLogFileName,
  [in]  DWORD      dwAccessFlags,
  [in]  LPDWORD    lpdwLogType,
  [in]  PDH_HQUERY hQuery,
  [in]  DWORD      dwMaxSize,
  [in]  LPCSTR     szUserCaption,
  [out] PDH_HLOG   *phLog
);

參數

[in] szLogFileName

以 Null 結束的字串，指定要開啟的記錄檔名稱。名稱可以包含絕對或相對路徑。

如果 lpdwLogType 參數PDH_LOG_TYPE_SQL，請以 SQL：DataSourceName 格式指定記錄檔的名稱！LogFileName。

[in] dwAccessFlags

用來開啟記錄檔的存取類型。指定下列其中一個值。

值	意義
PDH_LOG_READ_ACCESS	開啟記錄檔以供讀取。
PDH_LOG_WRITE_ACCESS	開啟要寫入的新記錄檔。
PDH_LOG_UPDATE_ACCESS	開啟現有的記錄檔以供寫入。

您可以使用位包含 OR 運算子 (|) 結合存取類型與下列一或多個建立旗標。

值	意義
PDH_LOG_CREATE_NEW	使用指定的名稱建立新的記錄檔。
PDH_LOG_CREATE_ALWAYS	使用指定的名稱建立新的記錄檔。如果記錄檔已經存在，此函式會在建立新檔案之前移除現有的記錄檔。
PDH_LOG_OPEN_EXISTING	開啟具有指定名稱的現有記錄檔。如果具有指定名稱的記錄檔不存在，這等於PDH_LOG_CREATE_NEW。
PDH_LOG_OPEN_ALWAYS	開啟具有指定名稱的現有記錄檔，或使用指定的名稱建立新的記錄檔。
PDH_LOG_OPT_CIRCULAR	建立具有指定名稱的循環記錄檔。當檔案到達 dwMaxSize 參數的值時，數據會換行到記錄檔的開頭。只有當 lpdwLogType 參數 PDH_LOG_TYPE_BINARY時，才可以指定這個旗標。
PDH_LOG_USER_STRING	與 PDH_LOG_TYPE_TSV 搭配使用，以寫入 PdhUpdateLog 或 PdhOpenLog之 szUserString 參數所指示的使用者標題或記錄檔描述。使用者標題或記錄檔描述會寫入為文字記錄第一行的最後一欄。

[in] lpdwLogType

要開啟的記錄檔類型。此參數可以是下列其中一個值。

值	意義
PDH_LOG_TYPE_UNDEFINED	未定義的記錄檔格式。如果指定，PDH 會決定記錄檔類型。如果 dwAccessFlags 參數 PDH_LOG_WRITE_ACCESS，則無法指定此值。
PDH_LOG_TYPE_CSV	文本檔，其中包含第一行中的數據行標頭，以及後續每一行中的個別數據記錄。每個數據記錄的欄位都是以逗號分隔。第一行也包含檔案格式、用來建立記錄檔的 PDH 版本，以及每個計數器的名稱和路徑的相關信息。
PDH_LOG_TYPE_SQL	記錄檔的數據源是 SQL 資料庫。
PDH_LOG_TYPE_TSV	文本檔，其中包含第一行中的數據行標頭，以及後續每一行中的個別數據記錄。每個數據記錄的欄位都是以製表元分隔。第一行也包含檔案格式、用來建立記錄檔的 PDH 版本，以及每個計數器的名稱和路徑的相關信息。
PDH_LOG_TYPE_BINARY	二進位記錄檔格式。

[in] hQuery

如果您要將查詢數據寫入記錄檔，請指定查詢句柄。 PdhOpenQuery 函式會傳回這個句柄。

如果您從記錄檔讀取，則會忽略此參數，而且應該是 NULL 。

[in] dwMaxSize

記錄檔的大小上限，以位元組為單位。如果您想要限制檔案大小，或 dwAccessFlags 指定 PDH_LOG_OPT_CIRCULAR，請指定大小上限;否則，請將設定為 0。

針對循環記錄檔，您必須指定足以保存至少一個樣本的值。樣本大小取決於所收集的數據。不過，指定至少一 MB 的值將涵蓋大部分的樣本。

[in] szUserCaption

以 Null 結尾的字串，指定記錄檔的使用者定義標題。記錄檔標題通常描述記錄檔的內容。開啟現有的記錄檔時，會忽略此參數的值。

[out] phLog

已開啟之記錄檔的句柄。

傳回值

如果函式成功，則會傳回ERROR_SUCCESS。

如果函式失敗，傳回值為系統錯誤碼或 PDH 錯誤碼。

備註

若要使用此函式將效能數據寫入記錄檔，您必須先使用 PdhOpenQuery 開啟查詢，並在呼叫此函式之前新增所需的計數器。

較新的操作系統可以讀取在舊版操作系統上產生的記錄檔;不過，在 Windows Vista 和更新版本的作業系統上建立的記錄檔無法在舊版作業系統上讀取。

下列規則適用於記錄檔

READ_ACCESS需要OPEN_EXISTING。
UPDATE_ACCESS無法與檔案型記錄搭配使用。它只能與資料庫記錄搭配使用。
WRITE_ACCESS需要其中一個CREATE_NEW、CREATE_ALWAYS、OPEN_EXISTING OPEN_ALWAYS。

範例

如需範例，請參閱將效能數據寫入記錄檔。

注意

pdh.h 標頭會將 PdhOpenLog 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	pdh.h
程式庫	Pdh.lib
Dll	Pdh.dll