src/remoting/protocol/session_manager.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 // The purpose of SessionManager is to facilitate creation of chromotocol
   6 // sessions. Both host and client use it to establish chromotocol
   7 // sessions. JingleChromotocolServer implements this inteface using
   8 // libjingle.
   9 //
  10 // OUTGOING SESSIONS
  11 // Connect() must be used to create new session to a remote host. The
  12 // returned session is initially in INITIALIZING state. Later state is
  13 // changed to CONNECTED if the session is accepted by the host or
  14 // CLOSED if the session is rejected.
  15 //
  16 // INCOMING SESSIONS
  17 // The IncomingSessionCallback is called when a client attempts to connect.
  18 // The callback function decides whether the session should be accepted or
  19 // rejected.
  20 //
  21 // AUTHENTICATION
  22 // Implementations of the Session and SessionManager interfaces
  23 // delegate authentication to an Authenticator implementation. For
  24 // incoming connections authenticators are created using an
  25 // AuthenticatorFactory set via the set_authenticator_factory()
  26 // method. For outgoing sessions authenticator must be passed to the
  27 // Connect() method. The Session's state changes to AUTHENTICATED once
  28 // authentication succeeds.
  29 //
  30 // SESSION OWNERSHIP AND SHUTDOWN
  31 // The SessionManager must not be closed or destroyed before all sessions
  32 // created by that SessionManager are destroyed. Caller owns Sessions
  33 // created by a SessionManager (except rejected
  34 // sessions). The SignalStrategy must outlive the SessionManager.
  35 //
  36 // PROTOCOL VERSION NEGOTIATION
  37 // When client connects to a host it sends a session-initiate stanza with list
  38 // of supported configurations for each channel. If the host decides to accept
  39 // session, then it selects configuration that is supported by both sides
  40 // and then replies with the session-accept stanza that contans selected
  41 // configuration. The configuration specified in the session-accept is used
  42 // for the session.
  43 //
  44 // The CandidateSessionConfig class represents list of configurations
  45 // supported by an endpoint. The |candidate_config| argument in the Connect()
  46 // specifies configuration supported on the client side. When the host receives
  47 // session-initiate stanza, the IncomingSessionCallback is called. The
  48 // configuration sent in the session-intiate staza is available via
  49 // ChromotocolConnnection::candidate_config(). If an incoming session is
  50 // being accepted then the IncomingSessionCallback callback function must
  51 // select session configuration and then set it with Session::set_config().
  52
  53 #ifndef REMOTING_PROTOCOL_SESSION_MANAGER_H_
  54 #define REMOTING_PROTOCOL_SESSION_MANAGER_H_
  55
  56 #include <string>
  57
  58 #include "base/callback.h"
  59 #include "base/memory/ref_counted.h"
  60 #include "base/threading/non_thread_safe.h"
  61 #include "remoting/protocol/session.h"
  62 #include "remoting/protocol/transport_config.h"
  63
  64 namespace remoting {
  65
  66 class SignalStrategy;
  67
  68 namespace protocol {
  69
  70 class Authenticator;
  71 class AuthenticatorFactory;
  72
  73 // Generic interface for Chromoting session manager.
  74 //
  75 // TODO(sergeyu): Split this into two separate interfaces: one for the
  76 // client side and one for the host side.
  77 class SessionManager : public base::NonThreadSafe {
  78  public:
  79   SessionManager() {}
  80   virtual ~SessionManager() {}
  81
  82   enum IncomingSessionResponse {
  83     // Accept the session.
  84     ACCEPT,
  85
  86     // Reject the session due to incompatible session configuration.
  87     INCOMPATIBLE,
  88
  89     // Reject the session because the host is currently disabled due
  90     // to previous login attempts.
  91     OVERLOAD,
  92
  93     // Reject the session because the client is not allowed to connect
  94     // to the host.
  95     DECLINE,
  96   };
  97
  98   class Listener {
  99    public:
 100     Listener() {}
 101
 102     // Called when the session manager is ready to create outgoing
 103     // sessions. May be called from Init() or after Init()
 104     // returns.
 105     virtual void OnSessionManagerReady() = 0;
 106
 107     // Called when a new session is received. If the host decides to
 108     // accept the session it should set the |response| to
 109     // ACCEPT. Otherwise it should set it to DECLINE, or
 110     // INCOMPATIBLE. INCOMPATIBLE indicates that the session has
 111     // incompatible configuration, and cannot be accepted. If the
 112     // callback accepts the |session| then it must also set
 113     // configuration for the |session| using Session::set_config().
 114     // The callback must take ownership of the |session| if it ACCEPTs it.
 115     virtual void OnIncomingSession(Session* session,
 116                                    IncomingSessionResponse* response) = 0;
 117
 118    protected:
 119     ~Listener() {}
 120   };
 121
 122   // Initializes the session client. Caller retains ownership of the
 123   // |signal_strategy| and |listener|.
 124   virtual void Init(SignalStrategy* signal_strategy,
 125                     Listener* listener) = 0;
 126
 127   // Tries to create a session to the host |jid|. Must be called only
 128   // after initialization has finished successfully, i.e. after
 129   // Listener::OnInitialized() has been called.
 130   //
 131   // |host_jid| is the full jid of the host to connect to.
 132   // |authenticator| is a client authenticator for the session.
 133   // |config| contains the session configurations that the client supports.
 134   virtual scoped_ptr<Session> Connect(
 135       const std::string& host_jid,
 136       scoped_ptr<Authenticator> authenticator,
 137       scoped_ptr<CandidateSessionConfig> config) = 0;
 138
 139   // Close session manager. Can be called only after all corresponding
 140   // sessions are destroyed. No callbacks are called after this method
 141   // returns.
 142   virtual void Close() = 0;
 143
 144   // Set authenticator factory that should be used to authenticate
 145   // incoming connection. No connections will be accepted if
 146   // authenticator factory isn't set. Must not be called more than
 147   // once per SessionManager because it may not be safe to delete
 148   // factory before all authenticators it created are deleted.
 149   virtual void set_authenticator_factory(
 150       scoped_ptr<AuthenticatorFactory> authenticator_factory) = 0;
 151
 152  private:
 153   DISALLOW_COPY_AND_ASSIGN(SessionManager);
 154 };
 155
 156 }  // namespace protocol
 157 }  // namespace remoting
 158
 159 #endif  // REMOTING_PROTOCOL_SESSION_MANAGER_H_