pdhOpenLogA 函式 (pdh.h)
開啟指定的記錄檔以供讀取或寫入。
語法
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
用來開啟記錄檔的存取類型。 指定下列其中一個值。
值 | 意義 |
---|---|
|
開啟記錄檔以供讀取。 |
|
開啟要寫入的新記錄檔。 |
|
開啟現有的記錄檔以供寫入。 |
您可以使用位包含 OR 運算子 (|) 結合存取類型與下列一或多個建立旗標。
值 | 意義 |
---|---|
|
使用指定的名稱建立新的記錄檔。 |
|
使用指定的名稱建立新的記錄檔。 如果記錄檔已經存在,此函式會在建立新檔案之前移除現有的記錄檔。 |
|
開啟具有指定名稱的現有記錄檔。 如果具有指定名稱的記錄檔不存在,這等於PDH_LOG_CREATE_NEW。 |
|
開啟具有指定名稱的現有記錄檔,或使用指定的名稱建立新的記錄檔。 |
|
建立具有指定名稱的循環記錄檔。 當檔案到達 dwMaxSize 參數的值時,數據會換行到記錄檔的開頭。 只有當 lpdwLogType 參數 PDH_LOG_TYPE_BINARY時,才可以指定這個旗標。 |
|
與 PDH_LOG_TYPE_TSV 搭配使用,以寫入 PdhUpdateLog 或 PdhOpenLog之 szUserString 參數所指示的使用者 標題 或記錄檔描述。 使用者 標題 或記錄檔描述會寫入為文字記錄第一行的最後一欄。 |
[in] lpdwLogType
要開啟的記錄檔類型。 此參數可以是下列其中一個值。
[in] hQuery
如果您要將查詢數據寫入記錄檔,請指定查詢句柄。 PdhOpenQuery 函式會傳回這個句柄。
如果您從記錄檔讀取,則會忽略此參數,而且應該是 NULL 。
[in] dwMaxSize
記錄檔的大小上限,以位元組為單位。 如果您想要限制檔案大小,或 dwAccessFlags 指定 PDH_LOG_OPT_CIRCULAR,請指定大小上限;否則,請將 設定為 0。
針對循環記錄檔,您必須指定足以保存至少一個樣本的值。 樣本大小取決於所收集的數據。 不過,指定至少一 MB 的值將涵蓋大部分的樣本。
[in] szUserCaption
以 Null 結尾的字串,指定記錄檔的使用者定義 標題。 記錄檔 標題 通常描述記錄檔的內容。 開啟現有的記錄檔時,會忽略此參數的值。
[out] phLog
已開啟之記錄檔的句柄。
傳回值
如果函式成功,則會傳回ERROR_SUCCESS。
備註
若要使用此函式將效能數據寫入記錄檔,您必須先使用 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 |