Open Protocol™ Rust 接口库

Rust 版本：2018
Rust 版本：1.37 及以上

Rust crate 用于通过 Open Protocol™ 与 iChen® System 4 进行接口。

有关协议的详细信息，请参阅此文档。

包

在 ichen-openprotocol 包在 crates.io 上可用。

示例

示例程序可在 src 下的 bin 目录中找到。

设计说明

请注意，此包中定义的所有数据类型都广泛使用借用字符串切片（即 &str）。这是因为最常见的用法模式是创建一个数据变量，设置字段，立即将其序列化为 JSON，然后丢弃数据变量。反序列化的故事类似。

错误值也大量借用输入字段，因为这些错误预计将尽快处理。

结果是分配和复制最小化，但代价是更严格的生存期管理，尤其是在反序列化时——消息结构体不能比原始 JSON 文本字符串存活时间更长，因为字段大量借用自原始 JSON 字符串。

由于广泛使用借用字符串切片，另一个影响是由于转义序列的字符串字面量将导致解析错误，因为实际字符串不能简单地从原始 JSON 字符串中借用。幸运的是，对于大多数包含名称、ID 等的字段来说，这极为罕见。因此，只有某些可能包含转义字符的用户定义文本字段（如 job_card_id）才使用 Cow<&str> 来建模。

如何使用

在 Cargo.toml 中导入 ichen-openprotocol 包，以及 WebSocket 客户端包（如 websocket）

[dependencies]
ichen-openprotocol = "*"
websocket = "*"

导入命名空间

use ichen_openprotocol::*;
use websocket::client::ClientBuilder;
use websocket::OwnedMessage;

通过WebSocket连接到iChen 4服务器（默认端口为5788）

let client = ClientBuilder::new("1.2.3.4:5788").connect_insecure()?;

// Split WebSocket into sender and receiver
let (mut receiver, mut sender) = client.split()?;

使用合适的密码和过滤器创建一个JOIN消息，使用Message::to_json_str()将其序列化为JSON格式，然后将JSON字符串发送到WebSocket

// Create the JOIN message
let join = Message::new_join("mypassword", Filters::All + Filters::JobCards + Filters::Operators)?;

// Serialize the JOIN message with to_json_str()
let json = join.to_json_str();

// Send it over the WebSocket
sender.send(OwnedMessage::Text(json))?;

循环监听并解析消息

for msg in receiver.incoming_messages() {
    match msg.unwrap() {
    OwnedMessage::Text(json) => {
        // Got a JSON message!  Parse it.
        let message = Message::parse_from_json_str(&json)?;

        // Process it...
                :
                :
        }
        // Handle other WebSocket message types, e.g. OwnedMessage::Close
                :
                :
    }
}

处理收到的消息

记住字符串字段大量借用原始JSON字符串，因此正确的使用模式是将JSON字符串解析为Message结构体（使用Message::parse_from_json()），然后立即消费该结构体，释放所有借用的字符串数据。

match message {
    // Response of the `JOIN`
    // Result < 100 indicates failure
    Message::JoinResponse { result, .. } if result < 100 => {
    // Failed to join
            :
            :
    }
    // Response of the `JOIN`
    // Result >= 100 indicates success
    Message::JoinResponse { result, level, .. } => {
    // Success!
            :
            :
    }),
    // Process other messages
            :
            :
}

定期发送ALIVE消息以保持连接活跃

let alive = Message::new_alive();
let json = alive.to_json_str();
sender.send(OwnedMessage::Text(json))?;