windows-xp/Source/XPSP1/NT/com/ole32/ole232/doc/tracegrm.txt

	Linking and Embedding Call Tracing

Alex Gounares (alexgo), 12/15/93


------------------------------

NB:  All call tracing added to the L&E layers of OLE *must*
conform to this spec; post processing tools may break otherwise.

Syntax of this grammar:
	non-terminals are bracketed with underscores (e.g. _foo_)
	Other tokens are literally or as described

General:

	Call logging should be done via the LEDebugOut macro, which
	takes the following parameters:

	LEDebugOut(( _type_ , _formatstring_ , _arguments));

	_type_	:	DEB_TRACE
		|	DEB_ITRACE
		;

	DEB_TRACE should be used for any API or method *directly*
	reachable by an OLE app. 

	DEB_ITRACE should be used for all internal APIs and
	methods.

	In some circumstances (an important internal function),
	it is permissible to use DEB_TRACE for internal functions
	and methods, but this is discouraged.
	
	_arguments_	:  whatever is needed by _formatstring_

	There are three _formatstring_ formats currently supported,
	one for function entrance, another for function exit, and
	a third for object deletion.  More formats may be added
	as needed, so tools must be prepared to ignore
	non-conforming strings (as it may be a new format for a new
	tool).

	_formatstring_	:	_in_
			|	_out_
			|	_delete_
			;

Function entrance:	// _IN is literal

	_in_		:	"_this_ _IN _name_ _args_ _extra_ \n"
			;

	_this_		:	%p	
				//should be passed the pointer
				//to the *top* level object in
				//the class (if the this pointer
				//points to a nested class)
				//If a function, then 0 should be
				//passed.
			;

	_name_		:	// the complete name of the function
				// or method (i.e. CFoo::CBar::Blah)

	_args_		:	( )
			|	( _arglist_ )
			;

	_arglist_	:	_arglist_ , _arg_
			|	_arg_
			;

	_arg_		:	_string_
			|	_integral_
			;

	_string_	:	\"%s\"
			|	\"%ws\"
			;
			
	_integral_	:	any printf conversion string
				other than strings (see NOTES)

	_extra_		:	an arbitrary number of bytes
				with no newline character

Function exit:

	_out_	: "_this_ OUT _name_ _return_ _outparams_ _extra_ \n"
		;

	_return_	:	( _arg_ )
			;
			
	_outparams_	:	[ _arglist_ ]	// used to put the
			|			// values of the
			;			// out parameters


Object Deletion:

	_delete_	: "_this_ DELETED _extra_ \n"
			;

			
				
NOTES:

	1.  	The newline does not need to be preceeded by a space.
		Other spaces in the grammar are intentional (the
		space character is the token delimiter)

	2. 	Tools should ignore any extra bytes after the known
		fields to be compatible with future revs of the
		logging.

	3.	In general, the following conversion codes are used
		for the following data types.  These are not binding,
		however, individual functions/methods may do 
		something different as appropriate.

		HRESULT		%lx
		pointer		%p
		DWORD		%lu
		DWORD(bitflags)	%lx
		ULONG		%lu
		LONG		%ld
		REFGUID		%p

	4.	For in/out params, in may be awkward to print
		the out value (since it may be a long piece of
		memory).  In this case, just printing the pointer
		value (although the same as the argument) is
		sufficient.