Struct matrix_sdk::Client

pub struct Client { /* fields omitted */ }

An async/await enabled Matrix client.

All of the state is held in an Arc so the Client can be cloned freely.

Implementations

impl Client

pub fn new(homeserver_url: impl TryInto<Url>) -> Result<Self>

Creates a new client for making HTTP requests to the given homeserver.

Arguments

• homeserver_url - The homeserver that the client should connect to.

pub fn new_with_config(
    homeserver_url: impl TryInto<Url>,
    config: ClientConfig
) -> Result<Self>

Create a new client with the given configuration.

Arguments

• homeserver_url - The homeserver that the client should connect to.

• config - Configuration for the client.

pub async fn logged_in(&self) -> bool

Is the client logged in.

pub fn homeserver(&self) -> &Url

The Homeserver of the client.

pub async fn user_id(&self) -> Option<UserId>

Get the user id of the current owner of the client.

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

Fetches the display name of the owner of the client.

Example

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

if let Some(name) = client.display_name().await.unwrap() {
    println!("Logged in as user '{}' with display name '{}'", user, name);
}

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

Sets the display name of the owner of the client.

Example

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

client.set_display_name(Some("Alice")).await.expect("Failed setting display name");

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

Gets the mxc avatar url of the owner of the client, if set.

Example

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

if let Some(url) = client.avatar_url().await.unwrap() {
    println!("Your avatar's mxc url is {}", url);
}

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

Sets the mxc avatar url of the client's owner. The avatar gets unset if url is None.

pub async fn upload_avatar<R: Read>(
    &self,
    content_type: &Mime,
    reader: &mut R
) -> Result<()>

Upload and set the owning client's avatar.

The will upload the data produced by the reader to the homeserver's content repository, and set the user's avatar to the mxc url for the uploaded file.

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

Example

let path = Path::new("/home/example/selfie.jpg");
let mut image = File::open(&path).unwrap();

client.upload_avatar(&mime::IMAGE_JPEG, &mut image).await.expect("Can't set avatar");

pub async fn add_event_emitter(&mut self, emitter: Box<dyn EventEmitter>)

Add EventEmitter to Client.

The methods of EventEmitter are called when the respective RoomEvents occur.

pub fn joined_rooms(&self) -> Arc<RwLock<HashMap<RoomId, Arc<RwLock<Room>>>>>

Returns the joined rooms this client knows about.

pub fn invited_rooms(&self) -> Arc<RwLock<HashMap<RoomId, Arc<RwLock<Room>>>>>

Returns the invited rooms this client knows about.

pub fn left_rooms(&self) -> Arc<RwLock<HashMap<RoomId, Arc<RwLock<Room>>>>>

Returns the left rooms this client knows about.

pub async fn get_joined_room(
    &self,
    room_id: &RoomId
) -> Option<Arc<RwLock<Room>>>

Get a joined room with the given room id.

Arguments

room_id - The unique id of the room that should be fetched.

pub async fn get_invited_room(
    &self,
    room_id: &RoomId
) -> Option<Arc<RwLock<Room>>>

Get an invited room with the given room id.

Arguments

room_id - The unique id of the room that should be fetched.

pub async fn get_left_room(&self, room_id: &RoomId) -> Option<Arc<RwLock<Room>>>

Get a left room with the given room id.

Arguments

room_id - The unique id of the room that should be fetched.

pub async fn store_room_state(&self, room_id: &RoomId) -> Result<()>

This allows Client to manually store Room state with the provided StateStore.

Returns Ok when a successful Room store occurs.

pub async fn login(
    &self,
    user: &str,
    password: &str,
    device_id: Option<&str>,
    initial_device_display_name: Option<&str>
) -> Result<Response>

Login to the server.

This can be used for the first login as well as for subsequent logins, note that if the device id isn't provided a new device will be created.

If this isn't the first login a device id should be provided to restore the correct stores.

