Struct SpacePacket 

#[repr(C, packed(1))]
pub struct SpacePacket { /* private fields */ }

Space packets are implemented as dynamically-sized structs that contain the primary header as their first field, followed by the packet data as pure byte array. In this manner, deserialization can be reduced to a simple byte cast followed by interpretation of the primary header - without any data copies needed. This is useful for high-throughput applications, and ensures that no allocation or significant additional memory is needed to consume Space Packets.

This does also mean that Space Packets may only be handled by reference. In the context of this crate that helps enforce that no spurious copies can be made of the user data (which may be rather large and would incur additional allocations), albeit at the cost of some convenience.

Any means of constructing a SpacePacket in this crate shall perform a consistency check on any received bytes. Hence, any SpacePacket object may be assumed to be a valid Space Packet.

Implementations

impl SpacePacket

pub fn parse(bytes: &[u8]) -> Result<&SpacePacket, InvalidSpacePacket>

Attempts to parse a Space Packet from a given byte slice. If this fails, a reason is given for this failure. Shall never panic: rather, an error enum is returned explaining why the given octet string is not a valid Space Packet.

This deserialization is fully zero-copy. The &SpacePacket returned on success directly references the input slice bytes, but is merely validated to be a valid Space Packet.

pub fn assemble( buffer: &mut [u8], packet_type: PacketType, secondary_header_flag: SecondaryHeaderFlag, apid: Apid, sequence_flag: SequenceFlag, sequence_count: PacketSequenceCount, ) -> Result<&mut SpacePacket, PacketAssemblyError>

Assembles a Space Packet in-place on a given buffer. Computes the required packet data length from the passed buffer size. It is assumed that the caller has reserved the first six bytes of the buffer for the packet header. All other bytes are assumed to form the packet data field.

pub fn construct( buffer: &mut [u8], packet_type: PacketType, secondary_header_flag: SecondaryHeaderFlag, apid: Apid, sequence_flag: SequenceFlag, sequence_count: PacketSequenceCount, packet_data_length: u16, ) -> Result<&mut SpacePacket, PacketAssemblyError>

Constructs a Space Packet in-place on a given buffer. May return a SpacePacketConstructionError if this is not possible for whatever reason. Note that the data field is only “allocated” on the buffer, but never further populated. That may be done after the SpacePacket is otherwise fully constructed (or before: it is not touched during construction).

pub const fn primary_header_size() -> usize

Returns the size of a Space Packet primary header, in bytes. In the version that is presently implemented, that is always 6 bytes.

pub fn packet_version(&self) -> PacketVersionNumber

Since the Space Packet protocol may technically support alternative packet structures in future versions, the 3-bit packet version field may not actually contain a “correct” value.

pub fn packet_type(&self) -> PacketType

The packet type denotes whether a packet is a telecommand (request) or telemetry (report) packet. Note that the exact definition of telecommand and telemetry may differ per system, and indeed the “correct” value here may differ per project.

pub fn set_packet_type(&mut self, packet_type: PacketType)

Sets the packet type to the given value.

pub fn secondary_header_flag(&self) -> SecondaryHeaderFlag

Denotes whether the packet contains a secondary header. If no user field is present, the secondary header is mandatory (presumably, to ensure that some data is always transferred, considering the Space Packet header itself contains no meaningful data).

pub fn set_secondary_header_flag( &mut self, secondary_header_flag: SecondaryHeaderFlag, )

Updates the value of the secondary header flag with the provided value.

pub fn apid(&self) -> Apid

Returns the application process ID stored in the packet. The actual meaning of this APID field may differ per implementation: technically, it only represents “some” data path. In practice, it will often be a identifier for a data channel, the packet source, or the packet destination.

pub fn set_apid(&mut self, apid: Apid)

Sets the APID used to route the packet to the given value.

pub fn sequence_flag(&self) -> SequenceFlag

Sequence flags may be used to indicate that the data contained in a packet is only part of a larger set of application data.

pub fn set_sequence_flag(&mut self, sequence_flag: SequenceFlag)

Sets the sequence flag to the provided value.

pub fn packet_sequence_count(&self) -> PacketSequenceCount

The packet sequence count is unique per APID and denotes the sequential binary count of each Space Packet (generated per APID). For telecommands (i.e., with packet type 1) this may also be a “packet name” that identifies the telecommand packet within its communications session.

pub fn set_packet_sequence_count(&mut self, sequence_count: PacketSequenceCount)

Sets the packet sequence count to the provided value. This value must be provided by an external counter and is not provided at a Space Packet type level because it might differ between packet streams.

pub fn packet_data_length(&self) -> usize

The packet data length field represents the length of the associated packet data field. However, it is not stored directly: rather, the “length count” is stored, which is the packet data length minus one.

pub fn set_packet_data_length( &mut self, packet_data_length: u16, ) -> Result<(), InvalidPacketDataLength>

Sets the packet data length field to the provided value. Note that the given value is not stored directly, but rather decremented by one first. Accordingly, and as per the CCSDS Space Packet Protocol standard, packet data lengths of 0 are not allowed.

pub fn packet_length(&self) -> usize

Returns the total length of the packet in bytes. Note the distinction from the packet data length, which refers only to the length of the data field of the packet.

pub fn packet_data_field(&self) -> &[u8]

Returns a reference to the packet data field contained in this Space Packet.

pub fn packet_data_field_mut(&mut self) -> &mut [u8]

