CBS_Exception Class Reference

Base class of all exception classes. More...

Inheritance diagram for CBS_Exception:


Public Types
enum	BS_EX_SETTING { BS_EX_SETTING_NONE = 0x00, BS_EX_WRITE_TO_TRACE = 0x01, BS_EX_SHOW_MESSAGE_BOX = 0x02, BS_EX_EXIT_THREAD_IF_NONE_CONTINUABLE = 0x04, BS_EX_EXIT_PROC_IF_NONE_CONTINUABLE = 0x08, BS_EX_EXIT_THREAD_ALWAYS = 0x10, BS_EX_EXIT_PROC_ALWAYS = 0x20, BS_EX_THROW_ON_BREAKPOINT_EXCEPTION = 0x40, BS_EX_SETTING_DEFAULT = BS_EX_WRITE_TO_TRACE }
typedef void(*	FP_EXIT_PROCESS_CB )(LPVOID, CBS_Exception *)
typedef void(*	FP_EXIT_THREAD_CB )(LPVOID, CBS_Exception *)
typedef void(*	FP_FREE_LIB_CB )(LPVOID)
Public Member Functions
	DECLARE_BS_GENERAL_BASE_FUNCTIONS (CBS_Exception)
	DECLARE_DLL_OPERATORS (CBS_Exception::BS_EX_SETTING, GSUPPORT_IMP_EXP_DECL)
	DECLARE_SET_GET_MODE (CBS_Exception::BS_EX_SETTING, m_Setting, Setting)
	DECLARE_STATIC_SET_GET_MODE (CBS_Exception::BS_EX_SETTING, m_DefaultSetting, DefaultSetting)
virtual void	FreeResources (BOOL bFromDestructor=FALSE)
HWND	GetAppTopWnd ()
virtual DWORD	GetErrorMessage (LPTSTR lpMessage, DWORD dwBufLen)=NULL
DWORD	GetMBTimeout ()
CBS_Trace *	GetTrace ()
virtual CBS_Trace::BS_TRACE_MODE	GetTraceOutput ()=NULL
virtual BOOL	IsContinuable ()=NULL
virtual BOOL	ReportError (LPCSTR lpFileName, UINT nLine)
LPVOID	SetAppData (LPVOID lpAppData)
HWND	SetAppTopWnd (HWND hWnd)
FP_EXIT_PROCESS_CB	SetExitProcess (FP_EXIT_PROCESS_CB fpExitProcess)
FP_EXIT_THREAD_CB	SetExitThread (FP_EXIT_THREAD_CB fpExitThread)
DWORD	SetMBTimeout (DWORD dwTimeout)
CBS_Trace *	SetTrace (CBS_Trace *pTrace)
virtual	~CBS_Exception ()
Static Public Member Functions
HWND	GetDefaultAppTopWnd ()
DWORD	GetDefaultMBTimeout ()
CBS_Trace *	GetDefaultTrace ()
LPCTSTR	GetSettingFile ()
BOOL	IsInit ()
LPVOID	SetDefaultAppData (LPVOID lpAppData)
HWND	SetDefaultAppTopWnd (HWND hWnd)
FP_EXIT_PROCESS_CB	SetDefaultExitProcess (FP_EXIT_PROCESS_CB fpExitProcess)
FP_EXIT_THREAD_CB	SetDefaultExitThread (FP_EXIT_THREAD_CB fpExitThread)
DWORD	SetDefaultMBTimeout (DWORD dwTimeout)
CBS_Trace *	SetDefaultTrace (CBS_Trace *pTrace)
Protected Member Functions
	CBS_Exception ()
Protected Attributes
LPVOID	m_pExceptionData
	Private member for internal use.
BS_EX_SETTING	m_Setting
	The setting flags.
Static Protected Attributes
BS_EX_SETTING	m_DefaultSetting = CBS_Exception::BS_EX_SETTING_NONE
	The default setting, the m_Setting of every new object will be initiate with this value.

Detailed Description

Base class of all exception classes.

Author:: Dror Otmi

Date:: 12.10.2003

Version:: V 1.0 Initial version

