Función PdhOpenLogA (pdh.h)

Artículo
03/13/2024

Abre el archivo de registro especificado para leer o escribir.

Sintaxis

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
);

Parámetros

[in] szLogFileName

Cadena terminada en NULL que especifica el nombre del archivo de registro que se va a abrir. El nombre puede contener una ruta de acceso absoluta o relativa.

Si el parámetro lpdwLogType es PDH_LOG_TYPE_SQL, especifique el nombre del archivo de registro con el formato SQL:DataSourceName.LogFileName.

[in] dwAccessFlags

Tipo de acceso que se va a usar para abrir el archivo de registro. Especifique uno de los valores siguientes.

Valor	Significado
PDH_LOG_READ_ACCESS	Abra el archivo de registro para su lectura.
PDH_LOG_WRITE_ACCESS	Abra un nuevo archivo de registro para escribirlo.
PDH_LOG_UPDATE_ACCESS	Abra un archivo de registro existente para escribirlo.

Puede usar el operador OR inclusivo bit a bit (|) para combinar el tipo de acceso con una o varias de las marcas de creación siguientes.

Valor	Significado
PDH_LOG_CREATE_NEW	Crea un nuevo archivo de registro con el nombre especificado.
PDH_LOG_CREATE_ALWAYS	Crea un nuevo archivo de registro con el nombre especificado. Si el archivo de registro ya existe, la función quita el archivo de registro existente antes de crear el nuevo archivo.
PDH_LOG_OPEN_EXISTING	Abre un archivo de registro existente con el nombre especificado. Si no existe un archivo de registro con el nombre especificado, es igual a PDH_LOG_CREATE_NEW.
PDH_LOG_OPEN_ALWAYS	Abre un archivo de registro existente con el nombre especificado o crea un nuevo archivo de registro con el nombre especificado.
PDH_LOG_OPT_CIRCULAR	Crea un archivo de registro circular con el nombre especificado. Cuando el archivo alcanza el valor del parámetro dwMaxSize , los datos se ajustan al principio del archivo de registro. Puede especificar esta marca solo si el parámetro lpdwLogType es PDH_LOG_TYPE_BINARY.
PDH_LOG_USER_STRING	Se usa con PDH_LOG_TYPE_TSV para escribir la descripción del archivo de registro o subtítulo de usuario indicada por el parámetro szUserString de PdhUpdateLog o PdhOpenLog. El usuario subtítulo o la descripción del archivo de registro se escribe como la última columna de la primera línea del registro de texto.

[in] lpdwLogType

Tipo de archivo de registro que se va a abrir. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
PDH_LOG_TYPE_UNDEFINED	Formato de archivo de registro no definido. Si se especifica, PDH determina el tipo de archivo de registro. No se puede especificar este valor si el parámetro dwAccessFlags está PDH_LOG_WRITE_ACCESS.
PDH_LOG_TYPE_CSV	Archivo de texto que contiene encabezados de columna en la primera línea y registros de datos individuales en cada línea posterior. Los campos de cada registro de datos están delimitados por comas. La primera línea también contiene información sobre el formato del archivo, la versión de PDH utilizada para crear el archivo de registro y los nombres y rutas de acceso de cada uno de los contadores.
PDH_LOG_TYPE_SQL	El origen de datos del archivo de registro es una base de datos SQL.
PDH_LOG_TYPE_TSV	Archivo de texto que contiene encabezados de columna en la primera línea y registros de datos individuales en cada línea posterior. Los campos de cada registro de datos están delimitados por tabulaciones. La primera línea también contiene información sobre el formato del archivo, la versión de PDH utilizada para crear el archivo de registro y los nombres y rutas de acceso de cada uno de los contadores.
PDH_LOG_TYPE_BINARY	Formato de archivo de registro binario.

[in] hQuery

Especifique un identificador de consulta si está escribiendo datos de consulta en un archivo de registro. La función PdhOpenQuery devuelve este identificador.

Este parámetro se omite y debe ser NULL si está leyendo desde el archivo de registro.

[in] dwMaxSize

Tamaño máximo del archivo de registro, en bytes. Especifique el tamaño máximo si desea limitar el tamaño del archivo o si dwAccessFlags especifica PDH_LOG_OPT_CIRCULAR; de lo contrario, establezca en 0.

Para los archivos de registro circulares, debe especificar un valor lo suficientemente grande como para contener al menos una muestra. El tamaño de la muestra depende de los datos que se recopilan. Sin embargo, si se especifica un valor de al menos un megabyte, se tratarán la mayoría de las muestras.

[in] szUserCaption

Cadena terminada en NULL que especifica el subtítulo definido por el usuario del archivo de registro. Un archivo de registro subtítulo describe generalmente el contenido del archivo de registro. Cuando se abre un archivo de registro existente, se omite el valor de este parámetro.

[out] phLog

Identificador del archivo de registro abierto.

Valor devuelto

Si la función se realiza correctamente, devuelve ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es un código de error del sistema o un código de error PDH.

Comentarios

Para usar esta función para escribir datos de rendimiento en un archivo de registro, debe abrir una consulta mediante PdhOpenQuery y agregarle los contadores deseados antes de llamar a esta función.

Los sistemas operativos más recientes pueden leer los archivos de registro que se generaron en sistemas operativos más antiguos; sin embargo, los archivos de registro creados en Windows Vista y los sistemas operativos posteriores no se pueden leer en sistemas operativos anteriores.

Las reglas siguientes se aplican a los archivos de registro

READ_ACCESS requiere OPEN_EXISTING.
UPDATE_ACCESS no se puede usar con registros basados en archivos. Solo se puede usar con registros de base de datos.
WRITE_ACCESS requiere uno de CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS.

Ejemplos

Para obtener un ejemplo, consulte Escritura de datos de rendimiento en un archivo de registro.

Nota

El encabezado pdh.h define PdhOpenLog como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	pdh.h
Library	Pdh.lib
Archivo DLL	Pdh.dll