CPdh v1.03 - NT Performance Info

Download source files - 24 Kb

Introduction

Welcome to CPdh v1.03, a collection of freeware MFC classes to encapsulate the NT performance counters API as provided by PDH.DLL.

Features

History

API Reference

Usage

Contacting the Author

Features

• Simple and clean C++ interface based.
• The classes are fully Unicode compliant.
• Full documentation is provided in the form of a HTML file.

History

V1.0 (9 February 1999)

• Initial Release.

V1.01 (5 September 1999)

• Fixed a bug in pjPdhState::pjPdhState() in CPDHIMPL.CPP which was causing an access violation.

V1.02 (13 September 1999)

• Fixed a problem which was causing an unhandled exception being thrown when the PDH.DLL is not present on client machines.

V1.03 (25 January 2000)

• Minor update to improve the trace statements when exceptions are thrown.

API Reference

The CPdh classes provide the following functions:

CPdhException::CPdhException
CPdhException::m_Status
CPdhException::GetErrorMessage
CPdhCounterInfo
CPdhCounter::CPdhCounter
CPdhCounter::GetRawValue
CPdhCounter::SplitPath
CPdhCounter::GetInfo
CPdhCounter::CalculateFromRawValue
CPdhCounter::GetFormattedValue
CPdhCounter::ComputeStatistics
CPdhCounter::SetScaleFactor
CPdhQuery::Open
CPdhQuery::Close
CPdhQuery::Add
CPdhQuery::Remove
CPdhQuery::Collect
CPdh::ValidatePath
CPdh::ExpandPath
CPdh::ConnectMachine
CPdh::EnumMachines
CPdh::EnumObjects
CPdh::EnumObjectItems
CPdh::GetDefaultCounter
CPdh::GetDefaultObject
CPdh::BrowseCounters
CPdh::ParseInstanceName
CPdh::ThrowPdhException

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:

• dwFormat -- The format code composed of the following values:

  Value	Meaning
  PDH_FMT_DOUBLE	Return the calculated value as a double-precision floating point real.
  PDH_FMT_LARGE	Return the calculated value as a 64-bit integer.
  PDH_FMT_LONG	Return the calculated value as a long integer.

  The value selected from the previous table can be combined using the OR operator with one of the following scaling flags:

  Flag	Meaning
  PDH_FMT_NOSCALE	Do not apply the counter's scaling factors in the calculation.
  PDH_FMT_1000	Multiply the final value by 1000.

• rawValue1 -- Raw counter value used to compute the counter value. Some counters (for example, rate counters) require two raw values for a calculation. The format of the buffer depends on the type of counter to be processed.
• rawValue2 -- Raw counter value used in computations for counters that require two raw values (for example, rate counters). This value must be the older of the two raw values.
• fmtValue -- Data buffer that will receive the calculated counter value.

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:

• dwFormat -- The format code composed of the following values:

  Value	Meaning
  PDH_FMT_DOUBLE	Return the calculated value as a double-precision floating point real.
  PDH_FMT_LARGE	Return the calculated value as a 64-bit integer.
  PDH_FMT_LONG	Return the calculated value as a long integer.

  The value selected from the previous table can be combined using the OR operator with one of the following scaling flags:

  Flag	Meaning
  PDH_FMT_NOSCALE	Do not apply the counter's scaling factors in the calculation.
  PDH_FMT_1000	Multiply the final value by 1000.

• fmtValue -- Data buffer that will receive the calculated counter value.

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:

• dwFormat -- The format code composed of the following values:

  Value	Meaning
  PDH_FMT_DOUBLE	Return the calculated value as a double-precision floating point real.
  PDH_FMT_LARGE	Return the calculated value as a 64-bit integer.
  PDH_FMT_LONG	Return the calculated value as a long integer.

  The value selected from the previous table can be combined using the OR operator with one of the following scaling flags:

  Flag	Meaning
  PDH_FMT_NOSCALE	Do not apply the counter's scaling factors in the calculation.
  PDH_FMT_1000	Multiply the final value by 1000.

• dwFirstEntry -- The zero-based index of the first raw counter buffer to look at. This value must point to the oldest entry in the buffer. The function starts at this entry and scans through the buffer, wrapping at the last entry back to the beginning of the buffer and up to the dwFirstEntry-1 entry, which is assumed to be the newest or most recent data.
• dwNumEntries -- The number of raw counter entries in the lpRawValueArray buffer.
• lpRawValueArray -- A pointer to the raw counter value or values used to compute the counter value. Some counters (for example, rate counters) require two values for a calculation. The format of the buffer is assumed to be an array of PDH_RAW_COUNTER structures that contain dwNumEntries entries.
• data -- A PDH_STATISTICS buffer to receive the counter statistics.

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, 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, 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:

• pszInstanceString -- 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
  

• sInstanceName -- Receive the instance name parsed from the instance string.
• sParentName -- Receive the name of the parent index if one is specified.
• Index -- Receive the index value of the instance. If an index entry is not present in the string, then this value will be 0.

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.

Usage:

• To use the classes in your code, just #include cpdh.h in which ever module requires it and also include the cpdh & cpdhimpl .cpp and .h files in your project.
• The code is specific to Windows NT and will not work on Windows 95/98. It will however load up correctly on 95/98 even in the absence of PDH.DLL. When the first function is called, it will then throw a CPdhException which your code should handle. Alternatively you could call GetVersionEx() and only call the code when you know you are running on NT. This is modeled upon the behaviour of the WININET wrapper classes in MFC.
• The code is UNICODE enabled and build configurations are provided for the test program.
• You need to ensure that your application redistributes PDH.DLL with your application. This DLL can be found in the BIN directory of wherever you installed the MS platform SDK into.

Contacting the Author

PJ Naughter
Email: pjn@indigo..ie
Web: http://www.naughter.com
25 January 2000