The Ultimate Toolbox Utility Classes

The Ultimate Toolbox

4.38/5 (5 votes)

Aug 24, 2007

CPOL

5 min read

45041

The Ultimate Toolbox Utility classes deal with Memory, Clipboard, Parsing, etc.

Visit the Ultimate Toolbox main page for an overview and configuration guide to the Ultimate Toolbox library.

Introduction
Advanced Assert
Application State
Checksum and CRC
Clipboard
Command Line Processing
Large Integers
Memory
NT Event Processing
NT Services
Parsing
Process
Resource
Result Codes
Serialization
Sound Effects
Structured Exception Handling
System Information
Timer
TRACE
Version Information
Registry
History
Comments

Introduction

The Ultimate Toolbox Utility section contains classes that cover several areas of Windows programming that you might not ever care about... until you need them.

Advanced Assert

    int nMonth = 0;
    ASSERT( (nMonth >= 1) && (nMonth <=12) );

COXAdvancedAssert and COXAdvancedAssertMail can be used to invoke a custom assert dialog that can send a problem report via email.

Application State

Classes for saving/restoring application state and managing instances of a program.

     // save state to file...

     COXWorkspaceState workspaceState;
     workspaceState.StoreToFile("C:\\App.wsp");

     // or registry...

     workspaceState.StoreToRegistry();       // optionally specify value, 

                                             // company, app name etc.

Checksum and CRC

A collection of classes for performing both simple integrity and cyclic redundancy checks.

Class COXCheckBase is the abstract base class used for deriving the classes which carry out integrity checking on data buffers.

The pure virtual function CalculateBlock() needs to be implemented by the derived classes.

Five derived classes - COXCheckSum8, COXCheckSum16, COXCheckSum32, COXCRC16, and COXCRC32 are provided for calculating 8, 16, and 32-bit checks. Note that the COXCheckSum... classes are the simplest integrity check methods (each involves a simple summation of each byte of data), while the COXCRC... classes perform cyclic redundancy checks.

Clipboard

