Telecommand Class Reference
[Telecommand Management]

#include <Telecommand.h>

Inheritance diagram for Telecommand:

List of all members.

---

Detailed Description

Base class from which all telecommand classes are derived.

This is an abstract class. Concrete telecommands are obtained by deriving this class.

A telecommand is a form of punctual action. Telecommands add to the following attributes to those they inherit from their superclass:<ul> A time tag: the time when the telecommand should be executed. If the time tag is equal to zero, then the telecommand should be executed immediately. Negative values of the time tag indicate a non-configured or or otherwise invalid telecommand. A telecommand identifier: an integer that uniquely identifies the telecommand. A telecommand source: an integer that uniquely identifies the sender of the telecommand. A telecommand type: an integer that identifies the type of telecommand. A telecommand subtype: an integer that identifies the subtype of telecommand. This attribute is useful when the type attribute does not provide sufficient granularity to represent the various categories of telecommands. A validity check code: a read-only integer that conveys information about the failure of the validity check (see below). An execution check code: a read-only integer that conveys information about the failure of the execution check (see below). An acknowledge level: an integer that defines the level of acknowledgement that the telecommand sender requires for the telecommand (e.g. acknowledgement upon acceptance of the telecommand, acknowledgement upon execution start, acknowledgement upon execution termination, etc). An in use flag: a toggle attribute that can have two values: "telecommand is in use" and "telecommand is not in use". This attribute can be useful because telecommand components are normally created dynamically and therefore their resources must be managed dynamically. The "in use" attribute can then be used to discriminate between telecommands that are being used (and whose resources are therefore to be considered allocated) and telecommands that are not being used (and whose resources can therefore be reclaimed and used to construct other telecommand components). In the OBS Framework, the "in use" attribute would typically be used by the telecommand loader. With the exception of the "in use flag", all telecommand attributes are conceptually read-only attributes. However, since telecommand objects may have to be dynamically configured by the telecommand loader, setter methods are provided to dynamically set their values.

Telecommands implement the raw data load service. This is intended to facilitate the configuration of a telecommand by the telecommand loader. The usage scenario for this service is a situation where the telecommand loader receives the raw telecommand as a list of bytes. The list of bytes contain the configuration data for the telecommand component. The raw data load service allows the telecommand loader to load these bytes into the telecommand loader in an "anonymous manner" without having to know anything about their meaning for the telecommand component. The raw data load service is an optional service that only some concrete telecommand components will choose to implement. The choice to implement it depends on the mutual relationship between the concrete telecommand loader and the concrete telecommand components. Two alternative implementations for the raw data load service are defined. The first one is efficient but potentially unsafe (it does not comply with project-specific coding rule PR3.3). The second one is safe (it complies with all coding rules) but less efficient (it requires a virtual method call for each byte that is loaded in the telecommand component).

Telecommands can perform two checks: a validity check and an execution check. The validity check checks the internal validity of the telecommand attributes. It should normally be executed immediately after the telecommand is loaded to verify its formal correctness. The execution check should be performed just before the telecommand is executed and should verify whether conditions for the safe execution of the telecommand are satisfied.

This class provides a general interface that can model telecommand concepts of varying complexity but it only provides a minimal implementation. Thus, of the attributes it defines, only the time tag and the "in use" flag are implemented as true read/write attributes. The other attributes are implemented as fixed constants. Applications are free to provide subclasses that implement a larger subset of the attributes defined in this class.

Todo:

The possibility should be considered of making Telecommand a subclass of ConditionalPunctualAction. This would make sense because the Telecommand class contains a conditional execution check. However, this change would require delicate changes to the CC_TelecommandManager and CriticalTelecommand classes (at the least). For the time being, it seems wiser to leave things as they are. The advantage of the current solution is that it gives greater control to the telecommand manager over the execution of the telecommand and it makes it easier to implement "special" types of telecommands (such as, for instance, critical telecommands).

should new versions of method setRawData that take as argument unsigned short and unsigned int be added? This would speed up execution when a large number of data have to be loaded but it might make implementation of the methods in concrete subclasses more complex.

See also:

TelecommandLoader

CC_TelecommandManager

Author:

