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... | |
CrFwDestSrc_t | CrFwOutStreamGetDest (FwSmDesc_t outStream, CrFwCounterU1_t i) |
Return the i-th destination associated to the argument outStream. More... | |
CrFwCounterU1_t | CrFwOutStreamGetNOfDest (FwSmDesc_t outStream) |
Return the number of destinations associated to the argument outStream. 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... | |
void | CrFwOutStreamDefSetDTS (CrFwCounterU2_t *pNofTypeCounter, CrFwDestTypeKey_t **destTypeKey) |
Default implementation of Set DST Function for the OutStreams. More... | |
CrFwSeqCnt_t | CrFwOutStreamGetSeqCnt (CrFwGroup_t group) |
Return the value of the sequence counter for one of the groups maintained by the OutStreams. More... | |
void | CrFwOutStreamSetSeqCnt (CrFwGroup_t group, CrFwSeqCnt_t seqCnt) |
Sets the value of the sequence counter for one of the groups maintained by the OutStreams. More... | |
CrFwCounterU1_t | CrFwOutStreamGetNOfPendingPckts (FwSmDesc_t smDesc) |
Return the number of packets currently in the packet queue of an OutStream. More... | |
CrFwGroup_t | CrFwOutStreamGetNOfGroups () |
Return the number of groups associated to the OutStreams. More... | |
CrFwCounterU1_t | CrFwOutStreamGetPcktQueueSize (FwSmDesc_t smDesc) |
Return the size of the packet queue of the OutStream. More... | |
CrFwCounterU2_t | CrFwOutStreamGetNOfTypeCounters () |
Return the number of type counters maintained by the OutStreams. More... | |
CrFwTypeCnt_t | CrFwOutStreamGetTypeCounter (CrFwDestSrc_t dest, CrFwServType_t servType, CrFwServSubType_t servSubType) |
Return the current type counter for a (destination, type, sub-type) triplet or zero if the triplet is not in DTS_SET. More... | |
CrFwBool_t | CrFwOutStreamIsInDtsSet (CrFwDestSrc_t dest, CrFwServType_t servType, CrFwServSubType_t servSubType) |
Check whether the (destination, type, sub-type) triplet is in DTS_SET. More... | |
Definition of the OutStream component.
An application instantiates one or more OutStreams to represent the logical connections through which reports or commands are sent to their 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 component is associated to one or more destinations. The mapping from the destinations to the OutStreams is in parameter CR_FW_OUTSTREAM_DEST_PAIRS
.
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:
CrFwOutStreamSend
.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.
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.
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.
smDesc | the descriptor of the OutStream State Machine. |
Definition at line 329 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.
prDesc | the descriptor of the Reset Procedure of the OutStream |
Definition at line 363 of file CrFwOutStream.c.
void CrFwOutStreamDefInitAction | ( | FwPrDesc_t | prDesc | ) |
Default initialization action for an OutStream.
This function allocates the memory for the packet queue of the OutStream and for the array holding the destinations associated to the outStream, 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.
prDesc | the descriptor of the Initialization Procedure of the OutStream |
Definition at line 384 of file CrFwOutStream.c.
void CrFwOutStreamDefSetDTS | ( | CrFwCounterU2_t * | pNofTypeCounter, |
CrFwDestTypeKey_t ** | destTypeKey | ||
) |
Default implementation of Set DST Function for the OutStreams.
The Set DTS Function is responsible for defining the DTS_SET. The DTS_SET defines the triplets (destination,type,sub-type) for which the OutStream maintain a type counter.
The Set DTS function computes and returns:
This default implementation builds DTS_SET by collecting all the types and sub-types (t,s) of the out-going reports defined in CR_FW_OUTCMP_INIT_KIND_DESC
and then building all triplets for the case of the destination ID being equal to 1.
This function allocates the memory for array outStreamDestTypeKey
using malloc. It is therefore only suitable for use during the application initialization phase.
pNofTypeCounter | pointer to variable holding the number of type counters (i.e. the number of triplets (d,t,s) in DTS_SET) |
destTypeKey | pointer to array of products d*t*s for all triplets (d,t,s) in DTS_SET arranged in increasing order |
Definition at line 579 of file CrFwOutStream.c.
void CrFwOutStreamDefShutdownAction | ( | FwSmDesc_t | smDesc | ) |
Default shutdown action for an OutStream.
This function resets the packet queue and releases the memory allocated to it and to the array holding the destinations associated to the outStream.
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.
smDesc | the descriptor of the OutStream State Machine |
Definition at line 373 of file CrFwOutStream.c.
FwSmDesc_t CrFwOutStreamGet | ( | CrFwDestSrc_t | dest | ) |
Getter function for the OutStream corresponding to the argument destination.
An OutStream is associated to one or more destinations. The binding between an OutStream and its destinations 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.
dest | the destination associated to the OutStream |
Definition at line 293 of file CrFwOutStream.c.
CrFwDestSrc_t CrFwOutStreamGetDest | ( | FwSmDesc_t | outStream, |
CrFwCounterU1_t | i | ||
) |
Return the i-th destination associated to the argument outStream.
The value of i must be in the range 1 to N with N being the number of destinations associated to the outStream as returned by function CrFwOutStreamGetNOfDest
. If this constraint is violated, the return value of the function is unpredictable.
The binding between an OutStream and its destinations is done statically in the array CR_FW_OUTSTREAM_DEST_PAIRS
. The first destination associated to the outStream is the destination in the first pair of CR_FW_OUTSTREAM_DEST_PAIRS
whicih is associated to the outStream; the second destination associated to it is the destination in the second pair; etc.
This function may only be called after the outStream has been initialized.
outStream | the outStream |
i | the index of the desired destination (starting from 1) |
Definition at line 306 of file CrFwOutStream.c.
CrFwCounterU1_t CrFwOutStreamGetNOfDest | ( | FwSmDesc_t | outStream | ) |
Return the number of destinations associated to the argument outStream.
The binding between an OutStream and its destinations is done statically in the array CR_FW_OUTSTREAM_DEST_PAIRS
. This function may only be called after the outStream has been initialized.
outStream | the outStream |
Definition at line 314 of file CrFwOutStream.c.
CrFwGroup_t CrFwOutStreamGetNOfGroups | ( | ) |
Return the number of groups associated to the OutStreams.
Definition at line 351 of file CrFwOutStream.c.
CrFwCounterU1_t CrFwOutStreamGetNOfPendingPckts | ( | FwSmDesc_t | smDesc | ) |
Return the number of packets currently in the packet queue of an OutStream.
smDesc | the descriptor of the OutStream State Machine. |
Definition at line 344 of file CrFwOutStream.c.
CrFwCounterU2_t CrFwOutStreamGetNOfTypeCounters | ( | ) |
Return the number of type counters maintained by the OutStreams.
Definition at line 618 of file CrFwOutStream.c.
CrFwCounterU1_t CrFwOutStreamGetPcktQueueSize | ( | FwSmDesc_t | smDesc | ) |
Return the size of the packet queue of the OutStream.
smDesc | the descriptor of the OutStream State Machine. |
Definition at line 356 of file CrFwOutStream.c.
CrFwSeqCnt_t CrFwOutStreamGetSeqCnt | ( | CrFwGroup_t | group | ) |
Return the value of the sequence counter for one of the groups maintained by the OutStreams.
The group identifier is passed as an argument to the function call. No check is performed on the validity of the group identifier.
group | the identifier of the group |
Definition at line 334 of file CrFwOutStream.c.
CrFwTypeCnt_t CrFwOutStreamGetTypeCounter | ( | CrFwDestSrc_t | dest, |
CrFwServType_t | servType, | ||
CrFwServSubType_t | servSubType | ||
) |
Return the current type counter for a (destination, type, sub-type) triplet or zero if the triplet is not in DTS_SET.
The value returned by this function is the type counter which the OutStream will allocate to the next out-going packet with the argument destination, type and sub-type. If the (destination, type, sub-type) is not in DTS_SET, then zero is returned.
This function may only be called after the DTS_SET has been built. The DTS_SET is built the first time function CrFwOutStreamMake
is called.
dest | the packet destination |
servType | the packet service type |
servSubType | the packet service sub-type |
Definition at line 623 of file CrFwOutStream.c.
CrFwBool_t CrFwOutStreamIsInBuffering | ( | FwSmDesc_t | smDesc | ) |
Return true if the argument OutStream is in state BUFFERING.
smDesc | the descriptor of the Base State Machine of the OutStream |
Definition at line 288 of file CrFwOutStream.c.
CrFwBool_t CrFwOutStreamIsInDtsSet | ( | CrFwDestSrc_t | dest, |
CrFwServType_t | servType, | ||
CrFwServSubType_t | servSubType | ||
) |
Check whether the (destination, type, sub-type) triplet is in DTS_SET.
This function may only be called after the DTS_SET has been built. The DTS_SET is built the first time function CrFwOutStreamMake
is called.
dest | the packet destination |
servType | the packet service type |
servSubType | the packet service sub-type |
Definition at line 634 of file CrFwOutStream.c.
CrFwBool_t CrFwOutStreamIsInReady | ( | FwSmDesc_t | smDesc | ) |
Return true if the argument OutStream is in state READY.
smDesc | the descriptor of the Base State Machine of the OutStream |
Definition at line 283 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 outStreamId 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.
The first time this function is called, it builds the DTS_SET by calling the function CR_FW_OUTSTREAM_SET_DTS
. The number of elements in the DTS_SET is then used to allocate the memory for the array holding the type counters (since there is one type counter for each element of DTS_SET).
outStreamId | the identifier of the Base State Machine of the OutStream |
Definition at line 193 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.
smDesc | the descriptor of the OutStream State Machine. |
pckt | the packet to be sent by the OutStream |
Definition at line 321 of file CrFwOutStream.c.
void CrFwOutStreamSetSeqCnt | ( | CrFwGroup_t | group, |
CrFwSeqCnt_t | seqCnt | ||
) |
Sets the value of the sequence counter for one of the groups maintained by the OutStreams.
The group identifier is passed as an argument to the function call. No check is performed on the validity of the group identifier.
group | the identifier of the group |
seqCnt | the OutStream sequence counter |
Definition at line 339 of file CrFwOutStream.c.