Crate matrix_sdk
source · [−]Expand description
A high-level, batteries-included Matrix client library written in Rust.
This crate seeks to be a general-purpose library for writing software using the Matrix Client-Server API to communicate with a Matrix homeserver. If you’re writing a typical Matrix client or bot, this is likely the crate you need.
However, the crate is designed in a modular way and depends on several other lower-level crates. If you’re attempting something more custom, you might be interested in these:
matrix_sdk_base: A no-network-IO client state machine which can be used to embed a Matrix client into an existing network stack or to build a new Matrix client library on top.matrix_sdk_crypto: A no-network-IO encryption state machine which can be used to add Matrix E2EE support into an existing client or library.
Getting started
The central component you’ll be interacting with is the Client. A basic use
case will include instantiating the client, logging in as a user, registering
some event handlers and then syncing.
This is demonstrated in the example below.
use std::convert::TryFrom;
use matrix_sdk::{
Client, config::SyncSettings,
ruma::{user_id, events::room::message::SyncRoomMessageEvent},
};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let alice = user_id!("@alice:example.org");
let client = Client::builder().user_id(alice).build().await?;
// First we need to log in.
client.login(alice, "password", None, None).await?;
client
.register_event_handler(|ev: SyncRoomMessageEvent| async move {
println!("Received a message {:?}", ev);
})
.await;
// Syncing is important to synchronize the client state with the server.
// This method will never return.
client.sync(SyncSettings::default()).await;
Ok(())
}More examples can be found in the examples directory.
Crate Feature Flags
The following crate feature flags are available:
| Feature | Default | Description |
|---|---|---|
anyhow | No | Better logging for event handlers that return anyhow::Result |
e2e-encryption | Yes | Enable End-to-end encryption support |
eyre | No | Better logging for event handlers that return eyre::Result |
image-proc | No | Enables image processing to generate thumbnails |
image-rayon | No | Enables faster image processing |
markdown | No | Support to send Markdown-formatted messages |
qrcode | Yes | QR code verification support |
sled | Yes | Persistent storage of state and E2EE-Data using sled (if e2e-encryption is activated) |
indexeddb | No | Persistent storage of state and E2EE-Data for browsers using indexeddb (if e2e-encryption is activated) |
socks | No | Enables SOCKS support in the default HTTP client, reqwest |
sso-login | No | Enables SSO login with a local HTTP server |
Enabling logging
Users of the matrix-sdk crate can enable log output by depending on the
tracing-subscriber crate and including the following line in their
application (e.g. at the start of main):
tracing_subscriber::fmt::init();The log output is controlled via the RUST_LOG environment variable by
setting it to one of the error, warn, info, debug or trace levels.
The output is printed to stdout.
The RUST_LOG variable also supports a more advanced syntax for filtering
log output more precisely, for instance with crate-level granularity. For
more information on this, check out the tracing_subscriber documentation.
Re-exports
Modules
Types and traits for attachments.
e2e-encryptionEnd-to-end encryption related types
Types and traits related for event handlers. For usage, see
Client::register_event_handler.
Abstraction over an executor so we can spawn tasks under WASM the same way we do usually.
Common types for media content.
High-level room API
Functions and types to initialize a store.
Structs
A high-level API to manage the client owner’s account.
The underlying room data structure collecting state for joined, left and invited rooms.
A member of a room.
An async/await enabled Matrix client.
Builder that allows creating and configuring various parts of a Client.
The underlying pure data structure for joined and left rooms.
The high-level RoomMember representation
A user session, containing an access token and information about the associated user account.
Store state changes and pass them to the StateStore.
Enums
Errors that can happen in ClientBuilder::build.
The name of the room, either from the metadata or calculated according to matrix specification
Internal representation of errors.
An HTTP error, representing either a connection error or an error while converting the raw HTTP response into a Matrix response.
image-procAll possible errors that can happen during image processing.
Enum controlling if a loop running callbacks should continue or abort.
Enum keeping track in which state the room is, e.g. if our own user is joined, invited, or has left the room.
An error response from a Matrix API call, using a client API specific representation if the endpoint is from that.
State store specific error type.
Traits
Super trait that is used for our store traits, this trait will differ if
it’s used on WASM. WASM targets will not require Send and Sync to have
implemented, while other targets will.
Abstraction around the http layer. The allows implementors to use different http libraries.
Type Definitions
Result type of a pure HTTP request.
Result type of the matrix-sdk.