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
23namespace webrtc {
24class Trace
25{
26public:
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