CORDET Framework - C2 Implementation

Definition of the OutStream component. More...

Go to the source code of this file.

Functions

FwSmDesc_t CrFwOutStreamMake (CrFwInstanceId_t outStreamId)
 Factory function to retrieve the i-th OutStream State Machine instance. More...
 
CrFwBool_t CrFwOutStreamIsInReady (FwSmDesc_t smDesc)
 Return true if the argument OutStream is in state READY. More...
 
CrFwBool_t CrFwOutStreamIsInBuffering (FwSmDesc_t smDesc)
 Return true if the argument OutStream is in state BUFFERING. More...
 
FwSmDesc_t CrFwOutStreamGet (CrFwDestSrc_t dest)
 Getter function for the OutStream corresponding to the argument destination. More...
 
void CrFwOutStreamSend (FwSmDesc_t smDesc, CrFwPckt_t pckt)
 Send a packet to the OutStream. More...
 
void CrFwOutStreamConnectionAvail (FwSmDesc_t smDesc)
 Signal that the out-going middleware connection has become available. More...
 
void CrFwOutStreamDefConfigAction (FwPrDesc_t prDesc)
 Default configuration action for an OutStream. More...
 
void CrFwOutStreamDefInitAction (FwPrDesc_t prDesc)
 Default initialization action for an OutStream. More...
 
void CrFwOutStreamDefShutdownAction (FwSmDesc_t smDesc)
 Default shutdown action for an OutStream. More...
 
CrFwDestSrc_t CrFwOutStreamGetDest (FwSmDesc_t smDesc)
 Get the destination for an OutStream. More...
 
CrFwSeqCnt_t CrFwOutStreamGetSeqCnt (FwSmDesc_t smDesc, CrFwGroup_t group)
 Return the value of the sequence counter for one of the groups maintained by an OutStream. More...
 
void CrFwOutStreamSetSeqCnt (FwSmDesc_t smDesc, CrFwGroup_t group, CrFwSeqCnt_t seqCnt)
 Sets the value of the sequence counter for one of the groups maintained by an OutStream. More...
 
CrFwCounterU1_t CrFwOutStreamGetNOfPendingPckts (FwSmDesc_t smDesc)
 Return the number of packets currently in the packet queue of an OutStream. More...
 
CrFwGroup_t CrFwOutStreamGetNOfGroups (FwSmDesc_t smDesc)
 Return the number of groups associated to the OutStream. More...
 
CrFwCounterU1_t CrFwOutStreamGetPcktQueueSize (FwSmDesc_t smDesc)
 Return the size of the packet queue of the OutStream. More...
 

Detailed Description

Definition of the OutStream component.

An application will normally instantiate one OutStream Component for each report or command destination. An OutStream is implemented by the OutStream State Machine (see figures below) embedded within state CONFIGURED of a Base State Machine.

This header file defines a function to create and access the OutStream attached to a certain command or report destination. This header file therefore also defines the interface to the OutStreamRegistry component of the CORDET Framework.

An application can instantiate several OutStream Components. Each OutStream instance has an identifier which uniquely identifies it within the set of OutStream Components. This identifier is an integer in the range 0 to: CR_FW_NOF_OUTSTREAM-1.

Mode of Use of an OutStream Component

The configuration of the OutStream components is defined statically in CrFwOutStreamUserPar.h.

An OutStream component is created with function CrFwOutStreamMake. After being created, the OutStream must be initialized and reset. This is done with functions CrFwCmpInit and CrFwCmpReset. Nominally, after being initialized and reset the OutStream State Machine should be in state CONFIGURED (this can be checked by verifying that function FwSmGetCurState returns CR_FW_BASE_STATE_CONFIGURED).

After it has been configured, an OutStream can process two transition commands:

  • A Send command to send a packet (representing either a command or a report) to the middleware connection attached to the OutStream. This command is sent through function CrFwOutStreamSend.
  • A ConnectionAvailable command to signal the ability of the middleware to send a new packet to its destination. This command is sent with the the CrFwOutStreamConnectionAvail function.

If at the time the Send command is received, the middleware is not ready to receive the packet, the packet is stored in Packet Queue. The next attempt to send it out will be made when command ConnectionAvailable is sent.