Deriving all exceptions classes from this object bring the advantage of using one catch block for all exception, user defined and system exception (see derived class CBS_SE_Exception). The class provide an interface that lets the application decide how to react when an exception is raised. In addition, it searches during the startup the command line to see if the user wants to control the class's behavior during the execution time. The command:
-BSEX-f MySettingFile.ini
will cause the class to fetch the setting from MySettingFile.ini and to override the setting specified by the application.
The class is designed to open and fetch the settings from the file each time an exception is caught, so the user could change the setting during the runtime. Sample for a setting file:
#######################
[BS Exception Info]
Setting = 3
Timeout = 20000
TraceFile = TraceFromIni.txt
#######################
Setting := a bit combination of the member BS_EX_SETTING (see enumeration member bellow).
Timeout := the message box's timeout, -1 = infinite and 0 means the message box will not be displayed at all.
TraceFile := the trace file into which the exception should be written.

Another specialty of this class is the default values. All of the configuration values have a matched default values. At object creation time, the default values of the class will be assigned to the object configuration value. The object configuration value can be explicitly overwritten and do have higher priority at execution time.

Note:: The get and set functions of static and member variable are not thread safe, it make no sense to protect them because:
1.) The static member should be set once, it will be chaos if one module sets a value and another thread will overwrite it.
2.) The none static member will run in one thread: exceptions are thrown and catch within one thread, it can not be shared between threads.

Member Typedef Documentation

void(* CBS_Exception::FP_EXIT_PROCESS_CB)(LPVOID, CBS_Exception *)

An application defined callback function that will be invoked if the process should be exit upon exeption (see also CBS_Exception::BS_EX_SETTING).

void(* CBS_Exception::FP_EXIT_THREAD_CB)(LPVOID, CBS_Exception *)

An application defined callback function that will be invoked if the thread should be exit upon exeption (see also CBS_Exception::BS_EX_SETTING).

void(* CBS_Exception::FP_FREE_LIB_CB)(LPVOID)

A callback function of a decedent object that will be invoked when library is freed (CBS_GSupport::FreeGSupportLib()).

Member Enumeration Documentation

enum CBS_Exception::BS_EX_SETTING

This enum tells the object how to behave upon exception.
Enumeration values:

BS_EX_SETTING_NONE Do nothing

BS_EX_WRITE_TO_TRACE Write exception description to the trace

BS_EX_SHOW_MESSAGE_BOX Show a message box

BS_EX_EXIT_THREAD_IF_NONE_CONTINUABLE Exit the thread if the exception is none-continuable

BS_EX_EXIT_PROC_IF_NONE_CONTINUABLE Exit the process if the exception is none-continuable

BS_EX_EXIT_THREAD_ALWAYS Exit the thread on any exception

BS_EX_EXIT_PROC_ALWAYS Exit the process on any exception

BS_EX_THROW_ON_BREAKPOINT_EXCEPTION Throw exception when the exception is a debug break (throwing in this case will not open the debugger).

BS_EX_SETTING_DEFAULT Default setting, write to the trace only

Constructor & Destructor Documentation

CBS_Exception::CBS_Exception ( ) [protected]

The default constructor

CBS_Exception::~CBS_Exception ( ) [virtual]

The destructor

Member Function Documentation

CBS_Exception::DECLARE_BS_GENERAL_BASE_FUNCTIONS ( CBS_Exception )

Declares LPCTSTR GetClassName( ) and BOOL IsKindOf( LPCTSTR pCmp ) for CBS_Exception.

CBS_Exception::DECLARE_DLL_OPERATORS ( CBS_Exception::BS_EX_SETTING ,

GSUPPORT_IMP_EXP_DECL

)

Declares the operators &=, |=, & and | for the enum member CBS_Exception::BS_EX_SETTING in order to avoid compiler error (or casting).

CBS_Exception::DECLARE_SET_GET_MODE ( CBS_Exception::BS_EX_SETTING ,

m_Setting ,

Setting

)

Declares the folowing members function for manipulating the enum member m_Setting:

CBS_Exception::BS_EX_SETTING GetSettingMode( )
Return the value saved in the member m_Setting.

BOOL IsSettingModeSet( CBS_Exception::BS_EX_SETTING check )
Return TRUE if the setting mode saved in check is on.

CBS_Exception::BS_EX_SETTING SetSettingMode( CBS_Exception::BS_EX_SETTING )
Sets a new setting mode, returns the old setting mode.

CBS_Exception::BS_EX_SETTING AddSettingMode( CBS_Exception::BS_EX_SETTING )
Adds a new setting flag to the member m_Setting, returns the setting mode.

CBS_Exception::BS_EX_SETTING RemoveSettingMode( CBS_Exception::BS_EX_SETTING )
Removed a setting flag from the member m_Setting, returns the setting mode.

