Función PdhEnumObjectsHA (pdh.h)

  • Artículo

Devuelve una lista de objetos disponibles en el equipo especificado o en el archivo de registro especificado.

Esta función es idéntica a PdhEnumObjects, salvo que admite el uso de identificadores para orígenes de datos.

Sintaxis

PDH_FUNCTION PdhEnumObjectsHA(
  [in]      PDH_HLOG hDataSource,
  [in]      LPCSTR   szMachineName,
  [out]     PZZSTR   mszObjectList,
  [in, out] LPDWORD  pcchBufferSize,
  [in]      DWORD    dwDetailLevel,
  [in]      BOOL     bRefresh
);

Parámetros

[in] hDataSource

Identificador de un origen de datos devuelto por la función PdhBindInputDataSource .

[in] szMachineName

Cadena terminada en NULL que especifica el nombre del equipo utilizado para enumerar los objetos de rendimiento.

Incluya las barras diagonales iniciales en el nombre del equipo, por ejemplo, \computername.

Si szDataSource es NULL, puede establecer szMachineName en NULL para especificar el equipo local.

[out] mszObjectList

Búfer asignado por el autor de la llamada que recibe la lista de nombres de objeto. Cada nombre de objeto de esta lista finaliza con un carácter nulo . La lista finaliza con dos caracteres de terminador NULL. Se establece en NULL si pcchBufferLength es cero.

[in, out] pcchBufferSize

Tamaño del búfer mszObjectList , en TCHAR. Si es cero en la entrada, la función devuelve PDH_MORE_DATA y establece este parámetro en el tamaño de búfer necesario. Si el búfer es mayor que el tamaño necesario, la función establece este parámetro en el tamaño real del búfer que se usó. Si el tamaño especificado en la entrada es mayor que cero pero menor que el tamaño necesario, no debe confiar en el tamaño devuelto para reasignar el búfer.

Windows XP: Agregue uno al tamaño de búfer necesario.

[in] dwDetailLevel

Nivel de detalle de los elementos de rendimiento que se van a devolver. Se devolverán todos los elementos que son del nivel de detalle especificado o menos (los niveles se muestran en orden creciente). Este parámetro puede ser uno de los valores siguientes.

Valor Significado
PERF_DETAIL_NOVICE
 Nivel de detalle del usuario principiante.
PERF_DETAIL_ADVANCED
 Nivel de detalle avanzado del usuario.
PERF_DETAIL_EXPERT
 Nivel de detalle del usuario experto.
PERF_DETAIL_WIZARD
 Nivel de detalle del diseñador del sistema.

[in] bRefresh

Indica si la lista de objetos almacenados en caché se debe actualizar automáticamente. Especifique uno de los valores siguientes.

Si llama a esta función dos veces, una vez para obtener el tamaño de la lista y una segunda vez para obtener la lista real, establezca este parámetro en TRUE en la primera llamada y FALSE en la segunda llamada. Si ambas llamadas son TRUE, la segunda llamada también puede devolver PDH_MORE_DATA porque los datos del objeto pueden haber cambiado entre llamadas.

Valor Significado
TRUE
 La memoria caché de objetos se actualiza automáticamente antes de que se devuelvan los objetos.
FALSE
 No actualice automáticamente la memoria caché.

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. A continuación se muestran los valores posibles.

Código devuelto Descripción
PDH_MORE_DATA
 El búfer mszObjectList es demasiado pequeño para contener la lista de objetos. Este valor devuelto se espera si pcchBufferLength es cero en la entrada. Si el tamaño especificado en la entrada es mayor que cero pero menor que el tamaño necesario, no debe confiar en el tamaño devuelto para reasignar el búfer.
PDH_CSTATUS_NO_MACHINE
 El equipo especificado está sin conexión o no está disponible.
PDH_CSTATUS_NO_OBJECT
 No se encontró el objeto especificado.
PDH_INVALID_ARGUMENT
 Un parámetro no es válido. Por ejemplo, en algunas versiones podría recibir este error si el tamaño especificado en la entrada es mayor que cero pero menor que el tamaño necesario.

Comentarios

Debe llamar a esta función dos veces, la primera vez que obtenga el tamaño de búfer necesario (establezca mszObjectList en NULL y pcchBufferLength en 0) y la segunda vez para obtener los datos.

Nota

El encabezado pdh.h define PdhEnumObjectsH 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

Consulte también

PdhBindInputDataSource

PdhEnumObjectItemsH