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 };