CORDET Framework - C2 Implementation

Definition of the InCommand Component of the framework. More...

Go to the source code of this file.

Functions

FwSmDesc_t CrFwInCmdMakeBase ()
 Return the base InCommand from which all other InCommands are derived. More...
 
void CrFwInCmdTerminate (FwSmDesc_t smDesc)
 Send command Terminate to the argument InCommand. More...
 
CrFwBool_t CrFwInCmdIsInAccepted (FwSmDesc_t smDesc)
 Return true if the argument InCommand is in state ACCEPTED. More...
 
CrFwBool_t CrFwInCmdIsInProgress (FwSmDesc_t smDesc)
 Return true if the argument InCommand is in state PROGRESS. More...
 
CrFwBool_t CrFwInCmdIsInTerminated (FwSmDesc_t smDesc)
 Return true if the argument InCommand is in state TERMINATED. More...
 
CrFwBool_t CrFwInCmdIsInAborted (FwSmDesc_t smDesc)
 Return true if the argument InCommand is in state ABORTED. More...
 
void CrFwInCmdConfigCheck (FwPrDesc_t prDesc)
 Configuration check for an InCommand. More...
 
CrFwProgressStepId_t CrFwInCmdGetProgressStepId (FwSmDesc_t smDesc)
 Return the progress step identifier of the InCommand. More...
 
void CrFwInCmdSetProgressStepId (FwSmDesc_t smDesc, CrFwProgressStepId_t stepId)
 Set the progress step identifier of the InCommand. More...
 
CrFwBool_t CrFwInCmdIsProgressActionCompleted (FwSmDesc_t smDesc)
 Return the Completion Outcome of the progress action. More...
 
void CrFwInCmdSetProgressActionCompleted (FwSmDesc_t smDesc, CrFwBool_t progressActionCompleted)
 Set the Completion Outcome of the progress action. More...
 
CrFwProgressStepId_t CrFwInCmdGetNOfProgressFailure (FwSmDesc_t smDesc)
 Return the number of progress step failures. More...
 
CrFwDestSrc_t CrFwInCmdGetSrc (FwSmDesc_t smDesc)
 Return the source of the InCommand. More...
 
CrFwGroup_t CrFwInCmdGetGroup (FwSmDesc_t smDesc)
 Return the group of the InCommand. More...
 
CrFwServType_t CrFwInCmdGetServType (FwSmDesc_t smDesc)
 Return the type of the InCommand. More...
 
CrFwServType_t CrFwInCmdGetServSubType (FwSmDesc_t smDesc)
 Return the sub-type of the InCommand. More...
 
CrFwDiscriminant_t CrFwInCmdGetDiscriminant (FwSmDesc_t smDesc)
 Return the discriminant of the InCommand. More...
 
CrFwBool_t CrFwInCmdIsAcceptAck (FwSmDesc_t smDesc)
 Return the acknowledge level for command acceptance for the command encapsulated in the InCommand. More...
 
CrFwBool_t CrFwInCmdIsStartAck (FwSmDesc_t smDesc)
 Return the acknowledge level for command start for the command encapsulated in the InCommand. More...
 
CrFwBool_t CrFwInCmdIsProgressAck (FwSmDesc_t smDesc)
 Return the acknowledge level for command progress for the command encapsulated in the InCommand. More...
 
CrFwBool_t CrFwInCmdIsTermAck (FwSmDesc_t smDesc)
 Return the acknowledge level for command termination for the command encapsulated in the InCommand. More...
 
CrFwSeqCnt_t CrFwInCmdGetSeqCnt (FwSmDesc_t smDesc)
 Return the sequence counter of the InCommand. More...
 
CrFwPckt_t CrFwInCmdGetParStart (FwSmDesc_t smDesc)
 Return the start address of the parameter area of the InCommand. More...
 
CrFwPckt_t CrFwInCmdGetPckt (FwSmDesc_t smDesc)
 Return the pointer to the packet which holds the InCommand. More...
 
CrFwPcktLength_t CrFwInCmdGetParLength (FwSmDesc_t smDesc)
 Return the length in bytes of the parameter area of the InCommand. More...
 
CrFwPckt_t CrFwInCmdGetPcktFromPrDesc (FwPrDesc_t prDesc)
 Convenience function to extract the InCommand's packet from the descriptor of the InCommand's reset procedure. More...
 
CrFwBool_t CrFwInCmdDefValidityCheck (FwPrDesc_t prDesc)
 Default implementation of the validity check of an InCommand. More...
 

Detailed Description

Definition of the InCommand Component of the framework.

An InCommand encapsulates an incoming command in a service provider application. The InCommand is responsible for storing the attributes of an incoming command and for executing the conditional checks and actions associated to the command. The behaviour of an InCommand is defined by the InCommand State Machine (see figure below) embedded within state CONFIGURED of a Base Component State Machine.

Mode of Use of an InCommand Component

InCommands are created dynamically by the InLoader when it processes an incoming packet which holds a command. The InCommand component is created through a call to the factory function CrFwInFactoryMakeInCmd. The InLoader loads the InCommand into an InManager who is then responsible for executing it and, eventually, for returning it to the InFactory.

