FW Profile - C1 Implementation
FwPrConfig.h File Reference

Declaration of the configuration interface for a FW Procedure. More...

Go to the source code of this file.

Functions

void FwPrSetData (FwPrDesc_t prDesc, void *prData)
 Set the pointer to the procedure data in the procedure descriptor. More...
 
void * FwPrGetData (FwPrDesc_t prDesc)
 Get the pointer to the procedure data in the procedure descriptor. More...
 
void FwPrAddActionNode (FwPrDesc_t prDesc, FwPrCounterS1_t nodeId, FwPrAction_t action)
 Create an action node with the given characteristics and add it to a procedure. More...
 
void FwPrAddDecisionNode (FwPrDesc_t prDesc, FwPrCounterS1_t nodeId, FwPrCounterS1_t nOfOutFlows)
 Create a decision node with the given characteristics and add it to a procedure. More...
 
void FwPrAddFlowIniToAct (FwPrDesc_t prDesc, FwPrCounterS1_t destId, FwPrGuard_t cfGuard)
 Create a control flow from the initial node to an action node and add it to a procedure. More...
 
void FwPrAddFlowIniToDec (FwPrDesc_t prDesc, FwPrCounterS1_t destId, FwPrGuard_t cfGuard)
 Create a control flow from the initial node to a decision node and add it to a procedure. More...
 
void FwPrAddFlowActToAct (FwPrDesc_t prDesc, FwPrCounterS1_t srcId, FwPrCounterS1_t destId, FwPrGuard_t cfGuard)
 Create a control flow from an action node to another action node and add it to a procedure. More...
 
void FwPrAddFlowActToDec (FwPrDesc_t prDesc, FwPrCounterS1_t srcId, FwPrCounterS1_t destId, FwPrGuard_t cfGuard)
 Create a control flow from an action node to a decision node and add it to a procedure. More...
 
void FwPrAddFlowDecToAct (FwPrDesc_t prDesc, FwPrCounterS1_t srcId, FwPrCounterS1_t destId, FwPrGuard_t cfGuard)
 Create a control flow from a decision node to an action node and add it to a procedure. More...
 
void FwPrAddFlowDecToDec (FwPrDesc_t prDesc, FwPrCounterS1_t srcId, FwPrCounterS1_t destId, FwPrGuard_t cfGuard)
 Create a control flow from a decision node to another decision node and add it to a procedure. More...
 
void FwPrAddFlowActToFin (FwPrDesc_t prDesc, FwPrCounterS1_t srcId, FwPrGuard_t cfGuard)
 Create a control flow from an action node to the final node and add it to a procedure. More...
 
void FwPrAddFlowDecToFin (FwPrDesc_t prDesc, FwPrCounterS1_t srcId, FwPrGuard_t cfGuard)
 Create a control flow from a decision node to the final node and add it to a procedure. More...
 
FwPrErrCode_t FwPrCheck (FwPrDesc_t prDesc)
 Check the correctness and completeness of the configuration of a procedure descriptor. More...
 
void FwPrOverrideAction (FwPrDesc_t prDesc, FwPrAction_t oldAction, FwPrAction_t newAction)
 Override an action in a derived procedure. More...
 
void FwPrOverrideGuard (FwPrDesc_t prDesc, FwPrGuard_t oldGuard, FwPrGuard_t newGuard)
 Override a guard in a derived procedure. More...
 

Detailed Description

Declaration of the configuration interface for a FW Procedure.

A FW Procedure is described by a procedure descriptor. The functions declared in this interface allow a procedure descriptor to be configured. During the configuration process, the action nodes, the decision nodes and the control flows of the procedure are defined.

There are two types of procedures: newly created procedures (i.e. procedures which are created from scratch using FwPrCreate or FW_PR_INST) and derived procedures (i.e. procedures which are created by extending another procedure through calls to FwPrCreateDer or FW_PR_INST_DER). The functions declared in this header file can be used to configure both types of procedures.

In the case of a newly created procedure, the mode of use of the functions in this header file is as follows:

  1. The action nodes of the procedure are added to its descriptor with the FwPrAddActionNode function.
  2. The decision nodes of the procedure are added to its descriptor with the FwPrAddDecisionNode function.
  3. The control flows of the procedures are added to the procedure with the FwPrAddFlow* functions (there are several of these functions, one for each type of control flow source and destination).
  4. The pointer to the procedure data in the procedure descriptor is set with the FwPrSetData function.
  5. The consistency and completeness of the procedure configuration may optionally be verified with function FwPrCheck.

