1 /*
2  *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
3  *
4  *  Use of this source code is governed by a BSD-style license
5  *  that can be found in the LICENSE file in the root of the source
6  *  tree. An additional intellectual property rights grant can be found
7  *  in the file PATENTS.  All contributing project authors may
8  *  be found in the AUTHORS file in the root of the source tree.
9  */
10 
11 // System independant wrapper for logging runtime information to file.
12 // Note: All log messages will be written to the same trace file.
13 // Note: If to many messages are written to file there will be a build up of
14 //       messages. Apply filtering to avoid that.
15 #ifndef WEBRTC_SYSTEM_WRAPPERS_INTERFACE_TRACE_H_
16 #define WEBRTC_SYSTEM_WRAPPERS_INTERFACE_TRACE_H_
17 
18 #include "common_types.h"
19 #include "typedefs.h"
20 
21 #define WEBRTC_TRACE Trace::Add
22 
23 namespace webrtc {
24 class Trace
25 {
26 public:
27 
28     // Increments the reference count to the trace.
29     static void CreateTrace();
30     // Decrements the reference count to the trace.
31     static void ReturnTrace();
32     // Note: any instance that writes to the trace file should increment and
33     // decrement the reference count on construction and destruction
34     // respectively
35 
36     // Specifies what type of messages should be written to the trace file. The
37     // filter parameter is a bitmask where each message type is enumerated by
38     // the TraceLevel enumerator. TODO (hellner) why is the
39     // TraceLevel enumerator not defined in this file?
40     static WebRtc_Word32 SetLevelFilter(const WebRtc_UWord32 filter);
41 
42     // Returns what type of messages are written to the trace file.
43     static WebRtc_Word32 LevelFilter(WebRtc_UWord32& filter);
44 
45     // Sets the file name. If addFileCounter is false the same file will be
46     // reused when it fills up. If it's true a new file with incremented name
47     // will be used.
48     static WebRtc_Word32 SetTraceFile(const char* fileName,
49                                       const bool addFileCounter = false);
50 
51     // Returns the name of the file that the trace is currently writing to.
52     static WebRtc_Word32 TraceFile(char fileName[1024]);
53 
54     // Registers callback to receive trace messages. TODO (hellner)
55     // why not use OutStream instead? Why is TraceCallback not defined in this
56     // file
57     static WebRtc_Word32 SetTraceCallback(TraceCallback* callback);
58 
59     // Adds a trace message for writing to file. The message is put in a queue
60     // for writing to file whenever possible for performance reasons. I.e. there
61     // is a crash it is possible that the last, vital logs are not logged yet.
62     // level is the the type of message to log. If that type of messages is
63     // filtered it will not be written to file. module is an identifier for what
64     // part of the code the message is comming.
65     // id is an identifier that should be unique for that set of classes that
66     // are associated (e.g. all instances owned by an engine).
67     // msg and the elipsis are the same as e.g. sprintf.
68     // TODO (hellner) Why is TraceModule not defined in this file?
69     static void Add(const TraceLevel level,
70                     const TraceModule module,
71                     const WebRtc_Word32 id,
72                     const char* msg, ...);
73 };
74 } // namespace webrtc
75 #endif // WEBRTC_SYSTEM_WRAPPERS_INTERFACE_TRACE_H_
76