1/*
2 * libjingle
3 * Copyright 2004--2005, 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#ifndef TALK_BASE_NETWORK_H_
29#define TALK_BASE_NETWORK_H_
30
31#include <deque>
32#include <map>
33#include <string>
34#include <vector>
35
36#include "talk/base/basictypes.h"
37
38namespace talk_base {
39
40class Network;
41class NetworkSession;
42
43// Keeps track of the available network interfaces over time so that quality
44// information can be aggregated and recorded.
45class NetworkManager {
46 public:
47  virtual ~NetworkManager();
48
49  // Updates and returns the current list of networks available on this machine.
50  // This version will make sure that repeated calls return the same object for
51  // a given network, so that quality is tracked appropriately.
52  // Does not include ignored networks.
53  bool GetNetworks(std::vector<Network*>* networks);
54
55  // Logs the available networks.
56  void DumpNetworks(bool include_ignored);
57
58  // Reads and writes the state of the quality database in a string format.
59  std::string GetState() const;
60  void SetState(const std::string& str);
61
62  // Creates a network object for each network available on the machine.
63  static bool CreateNetworks(bool include_ignored,
64                             std::vector<Network*>* networks);
65  // Determines if a network should be ignored.
66  static bool IsIgnoredNetwork(const Network& network);
67
68 protected:
69  // Fills the supplied list with all usable networks. Overrideable.
70  virtual bool EnumNetworks(bool include_ignored,
71                            std::vector<Network*>* networks);
72
73 private:
74  typedef std::map<std::string, Network*> NetworkMap;
75
76  NetworkMap networks_;
77};
78
79// Represents a Unix-type network interface, with a name and single address.
80// It also includes the ability to track and estimate quality.
81class Network {
82 public:
83  Network(const std::string& name, const std::string& description,
84          uint32 ip, uint32 gateway_ip);
85
86  // Returns the index of this network.  This is considered the primary key
87  // that identifies each network.
88  const std::string& name() const { return name_; }
89
90  // Returns the OS-assigned name for this network. This is useful for
91  // debugging but should not be sent over the wire (for privacy reasons).
92  const std::string& description() const { return description_; }
93
94  // Identifies the current IP address used by this network.
95  uint32 ip() const { return ip_; }
96  void set_ip(uint32 ip) { ip_ = ip; }
97
98  // Identifies the current gateway IP address used by this network.
99  uint32 gateway_ip() const { return gateway_ip_; }
100  void set_gateway_ip(uint32 ip) { gateway_ip_ = ip; }
101
102  // Indicates whether this network should be ignored, perhaps because the
103  // IP/gateway is 0, or the interface is one we know is invalid.
104  bool ignored() const { return ignored_; }
105  void set_ignored(bool ignored) { ignored_ = ignored; }
106
107  // Updates the list of sessions that are ongoing.
108  void StartSession(NetworkSession* session);
109  void StopSession(NetworkSession* session);
110
111  // Re-computes the estimate of near-future quality based on the information
112  // as of this exact moment.
113  void EstimateQuality();
114
115  // Returns the current estimate of the near-future quality of connections
116  // that use this local interface.
117  double quality() { return quality_; }
118
119  // Debugging description of this network
120  std::string ToString() const;
121
122 private:
123  typedef std::vector<NetworkSession*> SessionList;
124
125  std::string name_;
126  std::string description_;
127  uint32 ip_;
128  uint32 gateway_ip_;
129  bool ignored_;
130  SessionList sessions_;
131  double uniform_numerator_;
132  double uniform_denominator_;
133  double exponential_numerator_;
134  double exponential_denominator_;
135  uint32 last_data_time_;
136  double quality_;
137
138  // Updates the statistics maintained to include the given estimate.
139  void AddDataPoint(uint32 time, double quality);
140
141  // Converts the internal state to and from a string.  This is used to record
142  // quality information into a permanent store.
143  void SetState(const std::string& str);
144  std::string GetState() const;
145
146  friend class NetworkManager;
147};
148
149// Represents a session that is in progress using a particular network and can
150// provide data about the quality of the network at any given moment.
151class NetworkSession {
152 public:
153  virtual ~NetworkSession() { }
154
155  // Determines whether this session has an estimate at this moment.  We will
156  // only call GetCurrentQuality when this returns true.
157  virtual bool HasQuality() = 0;
158
159  // Returns an estimate of the quality at this exact moment.  The result should
160  // be a MOS (mean opinion score) value.
161  virtual float GetCurrentQuality() = 0;
162};
163
164const double QUALITY_BAD  = 3.0;
165const double QUALITY_FAIR = 3.35;
166const double QUALITY_GOOD = 3.7;
167
168}  // namespace talk_base
169
170#endif  // TALK_BASE_NETWORK_H_
171