[−][src]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) |