fsfw/action/ActionHelper.h

126 lines
4.9 KiB
C
Raw Normal View History

#ifndef FSFW_ACTION_ACTIONHELPER_H_
#define FSFW_ACTION_ACTIONHELPER_H_
2020-08-13 20:53:35 +02:00
#include "ActionMessage.h"
#include "../serialize/SerializeIF.h"
#include "../ipc/MessageQueueIF.h"
2018-07-13 18:28:26 +02:00
/**
* @brief Action Helper is a helper class which handles action messages
2018-07-13 18:28:26 +02:00
*
* Components which use the HasActionIF this helper can be used to handle
* the action messages.
* It does handle step messages as well as other answers to action calls.
* It uses the executeAction function of its owner as callback.
* The call of the initialize function is mandatory and needs a
* valid MessageQueueIF pointer!
2018-07-13 18:28:26 +02:00
*/
class HasActionsIF;
class ActionHelper {
public:
2018-07-13 18:28:26 +02:00
/**
* Constructor of the action helper
* @param setOwner Pointer to the owner of the interface
* @param useThisQueue messageQueue to be used, can be set during
* initialize function as well.
2018-07-13 18:28:26 +02:00
*/
ActionHelper(HasActionsIF* setOwner, MessageQueueIF* useThisQueue);
2018-07-13 18:28:26 +02:00
virtual ~ActionHelper();
2018-07-13 18:28:26 +02:00
/**
* Function to be called from the owner with a new command message
*
* If the message is a valid action message the helper will use the
* executeAction function from HasActionsIF.
* If the message is invalid or the callback fails a message reply will be
* send to the sender of the message automatically.
2018-07-13 18:28:26 +02:00
*
* @param command Pointer to a command message received by the owner
* @return HasReturnvaluesIF::RETURN_OK if the message is a action message,
* CommandMessage::UNKNOW_COMMAND if this message ID is unkown
2018-07-13 18:28:26 +02:00
*/
ReturnValue_t handleActionMessage(CommandMessage* command);
2018-07-13 18:28:26 +02:00
/**
* Helper initialize function. Must be called before use of any other
* helper function
* @param queueToUse_ Pointer to the messageQueue to be used, optional
* if queue was set in constructor
2018-07-13 18:28:26 +02:00
* @return Returns RETURN_OK if successful
*/
ReturnValue_t initialize(MessageQueueIF* queueToUse_ = nullptr);
2018-07-13 18:28:26 +02:00
/**
* Function to be called from the owner to send a step message.
* Success or failure will be determined by the result value.
2018-07-13 18:28:26 +02:00
*
* @param step Number of steps already done
* @param reportTo The messageQueueId to report the step message to
* @param commandId ID of the executed command
* @param result Result of the execution
*/
2020-10-29 13:34:53 +01:00
void step(uint8_t step, MessageQueueId_t reportTo,
ActionId_t commandId,
ReturnValue_t result = HasReturnvaluesIF::RETURN_OK);
2018-07-13 18:28:26 +02:00
/**
* Function to be called by the owner to send a action completion message
*
* @param reportTo MessageQueueId_t to report the action completion message to
* @param commandId ID of the executed command
* @param result Result of the execution
*/
void finish(MessageQueueId_t reportTo, ActionId_t commandId,
ReturnValue_t result = HasReturnvaluesIF::RETURN_OK);
2018-07-13 18:28:26 +02:00
/**
* Function to be called by the owner if an action does report data.
* Takes a SerializeIF* pointer and serializes it into the IPC store.
* @param reportTo MessageQueueId_t to report the action completion
* message to
2018-07-13 18:28:26 +02:00
* @param replyId ID of the executed command
* @param data Pointer to the data
* @return Returns RETURN_OK if successful, otherwise failure code
*/
ReturnValue_t reportData(MessageQueueId_t reportTo, ActionId_t replyId,
SerializeIF* data, bool hideSender = false);
/**
* Function to be called by the owner if an action does report data.
* Takes the raw data and writes it into the IPC store.
* @param reportTo MessageQueueId_t to report the action completion
* message to
* @param replyId ID of the executed command
* @param data Pointer to the data
* @return Returns RETURN_OK if successful, otherwise failure code
*/
ReturnValue_t reportData(MessageQueueId_t reportTo, ActionId_t replyId,
const uint8_t* data, size_t dataSize, bool hideSender = false);
2018-07-13 18:28:26 +02:00
/**
* Function to setup the MessageQueueIF* of the helper. Can be used to
* set the MessageQueueIF* if message queue is unavailable at construction
* and initialize but must be setup before first call of other functions.
2018-07-13 18:28:26 +02:00
* @param queue Queue to be used by the helper
*/
void setQueueToUse(MessageQueueIF *queue);
protected:
2021-01-27 14:18:51 +01:00
//! Increase of value of this per step
static const uint8_t STEP_OFFSET = 1;
2018-07-13 18:28:26 +02:00
HasActionsIF* owner;//!< Pointer to the owner
//! Queue to be used as response sender, has to be set in ctor or with
//! setQueueToUse
MessageQueueIF* queueToUse;
//! Pointer to an IPC Store, initialized during construction or
StorageManagerIF* ipcStore = nullptr;
2018-07-13 18:28:26 +02:00
/**
* Internal function called by handleActionMessage
2018-07-13 18:28:26 +02:00
* @param commandedBy MessageQueueID of Commander
* @param actionId ID of action to be done
* @param dataAddress Address of additional data in IPC Store
*/
virtual void prepareExecution(MessageQueueId_t commandedBy,
ActionId_t actionId, store_address_t dataAddress);
2018-07-13 18:28:26 +02:00
/**
* @brief Default implementation is empty.
2018-07-13 18:28:26 +02:00
*/
virtual void resetHelper();
};
#endif /* FSFW_ACTION_ACTIONHELPER_H_ */