The only constraint on the order in which the above functions are called is that a control flow from an action node or decision node can only be defined after the source action node or decision node has been defined.

In the case of a derived procedure, the mode of use of the functions declared in this header file is as follows:

  1. An action can be overridden with the FwPrOverrideAction function.
  2. A guard can be overridden with the FwPrOverrideGuard function.
  3. The consistency and completeness of the configuration of the derived procedure may optionally be verified with function FwPrCheck.

There are no constraints on the order in which the above functions are called.

Error handling is done as follows:

  • Errors are reported through error codes. The range of error codes is defined in header file FwPrConstant.h. The error code is stored in the procedure descriptor (see FwPrGetErrCode).
  • If an illegal input value could cause a corruption of the internal data structures of a procedure descriptor, a check is performed on the input parameter value and the function is aborted if this is found to be illegal.
  • When a function takes a procedure descriptor as an argument, no check is performed that the argument is non-NULL and valid (e.g. if a configuration function is called with a NULL value for the procedure descriptor argument, this error is not handled and the call will probably result in a segmentation fault).
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 FW Profile.

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

Function Documentation

void FwPrAddActionNode ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  nodeId,
FwPrAction_t  action 
)

Create an action node with the given characteristics and add it to a procedure.

This function reports the following errors in the error code of the procedure descriptor:

  • prIllActNodeId: illegal value of the action node identifier
  • prActNodeIdInUse: an action node with this identifier has already been defined
  • prTooManyOutFlows: there is no space left in the procedure descriptor for the out-going control flow of this node
  • prTooManyActions: there is no space left in the procedure descriptor for the action of this node
  • prNullAction: the action associated to this node is a NULL pointer
Parameters
prDescthe procedure to which the action node is added.
nodeIdthe identifier of the action node to be added (an integer in the range [1,N] where N is the number of action nodes in the procedure).
actionthe action for the new action node (a function pointer).

Definition at line 92 of file FwPrConfig.c.

void FwPrAddDecisionNode ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  nodeId,
FwPrCounterS1_t  nOfOutFlows 
)

Create a decision node with the given characteristics and add it to a procedure.

This function reports the following errors in the error code of the procedure descriptor:

Parameters
prDescthe descriptor of the procedure to which the decision node is added.
nodeIdthe identifier of the decision node to be added (an integer in the range [1,N] where N is the number of decision nodes).
nOfOutFlowsthe number of outgoing control flows from the new action node (a positive integer greater than 1).

Definition at line 134 of file FwPrConfig.c.

void FwPrAddFlowActToAct ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  srcId,
FwPrCounterS1_t  destId,
FwPrGuard_t  cfGuard 
)

Create a control flow from an action node to another action node and add it to a procedure.

This function should only be performed after the source action node of the control flow has been added to the procedure. This function reports the following errors in the error code of the procedure descriptor:

  • prIllFlowSrc: the identifier of the source of this control flow has an illegal value
  • prUndefinedFlowSrc: the source of this control flow has not yet been added to the procedure
  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
srcIdthe identifier of the source action node of the control flow (an integer in the range [1,N] where N is the number of action nodes).
destIdthe identifier of the destination action node of the control flow (an integer in the range [1,N] where N is the number of action nodes).
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 185 of file FwPrConfig.c.

void FwPrAddFlowActToDec ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  srcId,
FwPrCounterS1_t  destId,
FwPrGuard_t  cfGuard 
)

Create a control flow from an action node to a decision node and add it to a procedure.

This function should only be performed after the source action node of the control flow has been added to the action node procedure. This function reports the following errors in the error code of the procedure descriptor:

  • prIllFlowSrc: the identifier of the source of this control flow has an illegal value
  • prUndefinedFlowSrc: the source of this control flow has not yet been added to the procedure
  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
srcIdthe identifier of the source action node of the control flow (an integer in the range [1,N] where N is the number of action nodes)
destIdthe identifier of the destination decision node of the control flow (an integer in the range [1,M] where M is the number of decision nodes)
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 190 of file FwPrConfig.c.

void FwPrAddFlowActToFin ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  srcId,
FwPrGuard_t  cfGuard 
)

Create a control flow from an action node to the final node and add it to a procedure.

This function should only be performed after the source action node of the control flow has been added to the action node procedure. This function reports the following errors in the error code of the procedure descriptor:

  • prIllFlowSrc: the identifier of the source of this control flow has an illegal value
  • prUndefinedFlowSrc: the source of this control flow has not yet been added to the procedure
  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
