CORDET Framework - C2 Implementation

Definition of the OutRegistry Component. More...

Go to the source code of this file.

Enumerations

enum  CrFwOutRegistryCmdRepState_t {
  crOutRegistryNoEntry = 0 , crOutRegistryPending = 1 , crOutRegistryAborted = 2 , crOutRegistryTerminated = 3 ,
  crOutRegistryNotTracked = 4
}
 Enumerated type for the state of an out-going command or report tracked by the OutRegistry. More...
 

Functions

FwSmDesc_t CrFwOutRegistryMake ()
 Factory function for the singleton instance of the OutRegistry. More...
 
CrFwServType_t CrFwOutRegistryGetServType (CrFwCmdRepIndex_t cmdRepIndex)
 Get the service type of the argument command or report index. More...
 
CrFwServSubType_t CrFwOutRegistryGetServSubType (CrFwCmdRepIndex_t cmdRepIndex)
 Get the service sub-type of the argument command or report index. More...
 
CrFwDiscriminant_t CrFwOutRegistryGetLowerDiscriminant (CrFwCmdRepIndex_t cmdRepIndex)
 Get the lower bound of the argument command or report index. More...
 
CrFwDiscriminant_t CrFwOutRegistryGetUpperDiscriminant (CrFwCmdRepIndex_t cmdRepIndex)
 Get the upper bound of the argument command or report index. More...
 
CrFwBool_t CrFwOutRegistryIsDiscriminantEnabled (CrFwCmdRepIndex_t cmdRepIndex, CrFwDiscriminant_t disc)
 Get the enable status of a discriminant in the argument command or report index. More...
 
CrFwCmdRepIndex_t CrFwOutRegistryGetCmdRepIndex (CrFwServType_t servType, CrFwServSubType_t servSubType)
 Get the index corresponding to the argument [service type, service sub-type] of an out-going command or report. More...
 
void CrFwOutRegistrySetEnable (CrFwServType_t servType, CrFwServSubType_t servSubType, CrFwDiscriminant_t discriminant, CrFwBool_t isEnabled)
 Set the enable state of a set of out-going commands or reports. More...
 
CrFwBool_t CrFwOutRegistryIsEnabled (FwSmDesc_t outCmp)
 Query the enable status of an out-going command or report. More...
 
void CrFwOutRegistryStartTracking (FwSmDesc_t outCmp)
 Ask the OutRegistry to start tracking an out-going command or report. More...
 
void CrFwOutRegistryUpdateState (FwSmDesc_t outCmp, CrFwOutRegistryCmdRepState_t newState)
 Ask the OutRegistry to update the state of an out-going command or report. More...
 
CrFwOutRegistryCmdRepState_t CrFwOutRegistryGetState (CrFwInstanceId_t cmdRepId)
 Query the OutRegistry for the state of an out-going command or report. More...
 

Detailed Description

Definition of the OutRegistry Component.

An OutRegistry acts as a registry for out-going commands or reports (namely for commands or reports which have been loaded into an OutManager). The OutRegistry is responsible for:

  • keeping track of an out-going command's or report's state
  • storing the enable state of out-going commands or reports
  • storing the link between the index of an out-going command or report and its service type and sub-type

The index of an out-going command or report is a positive integer in the range from 0 to CR_FW_OUTREGISTRY_NSERV-1. CR_FW_OUTREGISTRY_NSERV is the total number of out-going service types and sub-types in an application. The index of an out-going command or report uniquely identifies the command's or report's type and sub-type.

The set of out-going service types and sub-types supported by an application is specified in CrFwOutRegistryUserPar.h.

The framework internally uses the index as a more efficient way of identifying a pair [service type, service sub-type] for an out-going command or report. The OutRegistry offers a function which allows the service type and service sub-type associated to a certain index to be retrieved.

The OutRegistry is a singleton component which is implemented as an extension of the Base Component of CrFwBaseCmp.h.

The OutRegistry maintains a list of the last N commands or reports to have been loaded in an OutManager. The OutRegistry maintains the state of each such command or report. The command's or report's state in the OutRegistry can have one of the following values:

  • PENDING: the command or report is waiting to be sent
  • ABORTED: the command or report was aborted because it was disabled when it was loaded
  • TERMINATED: the command or report has been passed to the OutStream

The value of N (the maximum number of items which can be tracked by the OutRegistry) is fixed and is an initialization parameter.

The OutRegistry uses the instance identifier of the OutComponent encapsulating the out-going report or command as the key through which the out-going command or report state is tracked.

The OutRegistry stores the enable state of out-going commands and reports. The enable state of out-going command and reports can be controlled at three levels:

  • At the level of the service type (all commands or reports of a certain type are disabled)
  • At the level of the service sub-type (all commands or reports matching a certain [type, sub-type] pair are disabled)
  • At the level of the discriminant (all commands or reports matching a certain [type, sub-type, discriminant] triplet are enabled or disabled)

