pub enum MemberHeader {
NoHeader,
PidCdr1 {
pid: u16,
extended: bool,
must_understand: bool,
},
EmHeader {
lc: LengthCode,
must_understand: bool,
},
OptionalCdr1 {
pid: u16,
extended: bool,
must_understand: bool,
},
OptionalFlag,
}Expand description
How a member is framed.
Five shapes, one per rule. The two Optional* ones are what
§7.4.3.5.1 calls an OPT_FMEMBER — an @optional member of a type
that is not @mutable — and they are separate variants rather
than a flag on the other two because their absence is written and
an MMEMBER’s absence is not. A @mutable member that is left out
leaves no trace in the parameter list; an OPT_FMEMBER that is left
out still occupies its place in the stream.
Variants§
NoHeader
No header: the member’s bytes follow directly.
NOPT_FMEMBER, XTypes 1.3 §7.4.3.5.3 rule (18).
PidCdr1
PL_CDR1 parameter header for an MMEMBER. XTypes 1.3 §7.4.1.2,
rules (24) and (25).
The short form is [id:u16][length:u16]; the extended form is
[PID_EXTENDED:u16][8:u16][id:u32][length:u32]. The length field
carries the unpadded value length; the padding to the next
four-byte boundary follows the value and is not counted.
Fields
extended: boolWhether the extended form is required.
Mandatory when the member id reaches PID_EXTENDED_THRESHOLD
or the value is longer than 0xFFFF bytes — the second
condition is easy to miss and makes a long member unreadable
when it is.
must_understand: boolWhether a reader must discard the sample rather than skip this member.
§7.4.1.2.2: FLAG_MUST_UNDERSTAND “shall be set if and only
if the must_understand property of the member is set to
true”. Bit 14 of the short header’s id, FLAG_2
(0x40000000) of the extended header’s eMemberHeader.
EmHeader
PL_CDR2 EMHEADER for an MMEMBER. XTypes 1.3 §7.4.2, rule (22).
Fields
lc: LengthCodeLength code.
OptionalCdr1
An OPT_FMEMBER under XCDR1: the same parameter header as an
MMEMBER, and a declared length of zero when the member takes
no value. XTypes 1.3 §7.4.3.5.3 rule (19), §7.4.1.2.
The clause is explicit: “If the member takes no value within that
particular object, the data length indicated by the header shall
be zero.” Cyclone, RTI and Fast DDS all write the header either
way — crates/ast-layout/tests/fixtures/vendor_bytes.md §1.
Omitting it instead leaves the sample four bytes short of what
every peer counts on and puts every following member at the wrong
offset.
Fields
extended: boolWhether the extended form is required, decided by the same
rule MemberHeader::PidCdr1 uses.
must_understand: boolWhether a reader must discard the sample rather than skip
this member, carried in the same bit and by the same clause
as MemberHeader::PidCdr1’s.
§7.4.1.2.2 conditions the flag on the member’s property and
not on the enclosing type’s extensibility, so an
@optional @must_understand member of a @final type
carries it too. No vendor row measures that combination;
this is the reading the clause’s “if and only if” gives.
OptionalFlag
An OPT_FMEMBER under XCDR2: a BOOLEAN <is_present>, then the
value when it is present. XTypes 1.3 §7.4.3.5.2, rule (20).
One byte, not an EMHEADER. The distinction is four bytes wide and
moves the value: @final struct { long a; @optional octet b; long c; } puts b at offset 5 behind a one-byte flag, where an
EMHEADER would put it at 8.
Implementations§
Source§impl MemberHeader
impl MemberHeader
Sourcepub const fn writes_absence(self) -> bool
pub const fn writes_absence(self) -> bool
Whether the member’s absence is written rather than left out.
True for the two OPT_FMEMBER forms and false for everything
else. An MMEMBER that is absent contributes nothing to the
parameter list; an OPT_FMEMBER that is absent contributes its
header with a length of zero, or its <is_present> byte.