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