protocol

协议

文档

Rust 中的简单协议定义。

该包添加了一个可以添加到类型中的自定义派生，允许从任何 IO 流发送和接收结构化数据。

网络是内置的，特别支持 TCP 和 UDP。

您定义的协议也可以在网络之外使用 - 请参阅Parcel::from_raw_bytes和Parcel::raw_bytes方法。

这个箱子还提供：

• TCP和UDP模块，方便发送和接收Parcel
• 用于自动转换发送/接收数据的通用中间件库
  • 已经编写了支持压缩的中间件
  • 自定义中间件可以通过具有两种方法的特征来实现

查看示例文件夹以了解用法。

用法

将其添加到您的Cargo.toml中：

[ dependencies ]
protocol = { version = " 3.4 " , features = [ " derive " ] }

然后使用#[derive(protocol::Protocol)]属性定义一个类型：

 # [ derive ( protocol :: Protocol ) ]
struct Hello {
    pub a : String ,
    pub b : u32 ,
} 

在引擎盖下

这里最有趣的部分是protocol::Parcel特征。然后，任何实现此特征的类型都可以序列化为字节流或从字节流序列化。所有原始类型、标准集合、元组和数组都实现此特征。

当您定义自己的Parcel类型时，此 crate 变得特别有用。您可以使用#[derive(protocol::Protocol)]来执行此操作。请注意，为了使类型实现Parcel ，它还必须实现Clone 、 Debug和PartialEq 。

 # [ derive ( Parcel , Clone , Debug , PartialEq ) ]
pub struct Health ( f32 ) ;

# [ derive ( Parcel , Clone , Debug , PartialEq ) ]
pub struct SetPlayerPosition {
    pub position : ( f32 , f32 ) ,
    pub health : Health ,
    pub values : Vec < String > ,
}

定制派生

任何用户定义的类型都可以自动派生Parcel特征。

例子

 # [ derive ( protocol :: Protocol , Clone , Debug , PartialEq ) ]
pub struct Handshake ;

# [ derive ( protocol :: Protocol , Clone , Debug , PartialEq ) ]
pub struct Hello {
    id : i64 ,
    data : Vec < u8 > ,
}

# [ derive ( protocol :: Protocol , Clone , Debug , PartialEq ) ]
pub struct Goodbye {
    id : i64 ,
    reason : String ,
}

# [ derive ( protocol :: Protocol , Clone , Debug , PartialEq ) ]
pub struct Node {
    name : String ,
    enabled : bool
}

# [ protocol ( discriminant = "integer" ) ]
# [ derive ( protocol :: Protocol , Clone , Debug , PartialEq ) ]
pub enum PacketKind {
    # [ protocol ( discriminator ( 0x00 ) ) ]
    Handshake ( Handshake ) ,
    # [ protocol ( discriminator ( 0xaa ) ) ]
    Hello ( Hello ) ,
    # [ protocol ( discriminator ( 0xaf ) ) ]
    Goodbye ( Goodbye ) ,
}

fn main ( ) {
    use std :: net :: TcpStream ;

    let stream = TcpStream :: connect ( "127.0.0.1:34254" ) . unwrap ( ) ;
    let mut connection = protocol :: wire :: stream :: Connection :: new ( stream , protocol :: wire :: middleware :: pipeline :: default ( ) ) ;

    connection . send_packet ( & Packet :: Handshake ( Handshake ) ) . unwrap ( ) ;
    connection . send_packet ( & Packet :: Hello ( Hello { id : 0 , data : vec ! [ 55 ] } ) ) . unwrap ( ) ;
    connection . send_packet ( & Packet :: Goodbye ( Goodbye { id : 0 , reason : "leaving" . to_string ( ) } ) ) . unwrap ( ) ;

    loop {
        if let Some ( response ) = connection . receive_packet ( ) . unwrap ( ) {
            println ! ( "{:?}" , response ) ;
            break ;
        }
    }
} 

枚举

鉴别器

枚举值可以通过其基于 1 的变体索引来传输，也可以通过传输每个变体的字符串名称来传输。

注意：默认行为是将变体名称用作字符串( string )。

此行为可以通过#[protocol(discriminant = "<type>")]属性更改。

支持的判别类型：

• string （默认）
  • 这会将枚举变量名称传输为线上判别式
  • 这每条消息使用更多字节，但非常灵活
• integer
  • 这会传输基于 1 的变体编号作为线上判别式
  • 如果枚举变体具有明确的鉴别器，则
  • 在不破坏协议的情况下，无法在源中重新排序枚举变体

 # [ derive ( protocol :: Protocol , Clone , Debug , PartialEq ) ]
# [ protocol ( discriminant = "string" ) ]
pub enum PlayerState {
  Stationary ,
  Flying { velocity : ( f32 , f32 , f32 ) } ,
  // Discriminators can be explicitly specified.
  # [ protocol ( discriminator ( "ArbitraryOverTheWireName" ) ) ]
  Jumping { height : f32 } ,
}

杂项

您可以为其序列化重命名变体。

 # [ derive ( protocol :: Protocol , Clone , Debug , PartialEq ) ]
# [ protocol ( discriminant = "string" ) ]
pub enum Foo {
  Bar ,
  # [ protocol ( name = "Biz" ) ] // the Bing variant will be send/received as 'Biz'.
  Bing ,
  Baz ,
}