Struct BaseClient

pub struct BaseClient {
    pub room_key_recipient_strategy: CollectStrategy,
    pub decryption_settings: DecryptionSettings,
    pub handle_verification_events: bool,
    pub threading_support: ThreadingSupport,
    /* private fields */
}

A no (network) IO client implementation.

This client is a state machine that receives responses and events and accordingly updates its state. It is not designed to be used directly, but rather through matrix_sdk::Client.

use matrix_sdk_base::{BaseClient, ThreadingSupport, store::StoreConfig};

let client = BaseClient::new(
    StoreConfig::new("cross-process-holder-name".to_owned()),
    ThreadingSupport::Disabled,
);

Fields

room_key_recipient_strategy: CollectStrategy

Available on crate feature e2e-encryption only.

The strategy to use for picking recipient devices, when sending an encrypted message.

decryption_settings: DecryptionSettings

Available on crate feature e2e-encryption only.

The settings to use for decrypting events.

handle_verification_events: bool

Available on crate feature e2e-encryption only.

If the client should handle verification events received when syncing.

threading_support: ThreadingSupport

Whether the client supports threads or not.

Implementations

impl BaseClient

pub fn new(config: StoreConfig, threading_support: ThreadingSupport) -> Self

Create a new client.

Arguments

• config - the configuration for the stores (state store, event cache store and crypto store).

pub async fn clone_with_in_memory_state_store( &self, cross_process_store_locks_holder_name: &str, handle_verification_events: bool, ) -> Result<Self>

Available on crate feature e2e-encryption only.

Clones the current base client to use the same crypto store but a different, in-memory store config, and resets transient state.

pub fn session_meta(&self) -> Option<&SessionMeta>

Get the session meta information.

If the client is currently logged in, this will return a SessionMeta object which contains the user ID and device ID. Otherwise it returns None.

pub fn rooms(&self) -> Vec<Room>

Get all the rooms this client knows about.

pub fn rooms_filtered(&self, filter: RoomStateFilter) -> Vec<Room>

Get all the rooms this client knows about, filtered by room state.

pub fn rooms_stream( &self, ) -> (Vector<Room>, impl Stream<Item = Vec<VectorDiff<Room>>> + use<>)

Get a stream of all the rooms changes, in addition to the existing rooms.

pub fn get_or_create_room( &self, room_id: &RoomId, room_state: RoomState, ) -> Room

Lookup the Room for the given RoomId, or create one, if it didn’t exist yet in the store

pub fn state_store(&self) -> &DynStateStore

Get a reference to the state store.

pub fn event_cache_store(&self) -> &EventCacheStoreLock

Get a reference to the event cache store.

pub fn media_store(&self) -> &MediaStoreLock

Get a reference to the media store.

pub fn is_active(&self) -> bool

Check whether the client has been activated.

See BaseClient::activate to know what it means.

pub async fn activate( &self, session_meta: SessionMeta, room_load_settings: RoomLoadSettings, custom_account: Option<Account>, ) -> Result<()>

Activate the client.

A client is considered active when:

1. It has a SessionMeta (user ID, device ID and access token),
2. Has loaded cached data from storage,
3. If encryption is enabled, it also initialized or restored its OlmMachine.

Arguments

• session_meta - The meta of a session that the user already has from a previous login call.

• custom_account - A custom matrix_sdk_crypto::vodozemac::olm::Account to be used for the identity and one-time keys of this BaseClient. If no account is provided, a new default one or one from the store will be used. If an account is provided and one already exists in the store for this UserId/DeviceId combination, an error will be raised. This is useful if one wishes to create identity keys before knowing the user/device IDs, e.g., to use the identity key as the device ID.

• room_load_settings — Specify how many rooms must be restored; use ::default() if you don’t know which value to pick.

Panics

This method panics if it is called twice.

pub async fn regenerate_olm( &self, custom_account: Option<Account>, ) -> Result<()>

Available on crate feature e2e-encryption only.

Recreate an OlmMachine from scratch.

In particular, this will clear all its caches.

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 room_knocked(&self, room_id: &RoomId) -> Result<Room>

User has knocked on a room.

Update the internal and cached state accordingly. Return the final Room.

pub async fn room_joined( &self, room_id: &RoomId, inviter: Option<OwnedUserId>, ) -> Result<Room>

The user has joined a room using this specific client.

This method should be called if the user accepts an invite or if they join a public room.