Alessandro Pasetti (P&P Software GmbH)

Version:

1.0

Definition at line 123 of file Telecommand.h.

Public Member Functions
	Telecommand (void)
	Instantiate a telecommand.
virtual bool	isValid (void)
	Execute the validity check on the telecommand.
virtual TD_CheckCode	getValidityCheckCode (void) const
	Return the validity check code for the telecommand.
virtual bool	canExecute (void)
	Perform the execution check on the telecommand.
virtual TD_CheckCode	getExecutionCheckCode (void) const
	Return the execution check code for the telecommand.
virtual TD_TelecommandId	getTelecommandId (void) const
	Getter method for the telecommand identifier.
virtual void	setTelecommandId (TD_TelecommandId tcIdentifier)
	Setter method for the telecommand identifier.
virtual TD_TelecommandType	getType (void) const
	Getter method for the telecommand type.
virtual void	setType (TD_TelecommandType tcType)
	Setter method for the telecommand type.
virtual TD_TelecommandSubType	getSubType (void) const
	Getter method for the telecommand sub-type.
virtual void	setSubType (TD_TelecommandSubType tcSubType)
	Setter method for the telecommand sub-type.
virtual TD_TelecommandSource	getSource (void) const
	Getter method for the telecommand source.
virtual void	setSource (TD_TelecommandSource tcSource)
	Setter method for the telecommand source.
TD_ObsTime	getTimeTag (void) const
	Getter method for the telecommand time tag.
void	setTimeTag (TD_ObsTime timeTag)
	Setter method for the telecommand time tag.
virtual void	setRawData (unsigned int i, unsigned char d)
	Implementation of the raw data load service.
virtual unsigned int	getNumberOfRawData (void) const
	Return the number of raw data bytes that can be loaded with the raw telecommand data load service setRawData(unsigned int, unsigned char).
virtual void	setRawData (unsigned char *d, unsigned int i)
	Implementation of the raw data load service.
void	setInUse (bool newInUse)
	Set the value of the "in use" attribute.
bool	isInUse (void) const
	Return the value of the "in use" attribute.
virtual void	setAcknowledgeLevel (TD_TelecommandAck ackLevel)
	Set the value of the acknowledge level for this telecommand.
virtual TD_TelecommandAck	getAcknowledgeLevel (void) const
	Return the value of the acknowledge level.
virtual bool	isObjectConfigured (void)
	Perform a class-specific configuration check on the telecommand: verify that the time tag has a legal value.

---

Constructor & Destructor Documentation

Telecommand::Telecommand (  void   )

Instantiate a telecommand. The telecommand attributes are set. The "in use" flag is set to "telecommand is not in use" and the time tag is initialized to an illegal value to signify that the component is not yet configured. Definition at line 15 of file Telecommand.cpp.

---

Member Function Documentation

bool Telecommand::canExecute (  void   )  [virtual]

Perform the execution check on the telecommand. This class provides a default implementation that always return "telecommand can execute". See also: CC_TelecommandManager::activate Returns: true if the telecommand can safely execute, false otherwise Reimplemented in CriticalTelecommand, DC_DummyTelecommand, and DC_TestPUSTelecommand. Definition at line 29 of file Telecommand.cpp.

TD_TelecommandAck Telecommand::getAcknowledgeLevel (  void   )  const [virtual]

Return the value of the acknowledge level. This class does not implement the acknowledge level and this method always returns a default and fixed value of zero. See also: setAcknowledgeLevel Returns: the value of the acknowledge level attribute Reimplemented in PUSTelecommand. Definition at line 109 of file Telecommand.cpp.

TD_CheckCode Telecommand::getExecutionCheckCode (  void   )  const [virtual]

Return the execution check code for the telecommand. The execution check code allows a telecommand to make information available about the reasons for the failure of the execution check. The return value of this method is only valid if the execution check has returned "telecommand cannot execute" (ie. if method canExecute has returned false). This class provides a default implementation that returns zero. See also: isValid Returns: the validity check code Reimplemented in DC_DummyTelecommand, and DC_TestPUSTelecommand. Definition at line 34 of file Telecommand.cpp.

unsigned int Telecommand::getNumberOfRawData (  void   )  const [virtual]

