|
1 // Clogger.h |
|
2 // |
|
3 // Copyright (c) 2006 - 2010 Accenture. All rights reserved. |
|
4 // This component and the accompanying materials are made available |
|
5 // under the terms of the "Eclipse Public License v1.0" |
|
6 // which accompanies this distribution, and is available |
|
7 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 // |
|
9 // Initial Contributors: |
|
10 // Accenture - Initial contribution |
|
11 // |
|
12 |
|
13 #ifndef CLOGGER_H |
|
14 #define CLOGGER_H |
|
15 |
|
16 #if defined(_DEBUG) && !defined(USE_CLOGGER) |
|
17 #define USE_CLOGGER |
|
18 #endif |
|
19 |
|
20 #ifdef __cplusplus |
|
21 |
|
22 #include <e32std.h> |
|
23 |
|
24 class CDesC16Array; |
|
25 |
|
26 class RClogger: public RSessionBase |
|
27 { |
|
28 public: |
|
29 /* |
|
30 * Logging commands |
|
31 */ |
|
32 |
|
33 IMPORT_C void Log(TRefByValue<const TDesC> aFmt, ...); |
|
34 IMPORT_C void Log(TRefByValue<const TDesC8> aFmt, ...); |
|
35 IMPORT_C void Log(const char* aFmt, ...); |
|
36 IMPORT_C void LogList(TRefByValue<const TDesC> aFmt, VA_LIST aList); |
|
37 IMPORT_C void LogList(TRefByValue<const TDesC8> aFmt, VA_LIST aList); |
|
38 IMPORT_C void LogList(const char* aFmt, VA_LIST aList); |
|
39 IMPORT_C void HexDump(const TDesC8& aHeader, const TDesC8& aData); |
|
40 |
|
41 IMPORT_C void Log(TUint32 aLogMask, TRefByValue<const TDesC> aFmt, ...); |
|
42 IMPORT_C void Log(TUint32 aLogMask, TRefByValue<const TDesC8> aFmt, ...); |
|
43 IMPORT_C void Log(TUint32 aLogMask, const char* aFmt, ...); |
|
44 IMPORT_C void LogList(TUint32 aLogMask, TRefByValue<const TDesC> aFmt, VA_LIST aList); |
|
45 IMPORT_C void LogList(TUint32 aLogMask, TRefByValue<const TDesC8> aFmt, VA_LIST aList); |
|
46 IMPORT_C void LogList(TUint32 aLogMask, const char* aFmt, VA_LIST aList); |
|
47 IMPORT_C void HexDump(TUint32 aLogMask, const TDesC8& aHeader, const TDesC8& aData); |
|
48 |
|
49 enum TLogBehaviour { |
|
50 /* This flag is no longer needed, and has no effect |
|
51 */ |
|
52 EMonitorTagState = 1, |
|
53 |
|
54 /* If set, a heap buffer will be allocated (and cached between calls) |
|
55 * so that arbitrary sized strings can be logged. If it is not set, a |
|
56 * fixed 256-character buffer on the stack will be used and anything |
|
57 * longer will be silently truncated. It means memory doesn't have to |
|
58 * be allocated in the client thread (which is good for performance, |
|
59 * and also means RClogger instances can be shared between threads). |
|
60 * |
|
61 * Note: an RClogger instance CANNOT be shared by multiple threads |
|
62 * if this flag is set. |
|
63 * |
|
64 * This flag is set by default. |
|
65 */ |
|
66 EUseHeapBuffer = 2, |
|
67 |
|
68 ETrimTrailingNewlines = 4, |
|
69 }; |
|
70 |
|
71 IMPORT_C void SetLogBehaviour(TUint aLogBehaviour); |
|
72 |
|
73 /* |
|
74 * These APIs use TLS to cache an RClogger session. The first time they |
|
75 * are called they will create a session, store it in TLS, and call |
|
76 * Connect() on it. They then call the non-static function of the same |
|
77 * name on that session. These functions will not allocate any memory |
|
78 * in the client heap unless SetStaticLogBehaviour is called with |
|
79 * EUseHeapBuffer. In other words the EUseHeapBuffer |
|
80 * flag is NOT set by default when calling the static functions. |
|
81 * |
|
82 * You can also call RClogger::StaticConnect(tag) to assign a tag to the |
|
83 * static session |
|
84 */ |
|
85 |
|
86 IMPORT_C static void Slog(TRefByValue<const TDesC> aFmt, ...); |
|
87 IMPORT_C static void Slog(TRefByValue<const TDesC8> aFmt, ...); |
|
88 IMPORT_C static void Slog(const char* aFmt, ...); |
|
89 IMPORT_C static void SlogList(TRefByValue<const TDesC> aFmt, VA_LIST aList); |
|
90 IMPORT_C static void SlogList(TRefByValue<const TDesC8> aFmt, VA_LIST aList); |
|
91 IMPORT_C static void SlogList(const char* aFmt, VA_LIST aList); |
|
92 IMPORT_C static void StaticHexDump(const TDesC8& aHeader, const TDesC8& aData); |
|
93 |
|
94 IMPORT_C static void Slog(TUint32 aLogMask, TRefByValue<const TDesC> aFmt, ...); |
|
95 IMPORT_C static void Slog(TUint32 aLogMask, TRefByValue<const TDesC8> aFmt, ...); |
|
96 IMPORT_C static void Slog(TUint32 aLogMask, const char* aFmt, ...); |
|
97 IMPORT_C static void SlogList(TUint32 aLogMask, TRefByValue<const TDesC> aFmt, VA_LIST aList); |
|
98 IMPORT_C static void SlogList(TUint32 aLogMask, TRefByValue<const TDesC8> aFmt, VA_LIST aList); |
|
99 IMPORT_C static void SlogList(TUint32 aLogMask, const char* aFmt, VA_LIST aList); |
|
100 IMPORT_C static void StaticHexDump(TUint32 aLogMask, const TDesC8& aHeader, const TDesC8& aData); |
|
101 |
|
102 IMPORT_C static void SetStaticLogBehaviour(TUint aLogBehaviour); |
|
103 IMPORT_C static TInt StaticConnect(); // This is implicitly called if you call Slog when not connected |
|
104 IMPORT_C static TInt StaticConnect(const TDesC& aTag); |
|
105 IMPORT_C static void StaticClose(); // Cleans up TLS, deallocates memory, closes the TLS session |
|
106 |
|
107 /* |
|
108 * Configuring logging on the fly - APIs for a gui config tool to use |
|
109 */ |
|
110 |
|
111 static const TUint32 EAllEnabled = 0xFFFFFFFFu; |
|
112 |
|
113 IMPORT_C TInt SetEnabled(const TDesC& aTag, TUint32 aEnabledMask); |
|
114 IMPORT_C TUint32 IsEnabled(const TDesC& aTag); // Non-existant tags will return all true, ie 0xFFFFFFFF, because if someone did create it later, it would default to being enabled). Failure to connect to the server will return false (because we can't log!) |
|
115 |
|
116 IMPORT_C void GetTagStatesL(CDesC16Array*& aTagNames, RBuf8& aEnabled); // aTagNames and aEnabled will be zeroed/deleted before being used. aEnabled is a bitfield of the enabled states (32 bits per tag in aTagNames) |
|
117 IMPORT_C void SetTagStatesL(const CDesC16Array* aTagNames, const TDesC8& aEnabled); // Any tag names not yet known to clogger will (in the current implementation) be ignored. aEnabled[0..4] is the enabled mask for aTagNames[0], aEnabled[4..8] is for aTagNames[1] etc |
|
118 |
|
119 /* |
|
120 * Global logging options (ones that affect all users of Clogger) |
|
121 */ |
|
122 |
|
123 enum TGlobalOptions { |
|
124 // All these options default to being unset |
|
125 EBufferLog = 1, // If set, use a RAM buffer for increased performance. If unset, writes are guaranteed to be flushed to disk before Log() returns. Default is not to buffer. |
|
126 ERDebugPrint = 2, // Deprecated because the name is no longer clear given we have ERedirectRDebugPrintToClogger as well. Use EMirrorToRDebugPrint instead. |
|
127 EMirrorToRDebugPrint = 2, // Mirror all logging to RDebug::Print. Note enabling this may impact performance as RDebug can be quite slow. If EBufferLog is enabled as well the RDebug printing will be done from the buffer in a separate thread, which should mean performance is not affected unless the clogger serve runs out of memory to buffer the output |
|
128 EMirrorToBluetooth = 4, // Outputs to a bluetooth serial port. The logger is dormant until something connects to the port |
|
129 EMirrorToMessageQueue = 32, // This outputs the log data to an RMsgQueue. Caution is advised, you should not turn on this option unless you know what you're doing! |
|
130 ERedirectRDebugPrintToClogger = 8, // Mirrors Kern::Printf and RDebug::Print to the clogger log file. May be combined with EMirrorToRDebugPrint, in which case all RDebug::Print calls *except* ones made by clogger itself are redirected |
|
131 EDisableFileWriter = 16, // Set this option to disable writing to the log file. Useful for debugging out-of-disk problems assuming you're using EMirrorToRDebugPrint |
|
132 }; |
|
133 |
|
134 IMPORT_C void SetGlobalOptions(TUint aGlobalOptions); |
|
135 IMPORT_C TUint GetGlobalOptions(); |
|
136 |
|
137 IMPORT_C TInt GetRamBufferSize(TInt* aNumberOfBuffers); |
|
138 IMPORT_C void SetRamBufferSize(TInt aSizeInBytes, TInt aNum); // If buffering is enabled the server will use this many buffers of this size |
|
139 |
|
140 /* |
|
141 * Configuring rotation on the fly |
|
142 */ |
|
143 |
|
144 IMPORT_C TInt Rotate(); |
|
145 IMPORT_C TInt Rotate(TDes& aFileName); // On success aFileName will be set to the name of the rotated log |
|
146 |
|
147 enum TRotateBehaviour { |
|
148 EDoNothingSpecial = 0, |
|
149 ECopyRotatedToExternalMedia = 1, |
|
150 EAutoRotateAtStartup = 4, |
|
151 ECompressRotatedLogs = 8, // Currently uses GZip compression on the rotated log files |
|
152 }; |
|
153 |
|
154 IMPORT_C void SetRotateBehaviour(TInt aNumberOfOldLogsToKeep, TUint aRotateBehaviour); // First argument of zero means don't keep any. If you don't want to ever delete the old logs, use A Big Number |
|
155 IMPORT_C TUint GetRotateBehaviour(TInt* aNumberOfOldLogsToKeep); |
|
156 |
|
157 /* |
|
158 * General |
|
159 */ |
|
160 IMPORT_C RClogger(); |
|
161 IMPORT_C TInt Connect(); // If using this overload your thread full name becomes your tag |
|
162 IMPORT_C TInt Connect(const TDesC& aTag); // All logging will be prepended with this tag. Multiple clients may use the same tag. |
|
163 IMPORT_C void Close(); |
|
164 |
|
165 IMPORT_C void PersistSettings(); // Store enabled and rotate settings for next boot |
|
166 IMPORT_C void ResetSettings(); // Restore all settings to default, including stored ones (ie PersistSettings is implicitly called) |
|
167 |
|
168 IMPORT_C TInt Reserved(TInt aCode, TAny*& aArg, TAny* aArg2); // Reserved, do not call or you will get panicked |
|
169 IMPORT_C static TInt StaticReserved(TInt aCode, TAny*& aArg, TAny* aArg2); // Reserved, do not call or you will get panicked |
|
170 |
|
171 private: |
|
172 static TBool GetTls(RClogger*& aClogger, TBool aAutoConnect, const TDesC* aTag = NULL, TInt* aError = 0); |
|
173 inline TBool Enabled(TUint32); |
|
174 void UpdateEnabled(TInt aSequence); |
|
175 IMPORT_C RClogger(TAny* aTls); // Do not call directly |
|
176 |
|
177 protected: |
|
178 TUint iFlags; |
|
179 TUint32 iEnabled; |
|
180 RBuf8 iBuf; |
|
181 TUint32 iPimpl[2]; // an RCloggerBody |
|
182 TUint32 iSpare; |
|
183 TInt iSequence; |
|
184 |
|
185 friend class RCloggerBody; |
|
186 }; |
|
187 |
|
188 _LIT(KCloggerDefaultTag, "DefaultForNewTags"); // This tag controls the default value for the enabled mask of things that start logging for the first time |
|
189 |
|
190 #ifdef USE_CLOGGER |
|
191 #define SLOG(args...) RClogger::Slog(args) |
|
192 #else |
|
193 #define SLOG(args...) |
|
194 #endif |
|
195 |
|
196 #ifdef USE_CLOGGER |
|
197 // Debatable whether you'd want/need these |
|
198 #define CLOGGER_STATICCONNECT(aTag) RClogger::StaticConnect(aTag) |
|
199 #define CLOGGER_STATICCONNECTL(aTag) User::LeaveIfError(RClogger::StaticConnect(aTag)) |
|
200 #define CLOGGER_STATICCLOSE() RClogger::StaticClose() |
|
201 #else |
|
202 #define CLOGGER_STATICCONNECT(aTag) |
|
203 #define CLOGGER_STATICCONNECTL(aTag) |
|
204 #define CLOGGER_STATICCLOSE() |
|
205 #endif |
|
206 |
|
207 class RCloggerLogConsumer : public RSessionBase |
|
208 { |
|
209 public: |
|
210 /* |
|
211 * API for clients that want the logging data - not for general usage! |
|
212 */ |
|
213 IMPORT_C RCloggerLogConsumer(); |
|
214 IMPORT_C TInt Connect(); |
|
215 IMPORT_C void GetNextLog(TRequestStatus& aStatus, TPtrC8& aResultBuffer); |
|
216 IMPORT_C void CancelGetNextLog(); |
|
217 IMPORT_C void Close(); |
|
218 |
|
219 private: |
|
220 RChunk iSharedChunk; |
|
221 TPtr8 iResultBufferPtr; |
|
222 }; |
|
223 |
|
224 extern "C" IMPORT_C void Clogger_Slog(const char* aFmt, ...); |
|
225 |
|
226 #else // __cplusplus |
|
227 |
|
228 IMPORT_C void Clogger_Slog(const char* aFmt, ...); |
|
229 |
|
230 #endif // __cplusplus |
|
231 |
|
232 |
|
233 #endif // CLOGGER_H |