Struct matrix_sdk::Account

pub struct Account { /* private fields */ }

A high-level API to manage the client owner’s account.

All the methods on this struct send a request to the homeserver.

Implementations

impl Account

pub async fn get_display_name(&self) -> Result<Option<String>>

Get the display name of the account.

Example

let user = "example";
let client = Client::new(homeserver).await?;
client.login(user, "password", None, None).await?;

if let Some(name) = client.account().get_display_name().await? {
    println!("Logged in as user '{user}' with display name '{name}'");
}

pub async fn set_display_name(&self, name: Option<&str>) -> Result<()>

Set the display name of the account.

Example

let user = "example";
let client = Client::new(homeserver).await?;
client.login(user, "password", None, None).await?;

client.account().set_display_name(Some("Alice")).await?;

pub async fn get_avatar_url(&self) -> Result<Option<OwnedMxcUri>>

Get the MXC URI of the account’s avatar, if set.

Example

let client = Client::new(homeserver).await?;
client.login(user, "password", None, None).await?;

if let Some(url) = client.account().get_avatar_url().await? {
    println!("Your avatar's mxc url is {url}");
}

pub async fn set_avatar_url(&self, url: Option<&MxcUri>) -> Result<()>

Set the MXC URI of the account’s avatar.

The avatar is unset if url is None.

pub async fn get_avatar(&self, format: MediaFormat) -> Result<Option<Vec<u8>>>

Get the account’s avatar, if set.

Returns the avatar.

If a thumbnail is requested no guarantee on the size of the image is given.

Arguments

• format - The desired format of the avatar.

Example

let client = Client::new(homeserver).await?;
client.login(user, "password", None, None).await?;

if let Some(avatar) = client.account().get_avatar(MediaFormat::File).await?
{
    std::fs::write("avatar.png", avatar);
}

pub async fn upload_avatar(
    &self,
    content_type: &Mime,
    data: &[u8]
) -> Result<OwnedMxcUri>

Upload and set the account’s avatar.

This will upload the data produced by the reader to the homeserver’s content repository, and set the user’s avatar to the MXC URI for the uploaded file.

This is a convenience method for calling Media::upload(), followed by Account::set_avatar_url().

Returns the MXC URI of the uploaded avatar.

Example

let image = fs::read("/home/example/selfie.jpg")?;

client.account().upload_avatar(&mime::IMAGE_JPEG, &image).await?;

pub async fn get_profile(&self) -> Result<Response>

Get the profile of the account.

Allows to get both the display name and avatar URL in a single call.

Example

if let profile = client.account().get_profile().await? {
    println!(
        "You are '{:?}' with avatar '{:?}'",
        profile.displayname, profile.avatar_url
    );
}

pub async fn change_password(
    &self,
    new_password: &str,
    auth_data: Option<AuthData<'_>>
) -> Result<Response>

Change the password of the account.

Arguments

• new_password - The new password to set.

• auth_data - This request uses the User-Interactive Authentication API. The first request needs to set this to None and will always fail with an UiaaResponse. The response will contain information for the interactive auth and the same request needs to be made but this time with some auth_data provided.

Returns

This method might return an ErrorKind::WeakPassword error if the new password is considered insecure by the homeserver, with details about the strength requirements in the error’s message.

Example

client.account().change_password(
    "myverysecretpassword",
    Some(AuthData::Dummy(Dummy::new())),
).await?;

pub async fn deactivate(
    &self,
    id_server: Option<&str>,
    auth_data: Option<AuthData<'_>>
) -> Result<Response>

Deactivate this account definitively.

Arguments

• id_server - The identity server from which to unbind the user’s Third Party Identifiers.

• auth_data - This request uses the User-Interactive Authentication API. The first request needs to set this to None and will always fail with an UiaaResponse. The response will contain information for the interactive auth and the same request needs to be made but this time with some auth_data provided.

Example

let response = account.deactivate(None, None).await;

// Proceed with UIAA.

pub async fn get_3pids(&self) -> Result<Response>

Get the registered Third Party Identifiers on the homeserver of the account.

These 3PIDs may be used by the homeserver to authenticate the user during sensitive operations.

Example

let threepids = client.account().get_3pids().await?.threepids;

for threepid in threepids {
    println!(
        "Found 3PID '{}' of type '{}'",
        threepid.address, threepid.medium
    );
}

pub async fn request_3pid_email_token(
    &self,
    client_secret: &ClientSecret,
    email: &str,
    send_attempt: UInt
) -> Result<Response>

Request a token to validate an email address as a Third Party Identifier.

This is the first step in registering an email address as 3PID. Next, call Account::add_3pid() with the same client_secret and the returned sid.

Arguments

• client_secret - A client-generated secret string used to protect this session.

• email - The email address to validate.

• send_attempt - The attempt number. This number needs to be incremented if you want to request another token for the same validation.

Returns

• sid - The session ID to be used in following requests for this 3PID.

• submit_url - If present, the user will submit the token to the client, that must send it to this URL. If not, the client will not be involved in the token submission.

This method might return an ErrorKind::ThreepidInUse error if the email address is already registered for this account or another, or an ErrorKind::ThreepidDenied error if it is denied.

