htrace.h

A Windows CE API Inecptor Tools

/*
TraceFreezeBufferAfter will freeze output to the trace buffer
after the specified amount of data (measured in percents
from the buffer size). 
Common use:
- TraceFreezeBufferAfter(0) to freeze output immediately - 
    last printed trace will remain the last in the buffer.
- TraceFreezeBufferAfter(50) - last printed trace will be
        approximately at the middle of the buffer
- TraceFreezeBufferAfter(100) - last printed trace will be
   the first in the trace buffer after freeze.
*/
void TraceFreezeBufferAfter(int p_iPercent);

/*
TraceEraseBuffer erases the trace buffer by resetting 
the "number of bytes written" field of the trace buffer
*/
void TraceEraseBuffer();

#ifdef TRACER_NTDRIVER
typedef struct _DRIVER_OBJECT *PDRIVER_OBJECT;
/*
EnableTraceToOutputLog used by NT drivers to enable some trace
groups to be printed to the system log.
*/
bool EnableTraceToOutputLog(PDRIVER_OBJECT p_pDriverObject,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify);
#endif

/*Actual trace output routines with group bit masks:*/
/*
OutputTraceString is the fastest tracing routine.It does no 
formatting, it simply copies the specified string to output 
streams, which matches the specified group mask.
   PARAMETERS:                   .
                        
    ULONG p_dwMask          flags from TraceGroups
    LPCSTR p_pszMessage,    string
    int     p_iLen          Number of characters in the string
*/
void OutputTraceString(ULONG p_dwMask, LPCTSTR p_pszMessage, 
                       int p_iLen);
/*
HTraceImpl and macro HTRACE are used to format trace message
and print it to streams,which matches the specified group mask.
*/
void HTraceImpl(ULONG p_dwMask, LPCTSTR p_pszFormat, ...);
#define HTRACE HTraceImpl
/*
OutputTraceStringUnconditional disregards group masks
and copies the given string to all output streams,
which has their TO_* constants included in p_dwOutputMask
*/
void OutputTraceStringUnconditional(ULONG   p_dwOutputMask,
    LPCTSTR  p_pszMessage, int     p_iLenChars);

void RegisterTraceView(LPCTSTR p_pszClassName);

/*Support for keyword masks*/
#ifdef __cplusplus
class TraceKeywordCheck 
{
public:
    void Output(char * p_pszKeyWord, LPCTSTR p_pszFormat,
        ...);
    void CompareKeyWords(const char * p_pszKeyWord);

    ULONG m_dwEnabledStreams;
    ULONG m_dwModificationCounter;
};/*class TraceKeywordCheck*/

/*
Parameters of HTRACEK must be enclosed in double brackets like:
HTRACEK(("KeyWord", "Format %s %d", "First Param", 123))
This macro formats the trace messages and prints it to the
output streams, which have keyword masks that matches the 
given keyword.
*/
#define HTRACEK(Params)  {  \
    static TraceKeywordCheck l_Check = {false, 0}; \
    l_Check.Output Params ;   \
}

#endif /*__cplusplus*/

#else /* } TRACE_ {*/

#if defined(__cplusplus) && !defined(TRACE_CPP) /* {*/
/*
The following are empty versions of all functions,
which are used then TRACE_ macro is not defined.
They should be completely optimized out by the compiler,
so the all trace calls can be left in the release version
of the program.
*/

inline bool TraceInitialize(){return false;};
inline bool TraceUnInitialize(){return false;};

inline bool TraceAssignGroupsToStream
    (ULONG   p_dwTraceOutputs, ULONG   p_dwNewGroupFlags,
    ULONG   p_dwGroupFlagsToModify) {return false;}
inline bool TraceAssignGroupKeyWordToStream
    (ULONG   p_dwTraceOutputs, char  * p_pszGroupKeyWord)
    {return false;}
inline ULONG TraceGetAssignedGroupsToStream
    (ULONG p_dwTraceOutputs) {return 0;}
inline LPCSTR TraceGetAssignedGroupKeyWordsToStream
    (ULONG p_dwTraceOutputs) {return NULL;};
inline bool TraceReadWriteSettings
    (HKEY p_hKeyRoot, LPCTSTR p_pszPath,
    bool p_bWrite, ULONG   p_ulOutputsToProcess) 
    {return false;}

#ifndef TRACER_NTDRIVER
inline bool TraceSetOutputToFile(LPCTSTR p_pszFileName,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify,
    ULONG   p_dwNewFlushBits ,ULONG   p_dwFlushBitsToModify)
    {return false;}
inline LPCTSTR TraceGetCurTraceFileName(){return NULL;};
#endif

inline bool TraceAllocateBuffer(int p_iSize,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify)
    {return false;}
inline bool TraceSetExternalBuffer(
    GlobalTraceBufferHeader* p_pBufferHeader,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify)
    {return false;}
inline bool TraceAttachToNTDriverBuffer
(
    LPCSTR  p_pszDeviceName,
    int    p_iIOCTLMapTraceBuffer,int p_iIOCTLUnMapTraceBuffer,
    bool    p_bDontComplainIfDeviceAbsent,
    ULONG   p_dwNewGroupFlags, ULONG   p_dwGroupFlagsToModify
){return false;}
inline bool TraceUseMemMapFileBuffer
(
    LPCTSTR p_pszMemMapFilePath,
    int     p_iFileSize,
    ULONG   p_dwNewGroupFlags, 
    ULONG   p_dwGroupFlagsToModify
){return false;}
inline bool TraceFreeBuffer(){return false;}
inline bool TraceDumpBufferToFile(LPCTSTR p_pszFileName)
{return false;}
inline LocalTraceBufferPointers*pGetTraceBuffer(){return NULL;}

#ifdef TRACER_NTDRIVER
typedef struct _DRIVER_OBJECT *PDRIVER_OBJECT;
inline bool EnableTraceToOutputLog(
    PDRIVER_OBJECT p_pDriverObject, ULONG   p_dwNewGroupFlags, 
    ULONG   p_dwGroupFlagsToModify) {return false;}
#endif

/*Actual trace output routines with group bit masks:*/
inline void OutputTraceString(ULONG p_dwMask, 
    LPCTSTR p_pszMessage, int p_iLen) {}
inline void HTraceImpl(ULONG p_dwMask, 
                       LPCTSTR p_pszFormat, ...){}
inline void OutputTraceStringUnconditional
    (ULONG p_dwOutputMask, LPCSTR  p_pszMessage, int p_iLen) {}
inline void RegisterTraceView(LPCTSTR p_pszClassName) {}
inline void Dummy(...){}
#define HTRACE            1 ? (void)0 : HTraceImpl
#define HTRACEK           1 ? (void)0 : Dummy

#endif /* #if defined(__cplusplus) && !defined(TRACE_CPP) }*/
#endif/*TRACE_ else }*/

/*The following definitions are for communication with NT 
driver*/
#if defined(WIN32) && !defined(TRACER_NTDRIVER)
#include <winioctl.h>
#endif

#if defined(WIN32) || defined(TRACER_NTDRIVER) /*{*/

#define TRACER_KERNEL_DEVICE_NAME L"\\Device\\HTrcDrv"
#define TRACER_DOS_DEVICE_NAME_A  "\\DosDevices\\HTrcDrv"
#define TRACER_DOS_DEVICE_NAME_W  L"\\DosDevices\\HTrcDrv"

#define TRACER_WIN32_FILE_NAME_W    L"\\\\.\\HTrcDrv"
#define TRACER_WIN32_FILE_NAME      _T("\\\\.\\HTrcDrv")

/*
Define a random device type and IOCTL codes, which will be used
by our launcher application to call our driver
*/
#define FILE_DEVICE_TRACER     0x83ff

#define IOCTL_TRACER_CHECK_ACTIVE ((ULONG) CTL_CODE\
( FILE_DEVICE_TRACER, 0x01, METHOD_BUFFERED, FILE_ANY_ACCESS ))
#define IOCTL_TRACER_DUMP_TRACE   ((ULONG) CTL_CODE\
( FILE_DEVICE_TRACER, 0x02, METHOD_BUFFERED, FILE_ANY_ACCESS ))
#define IOCTL_TRACER_MAP_BUFFER ((ULONG) CTL_CODE\
( FILE_DEVICE_TRACER, 0x03, METHOD_BUFFERED, FILE_ANY_ACCESS ))
#define IOCTL_TRACER_UNMAP_BUFFER ((ULONG) CTL_CODE\
( FILE_DEVICE_TRACER, 0x04, METHOD_BUFFERED, FILE_ANY_ACCESS ))

#endif /*#if defined(WIN32) || defined(TRACER_NTDRIVER) } */

#ifdef TRACER_NTDRIVER/* { */
/*
The following routines to be used by a NT driver to map, 
unmap and print trace buffer to a file
*/
#ifdef TRACE_ /* { */
/*
TraceIoctl: This function should be called by driver's dispatch
    routine to allow the tracer to respond to request for 
    mapping and unmapping trace buffer and dumping it to a file
      
PARAMETERS:                   .
                                  
   IN PDEVICE_OBJECT   p_pDeviceObject        our device object
   IN PIRP             p_pIrp                 request packet
          The following are IOCTL codes for tracer requests.
          Usually these are IOCTL_TRACER_* defined in HTrace.h,
          but the driver may assign different codes.
   IN ULONG p_dwIoctlCheckActive  - check presence of tracer.
              This code will be returned in the output buffer.
   IN ULONG p_dwIoctlDumpTrace    - dump the content of trace
              memory buffer to the file. IOCTL input buffer
              has the name of the file.
   IN ULONG p_dwIoctlMapBuffer    - map the trace memory buffer
              to the user space of the current application and
              return the address in the IOCTL output buffer.
   IN ULONG p_dwIoctlUnMapBuffer  - unmap the trace buffer.
           The IOCTL input buffer should have the user address,
           which was previously returned by p_iIoctlMapBuffer
*/
NTSTATUS TraceIoctl
( 
    IN PDEVICE_OBJECT   p_pDeviceObject, 
    IN PIRP             p_pIrp,
    IN ULONG            p_dwIoctlCheckActive,
    IN ULONG            p_dwIoctlDumpTrace,
    IN ULONG            p_dwIoctlMapBuffer,
    IN ULONG            p_dwIoctlUnMapBuffer
);
/*
MapTraceMemory map the trace buffer to the address context of the
current application and store the new MapMem object into
the given FILE_OBJECT, so we will be able to unmap the 
memory when the file is closed.
   PARAMETERS:
    PFILE_OBJECT p_pFileObject - file object, which was created 
        specifically for communication with the tracer driver.
        Don't try to call this function on other file objects,
        because it will overwrite FsContext field.
    ULONG   *p_pulReturnUserAddress - return the mapped address
*/
NTSTATUS MapTraceMemory(PFILE_OBJECT p_pFileObject, 
                        ULONG *p_pulReturnUserAddress);
/*
UnmapTraceMemory unmaps the trace buffer, which was mapped by 
    MapTraceMemory.
   PARAMETERS:
    ULONG        p_ulUserAddress - the address, which was
        returned by MapTraceMemory
    PFILE_OBJECT p_pFileObject - must be the file object, which
       was created for communication with the tracer driver and
       was used in call to MapTraceMemory.
*/
NTSTATUS UnmapTraceMemory(ULONG p_ulUserAddress, 
                          PFILE_OBJECT p_pFileObject);
#else
inline NTSTATUS TraceIoctl
( 
    IN PDEVICE_OBJECT   p_pDeviceObject, 
    IN PIRP             p_pIrp,
    IN ULONG            p_dwIoctlCheckActive,
    IN ULONG            p_dwIoctlDumpTrace,
    IN ULONG            p_dwIoctlMapBuffer,
    IN ULONG            p_dwIoctlUnMapBuffer
    ){return STATUS_NOT_IMPLEMENTED;}
inline NTSTATUS MapTraceMemory(PFILE_OBJECT p_pFileObject, 
                        ULONG *p_pulReturnUserAddress)
                        {return STATUS_NOT_IMPLEMENTED;}
inline NTSTATUS UnmapTraceMemory(ULONG p_ulUserAddress, 
                          PFILE_OBJECT p_pFileObject)
                          {return STATUS_NOT_IMPLEMENTED;}
#endif /*#ifdef TRACE_ else }*/
#endif /*#ifdef TRACER_NTDRIVER }*/

#ifdef __cplusplus
}/*extern "C"*/
#endif

#if defined(TRACE_) && defined WIN32 && !defined(TRACER_NTDRIVER)//{
#if defined(__cplusplus) /*{*/
/*
class LocalStringHolder, strGetErrorExplanation and ERR_EXPL
are useful for printing Win32 error messages.
For example : HTRACE(TG_Error, "ERROR: CreateFile failed - %s",
            ERR_EXPL(GetLastError());

class LocalStringHolder simply keeps a string allocated using 
LocalAlloc API function and frees this function in destructor.
*/
class LocalStringHolder
{
public:
    LocalStringHolder()
    {
        m_pszString = m_szDummy;
        *m_szDummy = 0;
    }
    ~LocalStringHolder(){Free();}
    LocalStringHolder(const LocalStringHolder & p_rScr) 
    {
        m_pszString = m_szDummy;
        *m_szDummy = 0;
        StrDup(p_rScr.m_pszString);
    }
    LocalStringHolder & operator = 
        (const LocalStringHolder & p_rScr) 
    {
        Free();
        StrDup(p_rScr.m_pszString);
        return *this;
    }

    void StrDup(PTSTR p_pszStr)
    {
        Free();
        int l_iSize = (_tcslen(p_pszStr)+1)*sizeof(TCHAR);
        m_pszString = (PTSTR)LocalAlloc(LPTR, l_iSize);
        if(!m_pszString)
            m_pszString = m_szDummy;
        else
            memcpy(m_pszString, p_pszStr, l_iSize);
    }/*void SetStr*/

    void AdoptStr(PTSTR p_pszStr)
        /*p_pszStr must be allocated using LocalAlloc*/
    {
        Free();
        m_pszString = p_pszStr;
    }
    LPCTSTR strGetStr(){return m_pszString;}
    void Free()
    {
        if(m_pszString != m_szDummy)
            LocalFree(m_pszString);
        m_pszString = m_szDummy;
    }/*void Free()*/
protected:
    PTSTR   m_pszString;
    TCHAR   m_szDummy[1];
};/*class LocalStringHolder*/

/*
strGetErrorExplanation takes WIN32 error code and returns 
error message
*/
LocalStringHolder strGetErrorExplanation(DWORD p_dwErrCode);

/*
ERR_EXPL is a convenient macro to be used in printf and 
HTRACE calls to print Win32 error messages.
*/
#define ERR_EXPL(ErrorCode) \
    ((LPCTSTR)strGetErrorExplanation(ErrorCode).strGetStr())

#endif /*defined(__cplusplus) } */
#endif /*defined WIN32 && !defined(TRACER_NTDRIVER) }*/

#if defined(_WIN32_WCE)

/*
#undef RETAILMSG
#define RETAILMSG(mask, printf_exp)  HTraceImpl(mask, A printf_exp)

#undef DEBUGZONE
#define DEBUGZONE(n) n
*/
#endif


#endif /*TRACE_H }*/