Return the number of raw data bytes that can be loaded with the raw telecommand data load service setRawData(unsigned int, unsigned char). This class provides a default implementation that returns zero. See also: setRawData Returns: the number of raw data bytes to be loaded with the raw data load service Reimplemented in DC_PUSClearDataReporting, DC_PUSControlDataReporting, and DC_TestPUSTelecommand. Definition at line 88 of file Telecommand.cpp.

TD_TelecommandSource Telecommand::getSource (  void   )  const [virtual]

Getter method for the telecommand source. This class does not model the telecommand source. This method always returns zero. Returns: the telecommand source Reimplemented in PUSTelecommand. Definition at line 62 of file Telecommand.cpp.

TD_TelecommandSubType Telecommand::getSubType (  void   )  const [virtual]

Getter method for the telecommand sub-type. This class does not model the telecommand sub-type. This method always returns zero. Returns: the telecommand sub-type Reimplemented in PUSTelecommand. Definition at line 54 of file Telecommand.cpp.

TD_TelecommandId Telecommand::getTelecommandId (  void   )  const [virtual]

Getter method for the telecommand identifier. This class implements the the telecommand identifier to coincide with the instance identifier. Note that this assumes that the type of the instance identifier (TD_InstanceId) is assignment-compatible with the type of the telecommand identifier (TD_TelecommandId). A pseudo-code implementation of this method therefore is:<PRE> return getInstanceId(); Returns: the telecommand identifier Reimplemented in PUSTelecommand. Definition at line 38 of file Telecommand.cpp.

TD_ObsTime Telecommand::getTimeTag (  void   )  const

Getter method for the telecommand time tag. Returns: the telecommand time tag Definition at line 70 of file Telecommand.cpp.

TD_TelecommandType Telecommand::getType (  void   )  const [virtual]

Getter method for the telecommand type. This class implements the telecommand type to coincide with the least significant byte of the class identifier. A pseudo-code implementation of this method therefore is:<PRE> return (TD_TelecommandType)(getClassId() mod 256); Returns: the telecommand type Reimplemented in PUSTelecommand. Definition at line 46 of file Telecommand.cpp.

TD_CheckCode Telecommand::getValidityCheckCode (  void   )  const [virtual]

Return the validity check code for the telecommand. The validity check code allows a telecommand to make information available about the reasons for the failure of the validity check. The return value of this method is only valid if the validity check has returned "telecommand not valid" (ie. if method isValid has returned false). This class provides a default implementation that returns zero. See also: isValid Returns: the validity check code Reimplemented in DC_DummyTelecommand, DC_TestPUSTelecommand, and PUSTelecommand. Definition at line 25 of file Telecommand.cpp.

bool Telecommand::isInUse (  void   )  const

Return the value of the "in use" attribute. If the method returns true, then the telecommand is in use, otherwise it is not in use. See also: setInUse Returns: the value of the "in use" attribute. Definition at line 101 of file Telecommand.cpp.

bool Telecommand::isObjectConfigured (  void   )  [virtual]

Perform a class-specific configuration check on the telecommand: verify that the time tag has a legal value. Returns: true if the component is configured, false otherwise. Reimplemented from CC_RootObject. Reimplemented in CriticalTelecommand, DC_PUSClearDataReporting, DC_PUSControlDataReporting, DC_PUSDefineDataReporting, PUSDumpMemory, PUSMemoryLoad, and PUSTelecommand. Definition at line 113 of file Telecommand.cpp.

bool Telecommand::isValid (  void   )  [virtual]

Execute the validity check on the telecommand. This class provides a default implementation that returns "telecommand is valid". Subclasses may introduce more complex validity checks (e.g. checksum checks). See also: CC_TelecommandManager::activate Returns: true if the telecommand is valid, false otherwise Reimplemented in DC_DummyTelecommand, DC_TestPUSTelecommand, and PUSTelecommand. Definition at line 20 of file Telecommand.cpp.

void Telecommand::setAcknowledgeLevel (  TD_TelecommandAck  ackLevel  )  [virtual]

Set the value of the acknowledge level for this telecommand. This class does not implement the acknowledge level and this method therefore returns without taking any action. See also: getAcknowledgeLevel Parameters: ackLevel  the new value of the acknowledge level attribute Reimplemented in PUSTelecommand. Definition at line 105 of file Telecommand.cpp.

void Telecommand::setInUse (  bool  newInUse  )

Set the value of the "in use" attribute. See also: isInUse Parameters: newInUse  the new value of the in use attribute Definition at line 97 of file Telecommand.cpp.

void Telecommand::setRawData (  unsigned char *  d, unsigned int  i )  [virtual]

Implementation of the raw data load service. This method would normally be called by a telecommand loader to load the configuration data for the telecommand as s single array of bytes. The telecommand component uses the data in the array to configure its internal data structures. This implementation of the raw data load service is efficient (unlike its alternative setRawData(unsigned int, unsigned char)) but is unsafe because it forces the caller to give access to its interal data structures to the telecommand component. This class provides a default implementation that does nothing and should never be called. Parameters: i  the number data in the d array d  the array holding the raw data Reimplemented in DC_PUSDefineDataReporting, DC_PUSMemoryLoadAbsolute, DC_PUSMemoryLoadOffset, and PUSDumpMemory. Definition at line 83 of file Telecommand.cpp.

void Telecommand::setRawData (  unsigned int  i, unsigned char  d )  [virtual]

Implementation of the raw data load service. This method would normally be called by a telecommand loader to load the i-th byte into the telecommand component. The telecommand component uses the data that it receives from the telecommand loader to configure its internal data structures. The index i should lie in an interval [0,N-1] where N is the return value of method getNumberOfRawData. This implementation of the raw data load service is safe (unlike its alternative setRawData(unsigned char*, unsigned int), it does not give access to the internal data of the caller) but can be inefficient because it requires the caller to pass the telecommand configuration bytes one by one through dedicated calls to a virtual method. This class provides a default implementation that does nothing and should never be called. See also: getNumberOfRawData Parameters: i  the index of the raw telecommand data d  the raw data Reimplemented in DC_PUSClearDataReporting, DC_PUSControlDataReporting, and DC_TestPUSTelecommand. Definition at line 78 of file Telecommand.cpp.

void Telecommand::setSource (  TD_TelecommandSource  tcSource  )  [virtual]

Setter method for the telecommand source. Since this class does not model the telecommand source, this method is implemented as a dummy method that returns without taking any action. See also: getSource Parameters: tcSource  the telecommand source Reimplemented in PUSTelecommand. Definition at line 66 of file Telecommand.cpp.

void Telecommand::setSubType (  TD_TelecommandSubType  tcSubType  )  [virtual]

Setter method for the telecommand sub-type. Since this class does not model the telecommand sub-type, this method is implemented as a dummy method that returns without taking any action. See also: #getTelecommandsubType Parameters: tcSubType  the telecommand sub-type Reimplemented in PUSTelecommand. Definition at line 58 of file Telecommand.cpp.

void Telecommand::setTelecommandId (  TD_TelecommandId  tcIdentifier  )  [virtual]

Setter method for the telecommand identifier. Since this class identifies the telecommand identifier with the instance identifier (see CC_RootObject), this method is implemented as a dummy method that returns without taking any action. See also: getTelecommandId Parameters: tcIdentifier  the telecommand identifier Reimplemented in PUSTelecommand. Definition at line 42 of file Telecommand.cpp.

void Telecommand::setTimeTag (  TD_ObsTime  timeTag  )

Setter method for the telecommand time tag. See also: TelecommandLoader Parameters: timeTag  the telecommand time tag Definition at line 74 of file Telecommand.cpp.

void Telecommand::setType (  TD_TelecommandType  tcType  )  [virtual]

Setter method for the telecommand type. Since this class identifies the telecommand type with the class identifier (see CC_RootObject), this method is implemented as a dummy method that returns without taking any action. See also: getType Parameters: tcType  the telecommand type Reimplemented in PUSTelecommand. Definition at line 50 of file Telecommand.cpp.

---

The documentation for this class was generated from the following files:

• Telecommand.h
• Telecommand.cpp

Copyright 2003 P&P Software GmbH - All Rights Reserved