Función PdhEnumObjectItemsA (pdh.h)

Devuelve el contador y los nombres de instancia del objeto especificados que existen en el equipo especificado o en el archivo de registro especificado.

Para usar identificadores para orígenes de datos, use la función PdhEnumObjectItemsH.

Sintaxis

PDH_FUNCTION PdhEnumObjectItemsA(
  [in]      LPCSTR  szDataSource,
  [in]      LPCSTR  szMachineName,
  [in]      LPCSTR  szObjectName,
  [out]     PZZSTR  mszCounterList,
  [in, out] LPDWORD pcchCounterListLength,
  [out]     PZZSTR  mszInstanceList,
  [in, out] LPDWORD pcchInstanceListLength,
  [in]      DWORD   dwDetailLevel,
  [in]      DWORD   dwFlags
);

Parámetros

[in] szDataSource

cadena terminada en Nullque especifica el nombre del archivo de registro que se usa para enumerar los nombres de instancia y contador. Si null, la función usa el equipo especificado en

el parámetro szMachineName para enumerar los nombres.

[in] szMachineName

cadena terminada en nullque especifica el nombre del equipo que contiene los nombres de contador e instancia que desea enumerar.

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

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

[in] szObjectName

cadena terminada en Nullque especifica el nombre del objeto cuyos nombres de contador e instancia desea enumerar.

[out] mszCounterList

Búfer asignado por el autor de la llamada que recibe una lista de nombres de contador nulosterminados proporcionados por el objeto especificado. La lista contiene nombres de contador únicos. La lista finaliza con dos caracteres NULL. Se establece en NULL si el parámetro pcchCounterListLength es cero.

[in, out] pcchCounterListLength

Tamaño del búfer de mszCounterList de , en TCHAR. Si hay cero en la entrada y el objeto, 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.

[out] mszInstanceList

Búfer asignado por el autor de la llamada que recibe una lista de nombres de instancia nulosterminados proporcionados por el objeto especificado. La lista contiene nombres de instancia únicos. La lista finaliza con dos caracteres NULL. Establézcalo en null si pcchInstanceListLength es cero.

[in, out] pcchInstanceListLength

Tamaño del búfer de mszInstanceList de , en TCHAR. Si hay cero en la entrada y el objeto, 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.

Si el objeto especificado no admite instancias de variables, el valor devuelto será cero. Si el objeto especificado admite instancias de variables, pero actualmente no tiene ninguna instancia, el valor devuelto es 2, que es el tamaño de una cadena de lista de MULTI_SZ vacía.

[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 siguientes valores.

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

[in] dwFlags

Este parámetro debe ser cero.

Valor devuelto

Si la función se ejecuta 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	Uno de los búferes es demasiado pequeño para contener la lista de nombres. Este valor devuelto se espera si pcchCounterListLength o pcchInstanceListLength 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_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.
PDH_MEMORY_ALLOCATION_FAILURE	No se puede asignar memoria para admitir esta función.
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 en el equipo especificado o en el archivo de registro especificado.

Observaciones

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

Las llamadas consecutivas a esta función devolverán listas idénticas de contadores e instancias, ya que PdhEnumObjectItems consultarán siempre la lista de objetos de rendimiento definidos por la última llamada a PdhEnumObjects o PdhEnumObjectItems. Para actualizar la lista de objetos de rendimiento, llame a PdhEnumObjects con un valor de marca bRefresh de TRUE antes de llamar a PdhEnumObjectItems de nuevo.

El orden de los nombres de instancia y contador es indeterminado.

Ejemplos

Para obtener un ejemplo, vea Enumerar objetos de proceso.

Nota

El encabezado pdh.h define PdhEnumObjectItems 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	pdh.h
biblioteca de	Pdh.lib
DLL de	Pdh.dll

Consulte también

PdhEnumObjectItemsH

PdhEnumObjects