The enable state of a particular out-going command or report is derived from these three enable levels by running the Enable State Determination Procedure shown in the figure below. The OutRegistry offers functions through which all three levels of enable state can be controlled and through which the enable state of a specific out-going command or report can be determined. By default, the enable state for all kinds of reports or commands is set to: "enabled".

Mode of Use of an OutRegistry Component

The configuration of the OutRegistry component is defined statically in CrFwOutRegistryUserPar.h.

The OutRegistry component is a "final" component that does not normally need to be extended.

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

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 CrFwOutRegistry.h.

Enumeration Type Documentation

◆ CrFwOutRegistryCmdRepState_t

Enumerated type for the state of an out-going command or report tracked by the OutRegistry.

Enumerator
crOutRegistryNoEntry 

No entry yet in OutRegistry.

crOutRegistryPending 

Out-going command or report is pending (waiting to be sent)

crOutRegistryAborted 

Out-going command or report has been aborted.

crOutRegistryTerminated 

Out-going command or report has been passed to the OutStream.

crOutRegistryNotTracked 

Out-going command or report is not tracked.

Definition at line 106 of file CrFwOutRegistry.h.

Function Documentation

◆ CrFwOutRegistryGetCmdRepIndex()

CrFwCmdRepIndex_t CrFwOutRegistryGetCmdRepIndex ( CrFwServType_t  servType,
CrFwServSubType_t  servSubType 
)

Get the index corresponding to the argument [service type, service sub-type] of an out-going command or report.

For out-going commands or reports the index uniquely identifies a pair: [service type, service sub-type]. This function returns the index corresponding to a specific [service type, service sub-type] pair. If either of the two arguments has an illegal value (i.e. if it has a value which does not correspond to any [service type, service sub-type] declared in the initializer of the service descriptor CR_FW_OUTREGISTRY_INIT_SERV_DESC.), the function returns CR_FW_OUTREGISTRY_NSERV.

Parameters
servTypethe service type
servSubTypethe service sub-type
Returns
cmdRepIndex the command or report index or CR_FW_OUTREGISTRY_NSERV if the specified [type, sub-type] does not exist

Definition at line 167 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryGetLowerDiscriminant()

CrFwDiscriminant_t CrFwOutRegistryGetLowerDiscriminant ( CrFwCmdRepIndex_t  cmdRepIndex)

Get the lower bound of the argument command or report index.

For out-going commands or reports the index uniquely identifies a pair: [service type, service sub-type]. This function returns the lower discriminant value corresponding to a certain index value. If the index value is out of range (i.e. if it is greater than CR_FW_OUTREGISTRY_NSERV-1), the behaviour of this function is undefined.

Parameters
cmdRepIndexthe command or report index
Returns
the lower discriminant bound corresponding to the command or report index

Definition at line 156 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryGetServSubType()

CrFwServSubType_t CrFwOutRegistryGetServSubType ( CrFwCmdRepIndex_t  cmdRepIndex)

Get the service sub-type of the argument command or report index.

For out-going commands or reports the index uniquely identifies a pair: [service type, service sub-type]. This function returns the service sub-type corresponding to a certain index value. If the index value is out of range (i.e. if it is greater than CR_FW_OUTREGISTRY_NSERV-1), the behaviour of this function is undefined.

Parameters
cmdRepIndexthe command or report index
Returns
the service type corresponding to the command or report index

Definition at line 146 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryGetServType()

CrFwServType_t CrFwOutRegistryGetServType ( CrFwCmdRepIndex_t  cmdRepIndex)

Get the service type of the argument command or report index.

For out-going commands or reports the index uniquely identifies a pair: [service type, service sub-type]. This function returns the service type corresponding to a certain index value. If the index value is out of range (i.e. if it is greater than CR_FW_OUTREGISTRY_NSERV-1), the behaviour of this function is undefined.

Parameters
cmdRepIndexthe command or report index
Returns
the service type corresponding to the command or report index

Definition at line 141 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryGetState()

CrFwOutRegistryCmdRepState_t CrFwOutRegistryGetState ( CrFwInstanceId_t  cmdRepId)

Query the OutRegistry for the state of an out-going command or report.

If the specified index does not correspond to any command or report being tracked by the OutRegistry, a value of crOutRegistryNotTracked is returned. This function searches all locations in the InRegistry in sequence until it finds the out-going command or report.

Parameters
cmdRepIdthe instance identifier of the out-going command or report.
Returns
the state of the out-going command or report (or crOutRegistryNotTracked if the command or report is not tracked)

Definition at line 307 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryGetUpperDiscriminant()

CrFwDiscriminant_t CrFwOutRegistryGetUpperDiscriminant ( CrFwCmdRepIndex_t  cmdRepIndex)

Get the upper bound of the argument command or report index.

For out-going commands or reports the index uniquely identifies a pair: [service type, service sub-type]. This function returns the upper discriminant value corresponding to a certain index value. If the index value is out of range (i.e. if it is greater than CR_FW_OUTREGISTRY_NSERV-1), the behaviour of this function is undefined.