Alternatively the restore_login method can be used to restore a logged in client without the password.

Arguments

• user - The user that should be logged in to the homeserver.

• password - The password of the user.

• device_id - A unique id that will be associated with this session. If not given the homeserver will create one. Can be an existing device_id from a previous login call. Note that this should be done only if the client also holds the encryption keys for this device.

Example

let client = Client::new(homeserver).unwrap();
let user = "example";
let response = client
    .login(user, "wordpass", None, Some("My bot")).await
    .unwrap();

println!("Logged in as {}, got device_id {} and access_token {}",
         user, response.device_id, response.access_token);

pub async fn restore_login(&self, session: Session) -> Result<()>

Restore a previously logged in session.

This can be used to restore the client to a logged in state, loading all the stored state and encryption keys.

Alternatively, if the whole session isn't stored the login method can be used with a device id.

Arguments

• session - A session that the user already has from a previous login call.

pub async fn register(
    &self,
    registration: impl Into<Request<'_>>
) -> Result<Response>

Register a user to the server.

Arguments

• registration - The easiest way to create this request is using the register::Request itself.

Examples

let request = assign!(RegistrationRequest::new(), {
    username: Some("user"),
    password: Some("password"),
    auth: Some(AuthData::FallbackAcknowledgement { session: "foobar" }),
});
let client = Client::new(homeserver).unwrap();
client.register(request).await;

pub async fn join_room_by_id(&self, room_id: &RoomId) -> Result<Response>

Join a room by RoomId.

Returns a join_room_by_id::Response consisting of the joined rooms RoomId.

Arguments

• room_id - The RoomId of the room to be joined.

pub async fn join_room_by_id_or_alias(
    &self,
    alias: &RoomIdOrAliasId,
    server_names: &[Box<ServerName>]
) -> Result<Response>

Join a room by RoomId.

Returns a join_room_by_id_or_alias::Response consisting of the joined rooms RoomId.

Arguments

• alias - The RoomId or RoomAliasId of the room to be joined. An alias looks like #name:example.com.

pub async fn forget_room_by_id(&self, room_id: &RoomId) -> Result<Response>

Forget a room by RoomId.

Returns a forget_room::Response, an empty response.

Arguments

• room_id - The RoomId of the room to be forget.

pub async fn ban_user(
    &self,
    room_id: &RoomId,
    user_id: &UserId,
    reason: Option<&str>
) -> Result<Response>

Ban a user from a room by RoomId and UserId.

Returns a ban_user::Response, an empty response.

Arguments

• room_id - The RoomId of the room to ban the user from.

• user_id - The user to ban by UserId.

• reason - The reason for banning this user.

pub async fn kick_user(
    &self,
    room_id: &RoomId,
    user_id: &UserId,
    reason: Option<&str>
) -> Result<Response>

Kick a user out of the specified room.

Returns a kick_user::Response, an empty response.

Arguments

• room_id - The RoomId of the room the user should be kicked out of.

• user_id - The UserId of the user that should be kicked out of the room.

• reason - Optional reason why the room member is being kicked out.

pub async fn leave_room(&self, room_id: &RoomId) -> Result<Response>

Leave the specified room.

Returns a leave_room::Response, an empty response.

Arguments

• room_id - The RoomId of the room to leave.

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

Invite the specified user by UserId to the given room.

Returns a invite_user::Response, an empty response.

Arguments

• room_id - The RoomId of the room to invite the specified user to.

• user_id - The UserId of the user to invite to the room.

pub async fn invite_user_by_3pid(
    &self,
    room_id: &RoomId,
    invite_id: Invite3pid<'_>
) -> Result<Response>

Invite the specified user by third party id to the given room.

Returns a invite_user::Response, an empty response.

Arguments

• room_id - The RoomId of the room to invite the specified user to.

• invite_id - A third party id of a user to invite to the room.

