PdhExpandWildCardPath

The PdhExpandWildCardPath function expands any wildcard characters in the specified counter path string and returns the matching counter paths.

PDH_STATUS PdhExpandWildCardPath(
  LPCTSTR szDataSource,    
  LPCTSTR szWildCardPath,   
  LPTSTR mszExpandedPathList,    
  LPDWORD pcchPathListLength, 
  DWORD dwFlags
);

Parameters

szDataSource

Windows 2000: [in] A pointer to a null-terminated string containing either the name of a log file or a null string. If you specify the name of a log file, performance data will be taken from that log file. If this parameter contains a null string, performance data will be collected from a real-time data source.

Windows NT 4.0: [in] Reserved. Must be NULL.

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 buffer that szWildCardPath points to. Each counter path in this list is terminated by a NULL character. You must allocate the memory for this buffer before calling PdhExpandWildCardPath.

pcchPathListLength

[in/out] A pointer to a DWORD that specifies the size, in characters, of the buffer that mszExpandedPathList points to. On output, receives the length actually used by the returned path strings.

If the buffer that mszExpandedPathList points to is too small to receive the entire list, PdhExpandWildCardPath returns PDH_MORE_DATA. The pcchPathListLength parameter receives the length required for the returned path strings.

dwFlags

[in] Flags determining which wildcard characters in the counter path string are to be expanded.

Value	Meaning
PDH_NOEXPANDCOUNTERS	Wildcard characters in the counter names specified in the counter path list are not expanded.
PDH_NOEXPANDINSTANCES	Wildcard characters in the instance names specified in the counter path list are not expanded.

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

PdhExpandWildCardPath differs from PdhExpandCounterPath in three ways:

1. PdhExpandWildCardPath can expand only the wildcard characters in the counter or instance names according to the value of the dwFlags parameter, or it can expand all of them. PdhExpandCounterPath expands only the wildcard characters in the counter path string.
2. The contents of a log file can be used as the source of counter names. In this case, PdhExpandWildCardPath will filter the counters listed in the log file according to the values of szWildCardPath and dwFlags.
3. PdhExpandWildCardPath expands counter paths that include the machine to also include the machine and a connection will be made to the specified machine to resolve the wildcard matches. Counter paths that do not contain a machine name will use the local machine to resolve wildcard matches.

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.

You determine the counter paths to use based on 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

If a wildcard character is specified in the parent name, all instances of the specified object that match the specified instance and counter fields will be returned.

If a wildcard character is specified in the instance name, all instances of the specified object and parent object will be returned if all instance names corresponding to the specified index match the wildcard character.

If a wildcard character is specified in the counter name, all counters of the specified object are returned.

Partial counter path string matches (for example, "pro*") are not supported.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Pdh.h.
  Library: Use Pdh.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

PdhExpandCounterPath