Parameters
cmdRepIndexthe command or report index
Returns
the upper discriminant bound corresponding to the command or report index

Definition at line 151 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryIsDiscriminantEnabled()

CrFwBool_t CrFwOutRegistryIsDiscriminantEnabled ( CrFwCmdRepIndex_t  cmdRepIndex,
CrFwDiscriminant_t  disc 
)

Get the enable status of a discriminant in the argument command or report index.

For out-going commands or reports the index uniquely identifies a pair: [service type, service sub-type]. For each [service type, service sub-type], the OutRegistry stores the range of discriminant values and stores the current enable type of each discriminant value (the boudanries of the range are returned by functions CrFwOutRegistryGetUpperDiscriminant and CrFwOutRegistryGetLowerDiscriminant). This function returns the enable status of a discriminant in that range.

If the index value is out of range (i.e. if it is greater than CR_FW_OUTREGISTRY_NSERV-1) or if the argument discriminant is out of range (i.e. if it is outside the interval [l,u] where l and u are the return values of CrFwOutRegistryGetUpperDiscriminant and CrFwOutRegistryGetLowerDiscriminant), or if there are no discriminants associated to the argument command or report index, the behaviour of this function is undefined.

Parameters
cmdRepIndexthe command or report index
discthe value of the discriminant
Returns
the enable status of the i-th discriminant in the discriminant range of the command or report index

Definition at line 161 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryIsEnabled()

CrFwBool_t CrFwOutRegistryIsEnabled ( FwSmDesc_t  outCmp)

Query the enable status of an out-going command or report.

If the argument does not represent an out-going command or report (i.e. if it is not a component of type OutComponent), the behaviour of the function is undefined. The enable state of an out-going command or report is determined by running the Enable State Determination Procedure shown in the figure.

Parameters
outCmpthe out-going command or report as an OutComponent
Returns
the enable state of the specified command or report (1 means enabled and 0 means disabled)

Definition at line 257 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryMake()

FwSmDesc_t CrFwOutRegistryMake ( )

Factory function for the singleton instance of the OutRegistry.

The first time this function is called, it creates and configures the OutRegistry. Subsequent calls returns the same singleton instance. The first time this function is called, it returns the OutRegistry in state CREATED.

If the creation or the configuration of the OutRegistry fails, the function returns NULL.

Returns
singleton instance of the OutRegistry or NULL if the creation or configuration of the OutRegistry failed.

Definition at line 97 of file CrFwOutRegistry.c.

◆ CrFwOutRegistrySetEnable()

void CrFwOutRegistrySetEnable ( CrFwServType_t  servType,
CrFwServSubType_t  servSubType,
CrFwDiscriminant_t  discriminant,
CrFwBool_t  isEnabled 
)

Set the enable state of a set of out-going commands or reports.

The enable state of out-going command and reports can be controlled at three levels:

  • At the level of the service type (all commands or reports of a certain type are disabled)
  • At the level of the service sub-type (all commands or reports matching a certain [type, sub-type] pair are disabled)
  • At the level of the discriminant (all commands or reports matching a certain [type, sub-type, discriminant] triplet are enabled or disabled)

This function allows all three enable levels to be set according to the logic in the activity diagram shown below. Use of illegal values for the function parameters results in the application error code being set to: crIllServType (if the service type is illegal), or to crIllServSubType (if the service sub-type is illegal), or to crIllDiscriminant (if the discriminant value is illegal). A service type or sub-type or a discriminant value are illegal if they are not covered in the list of [type, sub-types, discriminant] in the CrFwOutRegistryUserPar.h (see CR_FW_OUTREGISTRY_INIT_SERV_DESC).

Parameters
servTypethe service type
servSubTypethe service type
discriminantthe discriminant
isEnabledthe enable state (1 means enabled and 0 means disabled)

Definition at line 193 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryStartTracking()

void CrFwOutRegistryStartTracking ( FwSmDesc_t  outCmp)

Ask the OutRegistry to start tracking an out-going command or report.

The OutRegistry tracks the state of the last N out-going command or reports to have been loaded with this function. Initially, when this function is called, the out-going command or report is placed in state PENDING. This function runs the procedure in the left-hand side of the activity diagram shown in the figure.

Parameters
outCmpthe out-going command or report to be tracked

Definition at line 278 of file CrFwOutRegistry.c.

◆ CrFwOutRegistryUpdateState()

void CrFwOutRegistryUpdateState ( FwSmDesc_t  outCmp,
CrFwOutRegistryCmdRepState_t  newState 
)

Ask the OutRegistry to update the state of an out-going command or report.

If the argument component is not tracked by the OutRegistry (perhaps because too many OutComponents have been added to the list of tracked components), nothing is done. This function runs the procedure in the right-hand side of the activity diagram shown in the figure.

Parameters
outCmpthe out-going command or report to be tracked
newStatethe new state of the out-going command or report

Definition at line 294 of file CrFwOutRegistry.c.

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