pub async fn public_rooms(
    &self,
    limit: Option<u32>,
    since: Option<&str>,
    server: Option<&ServerName>
) -> Result<Response>

Search the homeserver's directory of public rooms.

Sends a request to "_matrix/client/r0/publicRooms", returns a get_public_rooms::Response.

Arguments

• limit - The number of PublicRoomsChunks in each response.

• since - Pagination token from a previous request.

• server - The name of the server, if None the requested server is used.

Examples

use matrix_sdk::Client;

let mut client = Client::new(homeserver).unwrap();

client.public_rooms(limit, since, server).await;

pub async fn public_rooms_filtered(
    &self,
    room_search: impl Into<Request<'_>>
) -> Result<Response>

Search the homeserver's directory of public rooms with a filter.

Sends a request to "_matrix/client/r0/publicRooms", returns a get_public_rooms_filtered::Response.

Arguments

• room_search - The easiest way to create this request is using the get_public_rooms_filtered::Request itself.

Examples

let mut client = Client::new(homeserver).unwrap();

let generic_search_term = Some("matrix-rust-sdk");
let filter = assign!(Filter::new(), { generic_search_term });
let request = assign!(PublicRoomsFilterRequest::new(), { filter });

client.public_rooms_filtered(request).await;

pub async fn create_room(
    &self,
    room: impl Into<Request<'_>>
) -> Result<Response>

Create a room using the RoomBuilder and send the request.

Sends a request to /_matrix/client/r0/createRoom, returns a create_room::Response, this is an empty response.

Arguments

• room - The easiest way to create this request is using the create_room::Request itself.

Examples

use matrix_sdk::Client;

let request = CreateRoomRequest::new();
let client = Client::new(homeserver).unwrap();
assert!(client.create_room(request).await.is_ok());

pub async fn room_messages(
    &self,
    request: impl Into<Request<'_>>
) -> Result<Response>

Sends a request to /_matrix/client/r0/rooms/{room_id}/messages and returns a get_message_events::Response that contains a chunk of room and state events (AnyRoomEvent and AnyStateEvent).

Arguments

• request - The easiest way to create this request is using the get_message_events::Request itself.

Examples

use matrix_sdk::Client;

let room_id = room_id!("!roomid:example.com");
let request = MessagesRequest::backward(&room_id, "t47429-4392820_219380_26003_2265");

let mut client = Client::new(homeserver).unwrap();
assert!(client.room_messages(request).await.is_ok());

pub async fn typing_notice(
    &self,
    room_id: &RoomId,
    typing: impl Into<Typing>
) -> Result<TypingResponse>

Send a request to notify the room of a user typing.

Returns a create_typing_event::Response, an empty response.

Arguments

• room_id - The RoomId the user is typing in.

• typing - Whether the user is typing, and how long.

Examples

let response = client
    .typing_notice(&room_id, Typing::Yes(Duration::from_secs(4)))
    .await
    .expect("Can't get devices from server");

pub async fn read_receipt(
    &self,
    room_id: &RoomId,
    event_id: &EventId
) -> Result<Response>

Send a request to notify the room the user has read specific event.

Returns a create_receipt::Response, an empty response.

Arguments

• room_id - The RoomId the user is currently in.

• event_id - The EventId specifies the event to set the read receipt on.

pub async fn read_marker(
    &self,
    room_id: &RoomId,
    fully_read: &EventId,
    read_receipt: Option<&EventId>
) -> Result<Response>

Send a request to notify the room user has read up to specific event.

Returns a set_read_marker::Response, an empty response.

Arguments

• room_id - The RoomId the user is currently in.

• fully_read - The EventId of the event the user has read to.

• read_receipt - An EventId to specify the event to set the read receipt on.

pub async fn room_send(
    &self,
    room_id: &RoomId,
    content: impl Into<AnyMessageEventContent>,
    txn_id: Option<Uuid>
) -> Result<Response>

Send a room message to the homeserver.

