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 *  System independent wrapper for logging runtime information to file.
11 *  Note: All log messages will be written to the same trace file.
12 *  Note: If too many messages are written to file there will be a build up of
13 *  messages. Apply filtering to avoid that.
14 */
15
16#ifndef WEBRTC_SYSTEM_WRAPPERS_INTERFACE_TRACE_H_
17#define WEBRTC_SYSTEM_WRAPPERS_INTERFACE_TRACE_H_
18
19#include "webrtc/common_types.h"
20#include "webrtc/typedefs.h"
21
22namespace webrtc {
23
24#if defined(WEBRTC_RESTRICT_LOGGING)
25// Disable all TRACE macros. The LOG macro is still functional.
26#define WEBRTC_TRACE true ? (void) 0 : Trace::Add
27#else
28#define WEBRTC_TRACE Trace::Add
29#endif
30
31class Trace {
32 public:
33  // The length of the trace text preceeding the log message.
34  static const int kBoilerplateLength;
35  // The position of the timestamp text within a trace.
36  static const int kTimestampPosition;
37  // The length of the timestamp (without "delta" field).
38  static const int kTimestampLength;
39
40  // Increments the reference count to the trace.
41  static void CreateTrace();
42  // Decrements the reference count to the trace.
43  static void ReturnTrace();
44  // Note: any instance that writes to the trace file should increment and
45  // decrement the reference count on construction and destruction,
46  // respectively.
47
48  // Specifies what type of messages should be written to the trace file. The
49  // filter parameter is a bitmask where each message type is enumerated by the
50  // TraceLevel enumerator. TODO(hellner): why is the TraceLevel enumerator not
51  // defined in this file?
52  static void set_level_filter(uint32_t filter) { level_filter_ = filter; }
53
54  // Returns what type of messages are written to the trace file.
55  static uint32_t level_filter() { return level_filter_; }
56
57  // Sets the file name. If add_file_counter is false the same file will be
58  // reused when it fills up. If it's true a new file with incremented name
59  // will be used.
60  static int32_t SetTraceFile(const char* file_name,
61                              const bool add_file_counter = false);
62
63  // Returns the name of the file that the trace is currently writing to.
64  static int32_t TraceFile(char file_name[1024]);
65
66  // Registers callback to receive trace messages.
67  // TODO(hellner): Why not use OutStream instead? Why is TraceCallback not
68  // defined in this file?
69  static int32_t SetTraceCallback(TraceCallback* callback);
70
71  // Adds a trace message for writing to file. The message is put in a queue
72  // for writing to file whenever possible for performance reasons. I.e. there
73  // is a crash it is possible that the last, vital logs are not logged yet.
74  // level is the type of message to log. If that type of messages is
75  // filtered it will not be written to file. module is an identifier for what
76  // part of the code the message is coming.
77  // id is an identifier that should be unique for that set of classes that
78  // are associated (e.g. all instances owned by an engine).
79  // msg and the ellipsis are the same as e.g. sprintf.
80  // TODO(hellner) Why is TraceModule not defined in this file?
81  static void Add(const TraceLevel level,
82                  const TraceModule module,
83                  const int32_t id,
84                  const char* msg, ...);
85
86 private:
87  static uint32_t level_filter_;
88};
89
90}  // namespace webrtc
91
92#endif  // WEBRTC_SYSTEM_WRAPPERS_INTERFACE_TRACE_H_
93