char/matrix-rust-sdk
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

rust-sdk: Cleanup the docs and fix the examples up.

Browse source
This commit is contained in:
Damir Jelić 2020-03-02 11:31:03 +01:00
parent de154e272a
commit c41d3873b6
4 changed files with 98 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Cargo.toml
View file

@ -35,6 +35,6 @@ cjson = { version = "0.1.0", optional = true }
[dev-dependencies]
tokio = { version = "0.2.11", features = ["full"] }
async-std = { version = "1.5.0", features = ["attributes"] }
async-std = { version = "1.5.0", features = ["unstable", "attributes"] }
url = "2.1.1"
mockito = "0.23.3"

75
src/async_client.rs
View file

@ -67,10 +67,9 @@ pub struct AsyncClient {
/// # Example
///
/// ```
/// # use matrix_sdk::AsyncClientConfig;
/// // To pass all the request through mitmproxy set the proxy and disable SSL
/// // verification
/// use matrix_sdk::AsyncClientConfig;
///
/// let client_config = AsyncClientConfig::new()
/// .proxy("http://localhost:8080")
/// .unwrap()
@ -265,7 +264,17 @@ impl AsyncClient {
/// received.
///
/// # Examples
/// ```noexecute
/// ```
/// # use matrix_sdk::events::{
/// # collections::all::RoomEvent,
/// # room::message::{MessageEvent, MessageEventContent, TextMessageEventContent},
/// # EventResult,
/// # };
/// # use matrix_sdk::Room;
/// # use std::sync::{Arc, RwLock};
/// # use matrix_sdk::AsyncClient;
/// # use url::Url;
///
/// async fn async_cb(room: Arc<RwLock<Room>>, event: Arc<EventResult<RoomEvent>>) {
/// let room = room.read().unwrap();
/// let event = if let EventResult::Ok(event) = &*event {
@ -287,11 +296,15 @@ impl AsyncClient {
/// );
/// }
/// }
/// # fn main() -> Result<(), matrix_sdk::Error> {
/// let homeserver = Url::parse("http://localhost:8080")?;
///
/// async fn main(client: AsyncClient) {
/// client.add_event_callback(async_cb);
/// }
///```
/// let mut client = AsyncClient::new(homeserver, None)?;
///
/// client.add_event_callback(async_cb);
/// # Ok(())
/// # }
/// ```
pub fn add_event_callback<C: 'static>(
&mut self,
mut callback: impl FnMut(Arc<RwLock<Room>>, Arc<EventResult<RoomEvent>>) -> C + 'static + Send,
@ -309,9 +322,11 @@ impl AsyncClient {
///
/// # 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
/// * `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 exising
/// device_id from a previous login call. Note that this should be done
/// only if the client also holds the encryption keys for this devcie.
@ -408,6 +423,7 @@ impl AsyncClient {
///
/// * `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.
///
@ -417,16 +433,35 @@ impl AsyncClient {
/// the interesting events through a mpsc channel to another thread e.g. a
/// UI thread.
///
/// ```noexecute
/// ```compile_fail,E0658
/// # use matrix_sdk::events::{
/// # collections::all::RoomEvent,
/// # room::message::{MessageEvent, MessageEventContent, TextMessageEventContent},
/// # EventResult,
/// # };
/// # use matrix_sdk::Room;
/// # use std::sync::{Arc, RwLock};
/// # use matrix_sdk::{AsyncClient, SyncSettings};
/// # use url::Url;
/// # use futures::executor::block_on;
/// # block_on(async {
/// # let homeserver = Url::parse("http://localhost:8080").unwrap();
/// # let mut client = AsyncClient::new(homeserver, None).unwrap();
///
/// use async_std::sync::channel;
///
/// let (tx, rx) = channel(100);
///
/// let sync_channel = &tx;
/// let sync_settings = SyncSettings::new()
/// .timeout(30_000)
/// .unwrap();
///
/// client
/// .sync_forever(sync_settings, async move |response| {
/// let channel = sync_channel;
///
/// for (room_id, room) in response.rooms.join {
/// for event in room.state.events {
/// if let EventResult::Ok(e) = event {
/// channel.send(e).await;
/// }
/// }
/// for event in room.timeline.events {
/// if let EventResult::Ok(e) = event {
/// channel.send(e).await;
@ -435,6 +470,7 @@ impl AsyncClient {
/// }
/// })
/// .await;
/// })
/// ```
pub async fn sync_forever<C>(
&mut self,
@ -542,12 +578,13 @@ impl AsyncClient {
/// Send a room message to the homeserver.
///
/// Returns the parsed response from the server.
///
/// # Arguments
///
/// `room_id` - The id of the room that should receive the message.
/// `data` - The content of the message.
/// * `room_id` - The id of the room that should receive the message.
///
/// Returns the parsed response from the server.
/// * `data` - The content of the message.
pub async fn room_send(
&mut self,
room_id: &str,

46
src/base_client.rs
View file

@ -58,9 +58,11 @@ pub struct Room {
impl Room {
/// Create a new room.
///
/// # Arguments
///
/// * `room_id` - The unique id of the room.
///
/// * `own_user_id` - The mxid of our own user.
pub fn new(room_id: &str, own_user_id: &str) -> Self {
Room {
@ -137,11 +139,12 @@ impl Room {
}
/// Receive a timeline event for this room and update the room state.
/// # Arguments
///
/// `event` - The event of the room.
///
/// Returns true if the joined member list changed, false otherwise.
///
/// # Arguments
///
/// * `event` - The event of the room.
pub fn receive_timeline_event(&mut self, event: &RoomEvent) -> bool {
match event {
RoomEvent::RoomMember(m) => self.handle_membership(m),
@ -150,11 +153,12 @@ impl Room {
}
/// Receive a state event for this room and update the room state.
/// # Arguments
///
/// `event` - The event of the room.
///
/// Returns true if the joined member list changed, false otherwise.
///
/// # Arguments
///
/// * `event` - The event of the room.
pub fn receive_state_event(&mut self, event: &StateEvent) -> bool {
match event {
StateEvent::RoomMember(m) => self.handle_membership(m),
@ -180,9 +184,10 @@ pub struct Client {
impl Client {
/// Create a new client.
///
/// # Arguments
///
/// `session` - An optional session if the user already has one from a
/// * `session` - An optional session if the user already has one from a
/// previous login call.
pub fn new(session: Option<Session>) -> Self {
Client {
@ -198,9 +203,10 @@ impl Client {
}
/// Receive a login response and update the session of the client.
///
/// # Arguments
///
/// `response` - A successful login response that contains our access token
/// * `response` - A successful login response that contains our access token
/// and device id.
pub fn receive_login_response(&mut self, response: &api::session::login::Response) {
let session = Session {
@ -228,13 +234,14 @@ impl Client {
/// Receive a timeline event for a joined room and update the client state.
///
/// # Arguments
///
/// `room_id` - The unique id of the room the event belongs to.
/// `event` - The event that should be handled by the client.
///
/// Returns true if the membership list of the room changed, false
/// otherwise.
///
/// # Arguments
///
/// * `room_id` - The unique id of the room the event belongs to.
///
/// * `event` - The event that should be handled by the client.
pub fn receive_joined_timeline_event(
&mut self,
room_id: &str,
@ -251,13 +258,14 @@ impl Client {
/// Receive a state event for a joined room and update the client state.
///
/// # Arguments
///
/// `room_id` - The unique id of the room the event belongs to.
/// `event` - The event that should be handled by the client.
///
/// Returns true if the membership list of the room changed, false
/// otherwise.
///
/// # Arguments
///
/// * `room_id` - The unique id of the room the event belongs to.
///
/// * `event` - The event that should be handled by the client.
pub fn receive_joined_state_event(&mut self, room_id: &str, event: &StateEvent) -> bool {
let mut room = self.get_or_create_room(room_id).write().unwrap();
room.receive_state_event(event)
@ -267,7 +275,7 @@ impl Client {
///
/// # Arguments
///
/// `response` - The response that we received after a successful sync.
/// * `response` - The response that we received after a successful sync.
pub fn receive_sync_response(&mut self, response: &api::sync::sync_events::IncomingResponse) {
self.sync_token = Some(response.next_batch.clone());
}

19
src/crypto/machine.rs
View file

@ -80,7 +80,7 @@ impl OlmMachine {
///
/// # Arguments
///
/// `response` - The keys upload response of the request that the client
/// * `response` - The keys upload response of the request that the client
/// performed.
pub async fn receive_keys_upload_response(&mut self, response: &keys::upload_keys::Response) {
self.account.shared = true;
@ -186,7 +186,13 @@ impl OlmMachine {
Ok(one_time_key_map)
}
/// Convert a JSON value to the canonical representation and sign the JSON string.
/// Convert a JSON value to the canonical representation and sign the JSON
/// string.
///
/// # Arguments
///
/// * `json` - The value that should be converted into a canonical JSON
/// string.
fn sign_json(&self, json: &Value) -> String {
let canonical_json = cjson::to_string(json)
.unwrap_or_else(|_| panic!(format!("Can't serialize {} to canonical JSON", json)));
@ -198,16 +204,19 @@ impl OlmMachine {
/// The object must have a signatures key associated with an object of the
/// form `user_id: {key_id: signature}`.
///
/// Returns Ok if the signature was successfully verified, otherwise an
/// SignatureError.
///
/// # Arguments
///
/// * `user_id` - The user who signed the JSON object.
///
/// * `device_id` - The device that signed the JSON object.
///
/// * `user_key` - The public ed25519 key which was used to sign the JSON
/// object.
/// * `json` - The JSON object that should be verified.
///
/// Returns Ok if the signature was successfully verified, otherwise an
/// SignatureError.
/// * `json` - The JSON object that should be verified.
fn verify_json(
&self,
user_id: &str,