srcIdthe identifier of the source action node of the control flow (an integer in the range [1,N] where N is the number of action nodes).
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 205 of file FwPrConfig.c.

void FwPrAddFlowDecToAct ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  srcId,
FwPrCounterS1_t  destId,
FwPrGuard_t  cfGuard 
)

Create a control flow from a decision node to an action node and add it to a procedure.

This function should only be performed after the source of the control flow has been added to the action node procedure. This function reports the following errors in the error code of the procedure descriptor:

  • prIllFlowSrc: the identifier of the source of this control flow has an illegal value
  • prUndefinedFlowSrc: the source of this control flow has not yet been added to the procedure
  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
srcIdthe identifier of the source decision node of the control flow (an integer in the range [1,N] where N is the number of decision nodes).
destIdthe identifier of the destination action node of the control flow (an integer in the range [1,N] where N is the number of action nodes).
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 195 of file FwPrConfig.c.

void FwPrAddFlowDecToDec ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  srcId,
FwPrCounterS1_t  destId,
FwPrGuard_t  cfGuard 
)

Create a control flow from a decision node to another decision node and add it to a procedure.

This function should only be performed after the source of the control flow has been added to the action node procedure. This function reports the following errors in the error code of the procedure descriptor:

  • prIllFlowSrc: the identifier of the source of this control flow has an illegal value
  • prUndefinedFlowSrc: the source of this control flow has not yet been added to the procedure
  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
srcIdthe identifier of the source decision node of the control flow (an integer in the range [1,N] where N is the number of decision nodes).
destIdthe identifier of the destination decision node of the control flow (an integer in the range [1,N] where N is the number of decision nodes).
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 200 of file FwPrConfig.c.

void FwPrAddFlowDecToFin ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  srcId,
FwPrGuard_t  cfGuard 
)

Create a control flow from a decision node to the final node and add it to a procedure.

This function should only be performed after the source action node of the control flow has been added to the action node procedure. This function reports the following errors in the error code of the procedure descriptor:

  • prIllFlowSrc: the identifier of the source of this control flow has an illegal value
  • prUndefinedFlowSrc: the source of this control flow has not yet been added to the procedure
  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
srcIdthe identifier of the source action node of the control flow (an integer in the range [1,N] where N is the number of action nodes).
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 210 of file FwPrConfig.c.

void FwPrAddFlowIniToAct ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  destId,
FwPrGuard_t  cfGuard 
)

Create a control flow from the initial node to an action node and add it to a procedure.

This function reports the following errors in the error code of the procedure descriptor:

  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
destIdthe identifier of the destination action node of the control flow (an integer in the range [1,N] where N is the number of action nodes).
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 175 of file FwPrConfig.c.

void FwPrAddFlowIniToDec ( FwPrDesc_t  prDesc,
FwPrCounterS1_t  destId,
FwPrGuard_t  cfGuard 
)

Create a control flow from the initial node to a decision node and add it to a procedure.

This function reports the following errors in the error code of the procedure descriptor:

  • prTooManyFlows: there is no space left in the control flow array of the procedure descriptor for this control flow
  • prTooManyGuards: there is no space left in the guard array of the procedure descriptor for the guard defined by this control flow
Parameters
prDescthe descriptor of the procedure to which the control flow is added.
destIdthe identifier of the destination decision node of the control flow (an integer in the range [1,N] where N is the number of decision nodes).
cfGuardthe control flow guard (a function pointer) or NULL if no guard is attached to this control flow.

Definition at line 180 of file FwPrConfig.c.

FwPrErrCode_t FwPrCheck ( FwPrDesc_t  prDesc)

Check the correctness and completeness of the configuration of a procedure descriptor.

This function may be called on a procedure descriptor after it has been created and configured. This function does not modify the configuration of the procedure. It checks the error conditions which may arise when an application configures a procedure using the configuration functions declared in this header file. More specifically, this function performs the following checks:

  1. Check that no configuration errors have occurred (i.e. check that the error code in the procedure descriptor is equal to: prSuccess).
  2. Check that all action nodes have been defined.
  3. Check that all decision nodes have been defined.
  4. Check that all control flows have been defined.
  5. Check that the destinations of the control flows out of a action node represent legal entities.
  6. Check that the destinations of the control flows out of a decision node represent legal entities.
  7. Check that the number of actions declared when the procedure was created is the same as the number of actions defined during the procedure configuration process.
  8. Check that the number of guards declared when the procedure was created is the same as the number of guards defined during the procedure configuration process.
  9. Check that all action nodes are reachable (i.e. they are a destination for a control flow).
  10. Check that all decision nodes are reachable (i.e. they are a destination for a control flow).