Classes that allow for monitoring and access to separate blocks of clipboard data. The COXMulticlipboardDlg manages a number of COXClipPocket objects which are populated as the clipboard is monitored.

     ...
     COXClipPocket* pPocket=GetPocket(nPocketNumber);
     ASSERT(pPocket);

     COXToolTipCtrl* pTip=GetToolTip();

          if (pPocket->GetDataType()==CF_TEXT)
          {
               tOXData* pData=pPocket->GetData();
               ...

Command Line Processing

(Archived*) Classes for command line parsing.

*Archived classes can be found in the archive\source and archive\include directories - there may or may not be a usage example project in the archive\samples dir. There should still be class information in the compiled HTML help documentation. These classes were classified as unsupported in the last commercial version (9.2) of the Ultimate Toolbox, and have not be updated for VS2005 compilation.

Large Integers

The COXInteger class can be used to represent large integers and/or perform radix conversions.

    COXInteger integer;
    integer.SetStringNumber(m_sInput, nRadixIn);
    m_sOutput = integer.GetStringNumber(nRadixOut, m_bSeparated);

    // Test conversion features

    COXInteger a(_T("7B"), 16);
    COXInteger b(456);
    COXInteger c;

    ASSERT(a == 123);

    c = a + b;
    ASSERT(c == 579);

    a = b / 3;
    ASSERT(a == 152);

    c = c - 79;
    ASSERT(c == 500);
    ASSERT(c.GetStringNumber(2) == _T("111110100"));

Memory

COXWatchBuffer is a very simple class that allows you to monitor modifications to an array of bytes in memory.

Here, m_convertedBuffer is populated from a file, and later checked for modifications:

     while ((nRead < nCount) && !bEOF)
     {
          // First give caller the bytes that are in the buffer

          nCopy = __min(nCount - nRead, (UINT)(m_nBufferLength - 
              m_nBufferPos));
          if (nCopy != 0)
               memcpy(lpBuf, m_convertedBuffer.Get(m_nBufferPos), nCopy);
               lpBuf = LPBYTE(lpBuf) + nCopy;
               m_nBufferPos += nCopy;
               nRead += nCopy;
               ...
     if (!m_convertedBuffer.IsModified())
          return;

     // file has changed - write buffer

     ...
     // ... Mark as unmodified and read from file (because we have just 

     // written it)

     m_convertedBuffer.SetModified(FALSE);

NT Event Processing

The COXEventLog class provides NT Event log processing capabilities.

        switch(m_nEvent)
        {
        case 0:
            {
                /* Set up our array of insert strings for error message */
                aInsertStrs[0] = _T("test.cpp");
                aInsertStrs[1] = _T("Z");

                m_EventLog.Report(eventError, MSG_FILE_NOT_FOUND, 0, 2, 
                    aInsertStrs);
                break;
            }
        case 1:
            {
                m_EventLog.Report(eventWarning, MSG_UNABLE_START_GUARDIAN);
                break;
            }

NT Services

Classes for enumerating and creating NT services.

    if (m_itersrv.StartIteration())
        UpdateServiceList();
    else
        AfxMessageBox(_T("Failed to enumerate services."));

Parsing

HTML, XML, and regular expression parsers.

    CParserViewDoc* pDoc = GetDocument();
    COXParser* pParser = pDoc->GetParser();

    HTREEITEM hItem = GetTreeCtrl().InsertItem(pParser->Root()->GetName(), 
                                               m_nCloseFolder, 
                                               m_nCloseFolder);
    GetTreeCtrl().SetItemData(hItem, (DWORD) pParser->Root());

    CWaitCursor wait;
    FillTree(hItem, pParser->Root());

Process

The COXProcess and COXProcessIterator classes for combine to provide for iterating and retrieving process properties.

    if(m_process.GetProcessImageFileName(               
        m_arrAppInfo[nIndex].dwProcessID,sValue))
        {
            htiItem=InsertItem(_T("Executable"),htiRoot);
            ...

Resource

Classes for identifying resources in files.

The samples\utility\resfile sample in action.

See the Resource File article for more on these classes.

Result Codes

(Archived*) The COXResultPart and COXResultObj classes facilitate parsing and creating HRESULT codes.

*Archived classes can be found in the archive\source and archive\include directories. These directories are contained in the sample projects download. There may or may not be a usage example project in the archive\samples dir. There should still be class information in the compiled HTML help documentation. These classes were classified as unsupported in the last commercial version (9.2) of the Ultimate Toolbox, and have not be updated for VS2005 compilation.

Serialization

(Archived*) The COXSerializer class encapsulates serialization and exception handling for any CObject based class.

Sound Effects

COXSoundEffectManager and COXSoundEffectOrganizer manage sound effects for controls within your application.

See the Sound Manager article for more on these classes.

Structured Exception Handling

(Archived*) The COXSEHException class can trap various categories of SEH exceptions and translate to MFC exceptions.

System Information

COXSysInfo in action.

COXSysInfo can provide easy access to various categories of windows version, network, and physical machine resources.

See the System Info article for more the usage of the COXSysInfo class.

Timer

Fine grained synchronous and asynchronous timing.

The unit that is used throughout the COXTimer class is the ns (nanosecond). This granularity is fine enough for all applications because it is quicker than the hardware clock frequency. If you have a 200 MHz processor the clock will produce a pulse every 5 ns.

This also means that when you can specify a parameter in nanoseconds it is possible that the underlying hardware (and the Windows API) is not capable of such a fine accuracy. Where possible the actual resolution is provided.

COXTimer timer;
LONGLONG acc = timer.GetIntervalAccuracy();

COXTimer can be used to measure intervals by calling StartInterval and StopInterval on a particular timer object, or can be set to provide a notification by invoking a specified callback function:

void CallBack(COXTimer* pTimer) {
     ...
};

m_timer.StartNotifier(nDelay, pfCallback, bPeriodic, bSynchronized, 
    nAccuracy);

TRACE

COXTrace provides some simple extensions for the MFC TRACE macro.

Built-in word wrapping
Copying of the trace output to a file
Automatic marking of the start and end of a block of code
Automatic indenting of the messages to provide a way to track nesting of COXTrace blocks.

void CMyClass::MyFunction(int length)
{
COXTRACE("Entering MyFunction"); // initializes COXTrace for this scope


OXTRACE_WRITE("Hello world... etc.");
// Note: you can also call OXTRACE_SETDUMPFILE to set an optional

// output dump file, OXTRACE_WRAPWIDTH to set the line wrap

// width, etc.

// ...

}

Version Information

A simple class to read version information from a file.

After calling COXVersionInfo::ReadInfo with the module name, the following public data members can be examined:

DWORD m_dwSignature;
DWORD m_dwStrucVersion;
DWORD m_dwFileVersionMS;
DWORD m_dwFileVersionLS;
DWORD m_dwProductVersionMS;
DWORD m_dwProductVersionLS;
DWORD m_dwFileFlagsMask;
DWORD m_dwFileFlags;
DWORD m_dwFileOS;
DWORD m_dwFileType;
DWORD m_dwFileSubtype;
DWORD m_dwFileDateMS;
DWORD m_dwFileDateLS;

DWORD m_dwLanguageCountryID;
CString m_sLanguageCountry;

CString m_sComments;
CString m_sCompanyName;
CString m_sFileDescription;
CString m_sFileVersion;
CString m_sInternalName;
CString m_sLegalCopyright;
CString m_sLegalTrademarks;
CString m_sOriginalFilename;
CString m_sPrivateBuild;
CString m_sProductName;
CString m_sProductVersion;
CString m_sSpecialBuild;

Registry

Classes for accessing and monitoring the registry.

COXRegistryIteratorItem allows for iterating registry keys and subkeys, while COXRegistryItem encapsulates a registry item.

History

Initial CodeProject release August 2007.

The Ultimate Toolbox Utility Classes

Contents