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}