|
1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // ULogger Client API header |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 @publishedPartner |
|
21 @prototype |
|
22 */ |
|
23 |
|
24 #ifndef ULOGGERCLIENT_H |
|
25 #define ULOGGERCLIENT_H |
|
26 |
|
27 #include <e32std.h> // RSessionBase |
|
28 #include <e32base.h> |
|
29 #include "uloggerdatatypes.h" |
|
30 |
|
31 namespace Ulogger |
|
32 { |
|
33 |
|
34 /** |
|
35 Client-side session to the ULogger server. |
|
36 This class should be used to configure ULogger server. |
|
37 */ |
|
38 class RULogger : public RSessionBase |
|
39 { |
|
40 |
|
41 public: |
|
42 /* |
|
43 Default constructor. |
|
44 */ |
|
45 IMPORT_C RULogger(); |
|
46 |
|
47 /* |
|
48 Default destructor. |
|
49 Closes the client session. |
|
50 */ |
|
51 IMPORT_C ~RULogger(); |
|
52 |
|
53 /** |
|
54 Connects a client to the ULogger server. |
|
55 If the server isn't already running it will be started. |
|
56 To end the server session, use Close(). |
|
57 |
|
58 @return KErrNone, if successful, otherwise one of the other system-wide |
|
59 error codes returned by RProcess:Create() or |
|
60 RSessionBase::CreateSession(). |
|
61 */ |
|
62 IMPORT_C TInt Connect(); |
|
63 |
|
64 /** |
|
65 Not yet supported, does nothing and returns KErrNotSupported. |
|
66 |
|
67 Starts/stops running ULogger as a service. Running ULogger as a service |
|
68 means that ULogger is always active in the background, which is necessary |
|
69 if the objective is to connect to ULogger from a remote machine, so that |
|
70 ULogger is then listening for remote connections. |
|
71 If ULogger is not running as a service, it is only active when it is |
|
72 handling a client request or it is currenty logging traces (i.e. the Start() |
|
73 function was called). |
|
74 |
|
75 @param aRunAsService The flag to indicate whether the server should run as a |
|
76 service or not |
|
77 @return KErrNotSupported, as this function is not yet implemented in the server. |
|
78 */ |
|
79 IMPORT_C TInt RunAsService(TBool aRunAsService); |
|
80 |
|
81 /** |
|
82 Starts outputting trace packets. |
|
83 Pre-requisite: This will only output trace packets containing filter identifers that |
|
84 match enabled filters. Use SetPrimaryFiltersEnabled(), SetSecondaryFiltersEnabled() and |
|
85 SetSecondaryFilteringEnabled() to enable the relevant filters. |
|
86 |
|
87 @return KErrNone, if sending the Start message to the server was successful; |
|
88 KErrCorrupt, if the ULogger configuration file is corrupt; |
|
89 KErrServerTerminated, if the server is no longer present; |
|
90 KErrServerBusy, if there are no message slots available; |
|
91 KErrNoMemory, if there is insufficient memory available; |
|
92 KErrInUse, if server was started previously; |
|
93 otherwise one of the other system-wide error codes. |
|
94 */ |
|
95 IMPORT_C TInt Start(); |
|
96 |
|
97 /** |
|
98 Stops outputting trace packets. |
|
99 |
|
100 @return KErrNone, if sending the Stop message to the server was successful; |
|
101 KErrServerTerminated, if the server is no longer present; |
|
102 KErrServerBusy, if there are no message slots available; |
|
103 KErrNoMemory, if there is insufficient memory available; |
|
104 KErrNotReady, if ULogger wasn't started previously. |
|
105 */ |
|
106 IMPORT_C TInt Stop(); |
|
107 |
|
108 /** |
|
109 Restarts server. |
|
110 |
|
111 @return KErrNone, if sending the Restart message to the server was successful; |
|
112 KErrCorrupt, if the ULogger configuration file is corrupt; |
|
113 KErrServerTerminated, if the server is no longer present; |
|
114 KErrServerBusy, if there are no message slots available; |
|
115 KErrNoMemory, if there is insufficient memory available; |
|
116 otherwise one of the other system-wide error codes. |
|
117 */ |
|
118 IMPORT_C TInt Restart(); |
|
119 |
|
120 /** |
|
121 Enables/disables the specified primary filters. |
|
122 This allows output of trace packets containing primary filter identifiers that match the |
|
123 enabled primary filters. |
|
124 Note: If a trace packet contains a secondary filter identifier, and secondary filtering is |
|
125 enabled, the matching secondary filter must also be enabled to allow this packet to be output. |
|
126 |
|
127 @param aFilters The primary filters to enable/disable |
|
128 @param aEnabled The boolean to specify the action. ETrue to enable and EFalse to disable. |
|
129 @return KErrNone, if sending the SetPrimaryFiltersEnabled message to the |
|
130 server was successful; |
|
131 KErrArgument, if the specified array of filters contains more than |
|
132 KMaxPrimaryFiltersLimit elements or the array is empty; |
|
133 KErrCorrupt, if the ULogger configuration file is corrupt; |
|
134 otherwise one of the other system-wide error codes. |
|
135 */ |
|
136 IMPORT_C TInt SetPrimaryFiltersEnabled(const CArrayFixFlat<TUint8>& aFilters, TBool aEnabled); |
|
137 |
|
138 /** |
|
139 Gets all enabled primary filters. |
|
140 |
|
141 @param aFilters The array to be populated with enabled filters |
|
142 @return KErrNone, if sending the PrimaryFiltersEnabled message to the |
|
143 server was successful; |
|
144 KErrCorrupt, if the ULogger configuration file is corrupt; |
|
145 otherwise one of the other system-wide error codes. |
|
146 */ |
|
147 IMPORT_C TInt GetPrimaryFiltersEnabled(CArrayFixFlat<TUint8>& aFilters); |
|
148 |
|
149 /** |
|
150 Enables/disables the specified secondary filters. |
|
151 This allows output of trace packets containing secondary filter identifiers that match the |
|
152 enabled secondary filters. |
|
153 Note1: Secondary filters are only relevant when secondary filtering is |
|
154 enabled (see SetSecondaryFilteringEnabled()). If secondary filtering |
|
155 is disabled, trace packets are logged regardless of any secondary filter identifiers. |
|
156 Note2: Enabling secondary filters will automatically enable secondary filtering. |
|
157 Note3: Primary filtering is always enabled and therefore there is no |
|
158 equivalent method for enabling/disabling primary filtering. |
|
159 |
|
160 @param aFilters The secondary filters to enable/disable |
|
161 @param aEnabled The boolean to specify the action. ETrue to enable and EFalse to disable. |
|
162 @return KErrNone, if sending the SetSecondaryFiltersEnabled message to the |
|
163 server was successful; |
|
164 KErrArgument, if the specified array of filters contains more than |
|
165 KMaxSecondaryFiltersLimit elements, the array is empty or |
|
166 number of currently set filters plus number of elements in aFilters array |
|
167 is greather than KMaxSecondaryFiltersLimit; |
|
168 KErrCorrupt, if the ULogger configuration file is corrupt; |
|
169 otherwise one of the other system-wide error codes. |
|
170 */ |
|
171 IMPORT_C TInt SetSecondaryFiltersEnabled(const RArray<TUint32>& aFilters, TBool aEnabled); |
|
172 |
|
173 /** |
|
174 Gets all enabled secondary filters. |
|
175 |
|
176 @param aFilters The array to be populated with enabled filters |
|
177 @return KErrNone, if sending the SecondaryFiltersEnabled message to the |
|
178 server was successful; |
|
179 KErrNoMemory, if there is insufficient memory available; |
|
180 KErrCorrupt, if the ULogger configuration file is corrupt; |
|
181 otherwise one of the other system-wide error codes. |
|
182 */ |
|
183 IMPORT_C TInt GetSecondaryFiltersEnabled(RArray<TUint32>& aFilters); |
|
184 |
|
185 /** |
|
186 Enables/disables filtering on secondary filters. |
|
187 When secondary filtering is enabled, only those trace packets containing a |
|
188 secondary filter identifier matching an enabled secondary filter are output |
|
189 (see SetSecondaryFiltersEnabled()). Note that trace packets must also contain |
|
190 a primary filter identifier matching an enabled primary filter in order to be output |
|
191 (see SetPrimaryFilterEnabled()). |
|
192 |
|
193 @param aEnabled The boolean to specify the action. ETrue to enable and EFalse to disable. |
|
194 @return KErrNone, if sending the SetSecondaryFilteringEnabled message to the |
|
195 server was successful; |
|
196 KErrCorrupt, if the ULogger configuration file is corrupt; |
|
197 otherwise one of the other system-wide error codes. |
|
198 */ |
|
199 IMPORT_C TInt SetSecondaryFilteringEnabled(TBool aEnabled); |
|
200 |
|
201 /** |
|
202 Gets secondary filtering enabled value. |
|
203 |
|
204 @param aEnabled The boolean to be populated with the secondary filtering enabled value |
|
205 @return KErrNone, if sending the SecondaryFilteringEnabled message to the |
|
206 server was successful; |
|
207 otherwise one of the other system-wide error codes. |
|
208 */ |
|
209 IMPORT_C TInt GetSecondaryFilteringEnabled(TBool& aEnabled); |
|
210 |
|
211 /** |
|
212 Sets which output plug-in is to be used for outputting trace packets. |
|
213 The plug-in that is passed to this method needs to be one of the |
|
214 plug-ins reported by InstalledOutputPlugins(); |
|
215 |
|
216 @param aPluginName The name of the plug-in to be used, needs to be one of |
|
217 the names returned by InstalledOutputPlugins() |
|
218 @return KErrNone, if sending the SetActiveOutputPlugin message to the server |
|
219 was successful; |
|
220 KErrAlreadyExists, if aPluginName value was previously set; |
|
221 KErrNotFound, if aPluginName does not match the name of an existing Ulogger output plug-in; |
|
222 KErrNoMemory, if there is insufficient memory available; |
|
223 KErrArgument, if passed descriptor is empty; |
|
224 otherwise one of the other system-wide error codes. |
|
225 */ |
|
226 IMPORT_C TInt ActivateOutputPlugin(const TDesC8& aPluginName); |
|
227 |
|
228 /** |
|
229 Gets the active output plug-in. |
|
230 |
|
231 @param aPluginName The 8-bit descriptor to be populated with the name of |
|
232 the active output plug-in (max length: KMaxPath). |
|
233 @return KErrNone, if sending the ActiveOutputPlugin message to the |
|
234 server was successful; |
|
235 KErrOverflow, if the passed-in descriptor is smaller than the length |
|
236 of the plug-in name; |
|
237 KErrNotFound, if no output plug-in has been set; |
|
238 otherwise one of the other system-wide error codes. |
|
239 */ |
|
240 IMPORT_C TInt GetActiveOutputPlugin(TDes8& aPluginName); |
|
241 |
|
242 /** |
|
243 Gets all the installed output plug-ins. |
|
244 |
|
245 @param aPluginNames The array to be populated with the installed plug-in filename and plug-in names. |
|
246 @return KErrNone, if sending the InstalledOutputPlugins message to the |
|
247 server was successful; |
|
248 KErrNoMemory, if there is insufficient memory available; |
|
249 otherwise one of the other system-wide error codes. |
|
250 */ |
|
251 IMPORT_C TInt GetInstalledOutputPlugins(CArrayPtrFlat<HBufC8>& aPluginNames); |
|
252 |
|
253 /** |
|
254 Sets which input plug-in is to be used for sending messages to ULogger from a |
|
255 remote machine. This is only relevant for the remote control functionality |
|
256 of ULogger, which allows a remote machine to control the operation of |
|
257 ULogger, instead of a client on the device using RULogger. |
|
258 The plug-in that is passed to this method needs to be one of the |
|
259 plug-ins reported by GetInstalledInputPlugins. |
|
260 |
|
261 @param aPluginName The name of the input plug-in to be activated. |
|
262 @return KErrNone, if sending the SetActiveInputPlugin message to the server |
|
263 was successful; |
|
264 KErrAlreadyExists, if aPluginName value was previously set; |
|
265 KErrNotFound, if aPluginName does not match the name of an existing Ulogger input plug-in; |
|
266 KErrNoMemory, if there is insufficient memory available; |
|
267 KErrArgument, if passed descriptor is empty; |
|
268 otherwise one of the other system-wide error codes. |
|
269 */ |
|
270 IMPORT_C TInt ActivateInputPlugin(const TDesC8& aPluginName); |
|
271 |
|
272 /** |
|
273 Gets the active input plug-in. |
|
274 |
|
275 @param aPluginName The 8-bit descriptor to be populated with the name of |
|
276 the active plug-in (max length: KMaxPath). |
|
277 @return KErrNone, if sending the ActiveInputPlugin message to the |
|
278 server was successful; |
|
279 KErrOverflow, if the passed-in descriptor is smaller than the length |
|
280 of the plug-in name; |
|
281 KErrNotFound, if no input plug-in has been set; |
|
282 otherwise one of the other system-wide error codes. |
|
283 */ |
|
284 IMPORT_C TInt GetActiveInputPlugin(TDes8& aPluginName); |
|
285 |
|
286 /** |
|
287 Deactivates the currently active input plug-in. |
|
288 |
|
289 @return KErrNone, if sending the DeActivateInputPlugin message to the server |
|
290 was successful; |
|
291 KErrNotFound, if no input plug-in has been set; |
|
292 otherwise one of the other system-wide error codes. |
|
293 */ |
|
294 IMPORT_C TInt DeActivateInputPlugin(); |
|
295 |
|
296 /** |
|
297 Gets all installed input plug-ins. |
|
298 |
|
299 @param aPluginNames The array to be populated with the installed input plug-in names. |
|
300 @return KErrNone, if sending the GetInstalledInputPlugins message to the |
|
301 server was successful; |
|
302 otherwise one of the other system-wide error codes. |
|
303 */ |
|
304 IMPORT_C TInt GetInstalledInputPlugins(CArrayPtrFlat<HBufC8>& aPluginNames); |
|
305 |
|
306 /** |
|
307 Adds a configuration to a plug-in (output or input). This is specific to the plug-in. |
|
308 |
|
309 Example1: aPluginName="uloggerfileplugin", aConfiguration.SetKey("output_path"), aConfiguration.SetValue(_L("c:\\logs\\ulogger\\tracelogs.btl")) |
|
310 Example2: aPluginName="uloggerserialplugin", aConfiguration.SetKey("baudrate") , aConfiguration.SetValue("115200") |
|
311 |
|
312 @param aPluginName The plug-in name (without the .dll extension) |
|
313 @param aConfiguration TPluginConfiguration (key-value type configuration) |
|
314 @return KErrNone, if sending the SetPluginConfigurations message to the |
|
315 server was successful; |
|
316 KErrNotFound, if aPluginName does not match the name of an existing ULogger plug-in (output or input); |
|
317 KErrArgument, if aPluginName is an empty descriptor; |
|
318 otherwise one of the other system-wide error codes. |
|
319 */ |
|
320 IMPORT_C TInt SetPluginConfigurations(const TDesC8& aPluginName, const TPluginConfiguration& aConfiguration); |
|
321 |
|
322 /** |
|
323 Gets all configurationas for the specified plug-in (output or input). |
|
324 |
|
325 @param aPluginName The name of the plug-in. This is mapped to the plug-in |
|
326 file name, it can be retrieved by calling |
|
327 GetInstalledOutputPlugins and GetInstalledInputPlugins |
|
328 @param aConfigurations The array that is to be populated with plug-in |
|
329 configuration items. Ownership of any objects |
|
330 appended to this array is passed to the caller. |
|
331 @return KErrNone, if sending the PluginConfigurations message to the |
|
332 server was successful; |
|
333 KErrNotFound, if aPluginName does not match the name of an existing ULogger plug-in (output or input); |
|
334 KErrArgument, if aPluginName is an empty descriptor; |
|
335 otherwise one of the other system-wide error codes. |
|
336 |
|
337 */ |
|
338 IMPORT_C TInt GetPluginConfigurations(const TDesC8& aPluginName, RPointerArray<TPluginConfiguration>& aConfigurations); |
|
339 |
|
340 /** |
|
341 Removes all the configurations of the specified plug-in |
|
342 |
|
343 @param aPluginName The plug-in name whose settings are to be removed |
|
344 @return KErrNone, if sending the RemovePluginConfigurations message to the |
|
345 server was successful; |
|
346 KErrNotFound, if aPluginName does not match the name of an existing ULogger plug-in (output or input) |
|
347 or the plug-in had no settings; |
|
348 KErrArgument, if aPluginName is an empty descriptor; |
|
349 otherwise one of the other system-wide error codes. |
|
350 */ |
|
351 IMPORT_C TInt RemovePluginConfigurations(const TDesC8& aPluginName); |
|
352 |
|
353 /** |
|
354 Sets the size of the trace buffer, specified in KB (default: 1024KB). |
|
355 The trace buffer is the buffer that UTrace uses to hold the trace packets |
|
356 before they are output (using the currently active output plug-in). |
|
357 See also the documentation of SetNotificationSize(). |
|
358 |
|
359 @param aSize The desired new trace buffer size in KB |
|
360 @return KErrNone, if sending the SetBufferSize message to the server was |
|
361 successful; |
|
362 KErrArgument, if aSize value is not in range [1-1024]; |
|
363 KErrGeneral, if aSize value is smaller than data notification size; |
|
364 otherwise one of the other system-wide error codes. |
|
365 */ |
|
366 IMPORT_C TInt SetBufferSize(TInt aSize); |
|
367 |
|
368 /** |
|
369 Gets the size of the trace buffer in KB. |
|
370 See SetBufferSize() for an explanation of the trace buffer size. |
|
371 |
|
372 @param aSize The TInt to be populated with the trace buffer size in KB. |
|
373 @return KErrNone, if sending the BufferSize message to the server was |
|
374 successful; |
|
375 otherwise one of the other system-wide error codes. |
|
376 */ |
|
377 IMPORT_C TInt GetBufferSize(TInt& aSize); |
|
378 |
|
379 /** |
|
380 Sets the data notification size, specified in KB (default: 512KB). |
|
381 The data notification size is a threshold on the trace buffer usage, above |
|
382 which the trace buffer is flushed, i.e. all the trace packets in the trace buffer |
|
383 are output using the active output plug-in. |
|
384 See also the documentation of SetBufferSize(). |
|
385 |
|
386 @param aSize The desired new data notification size in KB |
|
387 @return KErrNone, if sending the SetNotificationSize message to the server |
|
388 was successful; |
|
389 KErrArgument, if aSize value is not in range [0-1024]; |
|
390 KErrGeneral, if aSize value is greater than trace buffer size; |
|
391 otherwise one of the other system-wide error codes. |
|
392 */ |
|
393 IMPORT_C TInt SetNotificationSize(TInt aSize); |
|
394 |
|
395 /** |
|
396 Gets the data notification size. |
|
397 See SetNotificationSize() for an explanation of the data notification size. |
|
398 |
|
399 @param aSize The TInt to be populated with the data notification size in KB. |
|
400 @return KErrNone, if sending the NotificationSize message to the server was |
|
401 successful; |
|
402 otherwise one of the other system-wide error codes. |
|
403 */ |
|
404 IMPORT_C TInt GetNotificationSize(TInt& aSize); |
|
405 |
|
406 /** |
|
407 Sets the trace buffer mode. |
|
408 |
|
409 @param aMode The buffer mode: 1 if Straight |
|
410 0 if Circular |
|
411 @return KErrNone, if sending the SetBufferMode message to the server was |
|
412 successful; |
|
413 KErrArgument, if the specified mode is not one of 0 or 1; |
|
414 otherwise one of the other system-wide error codes. |
|
415 */ |
|
416 IMPORT_C TInt SetBufferMode(TInt aMode); |
|
417 |
|
418 /** |
|
419 Gets the trace buffer mode. |
|
420 |
|
421 @param aMode The TInt to be populated with the buffer mode: 1 if Straight |
|
422 0 if Circular |
|
423 @return KErrNone, if sending the BufferMode message to the server was |
|
424 successful; |
|
425 otherwise one of the other system-wide error codes. |
|
426 */ |
|
427 IMPORT_C TInt GetBufferMode(TInt& aMode); |
|
428 |
|
429 /** |
|
430 Gets the client side version number. |
|
431 |
|
432 @return The client side version number. |
|
433 */ |
|
434 IMPORT_C TVersion Version(); |
|
435 |
|
436 private: |
|
437 TInt StartServer(); |
|
438 |
|
439 private: |
|
440 TUint32 iReserved1; // For future BC |
|
441 TUint32 iReserved2; // For future BC |
|
442 }; |
|
443 |
|
444 } // namespace |
|
445 |
|
446 #endif // ULOGGERCLIENT_H |