Struct Timeline

pub struct Timeline { /* private fields */ }

A high-level view into a regular¹ room’s contents.

¹ This type is meant to be used in the context of rooms without a room_type, that is rooms that are primarily used to exchange text messages.

Implementations

impl Timeline

pub async fn paginate_backwards(&self, num_events: u16) -> Result<bool, Error>

Add more events to the start of the timeline.

Returns whether we hit the start of the timeline.

pub async fn focused_paginate_forwards( &self, num_events: u16, ) -> Result<bool, Error>

Assuming the timeline is focused on an event, starts a forwards pagination.

Returns whether we hit the end of the timeline.

pub async fn focused_paginate_backwards( &self, num_events: u16, ) -> Result<bool, Error>

Assuming the timeline is focused on an event, starts a backwards pagination.

Returns whether we hit the start of the timeline.

pub async fn live_paginate_backwards(&self, batch_size: u16) -> Result<bool>

Paginate backwards in live mode.

This can only be called when the timeline is in live mode, not focused on a specific event.

Returns whether we hit the start of the timeline.

pub async fn live_back_pagination_status( &self, ) -> Option<(LiveBackPaginationStatus, impl Stream<Item = LiveBackPaginationStatus>)>

Subscribe to the back-pagination status of a live timeline.

This will return None if the timeline is in the focused mode.

Note: this may send multiple Paginating/Idle sequences during a single call to Self::paginate_backwards().

impl Timeline

pub fn builder(room: &Room) -> TimelineBuilder

Create a new TimelineBuilder for the given room.

pub fn room(&self) -> &Room

Returns the room for this timeline.

pub async fn clear(&self)

Clear all timeline items.

pub async fn retry_decryption<S: Into<String>>( &self, session_ids: impl IntoIterator<Item = S>, )

Retry decryption of previously un-decryptable events given a list of session IDs whose keys have been imported.

Examples

let path = PathBuf::from("/home/example/e2e-keys.txt");
let result =
    client.encryption().import_room_keys(path, "secret-passphrase").await?;

// Given a timeline for a specific room_id
if let Some(keys_for_users) = result.keys.get(room_id) {
    let session_ids = keys_for_users.values().flatten();
    timeline.retry_decryption(session_ids).await;
}

pub async fn item_by_event_id( &self, event_id: &EventId, ) -> Option<EventTimelineItem>

Get the current timeline item for the given event ID, if any.

Will return a remote event, or a local echo that has been sent but not yet replaced by a remote echo.

It’s preferable to store the timeline items in the model for your UI, if possible, instead of just storing IDs and coming back to the timeline object to look up items.

pub async fn latest_event(&self) -> Option<EventTimelineItem>

Get the latest of the timeline’s event items.

pub async fn subscribe( &self, ) -> (Vector<Arc<TimelineItem>>, impl Stream<Item = VectorDiff<Arc<TimelineItem>>>)

Get the current timeline items, and a stream of changes.

You can poll this stream to receive updates. See futures_util::StreamExt for a high-level API on top of Stream.

pub async fn subscribe_batched( &self, ) -> (Vector<Arc<TimelineItem>>, impl Stream<Item = Vec<VectorDiff<Arc<TimelineItem>>>>)

Get the current timeline items, and a batched stream of changes.

In contrast to subscribe, this stream can yield multiple diffs at once. The batching is done such that no arbitrary delays are added.

pub async fn send( &self, content: AnyMessageLikeEventContent, ) -> Result<SendHandle, RoomSendQueueError>

Send a message to the room, and add it to the timeline as a local echo.

For simplicity, this method doesn’t currently allow custom message types.

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

If sending the message fails, the local echo item will change its send_state to EventSendState::SendingFailed.

Arguments

• content - The content of the message event.

pub async fn send_reply( &self, content: RoomMessageEventContentWithoutRelation, replied_to_info: RepliedToInfo, forward_thread: ForwardThread, ) -> Result<(), RoomSendQueueError>

Send a reply to the given event.

Currently it only supports events with an event ID and JSON being available (which can be removed by local redactions). This is subject to change. Please check EventTimelineItem::can_be_replied_to to decide whether to render a reply button.

The sender will be added to the mentions of the reply if and only if the event has not been written by the sender.

Arguments

• content - The content of the reply

• replied_to_info - A wrapper that contains the event ID, sender, content and timestamp of the event to reply to

• forward_thread - Usually Yes, unless you explicitly want to the reply to show up in the main timeline even though the reply_item is part of a thread

pub async fn replied_to_info_from_event_id( &self, event_id: &EventId, ) -> Result<RepliedToInfo, UnsupportedReplyItem>

Get the information needed to reply to the event with the given ID.

pub async fn edit( &self, item_id: &TimelineEventItemId, new_content: EditedContent, ) -> Result<(), Error>

