Page MenuHomePhorge
Files F85118359

D316.1782459757.diff
No OneTemporary
Actions

Size
11 KB
Referenced Files
None
Subscribers
None

D316.1782459757.diff
View Options

diff --git a/src/client/client.hpp b/src/client/client.hpp
--- a/src/client/client.hpp
+++ b/src/client/client.hpp
@@ -239,8 +239,8 @@
*
* This will create a new session on the homeserver.
*
- * If the returned Promise resolves successfully, this will
- * call `startSyncing()`.
+ * If startSyncingOnSuccess is true and the returned Promise
+ * resolves successfully, this will call `startSyncing()`.
*
* @param homeserver The base url of the homeserver. E.g. `https://tusooa.xyz`.
* @param username The username. This can be the full user id or
@@ -248,11 +248,22 @@
* @param password The password.
* @param deviceName Optionally, a custom device name. If empty, `libkazv`
* will be used.
+ * @param startSyncingOnSuccess Start syncing immediately when
+ * the login is successful.
* @return A Promise that resolves when logging in successfully, or
* when there is an error.
*/
PromiseT passwordLogin(std::string homeserver, std::string username,
- std::string password, std::string deviceName) const;
+ std::string password, std::string deviceName, bool startSyncingOnSuccess) const;
+
+ /**
+ * Equivalent to `passwordLogin(homeserver, username, password, deviceName, true)`.
+ *
+ * This is an overloaded function.
+ */
+ [[deprecated("Specify startSyncingOnSuccess explicitly")]]
+ PromiseT passwordLogin(std::string homeserver, std::string username,
+ std::string password, std::string deviceName) const;
/**
* Login using `token` and `deviceId`.
@@ -260,33 +271,59 @@
* This will not make a request. Library users should make sure
* the information is correct and the token and the device id are valid.
*
- * If the returned Promise resolves successfully, this will
- * call `startSyncing()`.
+ * If startSyncingOnSuccess is true and the returned Promise resolves
+ * successfully, this will call `startSyncing()`.
*
* @param homeserver The base url of the homeserver. E.g. `https://tusooa.xyz`.
* @param username The full user id. E.g. `@tusooa:tusooa.xyz`.
* @param token The access token.
* @param deviceId The device id that is paired with `token`.
+ * @param startSyncingOnSuccess Start syncing immediately when
+ * the login is successful.
* @return A Promise that resolves when the account information is filled in.
*/
PromiseT tokenLogin(std::string homeserver, std::string username,
- std::string token, std::string deviceId) const;
+ std::string token, std::string deviceId, bool startSyncingOnSuccess) const;
+
+ /**
+ * Equivalent to `tokenLogin(homeserver, username, token, deviceId, true)`.
+ *
+ * This is an overloaded function.
+ */
+ [[deprecated("Specify startSyncingOnSuccess explicitly")]]
+ PromiseT tokenLogin(std::string homeserver, std::string username,
+ std::string token, std::string deviceId) const;
/**
* Login using a login token.
*
* This will create a new session on the homeserver.
*
- * If the returned Promise resolves successfully, this will
- * call `startSyncing()`.
+ * If startSyncingOnSuccess is true and the returned Promise resolves
+ * successfully, this will call `startSyncing()`.
*
* @param homeserver The base url of the homeserver. E.g. `https://tusooa.xyz`.
* @param loginToken The login token.
* @param deviceName Optionally, a custom device name. If empty, `libkazv`
* will be used.
+ * @param startSyncingOnSuccess Start syncing immediately when
+ * the login is successful.
* @return A Promise that resolves when logging in successfully, or
* when there is an error.
*/
+ PromiseT mLoginTokenLogin(
+ std::string homeserver,
+ std::string loginToken,
+ std::optional<std::string> deviceName,
+ bool startSyncingOnSuccess
+ ) const;
+
+ /**
+ * Equivalent to `mLoginTokenLogin(homeserver, loginToken, deviceName, true)`.
+ *
+ * This is an overloaded function.
+ */
+ [[deprecated("Specify startSyncingOnSuccess explicitly")]]
PromiseT mLoginTokenLogin(
std::string homeserver,
std::string loginToken,
@@ -296,15 +333,27 @@
/**
* Get the `shouldSync` field of current ClientModel.
*
+ * The shouldSync flag is only used internally by `startSyncing()`
+ * and `stopSyncing()`.
+ * If you use `doOneSyncCycle()` and implement your own sync loop,
+ * you probably do not need this.
+ *
* @return A lager::reader of bool of the `shouldSync` field of the ClientModel
*/
auto shouldSync() const -> lager::reader<bool>;
/**
- * Stop syncing and then logout current session.
+ * Set the `shouldSync` internal flag to false,
+ * and then logout current session.
+ *
+ * The access token in this client will no longer be valid.
*
* Meanwhile, clear the current token and set loggedIn to false.
*
+ * If you do not use `startSyncing()` and implement your own
+ * sync loop using `doOneSyncCycle()`, you need to stop syncing
+ * by yourself before calling this function.
+ *
* @return A promise that resolves when the syncing is stopped.
*/
PromiseT logout() const;
@@ -517,6 +566,13 @@
* This function internally calls ensureReadyForSyncing() and
* doOneSyncCycle().
*
+ * This will automatically retry the sync request if it fails,
+ * by first delaying `firstRetryMs`, then multiply the delay time
+ * by `retryTimeFactor`, until it reaches `maxRetryMs`. It also
+ * means that the application do not have a way to make the retry
+ * hit sooner. To do that, you need to implement your own sync loop
+ * using `doOneSyncCycle()`.
+ *
* @return A Promise that resolves when the Client is syncing
* (more exactly, when syncing() contains true), or when there
* is an error in the preparation of the sync.
@@ -524,11 +580,16 @@
PromiseT startSyncing() const;
/**
- * Stop the indefinite syncing.
+ * Stop the indefinite syncing started by `startSyncing()`.
+ *
+ * If you do not use `startSyncing()`, you probably do not need
+ * this.
*
- * After this, no more syncing actions will be dispatched.
+ * After this, it sets the `shouldSync` flag to false, so
+ * no more syncing actions will be dispatched by `startSyncing()`.
*
* @return A Promise that resolves when syncing is stopped.
+ * @sa shouldSync(), startSyncing()
*/
PromiseT stopSyncing() const;
diff --git a/src/client/client.cpp b/src/client/client.cpp
--- a/src/client/client.cpp
+++ b/src/client/client.cpp
@@ -131,61 +131,89 @@
}
auto Client::passwordLogin(std::string homeserver, std::string username,
- std::string password, std::string deviceName) const
+ std::string password, std::string deviceName, bool startSyncingOnSuccess) const
-> PromiseT
{
auto p1 = m_ctx.dispatch(LoginAction{
homeserver, username, password, deviceName});
- p1
- .then([that=toEventLoop()](auto stat) {
- if (! stat.success()) {
- return;
- }
- // It is meaningless to wait for it in a Promise
- // that is never exposed to the user.
- that.startSyncing();
- });
-
+ if (startSyncingOnSuccess) {
+ p1.then([that=toEventLoop()](auto stat) {
+ if (! stat.success()) {
+ return;
+ }
+ // It is meaningless to wait for it in a Promise
+ // that is never exposed to the user.
+ that.startSyncing();
+ });
+ }
return p1;
}
+ auto Client::passwordLogin(std::string homeserver, std::string username,
+ std::string password, std::string deviceName) const
+ -> PromiseT
+ {
+ return passwordLogin(std::move(homeserver), std::move(username),
+ std::move(password), std::move(deviceName), /* startSyncingOnSuccess = */ true);
+ }
+
auto Client::mLoginTokenLogin(
std::string homeserver,
std::string loginToken,
- std::optional<std::string> deviceName
+ std::optional<std::string> deviceName,
+ bool startSyncingOnSuccess
) const -> PromiseT
{
auto p1 = m_ctx.dispatch(MLoginTokenLoginAction{
homeserver, loginToken, deviceName});
- p1
- .then([that=toEventLoop()](auto stat) {
- if (! stat.success()) {
- return;
- }
- that.startSyncing();
- });
+ if (startSyncingOnSuccess) {
+ p1.then([that=toEventLoop()](auto stat) {
+ if (! stat.success()) {
+ return;
+ }
+ that.startSyncing();
+ });
+ }
return p1;
}
+ auto Client::mLoginTokenLogin(
+ std::string homeserver,
+ std::string loginToken,
+ std::optional<std::string> deviceName
+ ) const -> PromiseT
+ {
+ return mLoginTokenLogin(std::move(homeserver), std::move(loginToken),
+ std::move(deviceName), /* startSyncingOnSuccess = */ true);
+ }
auto Client::tokenLogin(std::string homeserver, std::string username,
- std::string token, std::string deviceId) const
+ std::string token, std::string deviceId, bool startSyncingOnSuccess) const
-> PromiseT
{
auto p1 = m_ctx.dispatch(TokenLoginAction{
homeserver, username, token, deviceId});
- p1
- .then([that=toEventLoop()](auto stat) {
- if (! stat.success()) {
- return;
- }
- that.startSyncing();
- });
+ if (startSyncingOnSuccess) {
+ p1.then([that=toEventLoop()](auto stat) {
+ if (! stat.success()) {
+ return;
+ }
+ that.startSyncing();
+ });
+ }
return p1;
}
+ auto Client::tokenLogin(std::string homeserver, std::string username,
+ std::string token, std::string deviceId) const
+ -> PromiseT
+ {
+ return tokenLogin(std::move(homeserver), std::move(username),
+ std::move(token), std::move(deviceId), /* startSyncingOnSuccess = */ true);
+ }
+
auto Client::shouldSync() const -> lager::reader<bool> {
return this->clientCursor()[&ClientModel::shouldSync];
}

File Metadata

Mime Type
text/plain
Expires
Fri, Jun 26, 12:42 AM (20 h, 24 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1626407
Default Alt Text
D316.1782459757.diff (11 KB)

Event Timeline