1/*
2 * libjingle
3 * Copyright 2012, Google Inc.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 *  1. Redistributions of source code must retain the above copyright notice,
9 *     this list of conditions and the following disclaimer.
10 *  2. Redistributions in binary form must reproduce the above copyright notice,
11 *     this list of conditions and the following disclaimer in the documentation
12 *     and/or other materials provided with the distribution.
13 *  3. The name of the author may not be used to endorse or promote products
14 *     derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28// This file contains a class used for gathering statistics from an ongoing
29// libjingle PeerConnection.
30
31#ifndef TALK_APP_WEBRTC_STATSCOLLECTOR_H_
32#define TALK_APP_WEBRTC_STATSCOLLECTOR_H_
33
34#include <map>
35#include <string>
36#include <vector>
37
38#include "talk/app/webrtc/mediastreaminterface.h"
39#include "talk/app/webrtc/peerconnectioninterface.h"
40#include "talk/app/webrtc/statstypes.h"
41#include "talk/app/webrtc/webrtcsession.h"
42
43namespace webrtc {
44
45class StatsCollector {
46 public:
47  enum TrackDirection {
48    kSending = 0,
49    kReceiving,
50  };
51
52  // The caller is responsible for ensuring that the session outlives the
53  // StatsCollector instance.
54  explicit StatsCollector(WebRtcSession* session);
55  virtual ~StatsCollector();
56
57  // Adds a MediaStream with tracks that can be used as a |selector| in a call
58  // to GetStats.
59  void AddStream(MediaStreamInterface* stream);
60
61  // Adds a local audio track that is used for getting some voice statistics.
62  void AddLocalAudioTrack(AudioTrackInterface* audio_track, uint32 ssrc);
63
64  // Removes a local audio tracks that is used for getting some voice
65  // statistics.
66  void RemoveLocalAudioTrack(AudioTrackInterface* audio_track, uint32 ssrc);
67
68  // Gather statistics from the session and store them for future use.
69  void UpdateStats(PeerConnectionInterface::StatsOutputLevel level);
70
71  // Gets a StatsReports of the last collected stats. Note that UpdateStats must
72  // be called before this function to get the most recent stats. |selector| is
73  // a track label or empty string. The most recent reports are stored in
74  // |reports|.
75  // TODO(tommi): Change this contract to accept a callback object instead
76  // of filling in |reports|.  As is, there's a requirement that the caller
77  // uses |reports| immediately without allowing any async activity on
78  // the thread (message handling etc) and then discard the results.
79  void GetStats(MediaStreamTrackInterface* track,
80                StatsReports* reports);
81
82  // Prepare an SSRC report for the given ssrc. Used internally
83  // in the ExtractStatsFromList template.
84  StatsReport* PrepareLocalReport(uint32 ssrc, const std::string& transport,
85                                  TrackDirection direction);
86  // Prepare an SSRC report for the given remote ssrc. Used internally.
87  StatsReport* PrepareRemoteReport(uint32 ssrc, const std::string& transport,
88                                   TrackDirection direction);
89
90  // Method used by the unittest to force a update of stats since UpdateStats()
91  // that occur less than kMinGatherStatsPeriod number of ms apart will be
92  // ignored.
93  void ClearUpdateStatsCache();
94
95 private:
96  bool CopySelectedReports(const std::string& selector, StatsReports* reports);
97
98  // Helper method for AddCertificateReports.
99  std::string AddOneCertificateReport(
100      const rtc::SSLCertificate* cert, const std::string& issuer_id);
101
102  // Adds a report for this certificate and every certificate in its chain, and
103  // returns the leaf certificate's report's ID.
104  std::string AddCertificateReports(const rtc::SSLCertificate* cert);
105
106  void ExtractSessionInfo();
107  void ExtractVoiceInfo();
108  void ExtractVideoInfo(PeerConnectionInterface::StatsOutputLevel level);
109  void BuildSsrcToTransportId();
110  webrtc::StatsReport* GetOrCreateReport(const std::string& type,
111                                         const std::string& id,
112                                         TrackDirection direction);
113  webrtc::StatsReport* GetReport(const std::string& type,
114                                 const std::string& id,
115                                 TrackDirection direction);
116
117  // Helper method to get stats from the local audio tracks.
118  void UpdateStatsFromExistingLocalAudioTracks();
119  void UpdateReportFromAudioTrack(AudioTrackInterface* track,
120                                  StatsReport* report);
121
122  // Helper method to get the id for the track identified by ssrc.
123  // |direction| tells if the track is for sending or receiving.
124  bool GetTrackIdBySsrc(uint32 ssrc, std::string* track_id,
125                        TrackDirection direction);
126
127  // A map from the report id to the report.
128  StatsSet reports_;
129  // Raw pointer to the session the statistics are gathered from.
130  WebRtcSession* const session_;
131  double stats_gathering_started_;
132  cricket::ProxyTransportMap proxy_to_transport_;
133
134  typedef std::vector<std::pair<AudioTrackInterface*, uint32> >
135      LocalAudioTrackVector;
136  LocalAudioTrackVector local_audio_tracks_;
137};
138
139}  // namespace webrtc
140
141#endif  // TALK_APP_WEBRTC_STATSCOLLECTOR_H_
142