An InCommand encapsulates an incoming command of a certain kind. The "kind" of an incoming command is defined by the triplet: [service type, service sub-type, discriminant]. InCommands are adapted to a certain incoming command kind by modifying one or more of the following:

  • The Validity Check Operation
  • The Ready Check Operation
  • The Start Action Operation
  • The Progress Action Operation
  • The Termination Action Operation
  • The Abort Action Operation

These operations are statically defined for each kind of InCommand in CrFwInFactoryUserPar.h.

This header file defines default values for all configurable operations listed above with the exception of the Configuration Check Operation for which the default is the function CrFwBaseCmpDefConfigCheck.

InCommand.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 CrFwInCmd.h.

Function Documentation

void CrFwInCmdConfigCheck ( FwPrDesc_t  prDesc)

Configuration check for an InCommand.

This function executes the Validity Check of the InCommand and sets the action outcome to 1 if the Validity Check returns true and sets it to zero if it returns false. This function is only intended to be used by the InFactory (see CrFwInFactory.h) and should not be used by applications.

Parameters
prDescthe descriptor of the InCommand Configuration Procedure

Definition at line 175 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdDefValidityCheck ( FwPrDesc_t  prDesc)

Default implementation of the validity check of an InCommand.

The validity check of an InCommand must conform to the CrFwInCmdValidityCheck_t function prototype. This default implementation verifies the correctness of the CRC of the packet which carries the command. The CRC is processed using the CRC functions defined by interface CrFwPckt.h.

Parameters
prDescthe descriptor of the InCommand's Reset Procedure
Returns
true if the CRC of the InCommand packet is correct

Definition at line 436 of file CrFwInCmd.c.

CrFwDiscriminant_t CrFwInCmdGetDiscriminant ( FwSmDesc_t  smDesc)

Return the discriminant of the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the discriminant of the InCommand

Definition at line 352 of file CrFwInCmd.c.

CrFwGroup_t CrFwInCmdGetGroup ( FwSmDesc_t  smDesc)

Return the group of the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the group of the InCommand

Definition at line 331 of file CrFwInCmd.c.

CrFwProgressStepId_t CrFwInCmdGetNOfProgressFailure ( FwSmDesc_t  smDesc)

Return the number of progress step failures.

A progress step failure occurs when the progress action is executed and it returns with the outcome of "failed" (see CrFwInCmdProgressAction_t). Normally, a progress step failure should only be reported at the end of a progress step. but this constraint is not enforced by the framework. It is the responsibility of the application to update the progress step identifier when a progress step has failed.

The number of progress steps which failed is initialized to zero when the InCommand is instantiated and is incremented by 1 every time a progress step has a "failed" outcome.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the number of progress steps which have failed.

Definition at line 429 of file CrFwInCmd.c.

CrFwPcktLength_t CrFwInCmdGetParLength ( FwSmDesc_t  smDesc)

Return the length in bytes of the parameter area of the InCommand.

The InCommand is encapsulated in a packet. The parameter area of the InCommand is the part of the packet which is reserved to the storage of the parameters of the InCommand. The parameter area consists of an uninterrupted sequence of bytes. The start address of the parameter area is returned by function CrFwInCmdGetParStart.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the length in bytes of the InCommand parameter area

Definition at line 401 of file CrFwInCmd.c.

CrFwPckt_t CrFwInCmdGetParStart ( FwSmDesc_t  smDesc)

Return the start address of the parameter area of the InCommand.

The InCommand is encapsulated in a packet. The parameter area of the InCommand is the part of the packet which is reserved to the storage of the parameters of the InCommand. The parameter area consists of an uninterrupted sequence of bytes. The size of the parameter area is returned by function CrFwInCmdGetParLength.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the start address of the InCommand parameter area.

Definition at line 394 of file CrFwInCmd.c.

CrFwPckt_t CrFwInCmdGetPckt ( FwSmDesc_t  smDesc)

Return the pointer to the packet which holds the InCommand.

The InCommand is encapsulated in a packet. This function returns this packet. The packet is only initialized if the InCommand has been correctly de-serialized. This is normally the case if the InCommand has been successfully returned by the InFactory. The length of the packet is stored in the packet itself and can be retrieved with function CrFwPcktGetLength.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the pointer to the packet holding the InCommand.

Definition at line 408 of file CrFwInCmd.c.

CrFwPckt_t CrFwInCmdGetPcktFromPrDesc ( FwPrDesc_t  prDesc)

Convenience function to extract the InCommand's packet from the descriptor of the InCommand's reset procedure.

One situation where this function is useful is as follows. One of the adaptation points of an InCommand is its Validity Check Operation. The Validity Check Operation is implemented by a function of type CrFwInRepValidityCheck_t. This function takes as an argument the descriptor of the InCommand's Reset Procedure. Applications will often have to provide an implementation of this function and, to do so, they will often need to access the packet holding the InCommand so as to access the InCommand's parameters, The present function offers an easy way to retrieve this packet.

