Crate ruma_client

Crate ruma_client is a Matrix client library.

Usage

Begin by creating a Client type, usually using the https method for a client that supports secure connections, and then logging in:

use ruma_client::Client;

let work = async {
    let homeserver_url = "https://example.com".parse().unwrap();
    let client = Client::https(homeserver_url, None);

    let session = client
        .log_in("@alice:example.com".to_string(), "secret".to_string(), None, None)
        .await?;

    // You're now logged in! Write the session to a file if you want to restore it later.
    // Then start using the API!
};

You can also pass an existing session to the Client constructor to restore a previous session rather than calling log_in. This can also be used to create a session for an application service that does not need to log in, but uses the access_token directly:

use ruma_client::{Client, Session};

let work = async {
    let homeserver_url = "https://example.com".parse().unwrap();
    let session = Session{access_token: "as_access_token".to_string(), identification: None};
    let client = Client::https(homeserver_url, Some(session));

    // make calls to the API
};

For the standard use case of synchronizing with the homeserver (i.e. getting all the latest events), use the Client::sync:

use std::time::Duration;

let mut sync_stream = Box::pin(client.sync(
    None,
    Some(next_batch_token),
    SetPresence::Online,
    Some(Duration::from_secs(30)),
));
while let Some(response) = sync_stream.try_next().await? {
    // Do something with the data in the response...
}

The Client type also provides methods for registering a new account if you don't already have one with the given homeserver.

Beyond these basic convenience methods, ruma-client gives you access to the entire Matrix client-server API via the api module. Each leaf module under this tree of modules contains the necessary types for one API endpoint. Simply call the module's call method, passing it the logged in Client and the relevant Request type. call will return a future that will resolve to the relevant Response type.

For example:

use std::convert::TryFrom;

use ruma_client::api::r0::alias::get_alias;
use ruma_identifiers::{RoomAliasId, RoomId};

async {
    let response = client
        .request(get_alias::Request {
            room_alias: RoomAliasId::try_from("#example_room:example.com").unwrap(),
        })
        .await?;

    assert_eq!(response.room_id, RoomId::try_from("!n8f893n9:example.com").unwrap());
}

Re-exports

pub use ruma_client_api as api;

pub use ruma_events as events;

pub use ruma_identifiers as identifiers;

Structs

Client	A client for the Matrix client-server API.
Identification	The identification information about the associated user account if the session is associated with a single user account.
Session	A user session, containing an access token and information about the associated user account.

Enums

Error

An error that can occur during client operations.

Type Definitions

HttpClient	Non-secured variant of the client (using plain HTTP requests)
HttpsClient	Secured variant of the client (using HTTPS requests)