Returns the parsed response from the server.

If the encryption feature is enabled this method will transparently encrypt the room message if the given room is encrypted.

Arguments

• room_id - The id of the room that should receive the message.

• content - The content of the message event.

• txn_id - A unique Uuid that can be attached to a MessageEvent held in its unsigned field as transaction_id. If not given one is created for the message.

Example

use matrix_sdk::events::{
    AnyMessageEventContent,
    room::message::{MessageEventContent, TextMessageEventContent},
};
use matrix_sdk_common::uuid::Uuid;

let content = AnyMessageEventContent::RoomMessage(
    MessageEventContent::Text(TextMessageEventContent::plain("Hello world"))
);

let txn_id = Uuid::new_v4();
client.room_send(&room_id, content, Some(txn_id)).await.unwrap();

pub async fn room_send_attachment<R: Read>(
    &self,
    room_id: &RoomId,
    body: &str,
    content_type: &Mime,
    reader: &mut R,
    txn_id: Option<Uuid>
) -> Result<Response>

Send an attachment to a room.

This will upload the given data that the reader produces using the upload() method and post an event to the given room. If the room is encrypted and the encryption feature is enabled the upload will be encrypted.

This is a convenience method that calls the upload() and afterwards the room_send().

Arguments

• room_id - The id of the room that should receive the media event.

• body - A textual representation of the media that is going to be uploaded. Usually the file name.

• content_type - The type of the media, this will be used as the content-type header.

• reader - A Reader that will be used to fetch the raw bytes of the media.

• txn_id - A unique Uuid that can be attached to a MessageEvent held in its unsigned field as transaction_id. If not given one is created for the message.

Examples

let path = PathBuf::from("/home/example/my-cat.jpg");
let mut image = File::open(path).unwrap();

let response = client
    .room_send_attachment(&room_id, "My favorite cat", &mime::IMAGE_JPEG, &mut image, None)
    .await
    .expect("Can't upload my cat.");

pub async fn upload(
    &self,
    content_type: &Mime,
    reader: &mut impl Read
) -> Result<Response>

Upload some media to the server.

Arguments

• content_type - The type of the media, this will be used as the content-type header.

• reader - A Reader that will be used to fetch the raw bytes of the media.

Examples

let path = PathBuf::from("/home/example/my-cat.jpg");
let mut image = File::open(path).unwrap();

let response = client
    .upload(&mime::IMAGE_JPEG, &mut image)
    .await
    .expect("Can't upload my cat.");

println!("Cat URI: {}", response.content_uri);

pub async fn send<Request>(
    &self,
    request: Request
) -> Result<Request::IncomingResponse> where
    Request: OutgoingRequest + Debug,
    Error: From<FromHttpResponseError<Request::EndpointError>>, 

Send an arbitrary request to the server, without updating client state.

Warning: Because this method does not update the client state, it is important to make sure than you account for this yourself, and use wrapper methods where available. This method should only be used if a wrapper method for the endpoint you'd like to use is not available.

Arguments

• request - A filled out and valid request for the endpoint to be hit

Example

use matrix_sdk::api::r0::profile;
use matrix_sdk::identifiers::user_id;

// First construct the request you want to make
// See https://docs.rs/ruma-client-api/latest/ruma_client_api/index.html
// for all available Endpoints
let user_id = user_id!("@example:localhost");
let request = profile::get_profile::Request::new(&user_id);

// Start the request using Client::send()
let response = client.send(request).await.unwrap();

// Check the corresponding Response struct to find out what types are
// returned

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

Get information of all our own devices.

Examples

let response = client.devices().await.expect("Can't get devices from server");

for device in response.devices {
    println!(
        "Device: {} {}",
        device.device_id,
        device.display_name.as_deref().unwrap_or("")
    );
}

pub async fn delete_devices(
    &self,
    devices: &[DeviceIdBox],
    auth_data: Option<AuthData<'_>>
) -> Result<Response>