The method will create a Room object if one does not exist yet and set the state of the Room to RoomState::Joined. The Room object will be persisted in the cache. Please note that the Room will be a stub until a sync has been received with the full room state using BaseClient::receive_sync_response.

Update the internal and cached state accordingly. Return the final Room.

Arguments

• room_id - The unique ID identifying the joined room.
• inviter - When joining this room in response to an invitation, the inviter should be recorded before sending the join request to the server. Providing the inviter here ensures that the InviteAcceptanceDetails are stored for this room.

Examples

let maybe_inviter = maybe_get_inviter(room_id).await?;
let room_id = send_join_request().await?;
let room = client.room_joined(&room_id, maybe_inviter).await?;

assert_eq!(room.state(), RoomState::Joined);

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

User has left a room.

Update the internal and cached state accordingly.

pub fn sync_lock(&self) -> &Mutex<()>

Get access to the store’s sync lock.

pub async fn receive_sync_response( &self, response: Response, ) -> Result<SyncResponse>

Receive a response from a sync call.

Arguments

• response - The response that we received after a successful sync.

pub async fn receive_sync_response_with_requested_required_states( &self, response: Response, requested_required_states: &RequestedRequiredStates, ) -> Result<SyncResponse>

Receive a response from a sync call, with the requested required state events.

Arguments

• response - The response that we received after a successful sync.
• requested_required_states - The requested required state events.

pub async fn receive_all_members( &self, room_id: &RoomId, request: &Request, response: &Response, ) -> Result<()>

Receive a get member events response and convert it to a deserialized MembersResponse

This client-server request must be made without filters to make sure all members are received. Otherwise, an error is returned.

Arguments

• room_id - The room id this response belongs to.

• response - The raw response that was received from the server.

pub async fn receive_filter_upload( &self, filter_name: &str, response: &Response, ) -> Result<()>

Receive a successful filter upload response, the filter id will be stored under the given name in the store.

The filter id can later be retrieved with the get_filter method.

Arguments

• filter_name - The name that should be used to persist the filter id in the store.

• response - The successful filter upload response containing the filter id.

pub async fn get_filter(&self, filter_name: &str) -> StoreResult<Option<String>>

Get the filter id of a previously uploaded filter.

Note: A filter will first need to be uploaded and persisted using receive_filter_upload.

Arguments

• filter_name - The name of the filter that was previously used to persist the filter.

pub async fn share_room_key( &self, room_id: &RoomId, ) -> Result<Vec<Arc<ToDeviceRequest>>>

Available on crate feature e2e-encryption only.

Get a to-device request that will share a room key with users in a room.

pub fn get_room(&self, room_id: &RoomId) -> Option<Room>

Get the room with the given room id.

Arguments

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

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

Forget the room with the given room ID.

The room will be dropped from the room list and the store.

Arguments

• room_id - The id of the room that should be forgotten.

pub async fn olm_machine(&self) -> RwLockReadGuard<'_, Option<OlmMachine>>

Available on crate feature e2e-encryption only.

Get the olm machine.

pub fn subscribe_to_ignore_user_list_changes(&self) -> Subscriber<Vec<String>>

Returns a subscriber that publishes an event every time the ignore user list changes

pub fn room_info_notable_update_receiver( &self, ) -> Receiver<RoomInfoNotableUpdate>

Returns a new receiver that gets future room info notable updates.

Learn more by reading the RoomInfoNotableUpdate type.

pub async fn is_user_ignored(&self, user_id: &UserId) -> bool

Checks whether the provided user_id belongs to an ignored user.

impl BaseClient

pub async fn process_sliding_sync_e2ee( &self, to_device: Option<&ToDevice>, e2ee: &E2EE, ) -> Result<Option<Vec<ProcessedToDeviceEvent>>>

Available on crate feature e2e-encryption only.

Processes the E2EE-related events from the Sliding Sync response.

In addition to writes to the crypto store, this may also write into the state store, in particular it may write latest-events to the state store.

Returns whether any change happened.

pub async fn process_sliding_sync( &self, response: &Response, requested_required_states: &RequestedRequiredStates, ) -> Result<SyncResponse>

Process a response from a sliding sync call.

Arguments

• response - The response that we received after a successful sliding sync.

Trait Implementations

impl Clone for BaseClient

fn clone(&self) -> BaseClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BaseClient

Available on non-tarpaulin_include only.

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

Formats the value using the given formatter.