Add documentation on LoginWizard and RegistrationWizard (#3303)

ee
This commit is contained in:
Benoit Marty 2021-05-14 11:39:02 +02:00
parent 796bb80868
commit 946208a84d
4 changed files with 89 additions and 13 deletions

View File

@ -23,7 +23,7 @@ Test:
-
Other changes:
-
- Add documentation on LoginWizard and RegistrationWizard (#3303)
Changes in Element 1.1.7 (2021-05-12)
===================================================

View File

@ -51,11 +51,15 @@ interface AuthenticationService {
/**
* Return a LoginWizard, to login to the homeserver. The login flow has to be retrieved first.
*
* See [LoginWizard] for more details
*/
fun getLoginWizard(): LoginWizard
/**
* Return a RegistrationWizard, to create an matrix account on the homeserver. The login flow has to be retrieved first.
*
* See [RegistrationWizard] for more details.
*/
fun getRegistrationWizard(): RegistrationWizard

View File

@ -17,34 +17,46 @@
package org.matrix.android.sdk.api.auth.login
import org.matrix.android.sdk.api.session.Session
import org.matrix.android.sdk.api.util.Cancelable
/**
* Set of methods to be able to login to an existing account on a homeserver.
*
* More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signin.md
*/
interface LoginWizard {
/**
* @param login the login field
* @param password the password field
* Login to the homeserver.
*
* @param login the login field. Can be a user name, or a msisdn (email or phone number) associated to the account
* @param password the password of the account
* @param deviceName the initial device name
* @param callback the matrix callback on which you'll receive the result of authentication.
* @return a [Cancelable]
* @return a [Session] if the login is successful
*/
suspend fun login(login: String,
password: String,
deviceName: String): Session
/**
* Exchange a login token to an access token
* Exchange a login token to an access token.
*
* @param loginToken login token, obtain when login has happen in a WebView, using SSO
* @return a [Session] if the login is successful
*/
suspend fun loginWithToken(loginToken: String): Session
/**
* Reset user password
* Ask the homeserver to reset the user password. The password will not be reset until
* [resetPasswordMailConfirmed] is successfully called.
*
* @param email an email previously associated to the account the user wants the password to be reset.
* @param newPassword the desired new password
*/
suspend fun resetPassword(email: String,
newPassword: String)
/**
* Confirm the new password, once the user has checked their email
* When this method succeed, tha account password will be effectively modified.
*/
suspend fun resetPasswordMailConfirmed()
}

View File

@ -16,32 +16,92 @@
package org.matrix.android.sdk.api.auth.registration
/**
* Set of methods to be able to create an account on a homeserver.
*
* More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signup.md
*/
interface RegistrationWizard {
/**
* Call this method to get the possible registration flow of the current homeserver.
* It can be useful to ensure that your application implementation supports all the stages
* required to create an account. If it is not the case, you will have to use the web fallback
* to let the user create an account with your application.
* See [org.matrix.android.sdk.api.auth.AuthenticationService.getFallbackUrl]
*/
suspend fun getRegistrationFlow(): RegistrationResult
/**
* Can be call to check is the desired userName is available for registration on the current homeserver.
* It may also fails if the desired userName is not correctly formatted or does not follow any restriction on
* the homeserver. Ex: userName with only digits may be rejected.
* @param userName the desired username. Ex: "alice"
*/
suspend fun registrationAvailable(userName: String): RegistrationAvailability
/**
* This is the first method to call in order to create an account and start the registration process.
*
* @param userName the desired username. Ex: "alice"
* @param password the desired password
* @param initialDeviceDisplayName the device display name
*/
suspend fun createAccount(userName: String?,
password: String?,
initialDeviceDisplayName: String?): RegistrationResult
/**
* Perform the "m.login.recaptcha" stage.
*
* @param response the response from ReCaptcha
*/
suspend fun performReCaptcha(response: String): RegistrationResult
/**
* Perform the "m.login.terms" stage.
*/
suspend fun acceptTerms(): RegistrationResult
/**
* Perform the "m.login.dummy" stage.
*/
suspend fun dummy(): RegistrationResult
/**
* Perform the "m.login.email.identity" or "m.login.msisdn" stage.
*
* @param threePid the threePid to add to the account. If this is an email, the homeserver will send an email
* to validate it. For a msisdn a SMS will be sent.
*/
suspend fun addThreePid(threePid: RegisterThreePid): RegistrationResult
/**
* Ask the homeserver to send again the current threePid (email or msisdn).
*/
suspend fun sendAgainThreePid(): RegistrationResult
/**
* Send the code received by SMS to validate a msisdn.
* If the code is correct, the registration request will be executed to validate the msisdn.
*/
suspend fun handleValidateThreePid(code: String): RegistrationResult
/**
* Useful to poll the homeserver when waiting for the email to be validated by the user.
* Once the email is validated, this method will return successfully.
* @param delayMillis the SDK can wait before sending the request
*/
suspend fun checkIfEmailHasBeenValidated(delayMillis: Long): RegistrationResult
suspend fun registrationAvailable(userName: String): RegistrationAvailability
/**
* This is the current ThreePid, waiting for validation. The SDK will store it in database, so it can be
* restored even if the app has been killed during the registration
*/
val currentThreePid: String?
// True when login and password has been sent with success to the homeserver
/**
* True when login and password have been sent with success to the homeserver, i.e. [createAccount] has been
* called successfully.
*/
val isRegistrationStarted: Boolean
}