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 63 namespace remoting { 64 65 class SignalStrategy; 66 67 namespace protocol { 68 69 class Authenticator; 70 class AuthenticatorFactory; 71 72 // Generic interface for Chromoting session manager. 73 // 74 // TODO(sergeyu): Split this into two separate interfaces: one for the 75 // client side and one for the host side. 76 class SessionManager : public base::NonThreadSafe { 77 public: 78 SessionManager() {} 79 virtual ~SessionManager() {} 80 81 enum IncomingSessionResponse { 82 // Accept the session. 83 ACCEPT, 84 85 // Reject the session due to incompatible session configuration. 86 INCOMPATIBLE, 87 88 // Reject the session because the host is currently disabled due 89 // to previous login attempts. 90 OVERLOAD, 91 92 // Reject the session because the client is not allowed to connect 93 // to the host. 94 DECLINE, 95 }; 96 97 class Listener { 98 public: 99 Listener() {} 100 101 // Called when the session manager is ready to create outgoing 102 // sessions. May be called from Init() or after Init() 103 // returns. 104 virtual void OnSessionManagerReady() = 0; 105 106 // Called when a new session is received. If the host decides to 107 // accept the session it should set the |response| to 108 // ACCEPT. Otherwise it should set it to DECLINE, or 109 // INCOMPATIBLE. INCOMPATIBLE indicates that the session has 110 // incompatible configuration, and cannot be accepted. If the 111 // callback accepts the |session| then it must also set 112 // configuration for the |session| using Session::set_config(). 113 // The callback must take ownership of the |session| if it ACCEPTs it. 114 virtual void OnIncomingSession(Session* session, 115 IncomingSessionResponse* response) = 0; 116 117 protected: 118 ~Listener() {} 119 }; 120 121 // Initializes the session client. Caller retains ownership of the 122 // |signal_strategy| and |listener|. 123 virtual void Init(SignalStrategy* signal_strategy, 124 Listener* listener) = 0; 125 126 // Tries to create a session to the host |jid|. Must be called only 127 // after initialization has finished successfully, i.e. after 128 // Listener::OnInitialized() has been called. 129 // 130 // |host_jid| is the full jid of the host to connect to. 131 // |authenticator| is a client authenticator for the session. 132 // |config| contains the session configurations that the client supports. 133 virtual scoped_ptr<Session> Connect( 134 const std::string& host_jid, 135 scoped_ptr<Authenticator> authenticator, 136 scoped_ptr<CandidateSessionConfig> config) = 0; 137 138 // Close session manager. Can be called only after all corresponding 139 // sessions are destroyed. No callbacks are called after this method 140 // returns. 141 virtual void Close() = 0; 142 143 // Set authenticator factory that should be used to authenticate 144 // incoming connection. No connections will be accepted if 145 // authenticator factory isn't set. Must not be called more than 146 // once per SessionManager because it may not be safe to delete 147 // factory before all authenticators it created are deleted. 148 virtual void set_authenticator_factory( 149 scoped_ptr<AuthenticatorFactory> authenticator_factory) = 0; 150 151 private: 152 DISALLOW_COPY_AND_ASSIGN(SessionManager); 153 }; 154 155 } // namespace protocol 156 } // namespace remoting 157 158 #endif // REMOTING_PROTOCOL_SESSION_MANAGER_H_ 159