Parameters
prDescthe descriptor of the InCommand's Reset Procedure
Returns
the packet holding the InCommand

Definition at line 200 of file CrFwInCmd.c.

CrFwProgressStepId_t CrFwInCmdGetProgressStepId ( FwSmDesc_t  smDesc)

Return the progress step identifier of the InCommand.

The progress step identifier is a non-negative integer which identifies the current progress step of the InCommand. A Progress Step is a set of logically related execution steps of the InCommand which are executed in sequence.

At framework level, the Progress Step Identifier is initialized to 0 and is never updated afterwards. Applications would normally set its initial value in the Start Action and would increment its value in the Progress Action.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the progress step

Definition at line 186 of file CrFwInCmd.c.

CrFwSeqCnt_t CrFwInCmdGetSeqCnt ( FwSmDesc_t  smDesc)

Return the sequence counter of the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the sequence counter of the InCommand

Definition at line 387 of file CrFwInCmd.c.

CrFwServType_t CrFwInCmdGetServSubType ( FwSmDesc_t  smDesc)

Return the sub-type of the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the sub-type of the InCommand

Definition at line 345 of file CrFwInCmd.c.

CrFwServType_t CrFwInCmdGetServType ( FwSmDesc_t  smDesc)

Return the type of the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the type of the InCommand

Definition at line 338 of file CrFwInCmd.c.

CrFwDestSrc_t CrFwInCmdGetSrc ( FwSmDesc_t  smDesc)

Return the source of the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the source of the InCommand

Definition at line 324 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsAcceptAck ( FwSmDesc_t  smDesc)

Return the acknowledge level for command acceptance for the command encapsulated in the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
1 if command acceptance is to be acknowledged, 0 otherwise.

Definition at line 359 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsInAborted ( FwSmDesc_t  smDesc)

Return true if the argument InCommand is in state ABORTED.

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

Definition at line 170 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsInAccepted ( FwSmDesc_t  smDesc)

Return true if the argument InCommand is in state ACCEPTED.

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

Definition at line 155 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsInProgress ( FwSmDesc_t  smDesc)

Return true if the argument InCommand is in state PROGRESS.

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

Definition at line 160 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsInTerminated ( FwSmDesc_t  smDesc)

Return true if the argument InCommand is in state TERMINATED.

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

Definition at line 165 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsProgressAck ( FwSmDesc_t  smDesc)

Return the acknowledge level for command progress for the command encapsulated in the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
1 if command progress is to be acknowledged, 0 otherwise.

Definition at line 373 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsProgressActionCompleted ( FwSmDesc_t  smDesc)

Return the Completion Outcome of the progress action.

The progress action is executed in steps. If the completion outcome is set to 0, then at least one more execution step must be run before the progress action can be deemed to be completed. If, instead, the completion outcome is set to 1, then the most recently executed step was the last step and the progress action is completed.

At framework level, the Completion Outcome is initialized to 1 and is never updated afterwards. This means that, by default, the progress action of an incoming command is completed in one single execution step. Applications would normally set the Completiong Outcome in the Progress Action.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
the completion outcome

Definition at line 415 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsStartAck ( FwSmDesc_t  smDesc)

Return the acknowledge level for command start for the command encapsulated in the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
1 if command start is to be acknowledged, 0 otherwise.

Definition at line 366 of file CrFwInCmd.c.

CrFwBool_t CrFwInCmdIsTermAck ( FwSmDesc_t  smDesc)

Return the acknowledge level for command termination for the command encapsulated in the InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
Returns
1 if command termination is to be acknowledged, 0 otherwise.

Definition at line 380 of file CrFwInCmd.c.

FwSmDesc_t CrFwInCmdMakeBase ( )

Return the base InCommand from which all other InCommands are derived.

The base InCommand is a singleton. The first time it is called, this function creates and configures the base InCommand instance. Subsequent calls return this same instance. This function is only intended to be used by the InFactory (see CrFwInFactory.h) and should not be used by applications.

Returns
the singleton instance of the base InCommand

Definition at line 110 of file CrFwInCmd.c.

void CrFwInCmdSetProgressActionCompleted ( FwSmDesc_t  smDesc,
CrFwBool_t  progressActionCompleted 
)

Set the Completion Outcome of the progress action.

This function would typically be used by the InCommand's Progress Action.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
progressActionCompletedthe completion outcome

Definition at line 422 of file CrFwInCmd.c.

void CrFwInCmdSetProgressStepId ( FwSmDesc_t  smDesc,
CrFwProgressStepId_t  stepId 
)

Set the progress step identifier of the InCommand.

This function would typically be used by the InCommand's Start Action to initialize the progress step identifier and by the Progress Action to update its value.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand
stepIdthe step identifier

Definition at line 193 of file CrFwInCmd.c.

void CrFwInCmdTerminate ( FwSmDesc_t  smDesc)

Send command Terminate to the argument InCommand.

Parameters
smDescthe descriptor of the Base State Machine of the InCommand

Definition at line 150 of file CrFwInCmd.c.

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