Example

let token_response = account
    .request_3pid_email_token(&secret, "john@matrix.org", uint!(0))
    .await?;

// Wait for the user to confirm that the token was submitted or prompt
// the user for the token and send it to submit_url.

let uiaa_response =
    account.add_3pid(&secret, &token_response.sid, None).await;

// Proceed with UIAA.

pub async fn request_3pid_msisdn_token(
    &self,
    client_secret: &ClientSecret,
    country: &str,
    phone_number: &str,
    send_attempt: UInt
) -> Result<Response>

Request a token to validate a phone number as a Third Party Identifier.

This is the first step in registering a phone number as 3PID. Next, call Account::add_3pid() with the same client_secret and the returned sid.

Arguments

• client_secret - A client-generated secret string used to protect this session.

• country - The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from.

• phone_number - The phone number to validate.

• send_attempt - The attempt number. This number needs to be incremented if you want to request another token for the same validation.

Returns

• sid - The session ID to be used in following requests for this 3PID.

• submit_url - If present, the user will submit the token to the client, that must send it to this URL. If not, the client will not be involved in the token submission.

This method might return an ErrorKind::ThreepidInUse error if the phone number is already registered for this account or another, or an ErrorKind::ThreepidDenied error if it is denied.

Example

let token_response = account
    .request_3pid_msisdn_token(&secret, "FR", "0123456789", uint!(0))
    .await?;

// Wait for the user to confirm that the token was submitted or prompt
// the user for the token and send it to submit_url.

let uiaa_response =
    account.add_3pid(&secret, &token_response.sid, None).await;

// Proceed with UIAA.

pub async fn add_3pid(
    &self,
    client_secret: &ClientSecret,
    sid: &SessionId,
    auth_data: Option<AuthData<'_>>
) -> Result<Response>

Add a Third Party Identifier on the homeserver for this account.

This 3PID may be used by the homeserver to authenticate the user during sensitive operations.

This method should be called after Account::request_3pid_email_token() or Account::request_3pid_msisdn_token() to complete the 3PID

Arguments

• client_secret - The same client secret used in Account::request_3pid_email_token() or Account::request_3pid_msisdn_token().

• sid - The session ID returned in Account::request_3pid_email_token() or Account::request_3pid_msisdn_token().

• auth_data - This request uses the User-Interactive Authentication API. The first request needs to set this to None and will always fail with an UiaaResponse. The response will contain information for the interactive auth and the same request needs to be made but this time with some auth_data provided.

pub async fn delete_3pid(
    &self,
    address: &str,
    medium: Medium,
    id_server: Option<&str>
) -> Result<Response>

Delete a Third Party Identifier from the homeserver for this account.

Arguments

• address - The 3PID being removed.

• medium - The type of the 3PID.

• id_server - The identity server to unbind from. If not provided, the homeserver should unbind the 3PID from the identity server it was bound to previously.

Returns

• ThirdPartyIdRemovalStatus::Success if the 3PID was also unbound from the identity server.

• ThirdPartyIdRemovalStatus::NoSupport if the 3PID was not unbound from the identity server. This can also mean that the 3PID was not bound to an identity server in the first place.

Example

match account
        .delete_3pid("paul@matrix.org", Medium::Email, None)
        .await?
        .id_server_unbind_result
    {
        ThirdPartyIdRemovalStatus::Success => {
            println!("3PID unbound from the Identity Server");
        }
        _ => println!("Could not unbind 3PID from the Identity Server"),
    }

pub async fn account_data<C>(&self) -> Result<Option<Raw<C>>>where
    C: GlobalAccountDataEventContent + StaticEventContent,

Get the content of an account data event of statically-known type.

Example

use matrix_sdk::ruma::events::ignored_user_list::IgnoredUserListEventContent;

let maybe_content = account.account_data::<IgnoredUserListEventContent>().await?;
if let Some(raw_content) = maybe_content {
    let content = raw_content.deserialize()?;
    println!("Ignored users:");
    for user_id in content.ignored_users {
        println!("- {user_id}");
    }
}

pub async fn account_data_raw(
    &self,
    event_type: GlobalAccountDataEventType
) -> Result<Option<Raw<AnyGlobalAccountDataEventContent>>>

Get the content of an account data event of a given type.

pub async fn set_account_data<T>(&self, content: T) -> Result<Response>where
    T: GlobalAccountDataEventContent,

Set the given account data event.

Example

use matrix_sdk::ruma::{
    events::ignored_user_list::IgnoredUserListEventContent, user_id,
};

let mut content = account
    .account_data::<IgnoredUserListEventContent>()
    .await?
    .map(|c| c.deserialize())
    .transpose()?
    .unwrap_or_default();
content.ignored_users.push(user_id!("@foo:bar.com").to_owned());
account.set_account_data(content).await?;

pub async fn set_account_data_raw(
    &self,
    event_type: GlobalAccountDataEventType,
    content: Raw<AnyGlobalAccountDataEventContent>
) -> Result<Response>

Set the given raw account data event.

Trait Implementations

impl Clone for Account

fn clone(&self) -> Account

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Account

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.