Función PdhExpandCounterPathW (pdh.h)

  • Artículo

Examina el equipo especificado (o equipo local si no se especifica ninguno) para los contadores y las instancias de contadores que coinciden con las cadenas con caracteres comodín en la ruta de acceso del contador.

Nota Esta función se sustituye por la función PdhExpandWildCardPath .
 

Sintaxis

PDH_FUNCTION PdhExpandCounterPathW(
  [in]      LPCWSTR szWildCardPath,
  [out]     PZZWSTR mszExpandedPathList,
  [in, out] LPDWORD pcchPathListLength
);

Parámetros

[in] szWildCardPath

Cadena terminada en NULL que contiene la ruta de acceso del contador que se va a expandir. La función busca coincidencias en el equipo especificado en la ruta de acceso. Si la ruta de acceso no especifica un equipo, la función busca en el equipo local. La longitud máxima de una ruta de acceso de contador es PDH_MAX_COUNTER_PATH.

[out] mszExpandedPathList

Búfer asignado por el autor de la llamada que recibe la lista de rutas de acceso de contador expandidas que coinciden con la especificación de caracteres comodín en szWildCardPath. Cada ruta de acceso de contador de esta lista finaliza con un carácter nulo . La lista finaliza con dos caracteres NULL . Se establece en NULL si pcchPathListLength es cero.

[in, out] pcchPathListLength

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

Nota Debe agregar uno al tamaño necesario en Windows XP.
 

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.

Código devuelto Descripción
PDH_MORE_DATA
 El búfer mszExpandedPathList es demasiado pequeño para contener la lista de rutas de acceso. Este valor devuelto se espera si pcchPathListLength 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.

Comentarios

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

El formato de ruta de acceso de contador general es el siguiente:

\computer\object(parent/instance#index)\counter

Los componentes primarios, de instancia, de índice y contador de la ruta de acceso del contador pueden contener un nombre válido o un carácter comodín. Los componentes de equipo, primario, instancia e índice no son necesarios para todos los contadores.

Las rutas de acceso de contador que debe usar están determinadas por el propio contador. Por ejemplo, el objeto LogicalDisk tiene un índice de instancia, por lo que debe proporcionar el #index o un carácter comodín. Por lo tanto, puede usar el siguiente formato:

\LogicalDisk(/#*)*

En comparación, el objeto Process no requiere un índice de instancia. Por lo tanto, puede usar el siguiente formato:

\Proceso(*)\Proceso de id.

A continuación se muestra una lista de los posibles formatos:

  • \\computer\object(parent/instance#index)\counter
  • \\computer\object(parent/instance)\counter
  • \\computer\object(instance#index)\counter
  • \\computer\object(instance)\counter
  • \\computer\object\counter
  • \object(parent/instance#index)\counter
  • \object(parent/instance)\counter
  • \object(instance#index)\counter
  • \object(instance)\counter
  • \object\counter
Si se especifica un carácter comodín en el nombre primario, se devolverán todas las instancias del objeto especificado que coincidan con los campos de instancia y contador especificados.

Si se especifica un carácter comodín en el nombre de instancia, se devolverán todas las instancias del objeto y el objeto primario especificados si todos los nombres de instancia correspondientes al índice especificado coinciden con el carácter comodín.

Si se especifica un carácter comodín en el nombre del contador, se devuelven todos los contadores del objeto especificado.

No se admiten coincidencias de cadena de ruta de acceso de contador parcial (por ejemplo, "pro*").

Ejemplos

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


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

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

CONST PWSTR WILDCARD_PATH = L"\\Processor(*)\\*";

void wmain(void)
{
    PDH_STATUS Status;
    PWSTR EndOfPaths;
    PWSTR Paths = NULL;
    DWORD BufferSize = 0;

    Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);

    while (Status == PDH_MORE_DATA) 
    {
        Paths = (PWSTR)malloc(BufferSize * sizeof(WCHAR));
        Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);
    }

    if (Status != ERROR_SUCCESS) 
    {
        wprintf(L"\nPdhExpandCounterPath failed with status 0x%x", Status);
        goto Cleanup;
    }

    if (Paths == NULL) 
    {
        wprintf(L"\nThe counter path %s cannot be expanded.", WILDCARD_PATH);
        goto Cleanup;
    }

    EndOfPaths = Paths + BufferSize;

    // On Vista and later operating systems, the buffer is terminated with two 
    // null-terminator characters; however, on earlier systems, the buffer is
    // not terminated with two null-terminator characters. This covers both cases.
    for (PWSTR p = Paths; ((p != EndOfPaths) && (*p != L'\0')); p += wcslen(p) + 1) 
    {
        wprintf(L"\n%s", p);
    }

Cleanup:
    if (Paths) 
    {
        free(Paths);
    }
}

Nota

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

   
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

PdhExpandWildCardPath

PdhMakeCounterPath