rename RoomMessageBuilder, make examp build, expand on docs

master
Devin R 2020-04-14 06:36:03 -04:00
parent 1a7856e9fe
commit e64d073402
3 changed files with 74 additions and 58 deletions

View File

@ -350,8 +350,7 @@ impl AsyncClient {
/// ///
/// # Arguments /// # Arguments
/// ///
/// * room_id - A valid RoomId otherwise sending will fail. /// * room_id - The `RoomId` of the room to be joined.
///
pub async fn join_room_by_id(&mut self, room_id: &RoomId) -> Result<join_room_by_id::Response> { pub async fn join_room_by_id(&mut self, room_id: &RoomId) -> Result<join_room_by_id::Response> {
let request = join_room_by_id::Request { let request = join_room_by_id::Request {
room_id: room_id.clone(), room_id: room_id.clone(),
@ -367,8 +366,8 @@ impl AsyncClient {
/// ///
/// # Arguments /// # Arguments
/// ///
/// * alias - A valid `RoomIdOrAliasId` otherwise sending will fail. /// * alias - The `RoomId` or `RoomAliasId` of the room to be joined.
/// /// An alias looks like this `#name:example.com`
pub async fn join_room_by_id_or_alias( pub async fn join_room_by_id_or_alias(
&mut self, &mut self,
alias: &RoomIdOrAliasId, alias: &RoomIdOrAliasId,
@ -386,12 +385,11 @@ impl AsyncClient {
/// ///
/// # Arguments /// # Arguments
/// ///
/// * room_id - A valid `RoomId` otherwise sending will fail. /// * room_id - The `RoomId` of the room the user should be kicked out of.
/// ///
/// * user_id - A valid `UserId`. /// * 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. /// * reason - Optional reason why the room member is being kicked out.
///
pub async fn kick_user( pub async fn kick_user(
&mut self, &mut self,
room_id: &RoomId, room_id: &RoomId,
@ -412,7 +410,7 @@ impl AsyncClient {
/// ///
/// # Arguments /// # Arguments
/// ///
/// * room_id - A valid `RoomId`. /// * room_id - The `RoomId` of the room to leave.
/// ///
pub async fn leave_room(&mut self, room_id: &RoomId) -> Result<leave_room::Response> { pub async fn leave_room(&mut self, room_id: &RoomId) -> Result<leave_room::Response> {
let request = leave_room::Request { let request = leave_room::Request {
@ -427,10 +425,9 @@ impl AsyncClient {
/// ///
/// # Arguments /// # Arguments
/// ///
/// * room_id - A valid `RoomId`. /// * room_id - The `RoomId` of the room to invite the specified user to.
///
/// * user_id - A valid `UserId`.
/// ///
/// * user_id - The `UserId` of the user to invite to the room.
pub async fn invite_user_by_id( pub async fn invite_user_by_id(
&mut self, &mut self,
room_id: &RoomId, room_id: &RoomId,
@ -451,10 +448,9 @@ impl AsyncClient {
/// ///
/// # Arguments /// # Arguments
/// ///
/// * room_id - A valid `RoomId`. /// * room_id - The `RoomId` of the room to invite the specified user to.
///
/// * invite_id - A valid `UserId`.
/// ///
/// * invite_id - A third party id of a user to invite to the room.
pub async fn invite_user_by_3pid( pub async fn invite_user_by_3pid(
&mut self, &mut self,
room_id: &RoomId, room_id: &RoomId,
@ -467,18 +463,22 @@ impl AsyncClient {
self.send(request).await self.send(request).await
} }
/// A builder to create a room and send the request. /// Create a room using the `RoomBuilder` and send the request.
/// ///
/// Returns a `create_room::Response`, an empty response. /// Sends a request to `/_matrix/client/r0/createRoom`, returns a `create_room::Response`,
/// this is an empty response.
/// ///
/// # Arguments /// # Arguments
/// ///
/// * room - the easiest way to create this request is using the `RoomBuilder`. /// * room - The easiest way to create this request is using the `RoomBuilder`.
/// ///
/// # Examples /// # Examples
/// ```ignore /// ```no_run
/// use matrix_sdk::{AsyncClient, RoomBuilder}; /// use matrix_sdk::{AsyncClient, RoomBuilder};
/// # use matrix_sdk::api::r0::room::Visibility;
/// # use url::Url;
/// ///
/// # let homeserver = Url::parse("http://example.com").unwrap();
/// let mut builder = RoomBuilder::default(); /// let mut builder = RoomBuilder::default();
/// builder.creation_content(false) /// builder.creation_content(false)
/// .initial_state(vec![]) /// .initial_state(vec![])
@ -486,10 +486,12 @@ impl AsyncClient {
/// .name("name") /// .name("name")
/// .room_version("v1.0"); /// .room_version("v1.0");
/// ///
/// let mut cli = AsyncClient::new(homeserver, Some(session)).unwrap(); /// let mut cli = AsyncClient::new(homeserver, None).unwrap();
/// # use futures::executor::block_on;
/// # block_on(async {
/// assert!(cli.create_room(builder).await.is_ok()); /// assert!(cli.create_room(builder).await.is_ok());
/// # });
/// ``` /// ```
///
pub async fn create_room<R: Into<create_room::Request>>( pub async fn create_room<R: Into<create_room::Request>>(
&mut self, &mut self,
room: R, room: R,
@ -498,27 +500,41 @@ impl AsyncClient {
self.send(request).await self.send(request).await
} }
/// Invite the specified user by third party id to the given room. /// Get messages starting at a specific sync point using the
/// `MessagesRequestBuilder`s `from` field as a starting point.
/// ///
/// Returns a `invite_user::Response`, an empty response. /// Sends a request to `/_matrix/client/r0/rooms/{room_id}/messages` and
/// returns a `get_message_events::IncomingResponse` that contains chunks
/// of `RoomEvents`.
/// ///
/// # Arguments /// # Arguments
/// ///
/// * request - The easiest way to create a `Request` is using the `GetMessageBuilder` /// * request - The easiest way to create a `Request` is using the
/// `MessagesRequestBuilder`.
/// ///
/// # Examples /// # Examples
/// ```ignore /// ```no_run
/// use matrix_sdk::{AsyncClient, RoomBuilder}; /// # use std::convert::TryFrom;
/// use matrix_sdk::{AsyncClient, MessagesRequestBuilder};
/// # use matrix_sdk::identifiers::RoomId;
/// # use matrix_sdk::api::r0::filter::RoomEventFilter;
/// # use matrix_sdk::api::r0::message::get_message_events::Direction;
/// # use url::Url;
/// # use js_int::UInt;
/// ///
/// let mut builder = RoomMessageBuilder::new(); /// # let homeserver = Url::parse("http://example.com").unwrap();
/// let mut builder = MessagesRequestBuilder::new();
/// builder.room_id(RoomId::try_from("!roomid:example.com").unwrap()) /// builder.room_id(RoomId::try_from("!roomid:example.com").unwrap())
/// .from("t47429-4392820_219380_26003_2265".to_string()) /// .from("t47429-4392820_219380_26003_2265".to_string())
/// .to("t4357353_219380_26003_2265".to_string()) /// .to("t4357353_219380_26003_2265".to_string())
/// .direction(Direction::Backward) /// .direction(Direction::Backward)
/// .limit(UInt::new(10).unwrap()); /// .limit(UInt::new(10).unwrap());
/// ///
/// let mut cli = AsyncClient::new(homeserver, Some(session)).unwrap(); /// let mut cli = AsyncClient::new(homeserver, None).unwrap();
/// assert!(cli.create_room(builder).await.is_ok()); /// # use futures::executor::block_on;
/// # block_on(async {
/// assert!(cli.room_messages(builder).await.is_ok());
/// # });
/// ``` /// ```
pub async fn room_messages<R: Into<get_message_events::Request>>( pub async fn room_messages<R: Into<get_message_events::Request>>(
&mut self, &mut self,

View File

@ -51,6 +51,6 @@ pub use async_client::{AsyncClient, AsyncClientConfig, SyncSettings};
pub use base_client::Client; pub use base_client::Client;
pub use event_emitter::EventEmitter; pub use event_emitter::EventEmitter;
pub use models::Room; pub use models::Room;
pub use request_builder::{RoomBuilder, RoomMessageBuilder}; pub use request_builder::{RoomBuilder, MessagesRequestBuilder};
pub(crate) const VERSION: &str = env!("CARGO_PKG_VERSION"); pub(crate) const VERSION: &str = env!("CARGO_PKG_VERSION");

View File

@ -174,8 +174,30 @@ impl Into<create_room::Request> for RoomBuilder {
} }
/// Create a builder for making get_message_event requests. /// Create a builder for making get_message_event requests.
///
/// # Examples
/// ```
/// # use matrix_sdk::{AsyncClient, MessagesRequestBuilder};
/// # use matrix_sdk::api::r0::message::get_message_events::{self, Direction};
/// # use matrix_sdk::identifiers::RoomId;
/// # use url::Url;
/// # let homeserver = Url::parse("http://example.com").unwrap();
/// # let mut rt = tokio::runtime::Runtime::new().unwrap();
/// # rt.block_on(async {
/// # let room_id = RoomId::new(homeserver.as_str()).unwrap();
/// # let last_sync_token = "".to_string();;
/// let mut cli = AsyncClient::new(homeserver, None).unwrap();
///
/// let mut builder = MessagesRequestBuilder::new();
/// builder.room_id(room_id)
/// .from(last_sync_token)
/// .direction(Direction::Forward);
///
/// cli.room_messages(builder).await.is_err();
/// # })
/// ```
#[derive(Clone, Default)] #[derive(Clone, Default)]
pub struct RoomMessageBuilder { pub struct MessagesRequestBuilder {
/// The room to get events from. /// The room to get events from.
room_id: Option<RoomId>, room_id: Option<RoomId>,
/// The token to start returning events from. /// The token to start returning events from.
@ -200,32 +222,10 @@ pub struct RoomMessageBuilder {
filter: Option<RoomEventFilter>, filter: Option<RoomEventFilter>,
} }
impl RoomMessageBuilder { impl MessagesRequestBuilder {
/// Create a `RoomMessageBuilder` builder to make a `get_message_events::Request`. /// Create a `MessagesRequestBuilder` builder to make a `get_message_events::Request`.
/// ///
/// The `room_id` and `from`` fields **need to be set** to create the request. /// The `room_id` and `from`` fields **need to be set** to create the request.
///
/// # Examples
/// ```
/// # use matrix_sdk::{AsyncClient, RoomMessageBuilder};
/// # use matrix_sdk::api::r0::message::get_message_events::{self, Direction};
/// # use matrix_sdk::identifiers::RoomId;
/// # use url::Url;
/// # let homeserver = Url::parse("http://example.com").unwrap();
/// # let mut rt = tokio::runtime::Runtime::new().unwrap();
/// # rt.block_on(async {
/// # let room_id = RoomId::new(homeserver.as_str()).unwrap();
/// # let last_sync_token = "".to_string();;
/// let mut cli = AsyncClient::new(homeserver, None).unwrap();
///
/// let mut builder = RoomMessageBuilder::new();
/// builder.room_id(room_id)
/// .from(last_sync_token)
/// .direction(Direction::Forward);
///
/// cli.room_messages(builder).await.is_err();
/// # })
/// ```
pub fn new() -> Self { pub fn new() -> Self {
Self::default() Self::default()
} }
@ -273,7 +273,7 @@ impl RoomMessageBuilder {
} }
} }
impl Into<get_message_events::Request> for RoomMessageBuilder { impl Into<get_message_events::Request> for MessagesRequestBuilder {
fn into(self) -> get_message_events::Request { fn into(self) -> get_message_events::Request {
get_message_events::Request { get_message_events::Request {
room_id: self.room_id.expect("`room_id` and `from` need to be set"), room_id: self.room_id.expect("`room_id` and `from` need to be set"),
@ -363,7 +363,7 @@ mod test {
device_id: "DEVICEID".to_owned(), device_id: "DEVICEID".to_owned(),
}; };
let mut builder = RoomMessageBuilder::new(); let mut builder = MessagesRequestBuilder::new();
builder builder
.room_id(RoomId::try_from("!roomid:example.com").unwrap()) .room_id(RoomId::try_from("!roomid:example.com").unwrap())
.from("t47429-4392820_219380_26003_2265".to_string()) .from("t47429-4392820_219380_26003_2265".to_string())