ruma-client-api

ruma-client-api 包含用于 Matrix 客户端 API 规范中每个端点请求和响应的可序列化类型。这些类型可以被客户端和服务器代码共享。

安装

在项目目录中运行以下 Cargo 命令：

cargo add ruma-client-api

或者在 Cargo.toml 中添加以下行：

ruma-client-api = "0.20.4"

完整示例

以下是一个使用 ruma-client-api 实现 Matrix 协议通信与消息处理的完整示例：

use ruma_client_api::{
    error::Error as RumaError,
    r0::{
        account::register::{Request as RegisterRequest, Response as RegisterResponse},
        session::login::{Request as LoginRequest, Response as LoginResponse},
        sync::sync_events::{Request as SyncRequest, Response as SyncResponse},
    },
};
use ruma_common::presence::PresenceState;
use ruma_identifiers::{DeviceId, RoomId, UserId};
use ruma_client::{Client, HttpClient};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // 创建 HTTP 客户端
    let client = Client::new().await?;

    // 1. 注册新用户
    let register_request = RegisterRequest::new().username("example_user").password("secure_password");
    let register_response: RegisterResponse = client.send_request(register_request).await?;
    println!("Registered user: {:?}", register_response.user_id);

    // 2. 登录
    let login_request = LoginRequest::Password {
        identifier: ruma_client_api::r0::session::login::UserIdentifier::MatrixId(register_response.user_id.clone()),
        password: "secure_password".to_string(),
        device_id: Some(DeviceId::new()),
        initial_device_display_name: Some("My Device".to_string()),
    };
    let login_response: LoginResponse = client.send_request(login_request).await?;
    println!("Logged in with access token: {}", login_response.access_token);

    // 3. 同步消息
    let sync_request = SyncRequest::new(login_response.next_batch.unwrap_or_default())
        .set_presence(PresenceState::Online);
    let sync_response: SyncResponse = client.send_request(sync_request).await?;
    println!("Received sync response with {} rooms", sync_response.rooms.join.len());

    // 4. 处理消息
    for (room_id, room_info) in sync_response.rooms.join {
        println!("Messages in room {}:", room_id);
        for event in room_info.timeline.events {
            println!("- {:?}", event);
        }
    }

    Ok(())
}

示例说明

1. 用户注册：使用 RegisterRequest 创建新用户账户
2. 用户登录：使用 LoginRequest 进行密码认证，获取访问令牌
3. 消息同步：使用 SyncRequest 获取最新消息和房间状态
4. 消息处理：遍历同步响应中的房间和消息事件

这个示例展示了如何使用 ruma-client-api 实现基本的 Matrix 客户端功能，包括用户认证、消息同步和处理。

扩展示例

以下是一个更完整的 Matrix 客户端实现示例，包含房间创建和消息发送功能：

use ruma_client_api::{
    r0::{
        account::register::{Request as RegisterRequest, Response as RegisterResponse},
        session::login::{Request as LoginRequest, Response as LoginResponse},
        sync::sync_events::{Request as SyncRequest, Response as SyncResponse},
        room::create_room::{Request as CreateRoomRequest, Response as CreateRoomResponse},
        message::send_message_event::{Request as SendMessageRequest, Response as SendMessageResponse},
    },
};
use ruma_common::presence::PresenceState;
use ruma_identifiers::{DeviceId, RoomId};
use ruma_events::{
    room::message::{MessageEventContent, TextMessageEventContent},
    EventType,
};
use ruma_client::{Client, HttpClient};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // 初始化客户端
    let client = Client::new().await?;
    
    // 1. 用户注册
    let register_response: RegisterResponse = client
        .send_request(
            RegisterRequest::new()
                .username("rust_user")
                .password("matrix_rs")
        )
        .await?;
    
    // 2. 用户登录
    let login_response: LoginResponse = client
        .send_request(LoginRequest::Password {
            identifier: ruma_client_api::r0::session::login::UserIdentifier::MatrixId(
                register_response.user_id.clone(),
            ),
            password: "matrix_rs".to_string(),
            device_id: Some(DeviceId::new()),
            initial_device_display_name: Some("Rust Client".to_string()),
        })
        .await?;

    // 3. 创建房间
    let create_room_response: CreateRoomResponse = client
        .send_request(
            CreateRoomRequest::new()
                .name("Ruma Test Room")
                .visibility(ruma_client_api::r0::room::Visibility::Public)
        )
        .await?;
    println!("Created room: {}", create_room_response.room_id);

    // 4. 发送消息
    let message_content = MessageEventContent::Text(
        TextMessageEventContent::plain("Hello from Ruma client!")
    );
    
    let send_message_response: SendMessageResponse = client
        .send_request(
            SendMessageRequest::new(
                create_room_response.room_id.clone(),
                EventType::RoomMessage,
                &message_content
            )
        )
        .await?;
    println!("Sent message with event ID: {}", send_message_response.event_id);

    // 5. 同步消息
    let sync_response: SyncResponse = client
        .send_request(
            SyncRequest::new(login_response.next_batch.unwrap_or_default())
                .set_presence(PresenceState::Online)
        )
        .await?;

    // 6. 处理同步事件
    for (room_id, room_info) in sync_response.rooms.join {
        println!("Room {} has {} messages", room_id, room_info.timeline.events.len());
    }

    Ok(())
}

示例说明

1. 用户注册：创建新用户账户
2. 用户登录：使用密码认证登录
3. 房间创建：创建一个新的公开聊天室
4. 消息发送：向新创建的聊天室发送文本消息
5. 消息同步：获取最新的消息和房间状态
6. 事件处理：处理同步响应中的房间和消息事件

这个扩展示例展示了更完整的 Matrix 客户端功能，包括房间创建和消息发送等高级操作。

许可证

MIT 许可证