OutStream.png
Author
Vaclav Cechticky vacla.nosp@m.v.ce.nosp@m.chtic.nosp@m.ky@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m
Alessandro Pasetti paset.nosp@m.ti@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m

This file is part of the CORDET Framework.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

For information on alternative licensing, please contact P&P Software GmbH.

Definition in file CrFwOutStream.h.

Function Documentation

void CrFwOutStreamConnectionAvail ( FwSmDesc_t  smDesc)

Signal that the out-going middleware connection has become available.

This function sends the ConnectionAvailable command to the OutStream State Machine.

Parameters
smDescthe descriptor of the OutStream State Machine.

Definition at line 245 of file CrFwOutStream.c.

void CrFwOutStreamDefConfigAction ( FwPrDesc_t  prDesc)

Default configuration action for an OutStream.

This function resets the packet queue of the OutStream.

Configuration actions have an outcome (see CrFwResetProc.h). The outcome of this configuration action is always "success".

This function should never be directly called by the end-application. It is declared as a public function so that it may be used in application-specific Configuration Actions.

Parameters
prDescthe descriptor of the Reset Procedure of the OutStream

Definition at line 292 of file CrFwOutStream.c.

void CrFwOutStreamDefInitAction ( FwPrDesc_t  prDesc)

Default initialization action for an OutStream.

This function: (a) allocates the memory for the packet queue of the OutStream; (b) allocates the memory for the array holding the sequence counters for the groups attached to the OutStream; and (c) initializes all data structures implementing the OutStream. Initialization actions have an outcome (see CrFwResetProc.h). The situation of where the memory allocation fails is not handled and therefore the outcome of this configuration action is always "success".

This function should never be directly called by the end-application. It is declared as a public function so that it may be used in application-specific Initialization Actions.

Parameters
prDescthe descriptor of the Initialization Procedure of the OutStream

Definition at line 312 of file CrFwOutStream.c.

void CrFwOutStreamDefShutdownAction ( FwSmDesc_t  smDesc)

Default shutdown action for an OutStream.

This function releases the memory allocated to the packet queue of the OutStream and releases the memory allocated to the array holding the sequence counters.

This function should never be directly called by the end-application. It is declared as a public function so that it may be used in application-specific Shutdown Actions.

Parameters
smDescthe descriptor of the OutStream State Machine

Definition at line 303 of file CrFwOutStream.c.

FwSmDesc_t CrFwOutStreamGet ( CrFwDestSrc_t  dest)

Getter function for the OutStream corresponding to the argument destination.

Nominally, each OutStream is associated to a certain destination. The binding between an OutStream and its destination is done statically in the configuration file CrFwOutStreamUserPar.h.

If the value of the destination argument is illegal (i.e. if no OutStream has been bound to it), this function returns NULL and sets the application error code to: crOutStreamUndefDest.

This function should only be called after all OutStreams have been built through calls to function CrFwOutStreamMake. If this pre-condition is not satisfied, execution of this function could result in an access to a NULL pointer.

Parameters
destthe destination associated to the OutStream
Returns
the descriptor of the OutStream State Machine or NULL if the argument destination was illegal or no OutStream had been bound to it.

Definition at line 226 of file CrFwOutStream.c.

CrFwDestSrc_t CrFwOutStreamGetDest ( FwSmDesc_t  smDesc)

Get the destination for an OutStream.

Parameters
smDescthe descriptor of the OutStream State Machine.
Returns
dest the destination associated to the OutStream

Definition at line 250 of file CrFwOutStream.c.

CrFwGroup_t CrFwOutStreamGetNOfGroups ( FwSmDesc_t  smDesc)

Return the number of groups associated to the OutStream.

Parameters
smDescthe descriptor of the OutStream State Machine.
Returns
the number of groups associated to the OutStream.

Definition at line 279 of file CrFwOutStream.c.

CrFwCounterU1_t CrFwOutStreamGetNOfPendingPckts ( FwSmDesc_t  smDesc)

Return the number of packets currently in the packet queue of an OutStream.

Parameters
smDescthe descriptor of the OutStream State Machine.
Returns
the number of packets currently in the packet queue of the OutStream.

Definition at line 272 of file CrFwOutStream.c.

