Skip to main content

rustorb_cdr/
lib.rs

1//! CDR (Common Data Representation) encoder and decoder.
2//!
3//! Handles primitive and constructed IDL types with GIOP alignment rules
4//! and both byte orders.
5//!
6//! - [`Encoder`] and [`Decoder`] read and write primitives, strings, wide
7//!   strings, sequences and encapsulations. Alignment is computed from the
8//!   absolute stream offset, so a body that starts in the middle of a GIOP
9//!   message keeps the alignment of the whole message.
10//! - [`CdrEncode`] and [`CdrDecode`] map Rust types to IDL types: integers
11//!   and floats to their IDL counterparts, [`String`] to `string`, [`Vec`] to
12//!   `sequence`, and fixed-size arrays to IDL arrays.
13//!
14//! - [`Octets`] is a `sequence<octet>` that shares its bytes: read from a
15//!   message without copying ([`Decoder::read_octet_seq_shared`]) and
16//!   written without copying into the message
17//!   ([`Encoder::write_octet_seq_shared`], when the encoder allows it).
18//!
19//! Code set conversion is out of scope: `string` is read and written as
20//! bytes (UTF-8 when converted to [`String`]), and `wchar`/`wstring` use
21//! UTF-16. Negotiating other code sets is left to the ORB core.
22//! `any`, `TypeCode` and `fixed` are in the ORB core, which knows the
23//! types. `long double` is [`LongDouble`], the IEEE 754 binary128 bits.
24//!
25//! Valuetypes are written and read in pieces: [`Encoder::begin_value`] /
26//! [`Encoder::end_value`] and [`Decoder::read_value_header`] /
27//! [`Decoder::end_value`] handle the value tags, sharing (indirections)
28//! and chunking, and the caller writes or reads the state members in
29//! between.
30
31/// Octet sequences at least this long are shared rather than copied, by
32/// [`Decoder::read_octet_seq_shared`] and
33/// [`Encoder::write_octet_seq_shared`]. Shorter ones are cheaper to copy,
34/// and a short slice should not keep a large message buffer alive.
35pub const SHARE_MIN: usize = 4096;
36
37mod decoder;
38mod encoder;
39mod error;
40mod long_double;
41mod octets;
42mod traits;
43mod value;
44
45pub use decoder::{Decoder, Segment};
46pub use encoder::Encoder;
47pub use error::{Error, Result};
48pub use long_double::LongDouble;
49pub use octets::Octets;
50pub use traits::{CdrDecode, CdrEncode};
51pub use value::ValueHeader;
52
53/// Byte order of a CDR stream.
54#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
55pub enum ByteOrder {
56    /// Big endian, flagged as `0` in GIOP headers and encapsulations.
57    Big,
58    /// Little endian, flagged as `1` in GIOP headers and encapsulations.
59    Little,
60}
61
62impl ByteOrder {
63    /// The byte order of the host.
64    pub const NATIVE: ByteOrder = if cfg!(target_endian = "little") {
65        ByteOrder::Little
66    } else {
67        ByteOrder::Big
68    };
69
70    /// The value of the GIOP byte order flag (`0` big, `1` little).
71    pub fn flag(self) -> u8 {
72        match self {
73            ByteOrder::Big => 0,
74            ByteOrder::Little => 1,
75        }
76    }
77
78    /// Converts a GIOP byte order flag. Only `0` and `1` are valid.
79    pub fn from_flag(flag: u8) -> Result<ByteOrder> {
80        match flag {
81            0 => Ok(ByteOrder::Big),
82            1 => Ok(ByteOrder::Little),
83            other => Err(Error::InvalidByteOrder(other)),
84        }
85    }
86}
87
88/// The GIOP version whose CDR rules a stream follows.
89///
90/// The versions differ only in how `wchar` and `wstring` are encoded:
91/// GIOP 1.0 has no wide characters, GIOP 1.1 encodes them as aligned
92/// fixed-width code units, and GIOP 1.2 encodes them as octet sequences.
93#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
94pub enum CdrVersion {
95    /// GIOP 1.0.
96    Giop1_0,
97    /// GIOP 1.1.
98    Giop1_1,
99    /// GIOP 1.2 and later.
100    Giop1_2,
101}