LoggingControl API Documentation

Version-0.4

Copyright Information

Logging Control Library/API

Copyright (C) 2004. Jeff Schiller

Revision History

Version	Notes
0.1	Initial version, contains support for log file sink, Visual C++ debugger sink and log node sink.
0.2	Removed the Win32-specific debugger and error functions from unconditional compile
0.3	Added LIB_API symbol to enable compiling into a DLL. Separated Threaded API from LoggingControl API.
0.31	Added Doxygen tags to the source
0.4	Added StdOutSink and StdErrSink

License Stuff

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Introduction

This is a an attempt to develop a library that will support various logging mechanisms that can be used for a variety of purposes. The logging mechanisms are protected resources that are thread-safe and can be used across modules in an application.

DISCLAIMERS: 1) This library is provided AS IS and without any warranty implied or otherwise. I am publishing this library for review purposes only.

This library is completely contained within the LoggingControl namespace. The API is accessed via a nested namespace LoggingControl::API. Internals of the library are accessed via a nested namespace LoggingControl::Internals.

The basic concepts are outlined here: Whitepaper PDF.

However, a brief description of the concepts will also be given here. Basically, each logical object that can be sent logging messages is called a LogNode. Each LogNode can have zero or more LogSinks. A LogSink is defined as an endpoint for text messages. Users of the Logging Control library create LogNodes in their application by calling API functions and attaching LogSinks to it (such as files, debuggers, etc). The application logs messages to the LogNode which automatically forwards all messages to its attached LogSinks.

The user has access to the following API functions:

CreateLogNode()
DestroyLogNode()
AddFileSinkToLogNode()
AddLogNodeSinkToLogNode()
AddSinkToLogNode()
AddWin32DebuggerSinkToLogNode()
LockLogNode()
GetLogNodeStream()
FlushAndReleaseLogNode()

A macro is used to ease the use of some of the Lock, stream, Flush and Release API calls:

LOG_LINE(hLog, _x_)

where:

hLog must be a handle to a valid, previously created Log Node _x_ can be any C++ code that correctly evaluates to send to a operator<<

For example:

    HLOGNODE hLoggy = CreateLogNode();
    AddFileSinkToLogNode(hLoggy, "mylog.txt");
    
    LOG_LINE(hLoggy, "The value of hLoggy is " << hLoggy << " and its address is " << &hLoggy);

---