CBS_Trace Class Reference

A class for tracing and logging information. More...

List of all members.

Public Types

enum BS_TRACE_MODE {
  BS_REPORT_NONE = 0x0000, BS_REPORT_INFORMATION = 0x0001, BS_REPORT_WARNING = 0x0002, BS_REPORT_ERROR = 0x0004,
  BS_REPORT_FATAL_ERROR = 0x0008, BS_REPORT_DEBUG_INFO = 0x0010, BS_REPORT_SYS_EXCEPTION_INFO = 0x0020, BS_REPORT_BS_EXCEPTION_INFO = 0x0040,
  BS_REPORT_MFC_EXCEPTION_INFO = 0x0080, BS_REPORT_STL_EXCEPTION_INFO = 0x0100, BS_REPORT_USER_EXCEPTION_INFO = 0x0200, BS_REPORT_VERBOSE = BS_REPORT_DEBUG_INFO,
  BS_REPORT_ALL = 0xffff, BS_REPORT_ALL_EXCEPTIONS, BS_REPORT_ERORRS_AND_HIGHER = BS_REPORT_ALL_EXCEPTIONS|BS_REPORT_FATAL_ERROR|BS_REPORT_ERROR, BS_REPORT_WARNING_AND_HIGHER = BS_REPORT_ERORRS_AND_HIGHER|BS_REPORT_WARNING,
  BS_REPORT_INFORMATION_AND_HIGHER = BS_REPORT_WARNING_AND_HIGHER|BS_REPORT_INFORMATION, BS_REPORT_DEFAULT = BS_REPORT_ALL
}

enum BS_TRACE_OUTPUT {
  BS_OUTPUT_NONE = 0x00, BS_OUTPUT_FILE = 0x01, BS_OUTPUT_SOCKET = 0x02, BS_OUTPUT_EVENT_VIEW = 0x04,
  BS_OUTPUT_DEBUG_WINDOW = 0x08, BS_OUTPUT_CONSOLE = 0x10, BS_OUTPUT_DEFAULT = BS_OUTPUT_DEBUG_WINDOW
}

enum BS_TRACE_TIME { BS_LOCAL_TIME = 1, BS_GMT_TIME = 2, BS_DEFAULT_TIME = BS_LOCAL_TIME }

typedef BOOL(* FP_SOCKET_HOOK )(LPSOCKET_HOOK)

typedef CBS_Trace::SocketHook_st * LPSOCKET_HOOK

A structure that will be passed with the socket hook callback function.

typedef CBS_Trace::SocketHook_st SOCKET_HOOK

A structure that will be passed with the socket hook callback function.

Public Member Functions

BOOL AttachFile (LPCTSTR lpNewFile)

CBS_Trace ()

BOOL ChangeFile (LPCTSTR lpNewFile, LPCTSTR lpCloseComment=NULL)

long CloseControlDlg ()

BOOL ConnectServer (DWORD dwIP, WORD wPort, BOOL bEnable=TRUE)

BOOL ConnectServer (LPCTSTR lpIP, WORD wPort, BOOL bDNSName, BOOL bEnable=TRUE)

BOOL CopyTraceFile (LPCTSTR lpNewFile)

DECLARE_DLL_OPERATORS (CBS_Trace::BS_TRACE_OUTPUT, GSUPPORT_IMP_EXP_DECL)

DECLARE_DLL_OPERATORS (CBS_Trace::BS_TRACE_MODE, GSUPPORT_IMP_EXP_DECL)

DECLARE_SET_GET_MODE (CBS_Trace::BS_TRACE_OUTPUT, m_stoOutput, Output)

DECLARE_SET_GET_MODE (CBS_Trace::BS_TRACE_MODE, m_stmReportMode, Report)

BOOL DeregisterEventSource ()

BOOL DeregisterExternEventSource (HANDLE hEventSource)

BOOL DetachFile (LPCTSTR lpReason=BS_TRACE_UNSPECIFIED)

BOOL DisconnectServer ()

DWORD FormatError (LPTSTR lpBuffer, DWORD dwBufLen)

void FreeResources ()

DWORD GetDefaultEventID ()

long GetFileMaxSize (char *pBuf, long lBufSize)

long GetFileMaxSize ()

BS_TRACE_ERRORS GetLastError ()

LPCTSTR GetLastErrorString (BS_TRACE_ERRORS steError)

LPCTSTR GetMillisecondDelimiter ()

BOOL GetPrintFileName ()

LPCTSTR GetReportTypeString (BS_TRACE_MODE)

SOCKET GetSocket ()

FP_SOCKET_HOOK GetSocketHook ()

virtual void GetTime (LPSYSTEMTIME lpSystemTime)

LPCTSTR GetTraceDateFormat ()

LPCTSTR GetTraceFileName ()

LPCTSTR GetTraceTimeFormat ()

BS_TRACE_TIME GetUsedTime ()

BOOL HaveEventSource ()

BOOL HaveFile ()

BOOL HaveSocket ()

BOOL IsOutputSupported (BS_TRACE_OUTPUT sto)

BOOL IsSystemError (BS_TRACE_ERRORS steError)

BOOL OpenControlDlg (HWND hParent)

BOOL RegisterEventSource (LPCTSTR lpSourceName)

BOOL RegisterEventSource (LPCTSTR lpServerName, LPCTSTR lpSourceName)

HANDLE RegisterExternEventSource (LPCTSTR lpSourceName)

HANDLE RegisterExternEventSource (LPCTSTR lpServerName, LPCTSTR lpSourceName)

SOCKET RemoveSocket ()

BOOL ReportEvent (WORD wType, DWORD dwEventID, LPCTSTR lpString=NULL)

BOOL ReportEvent (WORD wType, DWORD dwEventID, LPCTSTR *lpStrings, WORD wNumberOfStrings, DWORD dwDataSize=0, LPVOID lpRowData=NULL)

BOOL ReportExternEvent (HANDLE hEventSource, WORD wType, DWORD dwEventID, LPCTSTR lpString=NULL)

BOOL ReportExternEvent (HANDLE hEventSource, WORD wType, DWORD dwEventID, LPCTSTR *lpStrings, WORD wNumberOfStrings, DWORD dwDataSize=0, LPVOID lpRowData=NULL)

BOOL ReportMessage (BS_TRACE_MODE stmType, LPCTSTR lpFileName, UINT nLine, LPCTSTR lpModuleName, LPTSTR lpMessage,...)

BOOL ReportMessage (BS_TRACE_MODE stmType, LPCTSTR lpModuleName, LPTSTR lpMessage,...)

BOOL SetDateFormat (LPCTSTR lpDateFormat)

void SetDefaultEventID (DWORD dwEventID)

BOOL SetFileMaxSize (LPCTSTR lpcMaxSize)

void SetFileMaxSize (DWORD dwMaxSize)

void SetLastError (BS_TRACE_ERRORS steError)

void SetMillisecondDelimiter (LPCTSTR lpMilliSecondDelimiter)

void SetPrintFileName (BOOL bPrint)

SOCKET SetSocket (SOCKET socket, BOOL bEnable=TRUE)

void SetSocketHook (FP_SOCKET_HOOK fpSocketHook, LPVOID lpAppData)

BOOL SetTimeFormat (LPCTSTR lpTimeFormat)

void UseGMTTime ()

void UseLocalTime ()

virtual ~CBS_Trace ()

Static Public Member Functions

DWORD GetSysErrorString (int iError, LPTSTR lpBuf, DWORD dwBufLen)

LPCSTR GetWSAErrorString (int iWSAError)

Detailed Description

A class for tracing and logging information.

Author:: Dror Otmi

Date:: 12.07.2003

Version:: V 1.0 Initial version CBS_Trace, as the name already indicates, is a class that provides a comfortable interface for tracing a chronological occurrences. Tracking mechanism is an essential part of almost evry application, this implementation provides a comprehensive functionality for tracing the occurrences during processing with deferent message levels and outputs. CBS_Trace supports the following message types (levels):
Information
Warning
Error
Fatal Error
System Exceptions
MFC Exceptions
STL Exceptions
User Exceptions
Debug (or Verbose) information

and outputs:
File
Socket
Event Viewer
Debug Window (only if a debugger is present version)

Member Typedef Documentation

typedef BOOL(* CBS_Trace::FP_SOCKET_HOOK)(LPSOCKET_HOOK)

An application defined callback that will be invoked if writing to the socket was not success. If this funtion return TRUE, the trace will retry to send the data else the writing to the socket function will terminate with failures.

Member Enumeration Documentation

enum CBS_Trace::BS_TRACE_MODE

This enum defines the different message levels.
Enumeration values:

BS_REPORT_NONE Report nothing.

BS_REPORT_INFORMATION Report Information Messages.

BS_REPORT_WARNING Report Warning Messages.

BS_REPORT_ERROR Report Error Messages.

BS_REPORT_FATAL_ERROR Report Fatal Error Messages.

BS_REPORT_DEBUG_INFO Report Debug information Messages.

BS_REPORT_SYS_EXCEPTION_INFO Report System Exception Messages.

BS_REPORT_BS_EXCEPTION_INFO Report Bitspot Exception Messages.

BS_REPORT_MFC_EXCEPTION_INFO Report MFC Exception Messages.

BS_REPORT_STL_EXCEPTION_INFO Report STL Exception Messages.

BS_REPORT_USER_EXCEPTION_INFO Report User Exception Messages.

BS_REPORT_VERBOSE Report Verbose Messages (the same as debug messages).

BS_REPORT_ALL Report All Messages.

BS_REPORT_ALL_EXCEPTIONS Report All Exception Messages.

BS_REPORT_ERORRS_AND_HIGHER Report Error and higher Messages.

BS_REPORT_WARNING_AND_HIGHER Report warning and higher Messages.

BS_REPORT_INFORMATION_AND_HIGHER Report information and higher Messages.

BS_REPORT_DEFAULT The default setting, report all.

enum CBS_Trace::BS_TRACE_OUTPUT

Enumeration of the supported output target.
Enumeration values:

BS_OUTPUT_NONE No output.

BS_OUTPUT_FILE Write output to file.

BS_OUTPUT_SOCKET Write output to socket.

BS_OUTPUT_EVENT_VIEW Write output to event log.
Note:
This feature is only available on Windows XP, NT and 2000.

BS_OUTPUT_DEBUG_WINDOW Write output to debug window (if presence).

BS_OUTPUT_CONSOLE Write output to the console.

BS_OUTPUT_DEFAULT Default setting for the ouput.

enum CBS_Trace::BS_TRACE_TIME

Enumeration of the time that should be use in the formatted message.
Enumeration values:

BS_LOCAL_TIME Use local time.

BS_GMT_TIME Use GMT time.

BS_DEFAULT_TIME The default time (local).

Constructor & Destructor Documentation

CBS_Trace::CBS_Trace ( )

Constructor

CBS_Trace::~CBS_Trace ( ) [virtual]

Destructor

Member Function Documentation

BOOL CBS_Trace::AttachFile ( LPCTSTR lpNewFile )

Attach a file to the object. If the file exists the messages will be appended. If the file size is bigger then the maximal size (see SetFileMaxSize()) the file will be overwritten. If the file does not exists, a new file will be created.
Note:
The file is open as share read but for exclusive write!

Parameters:

lpNewFile The new file name.

Returns:
TRUE if the file was successfully attached to the object.

BOOL CBS_Trace::ChangeFile ( LPCTSTR lpNewFile,

LPCTSTR lpCloseComment = NULL

)

Changes the file that is currently attached to the object.
Parameters:

lpNewFile The new file name.

lpCloseComment A closure comment (see also DetachFile()). If this parameter is NULL (deafult) the following string fill be inserted: "A new file ('%s') will be set to the object."

Returns:
TRUE if succeed.

long CBS_Trace::CloseControlDlg ( )

Closes the the settings controls dialox box of the current object.
Returns:
:
1 if the dialog box was successfully closed.
0 if closing the dialog box return with a failure.
-1 if function that close the dialog could not be invoked.
-2 if the dialog box is not opened.
If the function return -1 or 0, the application should invoke the member GetLastError() to evaluate the failure.

Note:
The dialog box is loaded from the DLL "BS_TraceCtrl.dll" respective "BS_TraceCtrld.dll" for debug version. If this DLL does not exists or saved in an unkown path, the function will return -1.

BOOL CBS_Trace::ConnectServer ( DWORD dwIP,

WORD wPort,

BOOL bEnable = TRUE

)

Connecting a remote server. This method is very usfull if one wants to write all output to a remote server.
Parameters:

dwIP The server address.

wPort The port.

bEnable TRUE if the output CBS_Trace::BS_OUTPUT_SOCKET should be set to the object if the connect was successful.

Returns:
TRUE if succeed.

BOOL CBS_Trace::ConnectServer ( LPCTSTR lpIP,

WORD wPort,

BOOL bDNSName,

BOOL bEnable = TRUE

)

Connecting a remote server. This method is very usfull if one wants to write all output to a remote server.
Parameters:

lpIP The server address either DNS (e.g. www.myserver.com) or IP (e.g. 100.1.1.2).

wPort The port.

bDNSName TRUE if lpIP is a DNS Name.

bEnable TRUE if the output CBS_Trace::BS_OUTPUT_SOCKET should be set to the object if the connect was successful.

Returns:
TRUE if succeed.

BOOL CBS_Trace::CopyTraceFile ( LPCTSTR lpNewFile )

Copies the currently attached file to a new file.
Parameters:

lpNewFile The name of the file into which the trace file should be copied.

Returns:
TRUE if succeed.

CBS_Trace::DECLARE_DLL_OPERATORS ( CBS_Trace::BS_TRACE_OUTPUT ,

GSUPPORT_IMP_EXP_DECL

)

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

CBS_Trace::DECLARE_DLL_OPERATORS ( CBS_Trace::BS_TRACE_MODE ,

GSUPPORT_IMP_EXP_DECL

)

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

CBS_Trace::DECLARE_SET_GET_MODE ( CBS_Trace::BS_TRACE_OUTPUT ,

m_stoOutput ,

Output

)

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

CBS_Trace::BS_TRACE_OUTPUT GetOutputMode( )
Return the value saved in the member m_stoOutput.

BOOL IsOutputModeSet( CBS_Trace::BS_TRACE_OUTPUT check )
Return TRUE if the trace mode saved in check is on.

CBS_Trace::BS_TRACE_OUTPUT SetOutputMode( CBS_Trace::BS_TRACE_OUTPUT )
Sets a new trace output mode, returns the old output mode.

CBS_Trace::BS_TRACE_OUTPUT AddOutputMode( CBS_Trace::BS_TRACE_OUTPUT )
Adds a new trace output flag to the member m_stoOutput, returns the old output mode.

CBS_Trace::BS_TRACE_OUTPUT RemoveOutputMode( CBS_Trace::BS_TRACE_OUTPUT )
Removed a trace output flag from the member m_stoOutput, returns the old output mode.

CBS_Trace::BS_TRACE_OUTPUT SetDefaultOutputMode()
Sets the default trace output mode to the member m_stoOutput, returns the old output mode.

CBS_Trace::DECLARE_SET_GET_MODE ( CBS_Trace::BS_TRACE_MODE ,

m_stmReportMode ,

Report

)

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

CBS_Trace::BS_TRACE_MODE GetReportMode( )
Return the value saved in the member m_stmReportMode.

BOOL IsReportModeSet( CBS_Trace::BS_TRACE_MODE check )
Return TRUE if the trace mode saved in check is on.

CBS_Trace::BS_TRACE_MODE SetReportMode( CBS_Trace::BS_TRACE_MODE )
Sets a new report mode, returns the old report mode.

CBS_Trace::BS_TRACE_MODE AddReportMode( CBS_Trace::BS_TRACE_MODE )
Adds a new report flag to the member m_stmReportMode, returns the old report mode.

CBS_Trace::BS_TRACE_MODE RemoveReportMode( CBS_Trace::BS_TRACE_MODE )
Removed a report flag from the member m_stmReportMode, returns the old report mode.

CBS_Trace::BS_TRACE_MODE SetDefaultReportMode()
Sets the default report mode to the member m_stmReportMode, returns the old report mode.

BOOL CBS_Trace::DeregisterEventSource ( )

Deregister the event source used by the current object.
Returns:
TRUE if succeed.

BOOL CBS_Trace::DeregisterExternEventSource ( HANDLE hEventSource )

Deregister an extern event source.
Parameters:

hEventSource The event source to deregister.

Returns:
TRUE if succeed.

BOOL CBS_Trace::DetachFile ( LPCTSTR lpReason = BS_TRACE_UNSPECIFIED )

Detaches the file attached to the object. The closure reason will be written to the file.
Parameters:

lpReason The reason the file is detached.

Returns:
TRUE if succeed.

BOOL CBS_Trace::DisconnectServer ( )

Disconnects the socket associated with the object. If the application wishes to keep the socket handle valid, it should invoke RemoveSocket(). In this case, however, the application should call alsow WIN32 API WSAStartup.
Returns:
TRUE if the socket was closed.

DWORD CBS_Trace::FormatError ( LPTSTR lpBuffer,

DWORD dwBufLen

)

Format the last BS_Trace error into a string. If the last error involves a system error, the system error will be formatted as well.
Parameters:

lpBuffer The buffer into which the error string will be copied.

dwBufLen The length in bytes of lpBuffer.

Returns:
The number of bytes needed for the whole message not including the null terminate character. If lpBuffer is not big enough to fit all the data, nothing will be copied.

void CBS_Trace::FreeResources ( )

If an application declares the Trace object on the stack so that CBS_GSupport::FreeGSupportLib() will be invoked before the object's destructore invoked, CBS_ResTrack will report resources failures. To avoid this, the application should invoke this method for freeing the resources explicitly.
The application must not use the object after this function is called!!!!!

Returns:
Nothing.

DWORD CBS_Trace::GetDefaultEventID ( )

See return.
Returns:
The value of the default event ID.

long CBS_Trace::GetFileMaxSize ( char * pBuf,

long lBufSize

)

Formats the max size of the file into pBuf.
Parameters:

pBuf the buffer where the result is formatted.

lBufSize the size of pBuf in bytes.

Returns:
the size of bytes copied into pBuf, if pBuf is too small the number of bytes needed will be returned. \ if the return value is "-1" the max file size member is not set and therefore ingnored.

long CBS_Trace::GetFileMaxSize ( )

Returns:
the max size of the file attached.

CBS_Trace::BS_TRACE_ERRORS CBS_Trace::GetLastError ( )

See return.
Returns:
The last error associated with the current object and the current thread.

Note:
The error is per thread, each thread has its own "last error".

LPCTSTR CBS_Trace::GetLastErrorString ( CBS_Trace::BS_TRACE_ERRORS steError )

See return.
Parameters:

steError The error to which the string is searched.

Returns:
A string describing steError.

LPCTSTR CBS_Trace::GetMillisecondDelimiter ( )

See return.
Returns:
The millisecond delimiter of the current object.

BOOL CBS_Trace::GetPrintFileName ( )

See return.
Returns:
TRUE if the current object will print out the file name with the message.

LPCTSTR CBS_Trace::GetReportTypeString ( BS_TRACE_MODE strm )

See return.
Parameters:

strm The trace mode for which the string is wished.

Returns:
A string that describes the message type.

SOCKET CBS_Trace::GetSocket ( )

See return.
Returns:
The handle of the socket.

CBS_Trace::FP_SOCKET_HOOK CBS_Trace::GetSocketHook ( )

See return.
Returns:
A pointer to the application socket hook callback function.

