PdhOpenLogW 函式 (pdh.h)

  • 發行項

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

語法

PDH_FUNCTION PdhOpenLogW(
  [in]  LPCWSTR    szLogFileName,
  [in]  DWORD      dwAccessFlags,
  [in]  LPDWORD    lpdwLogType,
  [in]  PDH_HQUERY hQuery,
  [in]  DWORD      dwMaxSize,
  [in]  LPCWSTR    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

另請參閱

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog