1/*
2 * Python bindings.
3 *
4 * Open Phone Abstraction Library (OPAL)
5 *
6 * Copyright (c) 2011 Demetrius Cassidy
7 *
8 * The contents of this file are subject to the Mozilla Public License
9 * Version 1.0 (the "License"); you may not use this file except in
10 * compliance with the License. You may obtain a copy of the License at
11 * http://www.mozilla.org/MPL/
12 *
13 * Software distributed under the License is distributed on an "AS IS"
14 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
15 * the License for the specific language governing rights and limitations
16 * under the License.
17 *
18 * The Original Code is Open Phone Abstraction Library (OPAL)
19 *
20 * The Initial Developer of the Original Code is Demetrius Cassidy
21 *
22 * Contributor(s): ______________________________________.
23 *
24 * $Revision: 26117 $
25 * $Author: rjongbloed $
26 * $Date: 2011-07-04 22:45:05 -0500 (Mon, 04 Jul 2011) $
27 */
28
29/**Class to encapsulate tracing functions.
30   This class does not require any instances and is only being used as a
31   method of grouping functions together in a name space.
32  */
33class PTrace
34{
35%TypeHeaderCode
36#include <ptlib.h>
37#include <ptlib\object.h>
38%End
39public:
40  /// Options for trace output.
41  enum Options {
42    /**Include PTrace::Block constructs in output
43       If this is bit is clear, all PTrace::Block output is inhibited
44       regardless of the trace level. If set, the PTrace::Block may occur
45       provided the trace level is greater than zero.
46    */
47    Blocks = 1,
48    /// Include date and time in all output
49    DateAndTime = 2,
50    /// Include (millisecond) timestamp in all output
51    Timestamp = 4,
52    /// Include identifier for thread trace is made from in all output
53    Thread = 8,
54    /// Include trace level in all output
55    TraceLevel = 16,
56    /// Include the file and line for the trace call in all output
57    FileAndLine = 32,
58    /// Include thread object pointer address in all trace output
59    ThreadAddress = 64,
60    /// Append to log file rather than resetting every time
61    AppendToFile = 128,
62    /** Output timestamps in GMT time rather than local time
63      */
64    GMTTime = 256,
65    /** If set, log file will be rotated
66      */
67    RotateDaily = 512,
68    RotateHourly = 1024,
69    RotateMinutely = 2048,
70    RotateLogMask = 3584, //RotateDaily + RotateHourly + RotateMinutely,
71    /** SystemLog flag for tracing within a PServiceProcess application. Must
72        be set in conjection with SetStream(new PSystemLog).
73      */
74    SystemLogStream = 32768
75  };
76
77
78  /**Set the most common trace options.
79     If filename is not NULL then a PTextFile is created and attached the
80     trace output stream. This object is never closed or deleted until the
81     termination of the program.
82
83     A trace output of the program name version and OS is written as well.
84    */
85  static void Initialise(
86    unsigned level,
87    const char * filename = NULL,
88    unsigned options = Timestamp | Thread | Blocks
89  );
90
91  /**Set the most common trace options.
92     If filename is not NULL then a PTextFile is created and attached the
93     trace output stream. This object is never closed or deleted until the
94     termination of the program.
95
96     If rolloverPatterm is not NULL it is used as the time format patterm
97     appended to filename if the RotateDaily is set. Default: yyyy_MM_dd
98
99     A trace output of the program name version and OS is written as well.
100    */
101  static void Initialise(
102    unsigned level,
103    const char * filename,
104    const char * rolloverPattern,
105    unsigned options = Timestamp | Thread | Blocks
106  );
107
108  /** Set the trace options.
109  The PTRACE(), PTRACE_BLOCK() and PTRACE_LINE() macros output trace text that
110  may contain assorted values. These are defined by the Options enum.
111
112  Note this function OR's the bits included in the options parameter.
113  */
114  static void SetOptions(unsigned options /** New level for trace */ );
115
116  /** Clear the trace options.
117  The #PTRACE(), #PTRACE_BLOCK() and #PTRACE_LINE() macros output trace text that
118  may contain assorted values. These are defined by the Options enum.
119
120  Note this function AND's the complement of the bits included in the options
121  parameter.
122  */
123  static void ClearOptions(unsigned options /** New level for trace */ );
124
125  /** Get the current trace options.
126  The #PTRACE(), #PTRACE_BLOCK() and #PTRACE_LINE() macros output trace text that
127  may contain assorted values. These are defined by the Options enum.
128  */
129  static unsigned GetOptions();
130
131  /** Set the trace level.
132  The #PTRACE() macro checks to see if its level is equal to or lower then the
133  level set by this function. If so then the trace text is output to the trace
134  stream.
135  */
136  static void SetLevel(unsigned level /** New level for trace */ );
137
138  /** Get the trace level.
139  The #PTRACE() macro checks to see if its level is equal to or lower then the
140  level set by this function. If so then the trace text is output to the trace
141  stream.
142  */
143  static unsigned GetLevel();
144
145  /** Determine if the level may cause trace output.
146  This checks against the current global trace level set by #PSetTraceLevel
147  for if the trace output may be emitted. This is used by the PTRACE macro.
148  */
149  static PBoolean CanTrace(unsigned level /** Trace level to check */);
150
151   /** Cleanup the trace system for a specific thread
152      When using thread local storage, this will delete the per-thread trace context
153    */
154  static void Cleanup();
155 };