diff --git a/matrix_sdk_base/src/lib.rs b/matrix_sdk_base/src/lib.rs index 26041cce..8566c12c 100644 --- a/matrix_sdk_base/src/lib.rs +++ b/matrix_sdk_base/src/lib.rs @@ -29,6 +29,7 @@ //! * `markdown`: Support for sending markdown formatted messages. #![deny( missing_debug_implementations, + missing_docs, trivial_casts, trivial_numeric_casts, unused_extern_crates, diff --git a/matrix_sdk_base/src/store/mod.rs b/matrix_sdk_base/src/store/mod.rs index a96b40d4..de87554b 100644 --- a/matrix_sdk_base/src/store/mod.rs +++ b/matrix_sdk_base/src/store/mod.rs @@ -78,19 +78,48 @@ pub enum StoreError { /// A `StateStore` specific result type. pub type Result = std::result::Result; +/// An abstract state store trait that can be used to implement different stores +/// for the SDK. #[cfg_attr(target_arch = "wasm32", async_trait(?Send))] #[cfg_attr(not(target_arch = "wasm32"), async_trait)] pub trait StateStore: AsyncTraitDeps { + /// Save the given filter id under the given name. + /// + /// # Arguments + /// + /// * `filter_name` - The name that should be used to store the filter id. + /// + /// * `filter_id` - The filter id that should be stored in the state store. async fn save_filter(&self, filter_name: &str, filter_id: &str) -> Result<()>; + /// Save the set of state changes in the store. async fn save_changes(&self, changes: &StateChanges) -> Result<()>; - async fn get_filter(&self, filter_id: &str) -> Result>; + /// Get the filter id that was stored under the given filter name. + /// + /// # Arguments + /// + /// * `filter_name` - The name that was used to store the filter id. + async fn get_filter(&self, filter_name: &str) -> Result>; + /// Get the last stored sync token. async fn get_sync_token(&self) -> Result>; + /// Get the stored presence event for the given user. + /// + /// # Arguments + /// + /// * `user_id` - The id of the user for which we wish to fetch the presence + /// event for. async fn get_presence_event(&self, user_id: &UserId) -> Result>; + /// Get a state event out of the state store. + /// + /// # Arguments + /// + /// * `room_id` - The id of the room the state event was received for. + /// + /// * `event_type` - The event type of the state event. async fn get_state_event( &self, room_id: &RoomId, @@ -98,26 +127,54 @@ pub trait StateStore: AsyncTraitDeps { state_key: &str, ) -> Result>; + /// Get the current profile for the given user in the given room. + /// + /// # Arguments + /// + /// * `room_id` - The room id the profile is used in. + /// + /// * `user_id` - The id of the user the profile belongs to. async fn get_profile( &self, room_id: &RoomId, user_id: &UserId, ) -> Result>; + /// Get a raw `MemberEvent` for the given state key in the given room id. + /// + /// # Arguments + /// + /// * `room_id` - The room id the member event belongs to. + /// + /// * `state_key` - The user id that the member event defines the state for. async fn get_member_event( &self, room_id: &RoomId, state_key: &UserId, ) -> Result>; + /// Get all the user ids of members that are in the invited state for a + /// given room. async fn get_invited_user_ids(&self, room_id: &RoomId) -> Result>; + /// Get all the user ids of members that are in the joined state for a + /// given room. async fn get_joined_user_ids(&self, room_id: &RoomId) -> Result>; + /// Get all the pure `RoomInfo`s the store knows about. async fn get_room_infos(&self) -> Result>; + /// Get all the pure `StrippedRoomInfo`s the store knows about. async fn get_stripped_room_infos(&self) -> Result>; + /// Get all the users that use the given display name in the given room. + /// + /// # Arguments + /// + /// * `room_id` - The id of the room for which the display name users should + /// be fetched for. + /// + /// * `display_name` - The display name that the users use. async fn get_users_with_display_name( &self, room_id: &RoomId, @@ -125,6 +182,10 @@ pub trait StateStore: AsyncTraitDeps { ) -> Result>; } +/// A state store wrapper for the SDK. +/// +/// This adds additional higher level store functionality on top of a +/// `StateStore` implementation. #[derive(Debug, Clone)] pub struct Store { inner: Arc>, @@ -174,6 +235,14 @@ impl Store { Self::new(inner) } + /// Open the default Sled store. + /// + /// # Arguments + /// + /// * `path` - The path where the store should reside in. + /// + /// * `passphrase` - A passphrase that should be used to encrypt the state + /// store. #[cfg(feature = "sled_state_store")] pub fn open_default(path: impl AsRef, passphrase: Option<&str>) -> Result<(Self, Db)> { let inner = if let Some(passphrase) = passphrase { @@ -197,6 +266,7 @@ impl Store { self.rooms.get(room_id).map(|r| r.clone()) } + /// Get all the rooms this store knows about. pub fn get_rooms(&self) -> Vec { self.rooms .iter() @@ -204,18 +274,36 @@ impl Store { .collect() } + /// Get the joined room with the given room id. + /// + /// *Note*: A room with the given id might exist in a different state, this + /// will only return the room if it's in the joined state. pub fn get_joined_room(&self, room_id: &RoomId) -> Option { self.get_room(room_id).and_then(|r| r.joined()) } + /// Get the joined room with the given room id. + /// + /// *Note*: A room with the given id might exist in a different state, this + /// will only return the room if it's in the invited state. pub fn get_invited_room(&self, room_id: &RoomId) -> Option { self.get_room(room_id).and_then(|r| r.invited()) } + /// Get the joined room with the given room id. + /// + /// *Note*: A room with the given id might exist in a different state, this + /// will only return the room if it's in the left state. pub fn get_left_room(&self, room_id: &RoomId) -> Option { self.get_room(room_id).and_then(|r| r.left()) } + /// Get the room with the given room id. + /// + /// *Note*: This will return the room in the `RoomState` enum, a room might + /// turn from an invited room to a joined one between sync requests, this + /// room struct might have stale info in that case and a new one should be + /// pulled out of the store. pub fn get_room(&self, room_id: &RoomId) -> Option { self.get_bare_room(room_id) .and_then(|r| match r.room_type() {