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}