Función PdhLookupPerfNameByIndexA (pdh.h)

  • Artículo

Devuelve el nombre del objeto de rendimiento o el nombre del contador correspondiente al índice especificado.

Sintaxis

PDH_FUNCTION PdhLookupPerfNameByIndexA(
  [in]      LPCSTR  szMachineName,
  [in]      DWORD   dwNameIndex,
  [out]     LPSTR   szNameBuffer,
  [in, out] LPDWORD pcchNameBufferSize
);

Parámetros

[in] szMachineName

Cadena terminada en NULL que especifica el nombre del equipo donde se encuentra el objeto de rendimiento o contador especificados. El nombre del equipo se puede especificar mediante el nombre DNS o la dirección IP. Si es NULL, la función usa el equipo local.

[in] dwNameIndex

Índice del objeto o contador de rendimiento.

[out] szNameBuffer

Búfer asignado por el autor de la llamada que recibe el nombre terminado en null del objeto o contador de rendimiento. Establezca en NULL si pcchNameBufferSize es cero.

[in, out] pcchNameBufferSize

Tamaño del búfer szNameBuffer , 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.

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
 El búfer szNameBuffer no es lo suficientemente grande como para contener el nombre del contador. Este valor devuelto se espera si pcchNameBufferSize 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 o tiene un formato incorrecto. 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 szNameBuffer en NULL y pcchNameBufferSize en 0) y la segunda vez para obtener los datos.

Windows XP: Debe especificar un búfer y un tamaño de búfer. La función establece pcchNameBufferSize en el tamaño necesario o en el tamaño del búfer que se usó. Si el búfer es demasiado pequeño, la función devuelve PDH_INSUFFICIENT_BUFFER en lugar de PDH_MORE_DATA. El tamaño máximo de cadena en bytes es PDH_MAX_COUNTER_NAME * sizeof(TCHAR).

El valor de índice que especifique debe coincidir con uno de los valores de índice asociados a los objetos o contadores que se cargaron en el equipo. Los pares de valor de índice/nombre se almacenan en el valor del Registro contadores en la siguiente ubicación del Registro.

HKEY_LOCAL_MACHINE
   \SOFTWARE
      \Microsoft
         \Windows NT
            \CurrentVersion
               \Perflib
                  Last Counter = highest counter index
                  Last Help = highest help index
                  \009
                     Counters = 2 System 4 Memory...
                     Help = 3 The System Object Type...
                  \supported language, other than English
                     Counters = ...
                     Help = ...

Nota

El encabezado pdh.h define PdhLookupPerfNameByIndex 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en 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

PdhLookupPerfIndexByName