Returns a mutable reference to the packet data field contained in this Space Packet.

Trait Implementations

impl Debug for SpacePacket

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

Formats the value using the given formatter.

impl FromBytes for SpacePacket

where SpacePacketPrimaryHeader: FromBytes, [u8]: FromBytes,

fn ref_from_bytes( source: &[u8], ) -> Result<&Self, ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: KnownLayout + Immutable,

Interprets the given source as a &Self.

fn ref_from_prefix( source: &[u8], ) -> Result<(&Self, &[u8]), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: KnownLayout + Immutable,

Interprets the prefix of the given source as a &Self without copying.

fn ref_from_suffix( source: &[u8], ) -> Result<(&[u8], &Self), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: Immutable + KnownLayout,

Interprets the suffix of the given bytes as a &Self.

fn mut_from_bytes( source: &mut [u8], ) -> Result<&mut Self, ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout,

Interprets the given source as a &mut Self.

fn mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout,

Interprets the prefix of the given source as a &mut Self without copying.

fn mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout,

Interprets the suffix of the given source as a &mut Self without copying.

fn ref_from_bytes_with_elems( source: &[u8], count: usize, ) -> Result<&Self, ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the given source as a &Self with a DST length equal to count.

fn ref_from_prefix_with_elems( source: &[u8], count: usize, ) -> Result<(&Self, &[u8]), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the prefix of the given source as a DST &Self with length equal to count.

fn ref_from_suffix_with_elems( source: &[u8], count: usize, ) -> Result<(&[u8], &Self), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the suffix of the given source as a DST &Self with length equal to count.

fn mut_from_bytes_with_elems( source: &mut [u8], count: usize, ) -> Result<&mut Self, ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the given source as a &mut Self with a DST length equal to count.

fn mut_from_prefix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut Self, &mut [u8]), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the prefix of the given source as a &mut Self with DST length equal to count.

fn mut_from_suffix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut [u8], &mut Self), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the suffix of the given source as a &mut Self with DST length equal to count.

impl FromZeros for SpacePacket

where SpacePacketPrimaryHeader: FromZeros, [u8]: FromZeros,

fn zero(&mut self)

Overwrites self with zeros.

impl Hash for SpacePacket

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

impl IntoBytes for SpacePacket

where SpacePacketPrimaryHeader: IntoBytes, [u8]: IntoBytes,

fn as_bytes(&self) -> &[u8]

where Self: Immutable,

Gets the bytes of this value.

fn as_mut_bytes(&mut self) -> &mut [u8]

where Self: FromBytes,

Gets the bytes of this value mutably.

fn write_to(&self, dst: &mut [u8]) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to dst.

fn write_to_prefix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the prefix of dst.

fn write_to_suffix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the suffix of dst.

impl KnownLayout for SpacePacket

where [u8]: KnownLayout,

type PointerMetadata = <[u8] as KnownLayout>::PointerMetadata

The type of metadata stored in a pointer to Self.

impl PartialEq for SpacePacket

where Self: IntoBytes + Immutable,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFromBytes for SpacePacket

where SpacePacketPrimaryHeader: TryFromBytes, [u8]: TryFromBytes,

fn try_ref_from_bytes( source: &[u8], ) -> Result<&Self, ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout + Immutable,

Attempts to interpret the given source as a &Self.

fn try_ref_from_prefix( source: &[u8], ) -> Result<(&Self, &[u8]), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout + Immutable,

Attempts to interpret the prefix of the given source as a &Self.

fn try_ref_from_suffix( source: &[u8], ) -> Result<(&[u8], &Self), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout + Immutable,

Attempts to interpret the suffix of the given source as a &Self.

fn try_mut_from_bytes( bytes: &mut [u8], ) -> Result<&mut Self, ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the given source as a &mut Self without copying.

fn try_mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the prefix of the given source as a &mut Self.

fn try_mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the suffix of the given source as a &mut Self.

fn try_ref_from_bytes_with_elems( source: &[u8], count: usize, ) -> Result<&Self, ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Attempts to interpret the given source as a &Self with a DST length equal to count.

fn try_ref_from_prefix_with_elems( source: &[u8], count: usize, ) -> Result<(&Self, &[u8]), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Attempts to interpret the prefix of the given source as a &Self with a DST length equal to count.

fn try_ref_from_suffix_with_elems( source: &[u8], count: usize, ) -> Result<(&[u8], &Self), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Attempts to interpret the suffix of the given source as a &Self with a DST length equal to count.

fn try_mut_from_bytes_with_elems( source: &mut [u8], count: usize, ) -> Result<&mut Self, ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout<PointerMetadata = usize> + IntoBytes,

Attempts to interpret the given source as a &mut Self with a DST length equal to count.

fn try_mut_from_prefix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut Self, &mut [u8]), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout<PointerMetadata = usize> + IntoBytes,

Attempts to interpret the prefix of the given source as a &mut Self with a DST length equal to count.

fn try_mut_from_suffix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut [u8], &mut Self), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout<PointerMetadata = usize> + IntoBytes,

Attempts to interpret the suffix of the given source as a &mut Self with a DST length equal to count.

impl Eq for SpacePacket

where Self: IntoBytes + Immutable,

impl Immutable for SpacePacket

where SpacePacketPrimaryHeader: Immutable, [u8]: Immutable,

impl Unaligned for SpacePacket