Skip to main content

rustorb_cdr/
xcdr.rs

1//! The headers of DDS-XTypes Extended CDR (XCDR), clause 7.4 of
2//! DDS-XTypes 1.3, and the RTPS SerializedPayload header around them
3//! (DDSI-RTPS 2.5 clause 10).
4//!
5//! The encoder and decoder write and read values with the alignment of
6//! [`Encoding::Xcdr1`] or [`Encoding::Xcdr2`]; what is here adds the
7//! pieces that only XCDR has:
8//!
9//! - the encapsulation header of a payload
10//!   ([`Encoder::xcdr_payload`], [`Decoder::xcdr_payload`]), after which
11//!   alignment restarts, and whose options record the final padding;
12//! - the delimiter header (DHEADER) of XCDR2 appendable and mutable types,
13//!   and of XCDR2 collections of non-primitive elements
14//!   ([`Encoder::begin_dheader`], [`Decoder::read_dheader`]);
15//! - the member header (EMHEADER) of XCDR2 mutable types
16//!   ([`Encoder::begin_member`], [`Decoder::read_member_header`]);
17//! - the parameter headers of XCDR1 mutable types and optional members
18//!   ([`Encoder::begin_parameter`], [`Decoder::read_parameter`]).
19//!
20//! Which of them a type uses depends on its extensibility and the
21//! encoding version (Table 35, [`XcdrFormat::new`]); that choice belongs
22//! to the code that knows the type.
23
24use crate::{ByteOrder, Decoder, Encoder, Encoding, Error, Result};
25
26/// The extensibility kind of a type (DDS-XTypes 7.2.2.4.4.4.6, `@final`,
27/// `@appendable`, `@mutable`).
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
29pub enum Extensibility {
30    /// `@final`.
31    Final,
32    /// `@appendable`, the default.
33    Appendable,
34    /// `@mutable`.
35    Mutable,
36}
37
38/// The format of an XCDR payload: which encoding rules its top-level
39/// object follows (DDS-XTypes Table 35).
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
41pub enum XcdrFormat {
42    /// PLAIN_CDR: final or appendable types, encoding version 1.
43    PlainCdr,
44    /// PL_CDR: mutable types, encoding version 1.
45    PlCdr,
46    /// PLAIN_CDR2: final types, encoding version 2.
47    PlainCdr2,
48    /// DELIMITED_CDR: appendable types, encoding version 2.
49    DelimitedCdr2,
50    /// PL_CDR2: mutable types, encoding version 2.
51    PlCdr2,
52}
53
54impl XcdrFormat {
55    /// The format of a type of extensibility `kind` written with
56    /// `encoding`, or `None` when that is not an XCDR encoding.
57    pub fn new(encoding: Encoding, kind: Extensibility) -> Option<XcdrFormat> {
58        use Extensibility::*;
59        Some(match (encoding, kind) {
60            (Encoding::Xcdr1, Final | Appendable) => XcdrFormat::PlainCdr,
61            (Encoding::Xcdr1, Mutable) => XcdrFormat::PlCdr,
62            (Encoding::Xcdr2, Final) => XcdrFormat::PlainCdr2,
63            (Encoding::Xcdr2, Appendable) => XcdrFormat::DelimitedCdr2,
64            (Encoding::Xcdr2, Mutable) => XcdrFormat::PlCdr2,
65            _ => return None,
66        })
67    }
68
69    /// The encoding version: [`Encoding::Xcdr1`] or [`Encoding::Xcdr2`].
70    pub fn encoding(self) -> Encoding {
71        match self {
72            XcdrFormat::PlainCdr | XcdrFormat::PlCdr => Encoding::Xcdr1,
73            _ => Encoding::Xcdr2,
74        }
75    }
76}
77
78/// The encapsulation identifier at the start of a payload: a format and a
79/// byte order (DDS-XTypes Table 39, DDSI-RTPS 2.5 Table 10.3).
80#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
81pub struct EncapsulationId {
82    /// The format of the top-level object.
83    pub format: XcdrFormat,
84    /// The byte order of the payload.
85    pub order: ByteOrder,
86}
87
88impl EncapsulationId {
89    /// The two octets of the identifier.
90    ///
91    /// The encoding version 2 values are those of DDS-XTypes Table 39 and
92    /// DDSI-RTPS 2.5 Table 10.3 (`0x10` to `0x15`). DDS-XTypes Table 60
93    /// lists other values (`0x06` to `0x0b`) for the same formats; they
94    /// are accepted by [`from_bytes`](EncapsulationId::from_bytes) but
95    /// never written.
96    pub fn to_bytes(self) -> [u8; 2] {
97        let base = match self.format {
98            XcdrFormat::PlainCdr => 0x00,
99            XcdrFormat::PlCdr => 0x02,
100            XcdrFormat::PlainCdr2 => 0x10,
101            XcdrFormat::PlCdr2 => 0x12,
102            XcdrFormat::DelimitedCdr2 => 0x14,
103        };
104        [0x00, base | self.order.flag()]
105    }
106
107    /// Reads the two octets of an identifier. XML (`0x0004`) and unknown
108    /// identifiers are errors.
109    pub fn from_bytes(bytes: [u8; 2]) -> Result<EncapsulationId> {
110        let [0x00, id] = bytes else {
111            return Err(Error::InvalidXcdr("unknown encapsulation identifier"));
112        };
113        let format = match id & !1 {
114            0x00 => XcdrFormat::PlainCdr,
115            0x02 => XcdrFormat::PlCdr,
116            0x10 | 0x06 => XcdrFormat::PlainCdr2,
117            0x12 | 0x0a => XcdrFormat::PlCdr2,
118            0x14 | 0x08 => XcdrFormat::DelimitedCdr2,
119            _ => return Err(Error::InvalidXcdr("unknown encapsulation identifier")),
120        };
121        // In every identifier the low bit is the byte order.
122        let order = if id & 1 == 0 {
123            ByteOrder::Big
124        } else {
125            ByteOrder::Little
126        };
127        Ok(EncapsulationId { format, order })
128    }
129}
130
131/// The header of a payload read by [`Decoder::xcdr_payload`].
132#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
133pub struct PayloadHeader {
134    /// The encapsulation identifier.
135    pub id: EncapsulationId,
136    /// The options octets as received. The low two bits of the second are
137    /// the padding after the data, which the decoder leaves out.
138    pub options: [u8; 2],
139}
140
141/// Parameter ID of an extended parameter header (DDS-XTypes Table 34),
142/// with `FLAG_MUST_UNDERSTAND` set as the table requires.
143pub const PID_EXTENDED: u16 = 0x7F01;
144/// Parameter ID that ends an XCDR1 parameter list (DDS-XTypes Table 34),
145/// with `FLAG_MUST_UNDERSTAND` set as the table requires.
146pub const PID_LIST_END: u16 = 0x7F02;
147/// Parameter ID of a parameter every reader ignores (DDS-XTypes Table 34).
148pub const PID_IGNORE: u16 = 0x3F03;
149/// Parameter ID that ends the parameter lists of the RTPS built-in topic
150/// types (DDSI-RTPS 9.4.2.11).
151pub const PID_SENTINEL: u16 = 0x0001;
152/// The implementation-specific flag of a parameter ID.
153pub const FLAG_IMPL_EXTENSION: u16 = 0x8000;
154/// The must-understand flag of a parameter ID.
155pub const FLAG_MUST_UNDERSTAND: u16 = 0x4000;
156
157/// The largest member ID (28 bits), in an EMHEADER or an extended
158/// parameter header.
159pub const MAX_MEMBER_ID: u32 = 0x0FFF_FFFF;
160/// The largest member ID a short parameter header holds (DDS-XTypes
161/// 7.4.1.2.2).
162pub const MAX_SHORT_PID: u32 = 0x3F00;
163
164/// What ends an XCDR1 parameter list.
165#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
166pub enum ListEnd {
167    /// [`PID_LIST_END`], for user types.
168    Xtypes,
169    /// [`PID_SENTINEL`], for the RTPS built-in topic types (whose member
170    /// ID 1 is therefore never used). A reader also accepts
171    /// [`PID_LIST_END`].
172    Rtps,
173}
174
175impl ListEnd {
176    fn pid(self) -> u16 {
177        match self {
178            ListEnd::Xtypes => PID_LIST_END,
179            ListEnd::Rtps => PID_SENTINEL,
180        }
181    }
182}
183
184/// A DHEADER being written; see [`Encoder::begin_dheader`].
185#[derive(Debug)]
186#[must_use = "a DHEADER is written by end_dheader"]
187pub struct DHeaderMark {
188    at: usize,
189    start: usize,
190}
191
192/// A member with an EMHEADER being written; see [`Encoder::begin_member`].
193#[derive(Debug)]
194#[must_use = "a member header is written by end_member"]
195pub struct MemberMark {
196    at: usize,
197    start: usize,
198    header: u32,
199}
200
201/// A parameter being written; see [`Encoder::begin_parameter`].
202#[derive(Debug)]
203#[must_use = "a parameter header is written by end_parameter"]
204pub struct ParameterMark {
205    at: usize,
206    start: usize,
207    id: u32,
208    must_understand: bool,
209    extended: bool,
210    origin: usize,
211}
212
213/// An object read after its DHEADER; see [`Decoder::read_dheader`].
214#[derive(Debug, Clone, Copy, PartialEq, Eq)]
215#[must_use = "end_dheader skips what was not read"]
216pub struct Delimited {
217    end: usize,
218}
219
220impl Delimited {
221    /// Whether `dec` has not reached the end of the object yet: more
222    /// members of a mutable type, or more of an appendable one that the
223    /// reader may not know.
224    pub fn has_more(&self, dec: &Decoder<'_>) -> bool {
225        dec.pos < self.end
226    }
227
228    /// Bytes of the object left after the position of `dec`.
229    pub fn remaining(&self, dec: &Decoder<'_>) -> usize {
230        self.end.saturating_sub(dec.pos)
231    }
232}
233
234/// A member header read by [`Decoder::read_member_header`].
235#[derive(Debug, Clone, Copy, PartialEq, Eq)]
236#[must_use = "end_member skips what was not read"]
237pub struct MemberHeader {
238    /// The member ID.
239    pub id: u32,
240    /// Whether the member must be understood (`M_FLAG`).
241    pub must_understand: bool,
242    /// The length of the serialized member.
243    pub len: usize,
244    end: usize,
245}
246
247/// A parameter header read by [`Decoder::read_parameter`] or
248/// [`Decoder::read_parameter_header`].
249#[derive(Debug, Clone, Copy, PartialEq, Eq)]
250#[must_use = "end_parameter skips what was not read and restores the alignment origin"]
251pub struct Parameter {
252    /// The member ID (the low 14 bits of a short parameter ID, or the 28
253    /// bits of an extended header).
254    pub id: u32,
255    /// `FLAG_MUST_UNDERSTAND`.
256    pub must_understand: bool,
257    /// `FLAG_IMPL_EXTENSION`.
258    pub impl_extension: bool,
259    /// The length of the serialized member: 0 for an absent optional
260    /// member.
261    pub len: usize,
262    end: usize,
263    origin: usize,
264}
265
266impl Encoder {
267    /// Starts an RTPS SerializedPayload: the encapsulation identifier of
268    /// `format` and `order`, the options, and alignment counted from the
269    /// byte after them (DDSI-RTPS 2.5 10.2, DDS-XTypes 7.4.3.5.3 rule 1).
270    /// End it with [`finish_xcdr_payload`](Encoder::finish_xcdr_payload).
271    pub fn xcdr_payload(format: XcdrFormat, order: ByteOrder) -> Encoder {
272        let mut enc = Encoder::new(order, format.encoding());
273        enc.write_octets(&EncapsulationId { format, order }.to_bytes());
274        enc.write_octets(&[0, 0]);
275        enc.origin = 4;
276        enc
277    }
278
279    /// Ends a payload started with
280    /// [`xcdr_payload`](Encoder::xcdr_payload): zero padding up to a
281    /// multiple of 4 octets, its length recorded in the options
282    /// (DDS-XTypes 7.6.3.1.2), and the bytes.
283    pub fn finish_xcdr_payload(mut self) -> Vec<u8> {
284        let pad = (4 - self.len() % 4) % 4;
285        self.buf.resize(self.buf.len() + pad, 0);
286        if let Some(options) = self.buf.get_mut(3) {
287            *options = (*options & !3) | pad as u8;
288        }
289        self.into_bytes()
290    }
291
292    fn patch_u32(&mut self, at: usize, value: u32) {
293        let bytes = match self.order {
294            ByteOrder::Big => value.to_be_bytes(),
295            ByteOrder::Little => value.to_le_bytes(),
296        };
297        self.buf[at..at + 4].copy_from_slice(&bytes);
298    }
299
300    fn patch_u16(&mut self, at: usize, value: u16) {
301        let bytes = match self.order {
302            ByteOrder::Big => value.to_be_bytes(),
303            ByteOrder::Little => value.to_le_bytes(),
304        };
305        self.buf[at..at + 2].copy_from_slice(&bytes);
306    }
307
308    fn u16_bytes(&self, value: u16) -> [u8; 2] {
309        match self.order {
310            ByteOrder::Big => value.to_be_bytes(),
311            ByteOrder::Little => value.to_le_bytes(),
312        }
313    }
314
315    fn u32_bytes(&self, value: u32) -> [u8; 4] {
316        match self.order {
317            ByteOrder::Big => value.to_be_bytes(),
318            ByteOrder::Little => value.to_le_bytes(),
319        }
320    }
321
322    /// Writes a DHEADER to be filled in by
323    /// [`end_dheader`](Encoder::end_dheader) with the length of what is
324    /// written in between (DDS-XTypes 7.4.3.4.1).
325    ///
326    /// Marks of [`begin_dheader`](Encoder::begin_dheader),
327    /// [`begin_member`](Encoder::begin_member) and
328    /// [`begin_parameter`](Encoder::begin_parameter) must be ended
329    /// innermost first.
330    pub fn begin_dheader(&mut self) -> DHeaderMark {
331        self.align(4);
332        let at = self.buf.len();
333        self.write_u32(0);
334        DHeaderMark {
335            at,
336            start: self.len(),
337        }
338    }
339
340    /// Fills in the DHEADER of `mark`.
341    pub fn end_dheader(&mut self, mark: DHeaderMark) -> Result<()> {
342        let size = self.len() - mark.start;
343        let size = u32::try_from(size).map_err(|_| Error::LengthOverflow(size))?;
344        self.patch_u32(mark.at, size);
345        Ok(())
346    }
347
348    /// Starts a member of an XCDR2 mutable type: an EMHEADER for member
349    /// `id`, filled in by [`end_member`](Encoder::end_member) with the
350    /// length of what is written in between (DDS-XTypes 7.4.3.4.2, rule
351    /// 22). Only for [`Encoding::Xcdr2`].
352    pub fn begin_member(&mut self, id: u32, must_understand: bool) -> Result<MemberMark> {
353        if self.encoding() != Encoding::Xcdr2 {
354            return Err(Error::InvalidXcdr("EMHEADER outside XCDR2"));
355        }
356        if id > MAX_MEMBER_ID {
357            return Err(Error::InvalidXcdr("member ID larger than 28 bits"));
358        }
359        self.align(4);
360        let at = self.buf.len();
361        // EMHEADER1 and NEXTINT, which end_member drops when a length code
362        // of 0 to 3 is enough.
363        self.write_u32(0);
364        self.write_u32(0);
365        Ok(MemberMark {
366            at,
367            start: self.len(),
368            header: (u32::from(must_understand) << 31) | id,
369        })
370    }
371
372    /// Fills in the EMHEADER of `mark`. A member of 1, 2, 4 or 8 octets
373    /// gets a length code of 0 to 3 and no NEXTINT; any other gets length
374    /// code 4 and its length in NEXTINT. (Length codes 5 to 7, which share
375    /// NEXTINT with the member, are read but not written.)
376    pub fn end_member(&mut self, mark: MemberMark) -> Result<()> {
377        let size = self.len() - mark.start;
378        let lc = match size {
379            1 => Some(0),
380            2 => Some(1),
381            4 => Some(2),
382            8 => Some(3),
383            _ => None,
384        };
385        match lc {
386            // Dropping NEXTINT moves the member back by 4 octets, which
387            // keeps its alignment: XCDR2 aligns to no more than 4.
388            Some(lc) => {
389                self.buf.drain(mark.at + 4..mark.at + 8);
390                self.patch_u32(mark.at, mark.header | (lc << 28));
391            }
392            None => {
393                let size = u32::try_from(size).map_err(|_| Error::LengthOverflow(size))?;
394                self.patch_u32(mark.at, mark.header | (4 << 28));
395                self.patch_u32(mark.at + 4, size);
396            }
397        }
398        Ok(())
399    }
400
401    /// Starts a parameter of an XCDR1 parameter list, or the header of an
402    /// XCDR1 optional member: a parameter header for member `id`, filled
403    /// in by [`end_parameter`](Encoder::end_parameter) with the length of
404    /// what is written in between (DDS-XTypes 7.4.1.2, rules 24 and 25).
405    ///
406    /// The header is a short one (16-bit ID and length) when `id` is at
407    /// most [`MAX_SHORT_PID`], and an extended one ([`PID_EXTENDED`])
408    /// otherwise or when the member turns out longer than 65535 octets.
409    /// Alignment counts from the byte after the header until
410    /// `end_parameter`. An absent optional member is a parameter with
411    /// nothing written in it.
412    pub fn begin_parameter(&mut self, id: u32, must_understand: bool) -> Result<ParameterMark> {
413        if id > MAX_MEMBER_ID {
414            return Err(Error::InvalidXcdr("member ID larger than 28 bits"));
415        }
416        self.align(4);
417        let at = self.buf.len();
418        let extended = id > MAX_SHORT_PID;
419        if extended {
420            self.write_u16(PID_EXTENDED);
421            self.write_u16(8);
422            self.write_u32(extended_header(id, must_understand));
423            self.write_u32(0);
424        } else {
425            let flag = if must_understand {
426                FLAG_MUST_UNDERSTAND
427            } else {
428                0
429            };
430            self.write_u16(flag | id as u16);
431            self.write_u16(0);
432        }
433        let mark = ParameterMark {
434            at,
435            start: self.len(),
436            id,
437            must_understand,
438            extended,
439            origin: self.origin,
440        };
441        self.origin = self.offset();
442        Ok(mark)
443    }
444
445    /// Fills in the parameter header of `mark` and restores the alignment
446    /// origin. The length is that of the member, without padding
447    /// (DDS-XTypes 7.4.1.2).
448    pub fn end_parameter(&mut self, mark: ParameterMark) -> Result<()> {
449        let size = self.len() - mark.start;
450        let size32 = u32::try_from(size).map_err(|_| Error::LengthOverflow(size))?;
451        if mark.extended {
452            self.patch_u32(mark.at + 8, size32);
453        } else if let Ok(short) = u16::try_from(size) {
454            self.patch_u16(mark.at + 2, short);
455        } else {
456            // Too long for a short header: make it an extended one. The
457            // member moves with its alignment origin, so its padding stays
458            // right.
459            let mut header = Vec::with_capacity(12);
460            header.extend_from_slice(&self.u16_bytes(PID_EXTENDED));
461            header.extend_from_slice(&self.u16_bytes(8));
462            header
463                .extend_from_slice(&self.u32_bytes(extended_header(mark.id, mark.must_understand)));
464            header.extend_from_slice(&self.u32_bytes(size32));
465            self.buf.splice(mark.at..mark.at + 4, header);
466        }
467        self.origin = mark.origin;
468        Ok(())
469    }
470
471    /// Ends an XCDR1 parameter list with `end` and a zero length (rule
472    /// 23).
473    pub fn end_parameter_list(&mut self, end: ListEnd) {
474        self.align(4);
475        self.write_u16(end.pid());
476        self.write_u16(0);
477    }
478}
479
480/// The `eMemberHeader` of an extended parameter header: the
481/// must-understand flag (`FLAG_2`) and the member ID.
482fn extended_header(id: u32, must_understand: bool) -> u32 {
483    (u32::from(must_understand) << 30) | id
484}
485
486impl<'a> Decoder<'a> {
487    /// Opens an RTPS SerializedPayload: reads the encapsulation header and
488    /// returns a decoder positioned after it, with alignment counted from
489    /// there, and the header. Padding the options say follows the data is
490    /// left out of the decoder.
491    pub fn xcdr_payload(buf: &'a [u8]) -> Result<(Decoder<'a>, PayloadHeader)> {
492        let [a, b, o1, o2, ..] = *buf else {
493            return Err(Error::UnexpectedEof {
494                needed: 4,
495                remaining: buf.len(),
496            });
497        };
498        let id = EncapsulationId::from_bytes([a, b])?;
499        let pad = usize::from(o2 & 3);
500        let end = buf
501            .len()
502            .checked_sub(pad)
503            .filter(|&end| end >= 4)
504            .ok_or(Error::InvalidXcdr("payload padding longer than the data"))?;
505        let mut dec = Decoder::new(&buf[..end], id.order, id.format.encoding());
506        dec.pos = 4;
507        dec.origin = 4;
508        Ok((
509            dec,
510            PayloadHeader {
511                id,
512                options: [o1, o2],
513            },
514        ))
515    }
516
517    /// Reads a DHEADER (DDS-XTypes 7.4.3.4.1). Read the object, then call
518    /// [`end_dheader`](Decoder::end_dheader), which skips what was not
519    /// read: members that a newer version of an appendable type added.
520    pub fn read_dheader(&mut self) -> Result<Delimited> {
521        let size = self.read_u32()? as usize;
522        if size > self.remaining() {
523            return Err(Error::InvalidXcdr("DHEADER longer than the data"));
524        }
525        Ok(Delimited {
526            end: self.pos + size,
527        })
528    }
529
530    /// Moves to the end of the object of `delimited`. Reading past it is
531    /// an error.
532    pub fn end_dheader(&mut self, delimited: Delimited) -> Result<()> {
533        if self.pos > delimited.end {
534            return Err(Error::InvalidXcdr("object longer than its DHEADER"));
535        }
536        self.pos = delimited.end;
537        Ok(())
538    }
539
540    /// Reads the EMHEADER of a member of an XCDR2 mutable type
541    /// (DDS-XTypes 7.4.3.4.2) and leaves the decoder at the member. Read
542    /// it or not, then call [`end_member`](Decoder::end_member).
543    ///
544    /// With length codes 5 to 7, NEXTINT is also the first 4 octets of the
545    /// member (rule 22), so the decoder is left on it, and the length
546    /// counts it: 4 + NEXTINT, 4 + 4 × NEXTINT or 4 + 8 × NEXTINT octets.
547    pub fn read_member_header(&mut self) -> Result<MemberHeader> {
548        let header = self.read_u32()?;
549        let must_understand = header >> 31 == 1;
550        let lc = (header >> 28) & 7;
551        let id = header & MAX_MEMBER_ID;
552        let len = match lc {
553            0 => 1,
554            1 => 2,
555            2 => 4,
556            3 => 8,
557            _ => {
558                let next = self.read_u32()? as usize;
559                if lc == 4 {
560                    next
561                } else {
562                    self.pos -= 4;
563                    let unit = match lc {
564                        5 => 1,
565                        6 => 4,
566                        _ => 8,
567                    };
568                    next.checked_mul(unit)
569                        .and_then(|n| n.checked_add(4))
570                        .ok_or(Error::InvalidXcdr("member longer than the data"))?
571                }
572            }
573        };
574        if len > self.remaining() {
575            return Err(Error::InvalidXcdr("member longer than the data"));
576        }
577        Ok(MemberHeader {
578            id,
579            must_understand,
580            len,
581            end: self.pos + len,
582        })
583    }
584
585    /// Moves to the end of the member of `header`. Reading past it is an
586    /// error.
587    pub fn end_member(&mut self, header: MemberHeader) -> Result<()> {
588        if self.pos > header.end {
589            return Err(Error::InvalidXcdr("member longer than its EMHEADER"));
590        }
591        self.pos = header.end;
592        Ok(())
593    }
594
595    /// Reads a parameter header of XCDR1 (DDS-XTypes 7.4.1.2), short or
596    /// extended, and makes alignment count from the byte after it. Read
597    /// the member or not, then call
598    /// [`end_parameter`](Decoder::end_parameter).
599    ///
600    /// This reads the header in front of an optional member of a final or
601    /// appendable type, where a length of 0 means the member is absent.
602    /// In a parameter list use [`read_parameter`](Decoder::read_parameter),
603    /// which knows its end.
604    pub fn read_parameter_header(&mut self) -> Result<Parameter> {
605        self.align(4)?;
606        let pid = self.read_u16()?;
607        let short_len = self.read_u16()?;
608        let (id, must_understand, impl_extension, len) =
609            if pid & !(FLAG_MUST_UNDERSTAND | FLAG_IMPL_EXTENSION) == PID_EXTENDED & 0x3FFF
610                && pid & FLAG_IMPL_EXTENSION == 0
611            {
612                if short_len != 8 {
613                    return Err(Error::InvalidXcdr("PID_EXTENDED length is not 8"));
614                }
615                let header = self.read_u32()?;
616                let len = self.read_u32()? as usize;
617                (
618                    header & MAX_MEMBER_ID,
619                    header & (1 << 30) != 0,
620                    header & (1 << 31) != 0,
621                    len,
622                )
623            } else {
624                (
625                    u32::from(pid & 0x3FFF),
626                    pid & FLAG_MUST_UNDERSTAND != 0,
627                    pid & FLAG_IMPL_EXTENSION != 0,
628                    usize::from(short_len),
629                )
630            };
631        if len > self.remaining() {
632            return Err(Error::InvalidXcdr("parameter longer than the data"));
633        }
634        let origin = self.origin;
635        self.origin = self.position();
636        Ok(Parameter {
637            id,
638            must_understand,
639            impl_extension,
640            len,
641            end: self.pos + len,
642            origin,
643        })
644    }
645
646    /// Reads the next parameter header of an XCDR1 parameter list, or
647    /// `None` at its end. Parameters with [`PID_IGNORE`] are skipped. The
648    /// list ends with [`PID_LIST_END`] (with any flags), or for
649    /// [`ListEnd::Rtps`] also with [`PID_SENTINEL`].
650    pub fn read_parameter(&mut self, list_end: ListEnd) -> Result<Option<Parameter>> {
651        loop {
652            // The end of the list has a length that is not looked at.
653            self.align(4)?;
654            if let [a, b, ..] = *self.remaining_bytes() {
655                let pid = match self.order {
656                    ByteOrder::Big => u16::from_be_bytes([a, b]),
657                    ByteOrder::Little => u16::from_le_bytes([a, b]),
658                };
659                if pid & !FLAG_MUST_UNDERSTAND == PID_LIST_END & 0x3FFF
660                    || list_end == ListEnd::Rtps && pid == PID_SENTINEL
661                {
662                    self.skip(4)?;
663                    return Ok(None);
664                }
665            }
666            let param = self.read_parameter_header()?;
667            if !param.impl_extension && param.id == u32::from(PID_IGNORE) {
668                self.end_parameter(param)?;
669                continue;
670            }
671            return Ok(Some(param));
672        }
673    }
674
675    /// Moves to the end of the parameter `param` and restores the
676    /// alignment origin. Reading past it is an error.
677    pub fn end_parameter(&mut self, param: Parameter) -> Result<()> {
678        if self.pos > param.end {
679            return Err(Error::InvalidXcdr("member longer than its parameter"));
680        }
681        self.pos = param.end;
682        self.origin = param.origin;
683        Ok(())
684    }
685}