CBS_Exception::BS_EX_SETTING SetDefaultSettingMode()
Sets the default setting mode to the member m_Setting, returns the old setting mode.

CBS_Exception::DECLARE_STATIC_SET_GET_MODE ( CBS_Exception::BS_EX_SETTING ,

m_DefaultSetting ,

DefaultSetting

)

Declares the folowing members function for manipulating the enum member m_DefaultSetting:

CBS_Exception::BS_EX_SETTING GetDefaultSettingMode( )
Return the value saved in the member m_DefaultSetting.

BOOL IsDefaultSettingModeSet( CBS_Exception::BS_EX_SETTING check )
Return TRUE if the default setting mode saved in check is on.

CBS_Exception::BS_EX_SETTING SetDefaultSettingMode( CBS_Exception::BS_EX_SETTING )
Sets a new default setting mode, returns the old default setting mode.

CBS_Exception::BS_EX_SETTING AddDefaultSettingMode( CBS_Exception::BS_EX_SETTING )
Adds a new default setting flag to the member m_DefaultSetting, returns the default setting mode.

CBS_Exception::BS_EX_SETTING RemoveDefaultSettingMode( CBS_Exception::BS_EX_SETTING )
Removed a default setting flag from the member m_DefaultSetting, returns the default setting mode.

CBS_Exception::BS_EX_SETTING SetDefaultDefaultSettingMode()
Sets the default default setting mode to the member m_DefaultSetting, returns the old default setting mode.

void CBS_Exception::FreeResources ( BOOL bFromDestructor = FALSE ) [virtual]

Free the resources allocated by the current object.
Parameters:

bFromDestructor If the call was done from the destructor or not.

Returns:
Nothing.

Reimplemented in CBS_SE_Exception, CBS_SocketException, and CBS_UserException.

HWND CBS_Exception::GetAppTopWnd ( )

See return.
Returns:
The window handle of the application top window, the parent window of any message box that will be opened by the object.

HWND CBS_Exception::GetDefaultAppTopWnd ( ) [static]

See return.
Returns:
The default application top window of the exception class. The handle of this window is the default parent window of the message boxes that will be opened.

DWORD CBS_Exception::GetDefaultMBTimeout ( ) [static]

See return.
Returns:
The default timeout of the exception class.

CBS_Trace * CBS_Exception::GetDefaultTrace ( ) [static]

See return.
Returns:
A pointer of the default trace.

DWORD CBS_Exception::GetErrorMessage ( LPTSTR lpMessage,

DWORD dwBufLen

) [virtual]

The descendend classes must implement this function. This function is invoked from the base class, when it catches an exception, it expect the descended to format a message describing the exception in lpMessage. If the buffer is too small or lpMessage is NULL it expect the descendet to return the number of bytes needed for the message.
Parameters:

lpMessage The buffer in which the message will be formatted.

dwBufLen The length in bytes of lpMessage.

Returns:
The length of the formatted message.

Reimplemented in CBS_SE_Exception, CBS_SocketException, and CBS_UserException.

DWORD CBS_Exception::GetMBTimeout ( )

See return.
Returns:
The message box timeout.

LPCTSTR CBS_Exception::GetSettingFile ( ) [static]

See return.
Returns:
The file name of the setting file or NULL if no setting file is available.

CBS_Trace * CBS_Exception::GetTrace ( )

See return.
Returns:
The pointer to the trace object that is currently associated with the object.

CBS_Trace::BS_TRACE_MODE CBS_Exception::GetTraceOutput ( ) [virtual]

During the formatting this method will be invoked to get the trace output of the exception. For example an STL exception will return CBS_Trace::BS_REPORT_STL_EXCEPTION_INFO.
Returns:
The exception type of the current derived class.

Reimplemented in CBS_SE_Exception, CBS_SocketException, and CBS_UserException.

BOOL CBS_Exception::IsContinuable ( ) [virtual]

See return.
Returns:
TRUE if the exception is a contiuable, none-contiuable exception are very rare.

Reimplemented in CBS_SE_Exception, CBS_SocketException, and CBS_UserException.

BOOL CBS_Exception::IsInit ( ) [static]

Checks if the exception class is initialized. The exception class is loaded automatically when CBS_GSupport::LoadGSupportLib() is called.
Returns:
TRUE if the library is loaded.