Edit an event given its TimelineEventItemId and some new content.

Only supports events for which EventTimelineItem::is_editable() returns true.

pub async fn toggle_reaction( &self, item_id: &TimelineEventItemId, reaction_key: &str, ) -> Result<(), Error>

Toggle a reaction on an event.

Adds or redacts a reaction based on the state of the reaction at the time it is called.

When redacting a previous reaction, the redaction reason is not set.

Ensures that only one reaction is sent at a time to avoid race conditions and spamming the homeserver with requests.

pub fn send_attachment( &self, path: impl Into<PathBuf>, mime_type: Mime, config: AttachmentConfig, ) -> SendAttachment<'_>

Sends an attachment to the room.

It does not currently support local echoes.

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

The attachment and its optional thumbnail are stored in the media cache and can be retrieved at any time, by calling Media::get_media_content() with the MediaSource that can be found in the corresponding TimelineEventItem, and using a MediaFormat::File.

Arguments

• path - The path of the file to be sent.

• mime_type - The attachment’s mime type.

• config - An attachment configuration object containing details about the attachment like a thumbnail, its size, duration etc.

pub async fn redact( &self, item_id: &TimelineEventItemId, reason: Option<&str>, ) -> Result<(), Error>

Redact an event given its TimelineEventItemId and an optional reason.

pub async fn fetch_details_for_event( &self, event_id: &EventId, ) -> Result<(), Error>

Fetch unavailable details about the event with the given ID.

This method only works for IDs of remote EventTimelineItems, to prevent losing details when a local echo is replaced by its remote echo.

This method tries to make all the requests it can. If an error is encountered for a given request, it is forwarded with the TimelineDetails::Error variant.

Arguments

• event_id - The event ID of the event to fetch details for.

Errors

Returns an error if the identifier doesn’t match any event with a remote echo in the timeline, or if the event is removed from the timeline before all requests are handled.

pub async fn fetch_members(&self)

Fetch all member events for the room this timeline is displaying.

If the full member list is not known, sender profiles are currently likely not going to be available. This will be fixed in the future.

If fetching the members fails, any affected timeline items will have the sender_profile set to TimelineDetails::Error.

pub async fn latest_user_read_receipt( &self, user_id: &UserId, ) -> Option<(OwnedEventId, Receipt)>

Get the latest read receipt for the given user.

Contrary to Room::load_user_receipt() that only keeps track of read receipts received from the homeserver, this keeps also track of implicit read receipts in this timeline, i.e. when a room member sends an event.

pub async fn latest_user_read_receipt_timeline_event_id( &self, user_id: &UserId, ) -> Option<OwnedEventId>

Get the ID of the timeline event with the latest read receipt for the given user.

In contrary to Self::latest_user_read_receipt(), this allows to know the position of the read receipt in the timeline even if the event it applies to is not visible in the timeline, unless the event is unknown by this timeline.

pub async fn subscribe_own_user_read_receipts_changed( &self, ) -> impl Stream<Item = ()>

Subscribe to changes in the read receipts of our own user.

pub async fn send_single_receipt( &self, receipt_type: ReceiptType, thread: ReceiptThread, event_id: OwnedEventId, ) -> Result<bool>

Send the given receipt.

This uses Room::send_single_receipt internally, but checks first if the receipt points to an event in this timeline that is more recent than the current ones, to avoid unnecessary requests.

Returns a boolean indicating if it sent the request or not.

pub async fn send_multiple_receipts(&self, receipts: Receipts) -> Result<()>

Send the given receipts.

This uses Room::send_multiple_receipts internally, but checks first if the receipts point to events in this timeline that are more recent than the current ones, to avoid unnecessary requests.

pub async fn mark_as_read(&self, receipt_type: ReceiptType) -> Result<bool>

Mark the room as read by sending an unthreaded read receipt on the latest event, be it visible or not.

This works even if the latest event belongs to a thread, as a threaded reply also belongs to the unthreaded timeline. No threaded receipt will be sent here (see also #3123).

Returns a boolean indicating if we sent the request or not.

pub async fn pin_event(&self, event_id: &EventId) -> Result<bool>

Adds a new pinned event by sending an updated m.room.pinned_events event containing the new event id.

This method will first try to get the pinned events from the current room’s state and if it fails to do so it’ll try to load them from the homeserver.

Returns true if we pinned the event, false if the event was already pinned.

pub async fn unpin_event(&self, event_id: &EventId) -> Result<bool>

Removes a pinned event by sending an updated m.room.pinned_events event without the event id we want to remove.

This method will first try to get the pinned events from the current room’s state and if it fails to do so it’ll try to load them from the homeserver.

Returns true if we unpinned the event, false if the event wasn’t pinned before.

Trait Implementations

impl Debug for Timeline

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

Formats the value using the given formatter.