Home | History | Annotate | Download | only in protocol 
      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 // net::Socket or net::SocketStream which provides access to the data
     13 // channel. After a new transport is Initialize()'ed the Connect()
     14 // method must be called. Connect() starts asynchronous creation and
     15 // initialization of the connection socket that can be used later to
     16 // send and receive data. The socket is passed to the callback
     17 // specified in the Connect() call. The Transport object must exist
     18 // during the whole lifetime of the connection socket. Later deletion
     19 // of the connection socket causes teardown of the corresponding
     20 // Transport object.
     21 
     22 #ifndef REMOTING_PROTOCOL_TRANSPORT_H_
     23 #define REMOTING_PROTOCOL_TRANSPORT_H_
     24 
     25 #include <string>
     26 
     27 #include "base/basictypes.h"
     28 #include "base/callback_forward.h"
     29 #include "base/memory/scoped_ptr.h"
     30 #include "base/threading/non_thread_safe.h"
     31 #include "net/base/ip_endpoint.h"
     32 
     33 namespace cricket {
     34 class Candidate;
     35 }  // namespace cricket
     36 
     37 namespace net {
     38 class Socket;
     39 class StreamSocket;
     40 }  // namespace net
     41 
     42 namespace remoting {
     43 namespace protocol {
     44 
     45 class ChannelAuthenticator;
     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 when the transport generates a new candidate that needs
     73     // to be passed to the AddRemoteCandidate() method on the remote
     74     // end of the connection.
     75     virtual void OnTransportCandidate(Transport* transport,
     76                                       const cricket::Candidate& candidate) = 0;
     77 
     78     // Called when transport route changes. Can be called even before
     79     // the transport is connected.
     80     virtual void OnTransportRouteChange(Transport* transport,
     81                                         const TransportRoute& route) = 0;
     82 
     83     // Called when the transport inactivity state changes. When
     84     // |ready| is set to false incoming and outgoing data may be
     85     // delayed until connection goes back to the active state, at
     86     // which point that method is called again with |ready| set to
     87     // true. This is useful for UI indication of temporarily broken
     88     // connections.
     89     virtual void OnTransportReady(Transport* transport, bool ready) = 0;
     90 
     91     // Called when when the transport has failed to connect or reconnect.
     92     virtual void OnTransportFailed(Transport* transport) = 0;
     93 
     94     // Called when the transport is about to be deleted.
     95     virtual void OnTransportDeleted(Transport* transport) = 0;
     96   };
     97 
     98   Transport() {}
     99   virtual ~Transport() {}
    100 
    101   // Intialize the transport with the specified parameters.
    102   // |authenticator| is used to secure and authenticate the connection.
    103   virtual void Initialize(const std::string& name,
    104                           Transport::EventHandler* event_handler,
    105                           scoped_ptr<ChannelAuthenticator> authenticator) = 0;
    106 
    107   // Adds |candidate| received from the peer.
    108   virtual void AddRemoteCandidate(const cricket::Candidate& candidate) = 0;
    109 
    110   // Name of the channel. It is used to identify the channel and
    111   // disambiguate candidates it generates from candidates generated by
    112   // parallel connections.
    113   virtual const std::string& name() const = 0;
    114 
    115   // Returns true if the channel is already connected.
    116   virtual bool is_connected() const = 0;
    117 
    118  private:
    119   DISALLOW_COPY_AND_ASSIGN(Transport);
    120 };
    121 
    122 class StreamTransport : public Transport {
    123  public:
    124   typedef base::Callback<void(scoped_ptr<net::StreamSocket>)> ConnectedCallback;
    125 
    126   StreamTransport() { }
    127   virtual ~StreamTransport() { }
    128 
    129   virtual void Connect(const ConnectedCallback& callback) = 0;
    130 
    131  private:
    132   DISALLOW_COPY_AND_ASSIGN(StreamTransport);
    133 };
    134 
    135 class DatagramTransport : public Transport {
    136  public:
    137   typedef base::Callback<void(scoped_ptr<net::Socket>)> ConnectedCallback;
    138 
    139   DatagramTransport() { }
    140   virtual ~DatagramTransport() { }
    141 
    142   virtual void Connect(const ConnectedCallback& callback) = 0;
    143 
    144  private:
    145   DISALLOW_COPY_AND_ASSIGN(DatagramTransport);
    146 };
    147 
    148 class TransportFactory {
    149  public:
    150   TransportFactory() { }
    151   virtual ~TransportFactory() { }
    152 
    153   // Called to notify transport factory that a new transport might be created
    154   // soon, e.g. when a new session is being created. Implementation may use it
    155   // to start asynchronous preparation, e.g. fetch a new relay token if
    156   // necessary while the session is being authenticated.
    157   virtual void PrepareTokens() = 0;
    158 
    159   virtual scoped_ptr<StreamTransport> CreateStreamTransport() = 0;
    160   virtual scoped_ptr<DatagramTransport> CreateDatagramTransport() = 0;
    161 
    162  private:
    163   DISALLOW_COPY_AND_ASSIGN(TransportFactory);
    164 };
    165 
    166 }  // namespace protocol
    167 }  // namespace remoting
    168 
    169 #endif  // REMOTING_PROTOCOL_TRANSPORT_H_
    170