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.

Examples

let user = "example";
let client = Client::new(homeserver).await?;
client.matrix_auth().login_username(user, "password").send().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.

Examples

let user = "example";
let client = Client::new(homeserver).await?;
client.matrix_auth().login_username(user, "password").send().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.

This always sends a request to the server to retrieve this information. If successful, this fills the cache, and makes it so that Self::get_cached_avatar_url will always return something.

Examples

let client = Client::new(homeserver).await?;
client.matrix_auth().login_username(user, "password").send().await?;

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

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

Get the URL of the account’s avatar, if is stored in cache.

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.

Examples

let client = Client::new(homeserver).await?;
client.matrix_auth().login_username(user, "password").send().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: Vec<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.

Examples

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

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

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

Get the profile of the account.

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

Examples

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

pub async fn fetch_user_profile_of(&self, user_id: &UserId) -> Result<Response>

Get the profile for a given user id

Arguments

• user_id the matrix id this function downloads the profile for

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.

Examples

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

pub async fn deactivate( &self, id_server: Option<&str>, auth_data: Option<AuthData>, erase_data: bool, ) -> 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.

• erase - Whether the user would like their content to be erased as much as possible from the server.

Examples

let response = account.deactivate(None, None, false).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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.

Examples

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.keys() {
        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 fetch_account_data( &self, event_type: GlobalAccountDataEventType, ) -> Result<Option<Raw<AnyGlobalAccountDataEventContent>>>

Fetch a global account data event from the server.

The content from the response will not be persisted in the store.

Examples

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

if let Some(raw_content) = account.fetch_account_data(GlobalAccountDataEventType::IgnoredUserList).await? {
    let content = raw_content.deserialize_as::<IgnoredUserListEventContent>()?;

    println!("Ignored users:");

    for user_id in content.ignored_users.keys() {
        println!("- {user_id}");
    }
}

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

where T: GlobalAccountDataEventContent,

Set the given account data event.

Examples

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

let mut content = account
    .account_data::<IgnoredUserListEventContent>()
    .await?
    .map(|c| c.deserialize())
    .transpose()?
    .unwrap_or_default();
content
    .ignored_users
    .insert(user_id!("@foo:bar.com").to_owned(), IgnoredUser::new());
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.

pub async fn mark_as_dm( &self, room_id: &RoomId, user_ids: &[OwnedUserId], ) -> Result<()>

Marks the room identified by room_id as a “direct chat” with each user in user_ids.

Arguments

• room_id - The room ID of the direct message room.
• user_ids - The user IDs to be associated with this direct message room.

pub async fn ignore_user(&self, user_id: &UserId) -> Result<()>

Adds the given user ID to the account’s ignore list.

pub async fn unignore_user(&self, user_id: &UserId) -> Result<()>

Removes the given user ID from the account’s ignore list.

pub async fn push_rules(&self) -> Result<Ruleset>

Get the current push rules from storage.

If no push rules event was found, or it fails to deserialize, a ruleset with the server-default push rules is returned.

Panics if called when the client is not logged in.

pub async fn get_recently_visited_rooms(&self) -> Result<Vec<OwnedRoomId>>

Retrieves the user’s recently visited room list

pub async fn track_recently_visited_room( &self, room_id: OwnedRoomId, ) -> Result<(), Error>

Moves/inserts the given room to the front of the recently visited list

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.