Struct DatagramHeader 

pub struct DatagramHeader {
    pub datagram_type: u8,
    pub track_alias: VarInt,
    pub group_id: VarInt,
    pub object_id: VarInt,
    pub publisher_priority: Option<u8>,
    pub extension_headers: Vec<u8>,
    pub object_status: Option<ObjectStatus>,
}

Datagram header for draft-15.

The datagram_type byte encodes flags:

• 0x02: end-of-group
• 0x04: no object_id (object_id = 0 implied)
• 0x20: status datagram (carries object_status instead of payload)

Fields

datagram_type: u8

Raw datagram-type byte encoding flags + kind.

track_alias: VarInt

Track alias identifying the track.

group_id: VarInt

Group ID for the contained object.

object_id: VarInt

Object ID (zero when the no-object-id flag is set).

publisher_priority: Option<u8>

Publisher priority, present only when the type byte leaves the default-priority bit (0x08) clear.

None means the object inherits the priority the control message that established the subscription specified — draft-15 Section 10.3.1. This is optional here and not on draft-14 because draft-15 is the draft that made it so.

extension_headers: Vec<u8>

Opaque extension-headers blob (only when the 0x01 flag is set).

object_status: Option<ObjectStatus>

Object status (only when the 0x20 status flag is set).

The wire field is a varint and can carry any value up to 2^62-1; draft-15 Section 10.2.1.1 assigns four of them and says a peer SHOULD treat the rest as a protocol error. This field is typed to the assigned set, so it cannot hold 0x2 or anything from 0x5 up — Self::encode therefore needs no check and cannot emit a datagram that Self::decode would reject.

None while the status flag is set encodes as ObjectStatus::Normal: once the flag is set the field is present on the wire, so there is nothing for None to mean but the default.

Implementations

impl DatagramHeader

pub fn has_object_id(&self) -> bool

Whether the datagram carries an explicit object_id.

pub fn is_end_of_group(&self) -> bool

Whether this datagram marks the end of its group.

pub fn is_status(&self) -> bool

Whether this datagram carries an object_status instead of payload.

pub fn has_extensions(&self) -> bool

Whether this datagram carries extension headers.

pub fn has_default_priority(&self) -> bool

Whether the publisher priority is omitted and inherited.

Draft-15 Section 10.3.1: with Priority Present set to No the field is absent and “this Object inherits the Publisher Priority specified in the control message that established the subscription”. New in draft-15; draft-14 always carries the byte.

pub fn encode_checked(&self, buf: &mut impl BufMut) -> Result<(), CodecError>

Encode the datagram header, refusing a status the framing cannot carry.

A datagram states a status only when its type byte sets the status flag (0x20). With the flag clear there is no status field on the wire, so an object_status of anything but ObjectStatus::Normal has nowhere to go: Self::encode drops it, and the datagram parses back as an ordinary payload object. An End of Group marker written that way does not arrive late or malformed — it does not arrive at all, and the receiver sees a normal object in its place.

Draft-15 Section 10.3.1 puts the framing side plainly — “The Object Status field and Object Payload are mutually exclusive” — and Section 10.2.1.1 the conformance side: “Any object with a status code other than zero MUST have an empty payload.” Between them there is no datagram that carries a non-zero status and a payload, so the pair being refused here is not one this encoder merely declines to spell.

ObjectStatus::Normal with the flag clear is not that case and is accepted. It is the status the encoding elides for every datagram that carries a payload, so stating it asks for exactly the bytes leaving it out asks for, and nothing is lost.

Errors with CodecError::InvalidField on the lossy combination, before any byte is written, so a refused header leaves buf untouched. It also refuses a type byte Section 10.3.1 Table 5 does not assign, so this encoder cannot emit a datagram its own decoder — or a conforming peer — must close the session over.

The extension block is refused on the same terms the type byte governs it, in both directions. A type announcing extensions must carry some: Section 10.3.1 states that “If an endpoint receives a datagram with Extensions Present as ‘Yes’ and a Extension Headers Length of 0, it MUST close the session with a PROTOCOL_VIOLATION”, so a zero-length block under that type is a datagram no peer may accept. A type announcing none cannot carry any, because Self::encode would drop the bytes in silence.

That first rule belongs to datagrams alone. Section 10.4.2 says the opposite of a subgroup stream — “Objects with no extensions set Extension Headers Length to 0” — because there the type byte is fixed for the whole stream and a zero-length block is the only way one object among many can say it has no extensions. Applying the datagram rule to a subgroup object would refuse frames the draft spells out.

Also refused: an extension block beside a status other than Normal, per Section 10.2.1.2. Self::decode still parses such a datagram, so a capture containing one stays readable; see check_extensions_against_status_on_encode.

pub fn extensions_permitted(&self) -> bool

Whether this datagram’s status is allowed to carry the extension headers it has.

The datagram half of the rule SubgroupObject::extensions_permitted answers for a subgroup object; draft-15 Section 10.3.1 builds the datagram’s extension block out of the same structure Section 10.2.1.2 defines, so the rule covers both carriers.

Self::decode reports this rather than refusing, because the datagram is well framed and a codec that could not read one could not reproduce a capture containing it. Self::encode_checked does refuse it — that is the one direction with no such excuse, and a plain Self::encode stands beside it when verbatim reproduction is what is wanted.

pub fn encode(&self, buf: &mut impl BufMut)

Encode the datagram header to buf.

When the type byte sets the status flag the status field is written unconditionally, defaulting to ObjectStatus::Normal. Omitting it would truncate the datagram: Self::decode reads a status whenever the flag is set, and answers CodecError::UnexpectedEnd when the bytes stop first.

The type byte is taken as the authority on framing, which is what makes this infallible — and what makes it lossy when the struct disagrees with itself. An object_status set while the type byte leaves the status flag clear is discarded here without a word. Prefer Self::encode_checked, which refuses that combination instead of resolving it.

pub fn decode(buf: &mut impl Buf) -> Result<Self, CodecError>

Decode a datagram header from buf.

Trait Implementations

impl Clone for DatagramHeader

fn clone(&self) -> DatagramHeader

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DatagramHeader

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for DatagramHeader

impl PartialEq for DatagramHeader

fn eq(&self, other: &DatagramHeader) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for DatagramHeader