CrFwCounterU1_t CrFwOutStreamGetPcktQueueSize ( FwSmDesc_t  smDesc)

Return the size of the packet queue of the OutStream.

Parameters
smDescthe descriptor of the OutStream State Machine.
Returns
the size of the packet queue of the OutStream.

Definition at line 285 of file CrFwOutStream.c.

CrFwSeqCnt_t CrFwOutStreamGetSeqCnt ( FwSmDesc_t  smDesc,
CrFwGroup_t  group 
)

Return the value of the sequence counter for one of the groups maintained by an OutStream.

The group identifier is passed as an argument to the function call. No check is performed on the validity of the group identifier.

Parameters
smDescthe descriptor of the OutStream State Machine.
groupthe identifier of the group
Returns
the OutStream sequence counter

Definition at line 257 of file CrFwOutStream.c.

CrFwBool_t CrFwOutStreamIsInBuffering ( FwSmDesc_t  smDesc)

Return true if the argument OutStream is in state BUFFERING.

Parameters
smDescthe descriptor of the Base State Machine of the OutStream
Returns
1 if the argument InCommand is in state CONFIGURED, sub-state BUFFERING; 0 otherwise

Definition at line 221 of file CrFwOutStream.c.

CrFwBool_t CrFwOutStreamIsInReady ( FwSmDesc_t  smDesc)

Return true if the argument OutStream is in state READY.

Parameters
smDescthe descriptor of the Base State Machine of the OutStream
Returns
1 if the argument InCommand is in state CONFIGURED, sub-state READY; 0 otherwise

Definition at line 216 of file CrFwOutStream.c.

FwSmDesc_t CrFwOutStreamMake ( CrFwInstanceId_t  outStreamId)

Factory function to retrieve the i-th OutStream State Machine instance.

The first time this function is called with a certain value of the argument i, it creates the i-th OutStream State Machine instance. Subsequent calls returns the same instance.

The OutStream identifier i must be in the range: [0, CR_FW_NOF_OUTSTREAM-1]. If the identifier is out of range, the function returns NULL and sets the application error code to: crOutStreamIllId.

The first time this function is called with a certain value of i, it returns an OutStream State Machine which has been started but which still needs to be initialized and configured.

Parameters
outStreamIdthe identifier of the Base State Machine of the OutStream
Returns
the descriptor of the OutStream State Machine or NULL if the state machine could not be created or if the identifier i is out of range.

Definition at line 131 of file CrFwOutStream.c.

void CrFwOutStreamSend ( FwSmDesc_t  smDesc,
CrFwPckt_t  pckt 
)

Send a packet to the OutStream.

This function hands over the argument packet to the OutStream and then it sends command "Send" to its state machine. This causes the OutStream to try to send the packet to the destination associated to the OutStream. If the middleware is not ready to accept the packet, then a copy of the packet is made and is stored in the OutStream's Packet Queue from where it will be sent to the middleware at a later time. If the packet copy cannot be done because no more free packets are available, error crOutStreamNoMorePckt is generated. If the Packet Queue is full, the packet is released and error crOutStreamPQFull is generated.

If packet cannot be sent to the middleware (or to make a copy of the packet and buffer the copy internally if the middleware is currently not available).

The argument pckt is a pointer to the out-going packet. This pointer is "owned" by the caller of function CrFwOutStreamSend who remains responsible for releasing it when it is no longer needed. The function only uses the pointer during its execution.

Parameters
smDescthe descriptor of the OutStream State Machine.
pcktthe packet to be sent by the OutStream

Definition at line 237 of file CrFwOutStream.c.

void CrFwOutStreamSetSeqCnt ( FwSmDesc_t  smDesc,
CrFwGroup_t  group,
CrFwSeqCnt_t  seqCnt 
)

Sets the value of the sequence counter for one of the groups maintained by an OutStream.

The group identifier is passed as an argument to the function call. No check is performed on the validity of the group identifier.

Parameters
smDescthe descriptor of the OutStream State Machine.
groupthe identifier of the group
seqCntthe OutStream sequence counter

Definition at line 264 of file CrFwOutStream.c.

P&P Software GmbH, Copyright 2012-2013, All Rights Reserved