1 files changed, 37 insertions, 29 deletions

diff --git a/lib/connection.h b/lib/connection.h
index a32d0801..f3d7d725 100644
--- a/lib/connection.h
+++ b/lib/connection.h
@@ -50,28 +50,27 @@ class SendToDeviceJob;
 class SendMessageJob;
 class LeaveRoomJob;
 
+using LoginFlow = GetLoginFlowsJob::LoginFlow;
+
+/// Predefined login flows
+struct LoginFlows {
+    static inline const LoginFlow Password { "m.login.password" };
+    static inline const LoginFlow SSO { "m.login.sso" };
+    static inline const LoginFlow Token { "m.login.token" };
+};
+
 // To simplify comparisons of LoginFlows
 
-inline bool operator==(const GetLoginFlowsJob::LoginFlow& lhs,
-                       const GetLoginFlowsJob::LoginFlow& rhs)
+inline bool operator==(const LoginFlow& lhs, const LoginFlow& rhs)
 {
     return lhs.type == rhs.type;
 }
 
-inline bool operator!=(const GetLoginFlowsJob::LoginFlow& lhs,
-                       const GetLoginFlowsJob::LoginFlow& rhs)
+inline bool operator!=(const LoginFlow& lhs, const LoginFlow& rhs)
 {
     return !(lhs == rhs);
 }
 
-/// Predefined login flows
-struct LoginFlows {
-    using LoginFlow = GetLoginFlowsJob::LoginFlow;
-    static inline const LoginFlow Password { "m.login.password" };
-    static inline const LoginFlow SSO { "m.login.sso" };
-    static inline const LoginFlow Token { "m.login.token" };
-};
-
 class Connection;
 
 using room_factory_t =
@@ -492,13 +491,35 @@ public Q_SLOTS:
     /** Determine and set the homeserver from MXID */
     void resolveServer(const QString& mxid);
 
+    /** \brief Log in using a username and password pair
+     *
+     * Before logging in, this method checks if the homeserver is valid and
+     * supports the password login flow. If the homeserver is invalid but
+     * a full user MXID is provided, this method calls resolveServer() using
+     * this MXID.
+     *
+     * \sa resolveServer, resolveError, loginError
+     */
     void loginWithPassword(const QString& userId, const QString& password,
                            const QString& initialDeviceName,
                            const QString& deviceId = {});
+    /** \brief Log in using a login token
+     *
+     * One usual case for this method is the final stage of logging in via SSO.
+     * Unlike loginWithPassword() and assumeIdentity(), this method cannot
+     * resolve the server from the user name because the full user MXID is
+     * encoded in the login token. Callers should ensure the homeserver
+     * sanity in advance.
+     */
     void loginWithToken(const QByteArray& loginToken,
                         const QString& initialDeviceName,
                         const QString& deviceId = {});
-    void assumeIdentity(const QString& userId, const QString& accessToken,
+    /** \brief Use an existing access token to connect to the homeserver
+     *
+     * Similar to loginWithPassword(), this method checks that the homeserver
+     * URL is valid and tries to resolve it from the MXID in case it is not.
+     */
+    void assumeIdentity(const QString& mxId, const QString& accessToken,
                         const QString& deviceId);
     /*! \deprecated Use loginWithPassword instead */
     void connectToServer(const QString& userId, const QString& password,
@@ -650,9 +671,9 @@ Q_SIGNALS:
      * This was a signal resulting from a successful resolveServer().
      * Since Connection now provides setHomeserver(), the HS URL
      * may change even without resolveServer() invocation. Use
-     * homeserverChanged() instead of resolved(). You can also use
-     * connectToServer and connectWithToken without the HS URL set in
-     * advance (i.e. without calling resolveServer), as they now trigger
+     * loginFLowsChanged() instead of resolved(). You can also use
+     * loginWith*() and assumeIdentity() without the HS URL set in
+     * advance (i.e. without calling resolveServer), as they trigger
      * server name resolution from MXID if the server URL is not valid.
      */
     void resolved();
@@ -848,19 +869,6 @@ private:
     class Private;
     QScopedPointer<Private> d;
 
-    /**
-     * A single entry for functions that need to check whether the
-     * homeserver is valid before running. May either execute connectFn
-     * synchronously or asynchronously (if tryResolve is true and
-     * a DNS lookup is initiated); in case of errors, emits resolveError
-     * if the homeserver URL is not valid and cannot be resolved from
-     * userId.
-     *
-     * @param userId - fully-qualified MXID to resolve HS from
-     * @param connectFn - a function to execute once the HS URL is good
-     */
-    void checkAndConnect(const QString& userId, std::function<void()> connectFn);
-
     static room_factory_t _roomFactory;
     static user_factory_t _userFactory;
 };