Delete the given devices from the server.

Arguments

• devices - The list of devices that should be deleted from the server.

• auth_data - This request requires user interactive auth, 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.

let devices = &["DEVICEID".into()];

if let Err(e) = client.delete_devices(devices, None).await {
    if let Some(info) = e.uiaa_response() {
        let mut auth_parameters = BTreeMap::new();

        let identifier = json!({
            "type": "m.id.user",
            "user": "example",
        });
        auth_parameters.insert("identifier".to_owned(), identifier);
        auth_parameters.insert("password".to_owned(), "wordpass".into());

        // This is needed because of https://github.com/matrix-org/synapse/issues/5665
        auth_parameters.insert("user".to_owned(), "@example:localhost".into());

        let auth_data = AuthData::DirectRequest {
            kind: "m.login.password",
            auth_parameters,
            session: info.session.as_deref(),
        };

        client
            .delete_devices(devices, Some(auth_data))
            .await
            .expect("Can't delete devices");
    }
}

pub async fn sync_once(
    &self,
    sync_settings: SyncSettings<'_>
) -> Result<Response>

Synchronize the client's state with the latest state on the server.

Note: You should not use this method to repeatedly sync if encryption support is enabled, the sync method will make additional requests between syncs that are needed for E2E encryption to work.

Arguments

• sync_settings - Settings for the sync call.

pub async fn sync(&self, sync_settings: SyncSettings<'_>)

Repeatedly call sync to synchronize the client state with the server.

This method will never return, if cancellation is needed the method should be wrapped in a cancelable task or the sync_with_callback method can be used.

Arguments

• sync_settings - Settings for the sync call. Note that those settings will be only used for the first sync call.

pub async fn sync_with_callback<C>(
    &self,
    sync_settings: SyncSettings<'_>,
    callback: impl Fn(Response) -> C
) where
    C: Future<Output = LoopCtrl>, 

Repeatedly call sync to synchronize the client state with the server.

Arguments

• sync_settings - Settings for the sync call. Note that those settings will be only used for the first sync call.

• callback - A callback that will be called every time a successful response has been fetched from the server. The callback must return a boolean which signalizes if the method should stop syncing. If the callback returns LoopCtrl::Continue the sync will continue, if the callback returns LoopCtrl::Break the sync will be stopped.

Examples

The following example demonstrates how to sync forever while sending all the interesting events through a mpsc channel to another thread e.g. a UI thread.

use async_std::sync::channel;

let (tx, rx) = channel(100);

let sync_channel = &tx;
let sync_settings = SyncSettings::new()
    .timeout(Duration::from_secs(30));

client
    .sync_with_callback(sync_settings, async move |response| {
        let channel = sync_channel;

        for (room_id, room) in response.rooms.join {
            for event in room.timeline.events {
                if let Ok(e) = event.deserialize() {
                    channel.send(e).await;
                }
            }
        }

        LoopCtrl::Continue
    })
    .await;
})

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

Get the current, if any, sync token of the client. This will be None if the client didn't sync at least once.

pub async fn get_verification(&self, flow_id: &str) -> Option<Sas>

This is supported on encryption only.

Get a Sas verification object with the given flow id.

pub async fn get_device(
    &self,
    user_id: &UserId,
    device_id: &DeviceId
) -> StdResult<Option<Device>, CryptoStoreError>

This is supported on encryption only.

Get a specific device of a user.

Arguments

• user_id - The unique id of the user that the device belongs to.

• device_id - The unique id of the device.

Returns a Device if one is found and the crypto store didn't throw an error.

This will always return None if the client hasn't been logged in.

Example

let device = client.get_device(&alice, "DEVICEID".into())
    .await
    .unwrap()
    .unwrap();

println!("{:?}", device.is_trusted());

let verification = device.start_verification().await.unwrap();

