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;
44pub mod xcdr;
45
46pub use decoder::{Decoder, Segment};
47pub use encoder::Encoder;
48pub use error::{Error, Result};
49pub use long_double::LongDouble;
50pub use octets::Octets;
51pub use traits::{CdrDecode, CdrEncode};
52pub use value::ValueHeader;
53
54/// Byte order of a CDR stream.
55#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
56pub enum ByteOrder {
57    /// Big endian, flagged as `0` in GIOP headers and encapsulations.
58    Big,
59    /// Little endian, flagged as `1` in GIOP headers and encapsulations.
60    Little,
61}
62
63impl ByteOrder {
64    /// The byte order of the host.
65    pub const NATIVE: ByteOrder = if cfg!(target_endian = "little") {
66        ByteOrder::Little
67    } else {
68        ByteOrder::Big
69    };
70
71    /// The value of the GIOP byte order flag (`0` big, `1` little).
72    pub fn flag(self) -> u8 {
73        match self {
74            ByteOrder::Big => 0,
75            ByteOrder::Little => 1,
76        }
77    }
78
79    /// Converts a GIOP byte order flag. Only `0` and `1` are valid.
80    pub fn from_flag(flag: u8) -> Result<ByteOrder> {
81        match flag {
82            0 => Ok(ByteOrder::Big),
83            1 => Ok(ByteOrder::Little),
84            other => Err(Error::InvalidByteOrder(other)),
85        }
86    }
87}
88
89/// The encoding rules a stream follows.
90///
91/// The GIOP versions differ only in how `wchar` and `wstring` are encoded:
92/// GIOP 1.0 has no wide characters, GIOP 1.1 encodes them as aligned
93/// fixed-width code units, and GIOP 1.2 encodes them as octet sequences.
94///
95/// [`Xcdr1`](Encoding::Xcdr1) and [`Xcdr2`](Encoding::Xcdr2) are the
96/// Extended CDR encodings of DDS-XTypes, versions 1 and 2. XCDR2 aligns
97/// no primitive to more than 4 octets ([`max_align`](Encoding::max_align)).
98/// The headers they add (the payload header, DHEADER, EMHEADER, parameter
99/// headers) are in [`xcdr`]; which of them a type needs is up to the code
100/// that knows the type.
101#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
102pub enum Encoding {
103    /// GIOP 1.0.
104    Giop1_0,
105    /// GIOP 1.1.
106    Giop1_1,
107    /// GIOP 1.2 and later.
108    Giop1_2,
109    /// DDS-XTypes Extended CDR, encoding version 1.
110    Xcdr1,
111    /// DDS-XTypes Extended CDR, encoding version 2.
112    Xcdr2,
113}
114
115impl Encoding {
116    /// Whether this is one of the GIOP encodings.
117    pub fn is_giop(self) -> bool {
118        matches!(
119            self,
120            Encoding::Giop1_0 | Encoding::Giop1_1 | Encoding::Giop1_2
121        )
122    }
123
124    /// The largest alignment a value gets: 8 octets, or 4 for XCDR2.
125    ///
126    /// [`Encoder::align`] and [`Decoder::align`] use no more than this.
127    pub fn max_align(self) -> usize {
128        match self {
129            Encoding::Xcdr2 => 4,
130            _ => 8,
131        }
132    }
133}