DWORD CBS_Trace::GetSysErrorString ( int iError,

LPTSTR lpBuf,

DWORD dwBufLen

) [static]

Retrieve an error string describing a system error number.
Parameters:

iError The system error (typicaly retrieved by calling WIN32 API ::GetLastError()).

lpBuf The buffer to receive the result.

dwBufLen The length in bytes of the lpBuf.

Returns:
The number of bytes copied into lpBuf.

void CBS_Trace::GetTime ( LPSYSTEMTIME lpSystemTime ) [virtual]

Get the local or GMT time, depend on the setting of the current object.
Parameters:

lpSystemTime A pointer to a system time structure to receive the currrent data and time.

Returns:
Nothing.

LPCTSTR CBS_Trace::GetTraceDateFormat ( )

See return.
Returns:
The date format of the current object.

LPCTSTR CBS_Trace::GetTraceFileName ( )

See return.
Returns:
The name of the file associated with the current object.

LPCTSTR CBS_Trace::GetTraceTimeFormat ( )

See return.
Returns:
The time format of the current object.

CBS_Trace::BS_TRACE_TIME CBS_Trace::GetUsedTime ( )

See return.
Returns:
The time to use flag (local or GMT).

LPCSTR CBS_Trace::GetWSAErrorString ( int iWSAError ) [static]

Return a string describing the WSA error saved in iWSAError. This static function is here since the trace searches WSA error if a system error returned by GetLastError is not found in the system error tables. Up to Win 2000 this errors are included in the system error table so this function wont have any use.
Parameters:

iWSAError The WSA (Windows Socket API) error.

Returns:
A string describing the error iWSAError.

BOOL CBS_Trace::HaveEventSource ( )

See return.
Returns:
TRUE if the current object is associated with a valid event log handle.

BOOL CBS_Trace::HaveFile ( )

See return.
Returns:
TRUE if the current object is associated with a valid file.

BOOL CBS_Trace::HaveSocket ( )

See return.
Returns:
TRUE if the current object is associated with a valid socket.

BOOL CBS_Trace::IsOutputSupported ( CBS_Trace::BS_TRACE_OUTPUT sto )

Check if a given output is supported (e.g. if no file is associated with the object, then file output is not possible).
Parameters:

sto The output target.

Returns:
TRUE if the output target is supported.

BOOL CBS_Trace::IsSystemError ( BS_TRACE_ERRORS steError )

System error are errors that where caused by calling an OS API. An application could call the WIN32 API GetLastError() to retrieve more detail to the error.
Parameters:

steError The error we want to check.

Returns:
TRUE, if the error specified in steError is a system error.

BOOL CBS_Trace::OpenControlDlg ( HWND hParent )

Opens a dialog box that controls the settings of the current object and provides extern access to some of trace functionality like changing the associated file, starting the mole and more.
Parameters:

hParent the window handle of the parent window, this parameter can be NULL.

Returns:
TRUE if the dialog box was open. If the function return FALSE, the application should invoke the member GetLastError() to evaluate the failure.

Note:
The dialog box is loaded from the DLL "BS_TraceCtrl.dll" respective "BS_TraceCtrld.dll" for debug version. If this DLL does not exists or saved in an unkown path, the function will return FALSE. If the appliation calls this function when the dialog box is opened, the given hParent and the focus will be set to the open instance and the function will return 2.

BOOL CBS_Trace::RegisterEventSource ( LPCTSTR lpSourceName )

Associate the object with a new event source handle, not like RegisterExternEventSource() this method keeps the handle and writes direct with that handle to the event log. The function calls RegisterEventSource( LPCTSTR lpServerName, LPCTSTR lpSourceName ) with lpServerName = NULL.
Parameters:

lpSourceName The Event log source name.

Returns:
TRUE if a handle to the event log was successfully opened.

BOOL CBS_Trace::RegisterEventSource ( LPCTSTR lpServerName,

LPCTSTR lpSourceName

)

Registers an event source.
Parameters:

lpServerName The machine name on which the event should be registered, NULL = Local Machine.

lpSourceName The event source name.

Returns:
TRUE if succeed.

HANDLE CBS_Trace::RegisterExternEventSource ( LPCTSTR lpSourceName )

Opens a handle to a given event log. The function calls RegisterEventSource( LPCTSTR lpServerName, LPCTSTR lpSourceName ) with lpServerName = NULL.
Parameters:

lpSourceName The Event log source name.

Returns:
A handle of the open event log or NULL if failed.

HANDLE CBS_Trace::RegisterExternEventSource ( LPCTSTR lpServerName,

LPCTSTR lpSourceName

)

Register an event source. Some modules wants to have a multiple event source. This function open a handle to a require event source and return this to the calling module.
Parameters:

lpServerName The machine on which the event source exist, NULL = Local Machine.

lpSourceName The event source name.

Returns:
The handle of the opened event or NULL if a failure occurred.

SOCKET CBS_Trace::RemoveSocket ( )

Removes the currently set socket from the object.
Returns:

BOOL CBS_Trace::ReportEvent ( WORD wType,

DWORD dwEventID,

LPCTSTR lpString = NULL

)

Reports an event to the event source associated with the current object.
Parameters:

wType The event type.

dwEventID The event ID.

lpString A string to be formatted with the message, this arguement might be NULL.

Returns:
TRUE if succeed.

BOOL CBS_Trace::ReportEvent ( WORD wType,

DWORD dwEventID,

LPCTSTR * lpStrings,

WORD wNumberOfStrings,

DWORD dwDataSize = 0,

LPVOID lpRowData = NULL

)

Report a message to the event log using the event handle of the current object.
Parameters:

wType The event type (e.g. EVENTLOG_ERROR_TYPE).

dwEventID The event ID.

lpStrings An array of strings.

wNumberOfStrings The number of element in lpStrings.

dwDataSize The size of lpRowData.

lpRowData A pointer to a buffer with binary data or NULL.

Returns:
TRUE if succeed.

BOOL CBS_Trace::ReportExternEvent ( HANDLE hEventSource,

WORD wType,

DWORD dwEventID,

LPCTSTR lpString = NULL

)

Writes a message to the event log. This function invokes ReportExternEvent( HANDLE hEventSource, WORD wType, DWORD dwEventID, LPCTSTR *lpStrings, WORD wNumberOfStrings, DWORD dwDataSize, LPVOID lpRowData ) with wNumberOfStrings = 1, if lpString is not NULL, otherwise with wNumberOfStrings = 0.
Parameters:

hEventSource A handle to the event log.

wType The type of the message (e.g. EVENTLOG_INFORMATION_TYPE).

dwEventID The event ID.

lpString A string that should be formatted with the message.

Returns:
TRUE if the message was successfully written to the event viewer.

BOOL CBS_Trace::ReportExternEvent ( HANDLE hEventSource,

WORD wType,

DWORD dwEventID,

LPCTSTR * lpStrings,

WORD wNumberOfStrings,

DWORD dwDataSize = 0,

LPVOID lpRowData = NULL

)

Writes a message to the event log using extern event handle (hEventSource).
Parameters:

hEventSource A valid handle of en event source.

wType The event type (e.g. EVENTLOG_ERROR_TYPE).

dwEventID The event ID.

lpStrings An array of strings.

wNumberOfStrings The number of element in lpStrings.

dwDataSize The size of lpRowData.

lpRowData A pointer to a buffer with binary data or NULL.

Returns:
TRUE if succeed.
TRUE if succeed.

BOOL CBS_Trace::ReportMessage ( BS_TRACE_MODE stmType,

LPCTSTR lpFileName,

UINT nLine,

LPCTSTR lpModuleName,

LPTSTR lpMessage,

...

)

Reports a message to the available outputs.
Note:
If the stmType is not set m_stmReportMode, the function return immediately.

Parameters:

stmType The message type.

lpFileName A file name that will be formatted with the message if the print file option is on (see also GetPrintFileName() and SetPrintFileName( )).

nLine The line in lpFileName

lpModuleName The name of the module who reports the message.

lpMessage The message.

... Argument list to be formatted into lpMessage.

Returns:
TRUE if the message was reported.

BOOL CBS_Trace::ReportMessage ( BS_TRACE_MODE stmType,

LPCTSTR lpModuleName,

LPTSTR lpMessage,

...

)

Reports a message to the available outputs.
Note:
If the stmType is not set m_stmReportMode, the function return immediately.

Parameters:

stmType The message type.

lpModuleName The name of the module who reports the message.

lpMessage The message.

... Argument list to be formatted into lpMessage.

Returns:
TRUE if the message was reported.

BOOL CBS_Trace::SetDateFormat ( LPCTSTR lpDateFormat )

Sets an application defined data format.
Parameters:

lpDateFormat The new date format. If new data format is invalid, the current date format will not be changed. If this parameter is NULL, then the current date format will be set also to NULL (in this case the local setting will be used).

Returns:
TRUE if the date format is valid.

void CBS_Trace::SetDefaultEventID ( DWORD dwEventID )

Sets a default event ID. If the event is set and the object is associated with a valid event log handle and the output flag BS_OUTPUT_EVENT_VIEW is set to m_stoOutput, all messages will be printed to the event log using that handle and event ID.
Parameters:

dwEventID The deafult event ID.

Returns:

BOOL CBS_Trace::SetFileMaxSize ( LPCTSTR lpcMaxSize )

Set the maximal size of the file associated with the object. When the file is attached to the trace, the size will be compare, if the size of the file exeeded, its size will be reset to 0.
Note:
This method must be invoked before the file is attached to the object in order to take effect.

Parameters:

lpcMaxSize The maximal file size. The string accept the abbreviations M for Mega and K for Kilo.
For example CBS_Trace::SetFileMaxSize( 1048576 ) is equivalent to CBS_Trace::SetFileMaxSize( "1M" ).

Returns:
TRUE if succeed.

void CBS_Trace::SetFileMaxSize ( DWORD dwMaxSize )

Set the maximal size of the file associated with the object. When the file is attached to the trace, the size will be compare, if the size of the file exeeded, its size will be reset to 0.
Note:
This method must be invoked before the file is attached to the object in order to take effect.

Parameters:

dwMaxSize The maximal file size.

Returns:
Nothing.

void CBS_Trace::SetLastError ( CBS_Trace::BS_TRACE_ERRORS steError )

Sets the last error to the object, the error is object and thread specific.
Parameters:

steError The error.

Returns:
Nothing.

void CBS_Trace::SetMillisecondDelimiter ( LPCTSTR lpMilliSecondDelimiter )

Sets the millisecond delimiter (the default is '.').
Parameters:

lpMilliSecondDelimiter The new delimiter.

Returns:
Nothing.

void CBS_Trace::SetPrintFileName ( BOOL bPrint )

Tell the current object if it should print the file name with the message or not.
Parameters:

bPrint TRUE if the file should be printed.

Returns:
Nothing.

SOCKET CBS_Trace::SetSocket ( SOCKET socket,

BOOL bEnable = TRUE

)

Sets a socket handle to the current object.
Parameters:

socket The socket handle.

bEnable if the flag BS_OUTPUT_SOCKET should be enabled (default = TRUE).

Returns:
The value of the old socket of the current object.

void CBS_Trace::SetSocketHook ( FP_SOCKET_HOOK fpSocketHook,

LPVOID lpAppData

)

Sets the application socket hook function pointer to the current object. This callback function will be invoked if an error occurred when the trace tries to write data to the socket.
Parameters:

fpSocketHook The application hook.

lpAppData The application defined data that will be passed to the application with fpSocketHook.

Returns:
Nothing.

BOOL CBS_Trace::SetTimeFormat ( LPCTSTR lpTimeFormat )

Sets an application defined time format.
Parameters:

lpTimeFormat The new date format. If new time format is invalid, the current time format will not be changed. If this parameter is NULL, then the current time format will be set also to NULL (in this case the local setting will be used).

Returns:
TRUE if the time format is valid.

void CBS_Trace::UseGMTTime ( )

Set the time to use flag to the GMT time.
Returns:
Nothing.

void CBS_Trace::UseLocalTime ( )

Set the time to use flag to the local time.
Returns:
Nothing.

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


Public Types
enum	BS_TRACE_MODE { BS_REPORT_NONE = 0x0000, BS_REPORT_INFORMATION = 0x0001, BS_REPORT_WARNING = 0x0002, BS_REPORT_ERROR = 0x0004, BS_REPORT_FATAL_ERROR = 0x0008, BS_REPORT_DEBUG_INFO = 0x0010, BS_REPORT_SYS_EXCEPTION_INFO = 0x0020, BS_REPORT_BS_EXCEPTION_INFO = 0x0040, BS_REPORT_MFC_EXCEPTION_INFO = 0x0080, BS_REPORT_STL_EXCEPTION_INFO = 0x0100, BS_REPORT_USER_EXCEPTION_INFO = 0x0200, BS_REPORT_VERBOSE = BS_REPORT_DEBUG_INFO, BS_REPORT_ALL = 0xffff, BS_REPORT_ALL_EXCEPTIONS, BS_REPORT_ERORRS_AND_HIGHER = BS_REPORT_ALL_EXCEPTIONS\|BS_REPORT_FATAL_ERROR\|BS_REPORT_ERROR, BS_REPORT_WARNING_AND_HIGHER = BS_REPORT_ERORRS_AND_HIGHER\|BS_REPORT_WARNING, BS_REPORT_INFORMATION_AND_HIGHER = BS_REPORT_WARNING_AND_HIGHER\|BS_REPORT_INFORMATION, BS_REPORT_DEFAULT = BS_REPORT_ALL }
enum	BS_TRACE_OUTPUT { BS_OUTPUT_NONE = 0x00, BS_OUTPUT_FILE = 0x01, BS_OUTPUT_SOCKET = 0x02, BS_OUTPUT_EVENT_VIEW = 0x04, BS_OUTPUT_DEBUG_WINDOW = 0x08, BS_OUTPUT_CONSOLE = 0x10, BS_OUTPUT_DEFAULT = BS_OUTPUT_DEBUG_WINDOW }
enum	BS_TRACE_TIME { BS_LOCAL_TIME = 1, BS_GMT_TIME = 2, BS_DEFAULT_TIME = BS_LOCAL_TIME }
typedef BOOL(*	FP_SOCKET_HOOK )(LPSOCKET_HOOK)
typedef CBS_Trace::SocketHook_st *	LPSOCKET_HOOK
	A structure that will be passed with the socket hook callback function.
typedef CBS_Trace::SocketHook_st	SOCKET_HOOK
	A structure that will be passed with the socket hook callback function.
Public Member Functions
BOOL	AttachFile (LPCTSTR lpNewFile)
	CBS_Trace ()
BOOL	ChangeFile (LPCTSTR lpNewFile, LPCTSTR lpCloseComment=NULL)
long	CloseControlDlg ()
BOOL	ConnectServer (DWORD dwIP, WORD wPort, BOOL bEnable=TRUE)
BOOL	ConnectServer (LPCTSTR lpIP, WORD wPort, BOOL bDNSName, BOOL bEnable=TRUE)
BOOL	CopyTraceFile (LPCTSTR lpNewFile)
	DECLARE_DLL_OPERATORS (CBS_Trace::BS_TRACE_OUTPUT, GSUPPORT_IMP_EXP_DECL)
	DECLARE_DLL_OPERATORS (CBS_Trace::BS_TRACE_MODE, GSUPPORT_IMP_EXP_DECL)
	DECLARE_SET_GET_MODE (CBS_Trace::BS_TRACE_OUTPUT, m_stoOutput, Output)
	DECLARE_SET_GET_MODE (CBS_Trace::BS_TRACE_MODE, m_stmReportMode, Report)
BOOL	DeregisterEventSource ()
BOOL	DeregisterExternEventSource (HANDLE hEventSource)
BOOL	DetachFile (LPCTSTR lpReason=BS_TRACE_UNSPECIFIED)
BOOL	DisconnectServer ()
DWORD	FormatError (LPTSTR lpBuffer, DWORD dwBufLen)
void	FreeResources ()
DWORD	GetDefaultEventID ()
long	GetFileMaxSize (char *pBuf, long lBufSize)
long	GetFileMaxSize ()
BS_TRACE_ERRORS	GetLastError ()
LPCTSTR	GetLastErrorString (BS_TRACE_ERRORS steError)
LPCTSTR	GetMillisecondDelimiter ()
BOOL	GetPrintFileName ()
LPCTSTR	GetReportTypeString (BS_TRACE_MODE)
SOCKET	GetSocket ()
FP_SOCKET_HOOK	GetSocketHook ()
virtual void	GetTime (LPSYSTEMTIME lpSystemTime)
LPCTSTR	GetTraceDateFormat ()
LPCTSTR	GetTraceFileName ()
LPCTSTR	GetTraceTimeFormat ()
BS_TRACE_TIME	GetUsedTime ()
BOOL	HaveEventSource ()
BOOL	HaveFile ()
BOOL	HaveSocket ()
BOOL	IsOutputSupported (BS_TRACE_OUTPUT sto)
BOOL	IsSystemError (BS_TRACE_ERRORS steError)
BOOL	OpenControlDlg (HWND hParent)
BOOL	RegisterEventSource (LPCTSTR lpSourceName)
BOOL	RegisterEventSource (LPCTSTR lpServerName, LPCTSTR lpSourceName)
HANDLE	RegisterExternEventSource (LPCTSTR lpSourceName)
HANDLE	RegisterExternEventSource (LPCTSTR lpServerName, LPCTSTR lpSourceName)
SOCKET	RemoveSocket ()
BOOL	ReportEvent (WORD wType, DWORD dwEventID, LPCTSTR lpString=NULL)
BOOL	ReportEvent (WORD wType, DWORD dwEventID, LPCTSTR *lpStrings, WORD wNumberOfStrings, DWORD dwDataSize=0, LPVOID lpRowData=NULL)
BOOL	ReportExternEvent (HANDLE hEventSource, WORD wType, DWORD dwEventID, LPCTSTR lpString=NULL)
BOOL	ReportExternEvent (HANDLE hEventSource, WORD wType, DWORD dwEventID, LPCTSTR *lpStrings, WORD wNumberOfStrings, DWORD dwDataSize=0, LPVOID lpRowData=NULL)
BOOL	ReportMessage (BS_TRACE_MODE stmType, LPCTSTR lpFileName, UINT nLine, LPCTSTR lpModuleName, LPTSTR lpMessage,...)
BOOL	ReportMessage (BS_TRACE_MODE stmType, LPCTSTR lpModuleName, LPTSTR lpMessage,...)
BOOL	SetDateFormat (LPCTSTR lpDateFormat)
void	SetDefaultEventID (DWORD dwEventID)
BOOL	SetFileMaxSize (LPCTSTR lpcMaxSize)
void	SetFileMaxSize (DWORD dwMaxSize)
void	SetLastError (BS_TRACE_ERRORS steError)
void	SetMillisecondDelimiter (LPCTSTR lpMilliSecondDelimiter)
void	SetPrintFileName (BOOL bPrint)
SOCKET	SetSocket (SOCKET socket, BOOL bEnable=TRUE)
void	SetSocketHook (FP_SOCKET_HOOK fpSocketHook, LPVOID lpAppData)
BOOL	SetTimeFormat (LPCTSTR lpTimeFormat)
void	UseGMTTime ()
void	UseLocalTime ()
virtual	~CBS_Trace ()
Static Public Member Functions
DWORD	GetSysErrorString (int iError, LPTSTR lpBuf, DWORD dwBufLen)
LPCSTR	GetWSAErrorString (int iWSAError)