Opens the specified log file for reading or writing.
PDH_FUNCTION PdhOpenLogA( LPCSTR szLogFileName, DWORD dwAccessFlags, LPDWORD lpdwLogType, PDH_HQUERY hQuery, DWORD dwMaxSize, LPCSTR szUserCaption, PDH_HLOG *phLog );
Null-terminated string that specifies the name of the log file to open. The name can contain an absolute or relative path.
If the lpdwLogType parameter is PDH_LOG_TYPE_SQL, specify the name of the log file in the form, SQL:DataSourceName!LogFileName.
Type of access to use to open the log file. Specify one of the following values.
||Open the log file for reading.|
||Open a new log file for writing.|
||Open an existing log file for writing.|
You can use the bitwise inclusive OR operator (|) to combine the access type with one or more of the following creation flags.
||Creates a new log file with the specified name.|
||Creates a new log file with the specified name. If the log file already exists, the function removes the existing log file before creating the new file.|
||Opens an existing log file with the specified name. If a log file with the specified name does not exist, this is equal to PDH_LOG_CREATE_NEW.|
||Opens an existing log file with the specified name or creates a new log file with the specified name.|
||Creates a circular log file with the specified name. When the file reaches the value of the dwMaxSize parameter, data wraps to the beginning of the log file. You can specify this flag only if the lpdwLogType parameter is PDH_LOG_TYPE_BINARY.|
||Used with PDH_LOG_TYPE_TSV to write the user caption or log file description indicated by the szUserString parameter of PdhUpdateLog or PdhOpenLog. The user caption or log file description is written as the last column in the first line of the text log.|
Type of log file to open. This parameter can be one of the following values.
Specify a query handle if you are writing query data to a log file. The PdhOpenQuery function returns this handle.
This parameter is ignored and should be NULL if you are reading from the log file.
Maximum size of the log file, in bytes. Specify the maximum size if you want to limit the file size or if dwAccessFlags specifies PDH_LOG_OPT_CIRCULAR; otherwise, set to 0.
For circular log files, you must specify a value large enough to hold at least one sample. Sample size depends on data being collected. However, specifying a value of at least one megabyte will cover most samples.
Null-terminated string that specifies the user-defined caption of the log file. A log file caption generally describes the contents of the log file. When an existing log file is opened, the value of this parameter is ignored.
Handle to the opened log file.
If the function succeeds, it returns ERROR_SUCCESS.
To use this function to write performance data to a log file, you must open a query using PdhOpenQuery and add the desired counters to it, before calling this function.
Newer operating systems can read log files that were generated on older operating systems; however, log files that were created on Windows Vista and later operating systems cannot be read on earlier operating systems.
The following rules apply to log files
READ_ACCESS requires OPEN_EXISTING.
UPDATE_ACCESS cannot be used with file-based logs. It can only be used with database logs.
WRITE_ACCESS requires one of CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS.
For an example, see Writing Performance Data to a Log File.
|Minimum supported client||Windows XP [desktop apps only]|
|Minimum supported server||Windows Server 2003 [desktop apps only]|