protocol

بروتوكول

التوثيق

تعريفات بروتوكول سهلة في الصدأ.

يضيف هذا الصندوق مشتقًا مخصصًا يمكن إضافته إلى الأنواع، مما يسمح بإرسال البيانات المنظمة واستقبالها من أي تدفق 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 الخاصة بك. يمكنك استخدام #[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 ,
}