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 ,
}