Handling Windows API Errors with CWinException

• Download demo project - 34.3 KB
• Download source - 3 KB

Introduction

When using the Windows API, I think that it is better to get a well-formatted error description rather than its unmeaningful code. I also thought it may be useful that when you have some class based mostly on Win32 API functions to have it throw exceptions that can be handled in the caller block if needed. CWinException class solves those problems - it is derived from MFC's CException class and can be thrown by any API function that sets the 'last error' if it fails. Also, if a function does not set the last error, then you can set the last error to an appropriate value from the source block and catch the exception in the caller block.

Description

The CWinException class makes it possible to get the last error, set the value of the last error, or clear it (set it to ERROR_SUCCESS). It can also get a formatted error description and report it.

Usage

void CService::Start_1(void) throw()
{
    if (!::StartService(m_schService,    // handle to service
            NULL,        // number of arguments 
            NULL))        // no arguments
    {
        throw new CWinException();
    }
}

// Or:

BOOL CService::Start_2(void)
{
    return ::StartService(m_schService, NULL, NULL);
}

// Exception handling

// Header
include "WinException.h"
include "Service.h"
//...
public:
    CService m_cService;
//...

// cpp file
//...

void CMainFrame::OnStartService_1(void)
{
    try
    {
        m_cService.Start_1();
    }
    catch(CWinException* e)
    {
        e->ReportError();
		e->Delete();
    }
}

// Or:

void CMainFrame::OnStartService_2(void)
{
    if(m_cService.Start_1() == FALSE)
    {
        CWinException e;
        e.ReportError();
    }
}

Base Class

• CException

Class Members

• CWinException() - default constructor, gets last error on initialize
• CWinException(DWORD dwErrCode) - sets last error code to dwErrCode on initialize

• operator LPCTSTR() const - gives direct access to error description stored in CString type private variable
• operator DWORD() const - gives direct access to error code stored in DWORD type private variable

• BOOL SetLastError(DWORD dwErrorCode) - sets last error to dwErrorCode, returns TRUE if successful
• DWORD GetLastError(void) - regets last error code and returns it

• BOOL ToString(DWORD dwErrorCode, CString& szError) - writes dwErrCode error description to szError, returns TRUE if successful
• BOOL GetLastErrorString(CString& szLastError) - writes last error description to szError, returns TRUE if successful.
• void ClearLastError(void) - sets last error to 0 (ERROR_SUCCESS), clears it.

• virtual BOOL GetErrorMessage( LPTSTR lpszError, UINT nMaxError, PUINT pnHelpContext = NULL ) - provides text about an error that has occurred. Returns true if successful.
  • lpszError - a pointer to a buffer that will receive an error message
  • nMaxError - the maximum number of characters the buffer can hold, including the NULL terminator. If NULL, all characters will be written.
  • pnHelpContext - always NULL

• virtual int ReportError( UINT nType = MB_OK, UINT nMessageID = 0) - reports error text in a message box to the user. Returns an AfxMessageBox value.
  • nType - any combination of the message-box styles.
  • nMessageID - Specifies the resource ID (string table entry) of a message to add to the standard error message string (Run-time error : %d) if not NULL.

History

• 26^th December, 2001: Initial version