Note that there are configuration errors which are not covered by this function because they cannot occur if the procedure is configured using the functions declared in this header file.

Parameters
prDescthe descriptor of the procedure to be checked.
Returns
the outcome of the check. The outcome of the check is one of the following: This function returns when it encounters the first error. Hence, the function return value is determined by the first error encountered by the function.

Definition at line 341 of file FwPrConfig.c.

void* FwPrGetData ( FwPrDesc_t  prDesc)

Get the pointer to the procedure data in the procedure descriptor.

This function returns the pointer which was set with the FwPrSetData function. This function is normally used by the functions implementing a procedure action or guard to access the procedure data. See the description of the FwPrSetData function for more details.

Parameters
prDescthe descriptor of the procedure to which the data structure is attached.
Returns
the pointer to the procedure data or NULL if no procedure data were defined for the procedure.

Definition at line 87 of file FwPrConfig.c.

void FwPrOverrideAction ( FwPrDesc_t  prDesc,
FwPrAction_t  oldAction,
FwPrAction_t  newAction 
)

Override an action in a derived procedure.

By default a derived procedure has the same actions as the base procedure from which it was derived. This function overrides one of the actions of the derived procedure.

As an example consider the case of a base procedure B and suppose that action a1 is attached to node S1 and node S2. If an application creates a derived procedure D from B (for instance, through function FwPrCreateDer), then, after creation, the action of action nodes S1 and S2 in procedure D is still a1. This function can be used to change a1. Note that a single invocation of this function will change the action of both S1 and S2.

If an attempt is made to override a non-existent action, an error is declared and the function returns without doing anything.

The override mechanism is only available for derived procedures. If this function is called on a procedure which was not derived by extending some other procedure, an error is declared.

This function reports the following errors in the error code of the procedure descriptor:

Parameters
prDescthe descriptor of the derived procedure.
oldActionthe action to be overridden
newActionthe new action which overrides the old action

Definition at line 429 of file FwPrConfig.c.

void FwPrOverrideGuard ( FwPrDesc_t  prDesc,
FwPrGuard_t  oldGuard,
FwPrGuard_t  newGuard 
)

Override a guard in a derived procedure.

By default a derived procedure has the same guards as the base procedure from which it was derived. This function overrides one of the guards of the derived procedure.

As an example consider the case of a base procedure B and suppose that the control flows F1 and F2 both have the same guard g1. If an application creates a derived procedure D from B (for instance, through function FwPrCreateDer), then, after creation, the guard of the control flows F1 and F2 in D is still g1. This function can be used to change g1. Note that a single invocation of this function will change the guard on both control flows.

If an attempt is made to override a non-existent guard, the function declares an error and returns.

The override mechanism is only available for derived procedures. If this function is called on a procedure which was not derived by extending some other procedure, an error is declared.

This function reports the following errors in the error code of the procedure descriptor:

Parameters
prDescthe descriptor of the derived procedure.
oldGuardthe guard to be overridden
newGuardthe new guard which overrides the old guard

Definition at line 448 of file FwPrConfig.c.

void FwPrSetData ( FwPrDesc_t  prDesc,
void *  prData 
)

Set the pointer to the procedure data in the procedure descriptor.

The procedure data are data which are manipulated by the procedure actions and guards. The procedure descriptor holds a pointer to the procedure data. This function allows this pointer to be defined. The exact type of the procedure data is defined by applications for each procedure. It is therefore unknown at the level of the procedure module. This function accordingly treats the pointer to the procedure data as a pointer to void. In most cases, the procedure data will take the form of a struct whose fields represent the inputs and outputs for the procedure actions and guards.

The functions which implement the actions and guards access the procedure data as follows:

  • The functions implementing the actions and guards of a procedure take the procedure descriptor as an argument (because they must conform to the prototype defined by FwPrAction_t and FwPrGuard_t).
  • The functions implementing the actions and guards of a procedure use the FwPrGetData function to retrieve the pointer to the procedure data.
  • The pointer returned by FwPrGetData is defined as a pointer to void and will normally have to be cast to its true type.
Parameters
prDescthe descriptor of the procedure to which the data structure is attached.
prDatathe pointer to the procedure data. A value of NULL is legal (but note that the default value of the pointer to the procedure data when the procedure is created is NULL).

Definition at line 82 of file FwPrConfig.c.

P&P Software GmbH, Copyright 2011, All Rights Reserved