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 参数的值时,数据将换行到日志文件的开头。 仅当PDH_LOG_TYPE_BINARY lpdwLogType 参数时,才能指定此标志。 |
|
与 PDH_LOG_TYPE_TSV 一起使用,以编写由 PdhUpdateLog 或 PdhOpenLog 的 szUserString 参数指示的用户描述文字或日志文件说明。 用户描述文字或日志文件说明将作为文本日志第一行中的最后一列写入。 |
[in] lpdwLogType
要打开的日志文件的类型。 此参数的取值可为下列值之一:
[in] hQuery
如果要将查询数据写入日志文件,请指定查询句柄。 PdhOpenQuery 函数返回此句柄。
如果从日志文件中读取,则此参数将被忽略,并且应为 NULL 。
[in] dwMaxSize
日志文件的最大大小(以字节为单位)。 如果要限制文件大小,或者 dwAccessFlags 指定 PDH_LOG_OPT_CIRCULAR,请指定最大大小;否则,设置为 0。
对于循环日志文件,必须指定一个足够大的值来保存至少一个示例。 样本大小取决于收集的数据。 但是,指定至少一兆字节的值将涵盖大多数样本。
[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 |
Library | Pdh.lib |
DLL | Pdh.dll |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