htrace.h

A Windows CE API Inecptor Tools

/**************************************************************
Module : HTrace.h  Declaration of tracing routines.
             Written 1998,1999,2000 by Dmitri Leman
Purpose: Tracing framework allows inserting HTRACE and HTRACEK
  tracing statements to applications and drivers.
  Tracing messages may redirected to various output streams 
  without rebuilding the whole application.
  To enable the trace, define TRACE_ in the compiler settings.
  To compile for NT kernel mode driver, add TRACER_NTDRIVER 
  definition. To compile with Java JNI support, add TRACE_JNI.
  This file was compiled using Visual C++ 6.0 for WIN32 and NT
  kernel mode, 
  g++ version egcs-2.91 for Red Hat Linux 6.1  on Pentium
  Most of the tracer routines are also callable from C.
**************************************************************/
#ifndef TRACE_H /*{*/
#define TRACE_H

/*
The following are constants for various thread groups used in
the CeApiSpy application.
To use the trace in other applications, different groups
should be defined.
*/
enum TraceGroups
{
    TG_InterceptedInfo  = 1,/*The main output of the Spy -intercepted
                           functions, parameters, etc. */
    
    TG_DebugSpyBrief    = 2, /* Debug the Spy itself */
    TG_DebugSpyDetailed = 4, /*Detailed prints from Spy's internals*/

    TG_PrintAlways      = 8, /* Important messages */

/*The following are groups for error messages:*/
    TG_MessageBox =  0x1000000,/*errors and warnings*/

    TG_Error      = 0x80000000 /*errors*/
};/*enum TraceGroups*/


#ifdef __cplusplus
extern "C" {
#else
typedef int bool;
#endif

#ifdef WIN32
#include <tchar.h>

#else

#include <limits.h>
typedef unsigned long DWORD;
typedef unsigned long ULONG;
typedef unsigned long * PDWORD;
typedef unsigned long * PULONG;
typedef const char * LPCTSTR;
typedef const char * LPCSTR;
typedef const char * PCSTR;
typedef char * PTSTR;
typedef char * PSTR;
typedef char   TCHAR;
#define _tcslen strlen
#define IN
#define OUT
typedef struct
{
    int QuadPart;
} LARGE_INTEGER, *PLARGE_INTEGER;

typedef int HANDLE;
#define INVALID_HANDLE_VALUE -1

#define _MAX_PATH PATH_MAX

/*
These are replacement for Windows interlocked routines
for Linux implemented using Pentium inline assembly.
*/
long InterlockedExchangeAdd(long * p_plValue, long p_lAdd);
long InterlockedIncrement(long * p_plValue);
long InterlockedDecrement(long * p_plValue);

#endif

/*
The following are keyword to enable tracing of various 
routines in the applications and the driver.
*/
#define KeyWordDriverDebug "DrvD"
#define KeyWordAppDebug    "AppD"

/*
The following are constants for various trace output streams.
To add a new method of trace output just add a new constant,
then write a new output routine and add a new row in s_Outputs
array in htrace.cpp. For example one routine may send trace 
messages to a remote computer, another - to a database.
After that you can redirect selected trace groups to your 
new output stream by calling TraceAssignGroupsToStream
*/
enum TraceOutputs
{
    TO_DebugMonitor = 1,
    TO_File         = 2,
    TO_FlushFile    = 4,/*this is not a stream, but a command 
      to flush the file after a message is printed to TO_File*/
    TO_MessageBox   = 8,
    TO_Console      = 0x10,
    TO_MemoryBuffer = 0x20,
    TO_OutputLog    = 0x40,
};/*enum TraceOutputs*/

/*
The following is support for the trace memory buffer.
Most of the space in the trace buffer will be filled by actual
trace messages, but it also should keep several integers
used during tracing: buffer size, number of bytes written,
"stop after" threshold, frozen flag, enabled group mask, 
enabled keywords and keyword modification counter.

The purpose of m_dwStopAfterThreshold is to freeze the output
as soon as m_dwNumBytesWritten exceeds its value. Then m_iFrozen
will be set to 1 and no more traces will be added to the buffer.

We cannot keep integers in the header, because it will prevent
text editors from seeing our trace file as text. Therefore,
we will store size of the buffer as a text string at the
beginning of the buffer and the rest of the integer at the end.
This way text editors will be happy to open the buffer as text.

Layout of the memory trace buffer:
Header + 0: Signature       - 4 bytes
Header + 4: SizeTextAreaHex - 10 byte hexadecimal string
Actual text buffer of size == SizeTextAreaHex
Footer + 0: Number of bytes written - 4 bytes integer
Footer + 4: Threshold to stop       - 4 bytes integer
Footer + 8: Frozen or not           - 4 bytes integer
Footer + C: Group Mask              - 4 bytes integer
Footer + 10: Group Keyword Mask      - 256 bytes string
Footer + 110: Keyword modification counter - 4 bytes
*/
#define TRACE_BUFFER_SIGNATURE 0x46425254 /*"TRBF"*/
struct GlobalTraceBufferHeader/*may be in shared memory*/
{
    ULONG m_dwSignature;/*TRACE_BUFFER_SIGNATURE*/
    char  m_cSizeTextArea[12];
};/*struct GlobalTraceBufferHeader*/
struct GlobalTraceBufferFooter /*may be in shared memory*/
{
    ULONG m_dwNumBytesWritten;
    ULONG m_dwStopAfterThreshold;
    ULONG m_dwFrozen;
    ULONG m_dwEnabledGroups;
    ULONG m_dwEnabledGroupsTotal;
    char  m_szKeyWordMask[256];
    ULONG m_dwKeyWordModificationCounter;
};/*struct GlobalTraceBufferHeader*/
struct LocalTraceBufferPointers  /*kept local by application*/
{
    struct GlobalTraceBufferHeader *   m_pGlobalHeader;
    LPTSTR                      m_pTextArea;
    ULONG                       m_dwTextAreaSize;
    struct GlobalTraceBufferFooter *   m_pGlobalFooter;
};
#define TRACE_BUFFER_EXTRA_SIZE \
    (sizeof(GlobalTraceBufferHeader)+\
    sizeof(GlobalTraceBufferFooter))

#ifdef TRACE_ /*{*/
/*
Current implementation does not allow simultaneous modification
of trace parameters by multiple threads. Ideally, a process 
should initialize trace from the beginning and, may be, 
update trace parameters from a single thread.
Functions, which generate trace, such as HTraceImpl and 
OutputTraceString can be called by any thread at any time(after
the trace is initialized by TraceInitialize.
*/

/*
TraceInitialize should be called once for any process, which 
use the trace. TraceUnInitialize should be called before
the process terminates.
In some platforms C++ constructors can be used for this
purpose, but many other platforms lack such support.
*/
bool TraceInitialize(void);
bool TraceUnInitialize(void);

/*
TraceAssignGroupsToStream is the most important function of
the trace. It allows turning on and off individual group 
flags defined in enum TraceGroups for each trace output 
specified by constants in enum TraceOutputs, which will 
enable/disable and redirect the specified trace groups 
for the given output streams.
PARAMETERS:                   .
    p_dwTraceOutputs       flags from TraceOutputs.
    p_dwNewGroupFlags      groups to print
    p_dwGroupFlagsToModify which bits can be modified
*/
bool TraceAssignGroupsToStream
(
    ULONG   p_dwTraceOutputs,
    ULONG   p_dwNewGroupFlags,
    ULONG   p_dwGroupFlagsToModify

);
/*
TraceAssignGroupKeyWordToStream is useful when there is not
enough bit positions in 32 bit number to assign for various
trace groups in the program. In such a case string keywords
can be assigned to trace groups. 
TraceAssignGroupKeyWordToStream allows assigning
individual group keywords for each trace output 
specified by constants in enum TraceOutputs. 
PARAMETERS:                   .
    p_dwTraceOutputs       flags from TraceOutputs.
    char  *  p_pszGroupKeyWord      new keyword mask
*/
bool TraceAssignGroupKeyWordToStream
(
    ULONG   p_dwTraceOutputs,
    char  * p_pszGroupKeyWord
);
/*
TraceGetAssignedGroupsToStream and 
TraceGetAssignedGroupKeyWordsToStream allow to get currently
enabled trace groups for a particular trace output.
PARAMETERS:                   .
    p_dwTraceOutputs       flags from TraceOutputs.
*/
ULONG TraceGetAssignedGroupsToStream(ULONG   p_dwTraceOutputs);
LPCSTR TraceGetAssignedGroupKeyWordsToStream
    (ULONG p_dwTraceOutputs);

/*
TraceReadWriteSettings allows to read and write
the current trace settings, including group masks and keywords 
for some or all output streams to/from system registry or 
an INI file under WIN32. This allows defining trace settings 
in registry or INI file without modifying the program.
   PARAMETERS:                   .
    HKEY    p_hKeyRoot            root registry key (for example
        HKEY_CURRENT_USER). May be NULL - in that case p_pszPath
        should be a path to .INI file (if platform supports it).
    LPCTSTR  p_pszPath   if p_hKeyRoot != NULL - registry path
                         if p_hKeyRoot == NULL - INI file path
    bool    p_bWrite              true to write, false to read
    ULONG   p_ulOutputsToProcess  flags from TraceOutputs - 
        chose which stream settings to read/write
*/
bool TraceReadWriteSettings(HKEY p_hKeyRoot, LPCTSTR p_pszPath,
    bool p_bWrite, ULONG   p_ulOutputsToProcess);

#ifndef TRACER_NTDRIVER
/*
TraceSetOutputToFile enables tracing to a file. Unlike 
memory-mapped file, output to a file will directly print 
trace messages to a file, 
which allows an unlimited size, but may be slower.
This function accepts 2 masks: p_dwNewGroupFlags to decide
which trace statements should be printed to file and 
p_dwNewFlushBits to determine which trace statements should
also flush the file. Flushing the file allows to preserve
the trace if an application crashes, but is much slower.
   PARAMETERS:                   .
    LPCTSTR p_pszFileName       - file name to print traces to
    ULONG   p_dwNewGroupFlags     -  groups to print
    ULONG   p_dwGroupFlagsToModify-trace groups flags to change
    ULONG   p_dwNewFlushBits - groups which will flush the file
    ULONG   p_dwFlushBitsToModify  - trace flags to change
*/
bool TraceSetOutputToFile
(
    LPCTSTR p_pszFileName,
    ULONG   p_dwNewGroupFlags,
    ULONG   p_dwGroupFlagsToModify,
    ULONG   p_dwNewFlushBits   ,
    ULONG   p_dwFlushBitsToModify
);
LPCTSTR TraceGetCurTraceFileName();
#endif

/*
TraceAllocateBuffer - allocate trace buffer of the given size
and enable trace groups for that output. This buffer cannot be
shared with other applications or files. This buffer should be
dumped to a file using TraceDumpBufferToFile before the program
terminates. Other ways to enable trace to a memory buffer are
TraceSetExternalBuffer, TraceAttachToNTDriverBuffer, 
TraceUseMemMapFileBuffer 
   PARAMETERS:                   .
    int p_iSize    - size of the buffer text area to allocate
    ULONG   p_dwNewGroupFlags     - groups to print
    ULONG   p_dwGroupFlagsToModify-trace groups flags to change
*/
bool TraceAllocateBuffer(int p_iSize,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify);
/*
TraceSetExternalBuffer is used to share trace buffer between 
several application. If one application or driver created the 
trace buffer in some kind of shared memory, another application
can obtain a pointer to that buffer and call 
TraceSetExternalBuffer to start printing it's trace to the same
buffer. A care should be taken with group flags in this case,
because they will affect trace in both applications.
   PARAMETERS:                   .
    GlobalTraceBufferHeader* p_pBufferHeader - trace pointers 
                returned from pGetTraceBuffer
    ULONG   p_dwNewGroupFlags     - groups to print
    ULONG   p_dwGroupFlagsToModify-trace groups flags to change
*/
bool TraceSetExternalBuffer(
    struct GlobalTraceBufferHeader* p_pBufferHeader,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify);
/*
TraceAttachToNTDriverBuffer is a convenience function, which
requests the shared trace buffer from an NT kernel mode driver,
and calls TraceSetExternalBuffer to share the buffer with the
driver. The driver must process necessary IOCTL requests.
To easiest way to meet these requirements, is to include 
HTrace.cpp in the driver and call TraceIoctl
from the driver's dispatch routine, as shown in HTraceD.cpp.
   PARAMETERS:
    LPCTSTR  p_pszDeviceName - name of NT device. This parameter
      can be left NULL to use our default name
      TRACER_WIN32_FILE_NAME
    int     p_iIOCTLMapTraceBuffer - NT IOCTL code to map the
      buffer. This parameter can be left -1 to use our default
      IOCTL_TRACER_MAP_BUFFER
    int     p_iIOCTLUnMapTraceBuffer - NT IOCTL code to unmap 
      the buffer. This parameter can be left -1 to use our 
      default IOCTL_TRACER_MAP_BUFFER
    bool    p_bDontComplainIfDeviceAbsent - set to true if the 
      caller expects that the driver may be absent.
    ULONG   p_dwNewGroupFlags     - groups to print
    ULONG   p_dwGroupFlagsToModify-trace groups flags to change
*/
bool TraceAttachToNTDriverBuffer
(
    LPCTSTR p_pszDeviceName,
    int     p_iIOCTLMapTraceBuffer,
    int     p_iIOCTLUnMapTraceBuffer,
    bool    p_bDontComplainIfDeviceAbsent,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify
);
/*
TraceUseMemMapFileBuffer creates a memory mapped file
(or use an existing one) to shared trace buffer between 
several applications.
   PARAMETERS:
        p_pszMemMapFilePath  - file path
        p_iFileSize          - size (for creation)
        p_dwNewGroupFlags    - groups to print
        p_dwGroupFlagsToModify-trace groups flags to change
*/
bool TraceUseMemMapFileBuffer
(
    LPCTSTR p_pszMemMapFilePath,
    int     p_iFileSize,
    ULONG   p_dwNewGroupFlags, 
    ULONG   p_dwGroupFlagsToModify
);
/*
TraceFreeBuffer frees the trace buffer (if it was allocated),
releases memory mapped file or calls NT driver to detach from 
the buffer, which was shared by TraceAttachToNTDriverBuffer.
*/
bool TraceFreeBuffer();
/*
TraceDumpBufferToFile prints the memory buffer to the specified
file. It is usually called before the program terminates.
This function can handle circular buffers.
*/
bool TraceDumpBufferToFile(LPCTSTR p_pszFileName);

/*
pGetTraceBuffer returns LocalTraceBufferPointers structure,
which keeps pointers to the currently allocated trace buffer
(if any) including header, text area, size and footer.
*/
struct LocalTraceBufferPointers * pGetTraceBuffer();