An ITLogMsg object represents a logmessage being prepared for output in a (output) logchannel. From creation on it is connected to the (output) logchannel (class ITOutputLogChannel); if you don’t give one, the default channel "StdLog" is used. The typical cycle looks as follows:
§ create logmessage
§ modify logmessage properties
The most important property is the property "Text" containing the actual logmessage text, and the most common operation is to append text to this property.
§ send logmessage to the logchannel -- or cancel it to prevent output
In fact, ITLogMsg is a reference counting type, although it doesn’t look like one (in C++, reference counting is usually done using smart pointers, which are used mostly like pointers). The main reason for this design is to prevent memory leaks.
As ITLogMsg is a true reference counting type, various instances of class ITLogMsg can refer to the same logmessage object. This happens when you assign an ITLogMsg instance to another ITLogMsg instance.
The underlying "real" logmessage object is sent to the logchannel
§ when you call ITLogMsg::Send
or, if you forgot that,
§ as soon as there doesn’t exist an ITLogMsg instance any more that refers to it.
These are the ways to create an ITLogMsg object:
§ using one of the ITLogMsg constructors
§ using one of the ITLogMsg::Create methods
§ using the ITOutputLogChannel::CreateLogMsg method
To create the object, besides the logchannel name you give the name of the Module and the name of the Case under which to message is to be logged. These names are displayed in the ITLogBook application and can be used there to define display filters. Module and Case have not defaults.
Module and Case are also be used as the basis for the write-out filter mechanism. This mechanism allows you to suppress the output of certain logmessages. Write-out filters are defined on a per-log-channel basis. They are stored in the configuration file and can be modified at run-time.
Besides the logchannel, the Module and the Case at ITLogMsg creation time you can also set the initial Loglevel. The meaning of the loglevel is explained in ITLogLevel enum and its connection to the log level of a log message.
The logmessage also automatically gets a time-stamp, which can be queried using ITLogMsg::GetTimeAsString().
To summarize, the properties of the logmessage set at creating time are (in the order as displayed in the ITLogBook application):
§ logchannel
§ loglevel
§ time stamp
§ Module and Case name
§ logmessage text: set to "".
Modifying ITLogMsg objects
The properties that can still be modified after the creation of the logmessage object are
§ the loglevel
Use ITLogMsg::SetLogLevel() and ITLogMsg::AddLogLevel() to modify it and ITLogLMsg::GetLogLevel() to query it.
and
§ the logmessage text.
Use the ITLogMsg output operators to add text to it and ITLogMsg::GetText() to get the current text.
Sending or canceling ITLogMsg objects
This is done calling ITLogMsg::Send() or ITLogMsg::Cancel(). As was explained above in connection with reference counting, the underlying logmessage is also sent when the last ITLogMsg object that refers to it gives up its reference.