v1.03, a collection of freeware MFC classes to encapsulate the NT performance
counters API as provided by
- CPdhException::CPdhException
- CPdhException(PDH_STATUS Status);
Parameters:
- Status -- The PDH status error that caused the exception.
Remarks:
This member function is called when a CPdhException object is created. To throw a
CPdhException, call the function CPdh::ThrowPdhException().
- CPdhException::m_Status
- Remarks:
The error that caused the exception. This error value may be a PDH status error as defined in
PDHMSG.H. For a list of Win32 error codes, see Error Codes in the Win32 SDK. For a list of
PDH-specific error codes, see the PDH documentation.
- CPdhException::GetErrorMessage
- virtual BOOL GetErrorMessage(LPTSTR lpszError, UINT nMaxError, PUINT pnHelpContext = NULL );
virtual BOOL GetErrorMessage(CString& sError, PUINT pnHelpContext = NULL );
Return Value:
Nonzero if the function is successful; otherwise 0 if no error message text is available.
Parameters:
- lpszError -- A pointer to a buffer that will receive an error message.
- sError -- a CString that will receive an error message.
- nMaxError -- The maximum number of characters the buffer can hold, including the NULL
terminator.
- pnHelpContext -- The address of a UINT that will receive the help context ID. If NULL,
no ID will be returned.
Remarks:
Call this member function to provide text about an error that has occurred. Note:
GetErrorMessage() will not copy more than nMaxError-1 characters to the
buffer, and it will always add a trailing null to end the string. If the buffer is too small, the
error message may be truncated.
- CPdhCounterInfo
- Remarks:
A structure as returned from CPdhCounter::GetInfo() which contains info
related to a PDH counter.
Member Variables:
- m_dwType -- The counter type.
- m_CVersion -- Counter version information.
- m_CStatus -- The current counter status.
- m_lScale -- The current scale factor.
- m_lDefaultScale -- The recommended scale factor.
- m_dwUserData -- The value of the counter's User Data field.
- m_dwQueryUserData -- The value of the User Data field for the query to which the
counter belongs.
- m_sFullPath -- he full counter path.
- m_sMachineName -- The machine name, parsed from the counter path.
- m_sObjectName -- The object name, parsed from the counter path.
- m_sInstanceName -- The instance name, parsed from counter path.
- m_sParentInstance -- The parent instance name, parsed from counter path.
- m_dwInstanceIndex -- The index of duplicate instance names.
- m_sCounterName -- The counter name.
- m_sExplainText -- The explain text for this counter.
- CPdhCounter::CPdhCounter
- CPdhCounter(LPCTSTR pszFullCounterPath, DWORD dwUserData = 0);
CPdhCounter(PDH_COUNTER_PATH_ELEMENTS& CounterPathElements, DWORD dwUserData = 0);
Parameters:
- pszFullCounterPath -- The fully qualified and resolved path of the counter to create. This
path cannot contain wild card path strings or characters.
- dwUserData -- A user-defined value, typically, a pointer or index to the user's counter
structure.
- CounterPathElements -- A structure that contains the individual members that are to make up
the counter path.
Remarks:
Constructs a PDH counter using the specified name. The counter does not become valid until it has
been added to a query using CPdhQuery::Add(). If any error occurs, CPdhCounter
throws a CPdh::ThrowPdhException().
- CPdhCounter::GetRawValue
- DWORD GetRawValue(PDH_RAW_COUNTER& value);
Return Value:
The counter type. The possible counter types are described in winperf.h.
Parameters:
- value -- A data buffer that will receive the counter value.
Remarks:
Returns the current raw value of the counter. If any error occurs, GetRawValue() throws
a CPdh::ThrowPdhException().
- CPdhCounter::SplitPath
- void SplitPath(CString& sMachineName, CString& sObjectName, CString& sInstanceName, CString& sParentInstance, DWORD& dwInstanceIndex, CString& sCounterName);
Return Value:
The counter type. The possible counter types are described in winperf.h.
Parameters:
- sMachineName -- The machine name, parsed from the counter path.
- sObjectName -- The object name, parsed from the counter path.
- m_sInstanceName -- The instance name, parsed from counter path.
- sParentInstance -- The parent instance name, parsed from counter path.
- dwInstanceIndex -- The index of duplicate instance names.
- sCounterName -- The counter name.
Remarks:
Parses the elements of the counter path and stores the results in the parameters passed by the caller.
If any error occurs, GetRawValue() throws a
CPdh::ThrowPdhException.
- CPdhCounter::GetInfo
- void GetInfo(CPdhCounterInfo& info);
Return Value:
The counter type. The possible counter types are described in winperf.h.
Parameters:
- info -- A structure that will receive the counter info.
Remarks:
Retrieves information about a counter, such as data size, counter type, path, and user-supplied data
values. If any error occurs, GetInfo() throws a
CPdh::ThrowPdhException.
- CPdhCounter::CalculateFromRawValue
- void CalculateFromRawValue(DWORD dwFormat, PDH_RAW_COUNTER& rawValue1, PDH_RAW_COUNTER& rawValue2, PDH_FMT_COUNTERVALUE& fmtValue);
Return Value:
The counter type. The possible counter types are described in winperf.h.
Parameters:
Remarks:
Computes the current value of the counter, using the raw counter data passed in the parameter list.
If any error occurs, CalculateFromRawValue() throws a
CPdh::ThrowPdhException.
- CPdhCounter::GetFormattedValue
- DWORD GetFormattedValue(DWORD dwFormat, PDH_FMT_COUNTERVALUE& value);
Return Value:
The counter type. The possible counter types are described in winperf.h.
Parameters:
Remarks:
Returns the current value of the counter in the format requested by the caller. If any error occurs,
GetFormattedValue() throws a CPdh::ThrowPdhException.
- CPdhCounter::ComputeStatistics
- void ComputeStatistics(DWORD dwFormat, DWORD dwFirstEntry, DWORD dwNumEntries, PPDH_RAW_COUNTER lpRawValueArray, PPDH_STATISTICS data);
Parameters:
Remarks:
Computes statistics for a counter from an array of raw values. If any error occurs,
ComputeStatistics() throws a CPdh::ThrowPdhException.
- CPdhCounter::SetScaleFactor
- void SetScaleFactor(LONG lFactor);
Parameters:
- lFactor -- The power of ten by which to multiply the calculated value before returning it. The
valid range of this parameter is PDH_MIN_SCALE (-7) (the returned value is the actual value
times 10-7) to PDH_MAX_SCALE (+7) (the returned value is the actual value times 10+7). A value
of zero will set the scale to one, so that the actual value is returned.
Remarks:
Sets the scale factor that is applied to the calculated value of the counter when you request the
formatted counter value. If the PDH_FMT_NOSCALE flag is set, then this scale factor is ignored. If
any error occurs, SetScaleFactor throws a
CPdh::ThrowPdhException.
- CPdhQuery::Open
- void Open(DWORD dwUserData = 0);
Parameters:
- dwUserData -- A user-defined DWORD value that is to be associated with this query. You can call
GetInfo() to retrieve the user data value for the query in which a counter
resides.
Remarks:
Creates and initialises a unique query structure that is used to manage collection of performance data.
If any error occurs, Open() throws a
CPdh::ThrowPdhException.
- CPdhQuery::Close
- void Close();
Remarks:
Closes all counters contained in the query, closes all handles related to the query, and frees all
memory associated with the query. If any error occurs, Close() throws a
CPdh::ThrowPdhException.
- CPdhQuery::Add
- void Add(CPdhCounter& counter);
Parameters:
- counter -- A PDH counter to add to this query.
Remarks:
Initialises a counter structure for the specified counter in the query. If any error occurs,
<code">Add() throws a CPdh::ThrowPdhException.
- CPdhQuery::Remove
- void Remove(CPdhCounter& counter);
Parameters:
- counter -- A PDH counter to remove from this query.
Remarks:
Removes a counter from a query. If any error occurs, <code">Remove() throws a
CPdh::ThrowPdhException.
- CPdhQuery::Collect
- void Collect();
Remarks:
Collects the current raw data value for all counters in this query and updates the status code of each
counter. If any error occurs, Collect() throws a
CPdh::ThrowPdhException.
- CPdh::ValidatePath
- static void ValidatePath(LPCTSTR pszFullCounterPath);
Parameters:
- pszFullCounterPath -- The counter path to validate.
Remarks:
Validates that the specified counter is present on the machine specified in the counter path. If any
error occurs, ValidatePath() throws a
CPdh::ThrowPdhException.
- CPdh::ExpandPath
- static void ExpandPath(LPCTSTR pszWildCardPath, CStringArray& expandedPaths);
Parameters:
- pszWildCardPath -- The counter path to expand.
- expandedPaths -- Receives the list of counter path names that match the wild card specification
in the pszWildCardPath buffer.
Remarks:
Examines the specified machine (or local machine if none is specified) for counters and instances of
counters that match the wild card strings in the counter path. The counter path format is assumed to be:
\\machine\object(parent/instance#index)\countername
and the parent, instance, index, and countername elements may contain either a valid name or a wild
card character. If any error occurs, ExpandPath() throws a
CPdh::ThrowPdhException.
- CPdh::ConnectMachine
- static void ConnectMachine(LPCTSTR pszMachineName);
Parameters:
- pszMachineName -- The name of the machine to browse.
Remarks:
Connects to the specified machine, and creates and initialises a machine entry in the PDH DLL. If any
error occurs, ConnectMachine() throws a
CPdh::ThrowPdhException.
- CPdh::EnumMachines
- static void EnumMachines(CStringArray& machineNames);
Parameters:
- machineNames -- Receives the list of machines that have been opened previously.
Remarks:
Returns a list of the names of the machines that have been opened previously by the PDH DLL. If any
error occurs, EnumMachines() throws a
CPdh::ThrowPdhException.
- CPdh::EnumObjects
- static void EnumObjects(LPCTSTR pszMachineName, CStringArray& objects, DWORD dwDetailLevel, BOOL bRefresh);
Parameters:
- pszMachineName -- The name of the machine on which to list the objects. If the machine specified
is not in the list of currently connected machines, the PDH will try to connect to the machine
and add it to the list.
- objects -- Receives the list of objects available on the specified machine.
- dwDetailLevel -- The detail level of the performance items to return. All items that are of the
specified detail level or less will be returned.
- bRefresh -- Indicates that a new list of objects should be obtained from the specified machine.
If the machine is not currently connected by the PDH, then this flag is ignored and the list is
refreshed automatically.
Remarks:
Returns a list of objects available on the specified machine. If any error occurs,
EnumObjects() throws a CPdh::ThrowPdhException.
- CPdh::EnumObjectItems
- static void EnumObjectItems(LPCTSTR pszMachineName, LPCTSTR pszObjectName, CStringArray& counters, CStringArray& instances, DWORD dwDetailLevel);
Parameters:
- pszMachineName -- The name of the machine on which to list the counters and instances. If the
machine specified is not in the list of currently connected machines, the PDH will try to
connect to the machine and add it to the list.
- pszObjectName -- The name of the object on the specified machine from which the items are to be
listed.
- counters -- Receives the list of counters available on the specified machine.
- instances -- Receives the list of instances available on the specified machine.
- dwDetailLevel -- The detail level of the performance items to return. All items that are of the
specified detail level or less will be returned.
- bRefresh -- Indicates that a new list of objects should be obtained from the specified machine.
If the machine is not currently connected by the PDH, then this flag is ignored and the list is
refreshed automatically.
Remarks:
Returns the available counters and instances provided by the specified object on the specified machine.
If any error occurs, EnumObjectItems() throws a
CPdh::ThrowPdhException.
- CPdh::GetDefaultCounter
- static void GetDefaultCounter(LPCTSTR pszMachineName, LPCTSTR pszObjectName, CString& sDefaultCounterName);
Parameters:
- pszMachineName -- The name of the machine to query.
- pszObjectName -- The name of the object in pszMachineName to query.
- sDefaultCounterName -- Receives the default counter name for the specified object.
Remarks:
Retrieves the name of the default counter for the specified object. This can be used to set the initial
selection of the counter browser list/combo box. If any error occurs, GetDefaultCounter()
throws a CPdh::ThrowPdhException.
- CPdh::GetDefaultObject
- static void GetDefaultObject(LPCTSTR pszMachineName, CString& sDefaultObjectName);
Parameters:
- pszMachineName -- The name of the machine to query.
- sDefaultObjectName -- Receives the default object for the specified machine.
Remarks:
Retrieves the name of the default performance object. The name can be used to select the default entry
in the object browser list box. If any error occurs, GetDefaultObject()
throws a CPdh::ThrowPdhException.
- CPdhCounter::BrowseCounters
- static void BrowseCounters(PDH_BROWSE_DLG_CONFIG& BrowseDlgData);
Parameters:
- BrowseDlgData -- A structure that specifies the behaviour of the dialog box that receives the
counter path strings.
Remarks:
Displays the counter browsing dialog box so that the user can select the counters to be returned to
the caller. If any error occurs, BrowseCounters()
throws a CPdh::ThrowPdhException.
- CPdh::ParseInstanceName
- static void ParseInstanceName(LPCTSTR pszInstanceString, CString& sInstanceName, CString& sParentName, DWORD& Index);
Parameters:
Remarks:
Parses the elements of an instance string and returns them in the buffers supplied by the caller. If
any error occurs, ParseInstanceName()
throws a CPdh::ThrowPdhException.
- CPdh::ThrowPdhException
- void ThrowPdhException(DWORD dwError = 0 );
Parameters:
- dwError -- The error that caused the exception.
Remarks:
Throws an PDH exception.
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
