Click here to Skip to main content
Click here to Skip to main content

CPdh v1.03 - NT Performance Info

, 3 Mar 2000
Rate this:
Please Sign up or sign in to vote.
A collection of freeware MFC classes to encapsulate the NT Performance Counters.
  • 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


    License

    This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

    A list of licenses authors might use can be found here

    Share

    About the Author

    PJ Naughter

    United States United States
    No Biography provided

    Comments and Discussions

     
    QuestionDoes it work? Pinmemberlzf89775-Dec-07 16:07 
    GeneralRe: Does it work? [modified] PinmemberVEMS17-Dec-07 6:50 
    GeneralWindows Variants PinmemberArron2131-Oct-07 7:47 
    Hello,
     
    Will this code only work on NT or would it work on other Windows Variants.
     
    Regards

    QuestionWindows 2000 ????? PinsussDaniel Madden26-Sep-00 10:33 
    AnswerRe: Windows 2000 ????? Pinmemberpjnaughter28-Jan-03 13:49 
    AnswerRe: Windows 2000 ????? PinmemberAlexander Fedorov3-Oct-05 0:59 
    AnswerRe: Windows 2000 ????? Pinmemberabibok10-May-06 0:28 
    GeneralPerformance data query PinsussPuneet11-Jul-00 17:38 
    GeneralRe: Performance data query PinsussPJ Naughter11-Jul-00 23:58 

    General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

    Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

    | Advertise | Privacy | Terms of Use | Mobile
    Web04 | 2.8.141223.1 | Last Updated 4 Mar 2000
    Article Copyright 2000 by PJ Naughter
    Everything else Copyright © CodeProject, 1999-2014
    Layout: fixed | fluid