Platform SDK: Performance Monitoring

PdhExpandCounterPath

The PdhExpandCounterPath function examines the specified machine (or local machine if none is specified) for counters and instances of counters that match the wildcard strings in the counter path.

PDH_STATUS PdhExpandCounterPath(
  LPCTSTR szWildCardPath,          
  LPTSTR mszExpandedPathList,      
  LPDWORD pcchPathListLength   
);

Parameters

szWildCardPath: [in] A pointer to a null-terminated string containing the name of the counter path to expand.
mszExpandedPathList: [out] A pointer to a null-terminated string containing the name of the buffer that receives the list of counter path names that match the wildcard specification in the szWildCardPath buffer. Each counter path in this list is terminated by a NULL character. You must allocate the memory for this buffer before calling PdhExpandCounterPath.
pcchPathListLength: [in/out] A pointer to a DWORD that specifies the size of the mszExpandedPathList buffer, in characters. On output, receives the length actually used by the returned path strings.
If the mszExpandedPathList buffer is too small to receive the entire list, PdhExpandCounterPath returns PDH_MORE_DATA. The pcchPathListLength variable receives the length required for the returned path strings.

Return Values

If the function succeeds, it returns PDH_CSTATUS_VALID_DATA.

If the function fails, the return value is a PDH error status defined in PDHMsg.h.

Remarks

The general counter path format is as follows:

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

The parent, instance, index, and counter components of the format may contain either a valid name or a wildcard character. The machine, parent, instance, and index components are not necessary for all counters.

The counter paths you must use is determined by the counter itself. For example, the LogicalDisk object has an instance index, so you must provide the #index, or a wildcard. Therefore, you could use the following format:

\LogicalDisk(*/*#*)\*

In comparison, the Process object does not require an instance index. Therefore, you could use the following format:

\Process(*)\ID Process

The following is a list of the possible formats:

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

Example

The following example demonstrates how to use PdhExpandCounterPath.

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

#define INITIALPATHSIZE 1000

LPSTR  szCtrPath = NULL;
char   szWildCardPath[256] = "\000";
DWORD  dwCtrPathSize = 0;

PDH_STATUS  pdhStatus;
HQUERY      hQuery;

void main()
{
    pdhStatus = PdhOpenQuery(0,0, &hQuery);

// Use the counter path format without specifying the machine.
//    \object(parent/instance#index)\counter

    sprintf(szWildCardPath, "\\LogicalDisk(*/*#*)\\*");

// First try with an initial buffer size.
    szCtrPath = (LPSTR) GlobalAlloc(GPTR, INITIALPATHSIZE);
    dwCtrPathSize = INITIALPATHSIZE;

    pdhStatus = PdhExpandCounterPath(szWildCardPath, szCtrPath, 
                    &dwCtrPathSize);

// Check for a too small buffer.
    if (pdhStatus == PDH_MORE_DATA)
    {
        // dwCtrPathSize has the required length, minus the last NULL
        dwCtrPathSize++;
        GlobalFree(szCtrPath);
        szCtrPath = GlobalAlloc(GPTR, dwCtrPathSize);
        pdhStatus = PdhExpandCounterPath(szWildCardPath, szCtrPath, 
                        &dwCtrPathSize);
    }

// Upon success, print all counter path names.
    if (pdhStatus == PDH_CSTATUS_VALID_DATA)
    {
        LPTSTR ptr;

        ptr = szCtrPath;
        while (*ptr)
        {
            printf("%s\n", ptr);
            ptr += strlen(ptr);
            ptr++;
        }
    }
    else printf("PdhExpandCounterPath failed: %d\n", pdhStatus);
}

Requirements