138 lines
3 KiB
Plaintext
138 lines
3 KiB
Plaintext
|
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.
|
||
|
|
|