///////////////////////////////////////////////////////////////////////
//  Copyright (C) 2000 ILX Systems.  All Rights Reserved.
//
//      $Header: /u/4/m/me133/cvs/Common/ILXLog/ReadMe.txt,v 1.2 2004/09/07 06:06:05 me133 Exp $
//
//    File name:	Readme.txt
//   Created By:	Marc Eaddy
//   Created on:	05/02/2000
//
///////////////////////////////////////////////////////////////////////

//*******************************************************************//
//                       ILXLog Readme File                          //
//*******************************************************************//

TODO LIST
=========

NOTES
=====
- Q119394 - var len arg lists
- Research _ASSERTE to see how to implement Debug button and ILXASSERT

ISSUES
======

1)	OnLog Event
    -----------
	
	Ideally, when a message is logged, the OnLog event would be fired
	to allow arbitrary IDispatch clients (i.e., Scripting Subsystem)
	to be allowed to handle log messages.  For example a script could
	take the log message and display it in the status bar if the
	message has the error severity.

	However, IILXLog aggregates the free-threaded marshaller so all
	its connection points must be marshalled before we can fire the
	event.  We would probably have to override the default ATL
	IConnectionPoint implementation to store an IStream instead of
	an IUnknown ptr.  Obviously, the proxy marshalling combined with 
	IDispatch::Invoke() will make OnLog the slowest segment of logging
	an error message.

	Until its implemented properly IILXLog will not fire the OnLog
	event.

2)	printf-style log message support

	There are two different areas where this is desired.  The first
	area deals with the user message (szMessage).  Users would like
	to do the following

	ILXLOG(hr, _T("Failed to open file %s."), szFile, ILXLOG_ERROR);

	I call this user message formatting.  The second area deals with
	the message resource associated with the HRESULT.  The message
	resource string can have "insertion strings" like the following
	for ERROR_MR_MID_NOT_FOUND:

	The system cannot find message text for message number 0x%1
	in the message file for %2.

	In this case, the user might want to do this:

	ILXLOG(hr, szFile, _T("Failed to open workspace file."), ILXLOG_ERROR);

	I call this insertion string formatting.  Unfortunately, the above
	code would never compile because macros do not support variable
	function arguments.  So at the very least, we will have to use
	raw functions when passing variable arguments.

	LogMsg(hr, _T("Failed to open file %s."), szFile, ILXLOG_ERROR);

	The problem with the above approach is that it is not type safe.
	Someone can easily do the following:

	LogMsg(hr, _T("Failed to open file %s (Code: %d)."), szFile, ILXLOG_ERROR);

	This would cause unpredictable results.

	Using _variant_t
	----------------
	Instead of allowing a variable number of arguments, we could
	specify a maximum of four.  The arguments could be variants
	to enforce type safety and to provide automatic conversion:

	LogMsg(hr, ILXLOG_ERROR, _T("Failed to open file %s (Code: %d) - %s."), 
		_T("joe.txt"), 5, _T("I don't know"));

	Both string and number arguments would be implicitly converted to
	_variant_t via its overloaded type conversion constructors.  Since
	the variant stores the type of its value, we could parse the format
	string and enforce type checking.  For example, "%s" expects a
	variant type of VT_BSTR.  Unfortunately, it is damned near
	impossible to implement the full printf-style parser.  Just look
	at OUTPUT.C (MS runtime source file) to see what I mean.

	Stream-style formatting
	-----------------------
	What about this:

	LogMsgObj	<< hresult_val(hr)
				<< _T("Failed to open file ") << szFile
				<< _T(" (Code: ") << nCode
				<< _T(") - ") << szReason
				<< logILXLOG_ERROR;

	It is not as convenient as the printf-style formatting but it gets
	the job done in a type safe and fully extensible way.  The
	ILXLOG_ERROR signals when the log message is "finished".

FEATURE REQUESTS
================

1) Add support for a StackTrace log destination.
2) Add support for an Email log destination.
3) Add support for the Event Viewer log destination.
4) Use four digits for thread id
