Función PdhGetFormattedCounterArrayA (pdh.h)

Artículo
08/25/2023

Devuelve una matriz de valores de contador con formato. Use esta función cuando desee dar formato a los valores de contador de un contador que contenga un carácter comodín para el nombre de instancia.

Sintaxis

PDH_FUNCTION PdhGetFormattedCounterArrayA(
  [in]      PDH_HCOUNTER                 hCounter,
  [in]      DWORD                        dwFormat,
  [in, out] LPDWORD                      lpdwBufferSize,
  [out]     LPDWORD                      lpdwItemCount,
  [out]     PPDH_FMT_COUNTERVALUE_ITEM_A ItemBuffer
);

Parámetros

[in] hCounter

Identificador del contador cuyo valor actual desea dar formato. La función PdhAddCounter devuelve este identificador.

[in] dwFormat

Determina el tipo de datos del valor con formato. Especifique uno de los valores siguientes.

Valor	Significado
PDH_FMT_DOUBLE	Devuelve datos como un punto flotante de precisión doble real.
PDH_FMT_LARGE	Devuelve datos como un entero de 64 bits.
PDH_FMT_LONG	Devuelve datos como un entero largo.

Puede usar el operador OR inclusivo bit a bit (|) para combinar el tipo de datos con uno de los siguientes factores de escalado.

Valor	Significado
PDH_FMT_NOSCALE	No aplique el factor de escalado predeterminado del contador.
PDH_FMT_NOCAP100	Los valores de contador mayores que 100 (por ejemplo, valores de contador que miden la carga del procesador en equipos multiprocesador) no se restablecerán a 100. El comportamiento predeterminado es que los valores de contador están limitados en un valor de 100.
PDH_FMT_1000	Multiplique el valor real en 1000.

[in, out] lpdwBufferSize

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

[out] lpdwItemCount

Número de valores de contador en el búfer ItemBuffer .

[out] ItemBuffer

Búfer asignado por el autor de la llamada que recibe una matriz de estructuras de PDH_FMT_COUNTERVALUE_ITEM ; las estructuras contienen los valores de contador. Se establece en NULL si lpdwBufferSize es cero.

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 ItemBuffer no es lo suficientemente grande como para contener el nombre del objeto. Este valor devuelto se espera si lpdwBufferSize 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.
PDH_INVALID_HANDLE	El identificador de contador no es válido.

Comentarios

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

Los datos del contador se bloquean durante la llamada a PdhGetFormattedCounterArray para evitar cambios durante el procesamiento de la llamada.

Ejemplos

En el ejemplo siguiente se muestra cómo usar esta función.


#include <windows.h>
#include <stdio.h>
#include <pdh.h>
#include <pdhmsg.h>

#pragma comment(lib, "pdh.lib")

CONST PWSTR COUNTER_PATH = L"\\Processor(*)\\% Processor Time";
CONST ULONG SAMPLE_INTERVAL_MS = 1000;

void main()
{
    PDH_HQUERY hQuery = NULL;
    PDH_STATUS status = ERROR_SUCCESS;
    PDH_HCOUNTER hCounter = NULL;   
    DWORD dwBufferSize = 0;         // Size of the pItems buffer
    DWORD dwItemCount = 0;          // Number of items in the pItems buffer
    PDH_FMT_COUNTERVALUE_ITEM *pItems = NULL;  // Array of PDH_FMT_COUNTERVALUE_ITEM structures

    if (status = PdhOpenQuery(NULL, 0, &hQuery))
    {
        wprintf(L"PdhOpenQuery failed with 0x%x.\n", status);
        goto cleanup;
    }

    // Specify a counter object with a wildcard for the instance.
    if (status = PdhAddCounter(hQuery, COUNTER_PATH, 0, &hCounter))
    {
        wprintf(L"PdhAddCounter failed with 0x%x.\n", status);
        goto cleanup;
    }

    // Some counters need two sample in order to format a value, so
    // make this call to get the first value before entering the loop.
    if (status = PdhCollectQueryData(hQuery))
    {
        wprintf(L"PdhCollectQueryData failed with 0x%x.\n", status);
        goto cleanup;
    }

    for (int i = 0; i < 10; i++)
    {
        Sleep(SAMPLE_INTERVAL_MS);

        if (status = PdhCollectQueryData(hQuery))
        {
            wprintf(L"PdhCollectQueryData failed with 0x%x.\n", status);
            goto cleanup;
        }

        // Get the required size of the pItems buffer.
        status = PdhGetFormattedCounterArray(hCounter, PDH_FMT_DOUBLE, &dwBufferSize, &dwItemCount, pItems);
        if (PDH_MORE_DATA == status)
        {
            pItems = (PDH_FMT_COUNTERVALUE_ITEM *) malloc(dwBufferSize);
            if (pItems)
            {
                status = PdhGetFormattedCounterArray(hCounter, PDH_FMT_DOUBLE, &dwBufferSize, &dwItemCount, pItems);
                if (ERROR_SUCCESS == status)
                {
                    // Loop through the array and print the instance name and counter value.
                    for (DWORD i = 0; i < dwItemCount; i++)
                    {
                        wprintf(L"counter: %s, value %.20g\n", pItems[i].szName, pItems[i].FmtValue.doubleValue);
                    }
                }
                else
                {
                    wprintf(L"Second PdhGetFormattedCounterArray call failed with 0x%x.\n", status);
                    goto cleanup;
                }

                free(pItems);
                pItems = NULL;
                dwBufferSize = dwItemCount = 0;
            }
            else
            {
                wprintf(L"malloc for PdhGetFormattedCounterArray failed.\n");
                goto cleanup;
            }
        }
        else
        {
            wprintf(L"PdhGetFormattedCounterArray failed with 0x%x.\n", status);
            goto cleanup;
        }
    }

cleanup:

    if (pItems)
        free(pItems);

    if (hQuery)
        PdhCloseQuery(hQuery); // Closes all counter handles and the query handle
}

Nota

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