remoting/protocol/transport.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // This file defines the interface for peer-to-peer transport. There
   6 // are two types of transport: StreamTransport and DatagramTransport.
   7 // They must both be created using TransportFactory instances and they
   8 // provide the same interface, except that one should be used for
   9 // reliable stream connection and the other one for unreliable
  10 // datagram connection. The Transport interface itself doesn't provide
  11 // methods to send/receive data. Instead it creates an instance of
  12 // P2PDatagramSocket which provides access to the data channel. After a
  13 // new transport is Initialize()'ed the Connect() method must be called.
  14 // Connect() starts asynchronous creation and initialization of the
  15 // connection socket that can be used later to send and receive data.
  16 // The socket is passed to the callback specified in the Connect() call.
  17 // The Transport object must exist during the whole lifetime of the
  18 // connection socket. Later deletion of the connection socket causes
  19 // teardown of the corresponding Transport object.
  20
  21 #ifndef REMOTING_PROTOCOL_TRANSPORT_H_
  22 #define REMOTING_PROTOCOL_TRANSPORT_H_
  23
  24 #include <string>
  25
  26 #include "base/basictypes.h"
  27 #include "base/callback_forward.h"
  28 #include "base/memory/scoped_ptr.h"
  29 #include "base/threading/non_thread_safe.h"
  30 #include "net/base/ip_endpoint.h"
  31
  32 namespace cricket {
  33 class Candidate;
  34 }  // namespace cricket
  35
  36 namespace remoting {
  37 namespace protocol {
  38
  39 class ChannelAuthenticator;
  40 class P2PDatagramSocket;
  41
  42 enum class TransportRole {
  43   SERVER,
  44   CLIENT,
  45 };
  46
  47 struct TransportRoute {
  48   enum RouteType {
  49     DIRECT,
  50     STUN,
  51     RELAY,
  52   };
  53
  54   // Helper method to get string representation of the type.
  55   static std::string GetTypeString(RouteType type);
  56
  57   TransportRoute();
  58   ~TransportRoute();
  59
  60   RouteType type;
  61   net::IPEndPoint remote_address;
  62   net::IPEndPoint local_address;
  63 };
  64
  65 class Transport : public base::NonThreadSafe {
  66  public:
  67   class EventHandler {
  68    public:
  69     EventHandler() {};
  70     virtual ~EventHandler() {};
  71
  72     // Called to pass ICE credentials to the session. Used only for STANDARD
  73     // version of ICE, see SetIceVersion().
  74     virtual void OnTransportIceCredentials(Transport* transport,
  75                                            const std::string& ufrag,
  76                                            const std::string& password) = 0;
  77
  78     // Called when the transport generates a new candidate that needs
  79     // to be passed to the AddRemoteCandidate() method on the remote
  80     // end of the connection.
  81     virtual void OnTransportCandidate(Transport* transport,
  82                                       const cricket::Candidate& candidate) = 0;
  83
  84     // Called when transport route changes. Can be called even before
  85     // the transport is connected.
  86     virtual void OnTransportRouteChange(Transport* transport,
  87                                         const TransportRoute& route) = 0;
  88
  89     // Called when when the transport has failed to connect or reconnect.
  90     virtual void OnTransportFailed(Transport* transport) = 0;
  91
  92     // Called when the transport is about to be deleted.
  93     virtual void OnTransportDeleted(Transport* transport) = 0;
  94   };
  95
  96   typedef base::Callback<void(scoped_ptr<P2PDatagramSocket>)> ConnectedCallback;
  97
  98   Transport() {}
  99   virtual ~Transport() {}
 100
 101   // Connects the transport and calls the |callback| after that.
 102   virtual void Connect(const std::string& name,
 103                        Transport::EventHandler* event_handler,
 104                        const ConnectedCallback& callback) = 0;
 105
 106   // Sets remote ICE credentials.
 107   virtual void SetRemoteCredentials(const std::string& ufrag,
 108                                     const std::string& password) = 0;
 109
 110   // Adds |candidate| received from the peer.
 111   virtual void AddRemoteCandidate(const cricket::Candidate& candidate) = 0;
 112
 113   // Name of the channel. It is used to identify the channel and
 114   // disambiguate candidates it generates from candidates generated by
 115   // parallel connections.
 116   virtual const std::string& name() const = 0;
 117
 118   // Returns true if the channel is already connected.
 119   virtual bool is_connected() const = 0;
 120
 121  private:
 122   DISALLOW_COPY_AND_ASSIGN(Transport);
 123 };
 124
 125 class TransportFactory {
 126  public:
 127   TransportFactory() { }
 128   virtual ~TransportFactory() { }
 129
 130   // Called to notify transport factory that a new transport might be created
 131   // soon, e.g. when a new session is being created. Implementation may use it
 132   // to start asynchronous preparation, e.g. fetch a new relay token if
 133   // necessary while the session is being authenticated.
 134   virtual void PrepareTokens() = 0;
 135
 136   virtual scoped_ptr<Transport> CreateTransport() = 0;
 137
 138  private:
 139   DISALLOW_COPY_AND_ASSIGN(TransportFactory);
 140 };
 141
 142 }  // namespace protocol
 143 }  // namespace remoting
 144
 145 #endif  // REMOTING_PROTOCOL_TRANSPORT_H_