Struct SourceHandler

pub struct SourceHandler<PduSender: PduSendProvider, UserFaultHook: UserFaultHookProvider, Vfs: VirtualFilestore, RemoteCfgTable: RemoteEntityConfigProvider, TimerCreator: TimerCreatorProvider<Countdown = Countdown>, Countdown: CountdownProvider, SeqCountProvider: SequenceCountProvider> { /* private fields */ }

Available on crate feature alloc only.

This is the primary CFDP source handler. It models the CFDP source entity, which is primarily responsible for handling put requests to send files to another CFDP destination entity.

As such, it contains a state machine to perform all operations necessary to perform a source-to-destination file transfer. This class uses the user provides PduSendProvider to send the CFDP PDU packets generated by the state machine.

The following core functions are the primary interface:

1. Self::put_request can be used to start transactions, most notably to start and perform a Copy File procedure to send a file or to send a Proxy Put Request to request a file.
2. Self::state_machine is the primary interface to execute an active file transfer. It generates the necessary CFDP PDUs for this process. This method is also used to insert received packets with the appropriate destination ID and target handler type into the state machine.

A put request will only be accepted if the handler is in the idle state.

The handler requires the alloc feature but will allocated all required memory on construction time. This means that the handler is still suitable for embedded systems where run-time allocation is prohibited. Furthermore, it uses the VirtualFilestore abstraction to allow usage on systems without a std filesystem. This handler does not support concurrency out of the box. Instead, if concurrent handling is required, it is recommended to create a new handler and run all active handlers inside a thread pool, or move the newly created handler to a new thread.

Implementations

impl<PduSender: PduSendProvider, UserFaultHook: UserFaultHookProvider, Vfs: VirtualFilestore, RemoteCfgTable: RemoteEntityConfigProvider, TimerCreator: TimerCreatorProvider<Countdown = Countdown>, Countdown: CountdownProvider, SeqCountProvider: SequenceCountProvider> SourceHandler<PduSender, UserFaultHook, Vfs, RemoteCfgTable, TimerCreator, Countdown, SeqCountProvider>

pub fn new( cfg: LocalEntityConfig<UserFaultHook>, pdu_sender: PduSender, vfs: Vfs, put_request_cacher: StaticPutRequestCacher, pdu_and_cksum_buf_size: usize, remote_cfg_table: RemoteCfgTable, timer_creator: TimerCreator, seq_count_provider: SeqCountProvider, ) -> Self

Creates a new instance of a source handler.

Arguments

• cfg - The local entity configuration for this source handler.
• pdu_sender - PduSendProvider provider used to send CFDP PDUs generated by the handler.
• vfs - VirtualFilestore implementation used by the handler, which decouples the CFDP implementation from the underlying filestore/filesystem. This allows to use this handler for embedded systems where a standard runtime might not be available.
• put_request_cacher - The put request cacher is used cache put requests without requiring run-time allocation.
• pdu_and_cksum_buf_size - The handler requires a buffer to generate PDUs and perform checksum calculations. The user can specify the size of this buffer, so this should be set to the maximum expected PDU size or a conservative upper bound for this size, for example 2048 or 4096 bytes.
• remote_cfg_table - The RemoteEntityConfigProvider used to look up remote entities and target specific configuration for file copy operations.
• timer_creator - TimerCreatorProvider used by the CFDP handler to generate timers required by various tasks. This allows to use this handler for embedded systems where the standard time APIs might not be available.
• seq_count_provider - The SequenceCountProvider used to generate the TransactionId which contains an incrementing counter.

pub fn state_machine_no_packet( &mut self, cfdp_user: &mut impl CfdpUser, ) -> Result<u32, SourceError>

Calls Self::state_machine, without inserting a packet.

pub fn state_machine( &mut self, cfdp_user: &mut impl CfdpUser, pdu: Option<&impl PduProvider>, ) -> Result<u32, SourceError>

This is the core function to drive the source handler. It is also used to insert packets into the source handler.

The state machine should either be called if a packet with the appropriate destination ID is received, or periodically in IDLE periods to perform all CFDP related tasks, for example checking for timeouts or missed file segments.

The function returns the number of sent PDU packets on success.

pub fn put_request( &mut self, put_request: &impl ReadablePutRequest, ) -> Result<(), PutRequestError>

This function is used to pass a put request to the source handler, which is also used to start a file copy operation. As such, this function models the Put.request CFDP primtiive. Please note that the source handler can also process one put request at a time. The caller is responsible of creating a new source handler, one handler can only handle one file copy request at a time.

pub fn cancel_request( &mut self, user: &mut impl CfdpUser, transaction_id: &TransactionId, ) -> Result<bool, SourceError>

This functions models the Cancel.request CFDP primitive and is the recommended way to cancel a transaction.

This method will cause a Notice of Cancellation at this entity if a transaction is active and the passed transaction ID matches the currently active transaction ID. Please note that the state machine might still be active because a cancelled transfer might still require some packets to be sent to the remote receiver entity.

If not unexpected errors occur, this method returns true if the transfer was cancelled propery and false if there is no transaction active or the passed transaction ID and the active ID do not match.

pub fn transaction_id(&self) -> Option<TransactionId>

pub fn transmission_mode(&self) -> Option<TransmissionMode>

Returns the TransmissionMode for the active file operation.

pub fn step(&self) -> TransactionStep

Get the TransactionStep, which denotes the exact step of a pending CFDP transaction when applicable.

pub fn state(&self) -> State

pub fn local_cfg(&self) -> &LocalEntityConfig<UserFaultHook>

pub fn reset(&mut self)

This function is public to allow completely resetting the handler, but it is explicitely discouraged to do this. CFDP has mechanism to detect issues and errors on itself. Resetting the handler might interfere with these mechanisms and lead to unexpected behaviour.