Module ruma_common::events
source · [−]events
only.Expand description
(De)serializable types for the events in the Matrix specification. These types are used by other Ruma crates.
All data exchanged over Matrix is expressed as an event. Different event types represent different actions, such as joining a room or sending a message. Events are stored and transmitted as simple JSON structures. While anyone can create a new event type for their own purposes, the Matrix specification defines a number of event types which are considered core to the protocol. This module contains Rust types for all of the event types defined by the specification and facilities for extending the event system for custom event types.
Core event types
This module includes Rust types for all event types in the Matrix specification.
To better organize the crate, these types live in separate modules with a hierarchy that matches
the reverse domain name notation of the event type. For example, the m.room.message
event
lives at ruma::events::room::message::RoomMessageEvent
. Each type’s module also contains a
Rust type for that event type’s content
field, and any other supporting types required by the
event’s other fields.
Extending Ruma with custom events
For our examples we will start with a simple custom state event. ruma_event
specifies the state event’s type
and it’s kind
.
use ruma_common::events::macros::EventContent;
use serde::{Deserialize, Serialize};
#[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
#[ruma_event(type = "org.example.event", kind = State, state_key_type = String)]
pub struct ExampleContent {
field: String,
}
This can be used with events structs, such as passing it into
ruma::api::client::state::send_state_event
’s Request
.
As a more advanced example we create a reaction message event. For this event we will use a
OriginalSyncMessageLikeEvent
struct but any OriginalMessageLikeEvent
struct would work.
use ruma_common::{
events::{macros::EventContent, OriginalSyncMessageLikeEvent},
OwnedEventId,
};
use serde::{Deserialize, Serialize};
#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(tag = "rel_type")]
pub enum RelatesTo {
#[serde(rename = "m.annotation")]
Annotation {
/// The event this reaction relates to.
event_id: OwnedEventId,
/// The displayable content of the reaction.
key: String,
},
/// Since this event is not fully specified in the Matrix spec
/// it may change or types may be added, we are ready!
#[serde(rename = "m.whatever")]
Whatever,
}
/// The payload for our reaction event.
#[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
#[ruma_event(type = "m.reaction", kind = MessageLike)]
pub struct ReactionEventContent {
#[serde(rename = "m.relates_to")]
pub relates_to: RelatesTo,
}
let json = serde_json::json!({
"content": {
"m.relates_to": {
"event_id": "$xxxx-xxxx",
"key": "👍",
"rel_type": "m.annotation"
}
},
"event_id": "$xxxx-xxxx",
"origin_server_ts": 1,
"sender": "@someone:example.org",
"type": "m.reaction",
"unsigned": {
"age": 85
}
});
// The downside of this event is we cannot use it with event enums,
// but could be deserialized from a `Raw<_>` that has failed to deserialize.
assert_matches::assert_matches!(
serde_json::from_value::<OriginalSyncMessageLikeEvent<ReactionEventContent>>(json),
Ok(OriginalSyncMessageLikeEvent {
content: ReactionEventContent {
relates_to: RelatesTo::Annotation { key, .. },
},
..
}) if key == "👍"
);
Re-exports
pub use self::relation::Relations;
Modules
m.call
namespace.m.forwarded_room_key
event.m.fully_read
event.m.identity_server
event.m.ignored_user_list
event.m.key
namespace.unstable-pdu
m.policy
namespace.m.push_rules
event.unstable-msc2677
m.reaction
event.m.room
namespace.m.room_key
event.m.room_key_request
event.m.secret
namespace.m.secret_storage
namespace.m.space
events.Structs
m.megolm.v1.aes-sha2
event.m.olm.v1.curve25519-aes-sha2
event.state_key
for event types where that field is always empty.m.olm.v1.curve25519-aes-sha2
event.room_id
.room_id
.room_id
.room_id
.room_id
.Enums
EphemeralRoomEvent
this is.Event
this is.GlobalAccountDataEvent
this is.MessageLikeEvent
this is.RoomAccountDataEvent
this is.RoomEvent
this is.StateEvent
this is.room_id
.room_id
.ToDeviceEvent
this is.