pub async fn bootstrap_cross_signing(
    &self,
    auth_data: Option<AuthData<'_>>
) -> Result<()>

This is supported on encryption only.

Create and upload a new cross signing identity.

Arguments

• auth_data - This request requires user interactive auth, 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.

Examples

fn auth_data<'a>(user: &UserId, password: &str, session: Option<&'a str>) -> AuthData<'a> {
    let mut auth_parameters = BTreeMap::new();
    let identifier = json!({
        "type": "m.id.user",
        "user": user,
    });
    auth_parameters.insert("identifier".to_owned(), identifier);
    auth_parameters.insert("password".to_owned(), password.to_owned().into());
    // This is needed because of https://github.com/matrix-org/synapse/issues/5665
    auth_parameters.insert("user".to_owned(), user.as_str().into());
    AuthData::DirectRequest {
        kind: "m.login.password",
        auth_parameters,
        session,
    }
}

if let Err(e) = client.bootstrap_cross_signing(None).await {
    if let Some(response) = e.uiaa_response() {
        let auth_data = auth_data(&user_id, "wordpass", response.session.as_deref());
           client
               .bootstrap_cross_signing(Some(auth_data))
               .await
               .expect("Couldn't bootstrap cross signing")
    } else {
        panic!("Error durign cross signing bootstrap {:#?}", e);
    }
}

pub async fn get_user_devices(
    &self,
    user_id: &UserId
) -> StdResult<UserDevices, CryptoStoreError>

This is supported on encryption only.

Get a map holding all the devices of an user.

This will always return an empty map if the client hasn't been logged in.

Arguments

• user_id - The unique id of the user that the devices belong to.

Example

let devices = client.get_user_devices(&alice).await.unwrap();

for device in devices.devices() {
    println!("{:?}", device);
}

pub async fn export_keys(
    &self,
    path: PathBuf,
    passphrase: &str,
    predicate: impl FnMut(&InboundGroupSession) -> bool
) -> Result<()>

This is supported on encryption and non-WebAssembly only.

Export E2EE keys that match the given predicate encrypting them with the given passphrase.

Arguments

• path - The file path where the exported key file will be saved.

• passphrase - The passphrase that will be used to encrypt the exported room keys.

• predicate - A closure that will be called for every known InboundGroupSession, which represents a room key. If the closure returns true the InboundGroupSessoin will be included in the export, if the closure returns false it will not be included.

Panics

This method will panic if it isn't run on a Tokio runtime.

This method will panic if it can't get enough randomness from the OS to encrypt the exported keys securely.

Examples

let path = PathBuf::from("/home/example/e2e-keys.txt");
// Export all room keys.
client
    .export_keys(path, "secret-passphrase", |_| true)
    .await
    .expect("Can't export keys.");

// Export only the room keys for a certain room.
let path = PathBuf::from("/home/example/e2e-room-keys.txt");
let room_id = room_id!("!test:localhost");

client
    .export_keys(path, "secret-passphrase", |s| s.room_id() == &room_id)
    .await
    .expect("Can't export keys.");

pub async fn import_keys(
    &self,
    path: PathBuf,
    passphrase: &str
) -> Result<(usize, usize)>

This is supported on encryption and non-WebAssembly only.

Import E2EE keys from the given file path.

Arguments

• path - The file path where the exported key file will can be found.

• passphrase - The passphrase that should be used to decrypt the exported room keys.

Returns a tuple of numbers that represent the number of sessions that were imported and the total number of sessions that were found in the key export.

Panics

This method will panic if it isn't run on a Tokio runtime.

let path = PathBuf::from("/home/example/e2e-keys.txt");
client
    .import_keys(path, "secret-passphrase")
    .await
    .expect("Can't import keys");

Trait Implementations

impl Clone for Client

pub fn clone(&self) -> Client

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Client

pub fn fmt(&self, fmt: &mut Formatter<'_>) -> StdResult<(), Error>

Formats the value using the given formatter.