BOOL CBS_Exception::ReportError ( LPCSTR lpFileName,

UINT nLine

) [virtual]

Report an exception. This function should be called by the application in it's catch block.
This function is defined by a macro as:
#define ReportError() ReportError(__FILE__,__LINE__)

Parameters:

lpFileName The file in which the call is made.

nLine The line in lpFileName.

Returns:
FALSE if the setting mode is BS_EX_SETTING_NONE otherwise the return value is always TRUE.

LPVOID CBS_Exception::SetAppData ( LPVOID lpAppData )

Set a pointer to an application defined data that will be passed with the exit process respective thread callback function.
Parameters:

lpAppData An application defined data.

Returns:
The old pointer associated with the object.

HWND CBS_Exception::SetAppTopWnd ( HWND hWnd )

Sets the application top window handle to the object. Any message box opened when an exception is caught, will use this handle as the parent window.
Parameters:

hWnd A handle of the application top window.

Returns:
The old window handle associated with the current object.

LPVOID CBS_Exception::SetDefaultAppData ( LPVOID lpAppData ) [static]

Sets the default pointer to the application defined data which will be passed as argument to the exit tread and process callback functions.
Parameters:

lpAppData A pointer to an application defined data.

Returns:
The pointer to the old application data.

HWND CBS_Exception::SetDefaultAppTopWnd ( HWND hWnd ) [static]

Sets the default window handle of the application. This handle used as the parent window of any message box that will opened when an exception will caught.
Parameters:

hWnd A handle of the application main window.

Returns:
The old default window handle.

CBS_Exception::FP_EXIT_PROCESS_CB CBS_Exception::SetDefaultExitProcess ( FP_EXIT_PROCESS_CB fpExitProcess ) [static]

Sets the exit process callback function pointer to the exception class.
Parameters:

fpExitProcess The default exit process callback function pointer.

Returns:
The previous default exit process callback.

CBS_Exception::FP_EXIT_THREAD_CB CBS_Exception::SetDefaultExitThread ( FP_EXIT_THREAD_CB fpExitThread ) [static]

Sets the exit process callback function pointer to the exception class.
Parameters:

fpExitThread The default exit thread callback function pointer.

Returns:
The previous default exit thread callback.

DWORD CBS_Exception::SetDefaultMBTimeout ( DWORD dwTimeout ) [static]

Sets the default time out for the exception class.
Parameters:

dwTimeout The new default timeout.

Returns:
The previous default timeout.

CBS_Trace * CBS_Exception::SetDefaultTrace ( CBS_Trace * pTrace ) [static]

Sets the default trace to the exception class.
Parameters:

pTrace The new default trace.

Returns:
The previous default trace.

CBS_Exception::FP_EXIT_PROCESS_CB CBS_Exception::SetExitProcess ( FP_EXIT_PROCESS_CB fpExitProcess )

Sets an application defined exit process callback function that will be invoked if the flag BS_EX_EXIT_PROC_ALWAYS respective BS_EX_EXIT_PROC_IF_NONE_CONTINUABLE if the exception caught is a non continuable exception, is set.
Parameters:

fpExitProcess An application defined exit process callback function.

Returns:
The old function pointer associated with the object.

CBS_Exception::FP_EXIT_THREAD_CB CBS_Exception::SetExitThread ( FP_EXIT_THREAD_CB fpExitThread )

Sets an application defined exit thread callback function that will be invoked if the flag BS_EX_EXIT_THREAD_ALWAYS respective BS_EX_EXIT_THREAD_IF_NONE_CONTINUABLE if the exception caught is a non continuable exception, is set.
Parameters:

fpExitThread An application defined exit process callback function.

Returns:
The old function pointer associated with the object.

DWORD CBS_Exception::SetMBTimeout ( DWORD dwTimeout )

Sets the message box timeout to the object, -1 = infinite timeout.
Parameters:

dwTimeout The new timeout.

Returns:
The old message box timeout associated with the object.

CBS_Trace * CBS_Exception::SetTrace ( CBS_Trace * pTrace )

Sets a trace object to the current object.
Parameters:

pTrace The new trace.

Returns:
The function return a pointer to the old trace object associated with the current object.

Bitspot AG

Bitspot AG Rietlistrasse 1 CH-6345 Neuheim
Phone:	+41 41 755 11 22
Fax:	+41 41 755 11 31
e-mail:	mail@bitspot.com
Web:	www.bitspot.com

CBS_Exception Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation