iTech Logging Source Code Snippets
The 2nd generation logging solution
Source code snippets for iTech Logging (Microsoft Visual C++)
ITLogLib
ITLogMsg
Defining stream operators for homogeneous protocol outputs (recommended) |
|
Service functions
Opening ITLogBook out of your application with current logfiles |
|
Opening ITConfigManager out of your application with the current configuration file |
ITLogLib - Initializing your Windows application
ITLogLib must be initialized with a configuration file. This file can be created and edited by ITConfigManager, a special editor shipped with iTech Logging. The parameter application name is user-defined and identifies your application. Initialization fails if the configuration file could not be found.
After successful initialization the standard output channel StdLog is opened and ready to receive logmessages. Additional output channels should be opened within the InitInstance() function.
See also: ITLogLib - Opening an additional logical output channel.
#include
<ITLogLib2.h>
BOOL
CMyApp::InitInstance()
{
// Initialize the global ITLogLib object (for evaluation
use empty LicenseKey string)
if ( !GetITLogLib().Initialize("MyApplication",
"ConfigFileName.icf", "LicenseKey"))
{
MessageBox(NULL, GetITLogLib().GetLastErrorDescription(), "Error", MB_OK);
GetITLogLib().Deinitialize();
return FALSE;
}
return TRUE;
}
ITLogLib - Deinitializing your Windows application
Before your application exits, ITLogLib should be deinitialized in order to write out all buffered logmessages and close all opened output channels.
int
CMyApp::ExitInstance()
{
// Deinitialize the global ITLogLib object (forces
writing out buffered logmessages)
GetITLogLib().Deinitialize();
return
CWinApp::ExitInstance();
}
ITLogLib - Initializing and deinitializing your console application
See also:
ITLogLib - Initializing your Windows application
ITLogLib - Deinitializing your Windows application
#include
<ITLogLib2.h>
#include <ostream.h>
// only for 'cerr'
int main(int argc, char* argv[])
{
//
Initialize the global ITLogLib object (for evaluation use empty LicenseKey
string)
if ( !GetITLogLib().Initialize("MyApplication", "MyConfigFile.icf",
"LicenseKey"))
{
cerr << "Starting without iTech Logging :-(";
cerr << "\n";
cerr << GetITLogLib().GetLastErrorDescription();
}
...
// Deinitialize the global ITLogLib object (forces
writing out buffered logmessages)
GetITLogLib().Deinitialize();
return 0;
}
ITLogLib - Opening an additional logical output channel
Besides the standard output channel StdLog additional application specific logical output channels can be opened. For each output channel an appropriate set of configuration parameters must exist in the configuration file, otherwise OpenLogChannel() fails. Use ITConfigManager to create or edit the parameter set. (See also: ITLogLib - Initializing your Windows application).
It's recommended to open all used output channel within the InitInstance() function (for Windows applications) or main() function (for console applications).
// Open
additional logchannel 'DeveloperLog'
if ( GetITLogLib().OpenLogChannel ("DeveloperLog") == 0 )
{
ITLogMsg LogMsg("Application", "Initialize", LEVEL_WARNING);
// StdLog
LogMsg << "Can't open logchannel 'DeveloperLog'";
LogMsg << "\n";
LogMsg << GetITLogLib().GetLastErrorDescription();
}
ITLogLib - Closing a logical output channel
Closing a logical output channel forces writing out its buffered logmessages. If you deinitialize ITLogLib all opened output channels will be closed automatically.
The standard output channel StdLog can’t be closed explicitly by user.
// Close
additional logchannel 'DeveloperLog'
if
( !GetITLogLib().CloseLogChannel("DeveloperLog") )
{
QuickLog("Application",
"Deinitialize", "Can't close logchannel 'DeveloperLog'",
LEVEL_WARNING);
}
ITLogMsg - The simplest way to protocol
The easiest way to protocol is using the function QuickLog().
// Use default
loglevel (LEVEL_INFO) and standard logchannel (StdLog)
QuickLog("Application",
"Initialize", "Program started ...");
//
Use loglevel WARNING
QuickLog("Application",
"Deinitialize", "Program terminated by user",
LEVEL_WARNING);
// Use
logchannel 'DeveloperLog'
QuickLog("Application",
"Deinitialize", "Program terminated", LEVEL_INFO,
"DeveloperLog");
ITLogMsg - The standard way to protocol
Logmessages can be created anywhere in your applications code and passed as parameters to subsequent functions calls. Its interface provides different stream operators for C++ base types, which allow a comfortable extension of their logmessage texts. You also can define and use your own stream operators. The loglevel (info, warning, error and alarm) can be supplemented during the life cycle of a logmessage as well.
A logmessage will be send automatically to its output channel(s), as far as you didn’t explicitly send it or suppress its output.
bool bVal = false;
char cVal = 'c';
float fVal = 1.5;
int iVal = 42;
double dVal = 99.99;
char strVal[] =
"logmessage text string";
// Create the logmessage
ITLogMsg LogMsg("MyModule", "MyCase", /*optional*/
LEVEL_INFO, /*optional*/ "DeveloperLog");
// Add logmessage text
LogMsg << "bool: " << bVal << " char: " << cVal;
LogMsg << " float: " << fVal << " int: " << iVal << " double: " << dVal;
LogMsg << "\n" << strVal;
// Add loglevel
LogMsg.AddLogLevel(LEVEL_ERROR);
// LogMsg will be sent automatically to its logchannel
when destructor is called
ITLogMsg - Defining stream operators for homogeneous protocol outputs
Defining stream operators for your main classes allows comfortable and homogeneous protocolling of its objects instances. The more homogeneous your logmessage texts are, the easier is the future definition of custom filters during ITLogBook analysis.
// Define an operator for easy and homogenous logging
ITLogMsg& operator<< (ITLogMsg&
LogMsg, CMyClass& MyObj)
{
LogMsg << "Color=" << MyObj.GetColor();
LogMsg << " (Index=" << MyObj.GetIndex()
<< ")";
return LogMsg;
}
// Use the userdefined operator
CMyClass MyObj("RED", 1);
ITLogMsg LogMsg("MyModule", "MyCase");
LogMsg << MyObj;
LogMsg.Send();
ITLogMsg - Writing to a variable output channel
You can create logmessages dynamically using the create function of its output channel.
// Logging to variable logchannel
void LogState (ITOutputLogChannel& LogChannel)
{
ITLogMsg LogMsg = LogChannel.CreateLogMsg("Statistics",
"State");
LogMsg << "State=" << 42;
}
//
Call the function
ITOutputLogChannel* pLogChannel =
GetITLogLib().GetLogChannel("DeveloperLog");
if ( pLogChannel != 0 )
{
LogState(*pLogChannel);
}
ITLogMsg - Conditional creation of logmessages
As soon as a logmessage variable is declared, the complete ITLogMsg interface can be used, without producing runtime errors. Subsequent calls to its interface functions simply will be ignored as long as the object is not created. Thus you have the possibility of conditional creation of logmessages.
// Conditional creation of logmessages
ITLogMsg ErrorLogMsg;
// The ITLogMsg interface can be used at this
stage, but changes to ErrorLogMsg will be ignored.
if ( !CheckState() )
{
ErrorLogMsg.Create("Statistics",
"State", LEVEL_ERROR);
ErrorLogMsg << "Check failed ";
}
// ErrorLogMsg will only be sent, if above
CheckState function failed.
ErrorLogMsg.Send();
ITLogMsg - Explicit sending of logmessages
Logmessages can be sent explicitly, e.g. depending on a condition within your program code. Subsequent calls to its interface don’t result in a runtime error but will simply be ignored.
// Explicit sending of logmessages
ITLogMsg LogMsg("Statistics", "State");
if ( !CheckState() )
{
LogMsg << "Check failed";
LogMsg.AddLogLevel(LEVEL_ERROR);
LogMsg.Send();
}
// Additional changes to LogMsg will be
ignored, if above CheckState function failed.
ITLogMsg - Explicit cancelling of logmessages
Logmessages can be suppressed explicitly, e.g. depending on a condition within your program code. Subsequent calls to its interface don’t result in a runtime error but will simply be ignored.
// Cancelling Logmessages
ITLogMsg LogMsg("Statistics", "State");
if ( CheckState() )
{
LogMsg.Cancel();
}
// Additional changes to LogMsg will be
ignored, if above CheckState function failed.
ITLogMsg - Optimizing performance with active output filters
Using the IF_LOG … END_LOG macro avoids expensive calls to protocol functions if the logmessage will not be written out later, e.g. if you did set up an appropriate write-out filter, or did explicitly cancel (LogMsg.Cancel()) or send (LogMsg.Send()) the logmessage before. (‘Expensive’ means collecting lots of information and append it to the logmessage text.)
Remark: Using ELSE_LOG is optional.
// Using the IF_LOG macro
ITLogMsg LogMsg("Statistics", "ObjectDump");
IF_LOG (LogMsg)
{
LogMsg << MyObject.FullDump(); //
expensive function
}
ELSE_LOG
{
...
}
END_LOG
Service-Funktion - Opening ITLogBook out of your application with current logfiles
You may define a (hidden) button in your applications interface, that opens ITLogBook with the current logfile of a given output channel, thus your developer or end user always have comfortable access to the most recent log information. (Therefore iTech logging must be set up on the target system, in order to attach the “ilf” file extension to the ITLogBook application.
#include <windows.h>
#include <ostream.h>
// only for 'cerr'
//
Open ITLogBook with current logfile
ITOutputLogChannel* pLogChannel = GetITLogLib().GetLogChannel("DeveloperLog");
if ( pLogChannel == 0 )
{
cerr << "Can't open
ITLogBook - Logchannel 'DeveloperLog' not open";
}
else if (pLogChannel->GetCurrentLogFile()
== 0)
{
cerr << "Can't open
ITLogBook - Logchannel 'DeveloperLog'
still empty";
}
else
{
ShellExecute(0, "open", pLogChannel->GetCurrentLogFile(), 0, 0, SW_SHOWNORMAL);
}
You may define a (hidden) button in your applications interface, that opens ITConfigManager with the current configuration file, thus your developer or end user always have comfortable access to the current parameters, defining the output behavior. (Therefore iTech logging must be set up on the target system, in order to attach the “icf” file extension to the ITConfigManager application.
#include <windows.h>
//
Open ITConfigManager with application's current configfile
if ( GetITLogLib().IsInitialized() )
{
ShellExecute(0, "open", GetITLogLib().GetConfigFile(), 0, 0, SW_SHOWNORMAL);
}
Copyright © 1999 - 2004 iTech Software GmbH