PdhParseInstanceName

The PdhParseInstanceName function parses the elements of an instance string and returns them in the buffers supplied by the caller.

PDH_STATUS PdhParseInstanceName(
  IN LPCTSTR szInstanceString,       // instance string
  IN LPTSTR szInstanceName,          // parsed instance name
  IN LPDWORD pcchInstanceNameLength, // length of name
  IN LPTSTR szParentName,            // name of parent index
  IN LPDWORD pcchParentNameLength,   // length of parent name
  IN LPDWORD lpIndex                 // instance index
);
 

Parameters

szInstanceString

A pointer to the string containing the instance substring to parse into individual components. This string can contain the following formats, and is less than MAX_PATH characters in length:

instance
instance#index
parent/instance
parent/instance#index

szInstanceName

A pointer to the buffer that will receive the instance name parsed from the instance string. This pointer can be NULL if the DWORD referenced by the pcchInstanceNameLength parameter is 0.

pcchInstanceNameLength

A pointer to the DWORD that contains the length of the szInstanceName buffer. If the value of this DWORD is 0, then the buffer size required to hold the instance name will be returned.

szParentName

A pointer to the buffer that will receive the name of the parent index if one is specified. This parameter can be NULL if the value of the DWORD referenced by the pcchParentNameLength parameter is 0.

pcchParentNameLength

A pointer to the DWORD that contains the length of the szParentName buffer. If the value of this DWORD is 0, then the buffer size required to hold the instance name will be returned.

lpIndex

A pointer to the DWORD that will receive the index value of the instance. If an index entry is not present in the string, then this value will be 0. This argument can be NULL if this information is not needed.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in pdhmsg.h. The following are possible error values:

PDH_INVALID_ARGUMENT

An argument is invalid or incorrect.

PDH_INSUFFICIENT_BUFFER

One or both of the string buffers supplied is not large enough for the strings to be returned.

PDH_INVALID_INSTANCE

The instance string is incorrectly formatted, exceeds MAX_PATH characters in length, or cannot be parsed.

See Also

Performance Data Helper Overview, Performance Data Functions, , PdhMakeCounterPath