Action Module API

ActionHelper

class ActionHelper

Subclassed by SimpleActionHelper

Public Functions

ActionHelper(HasActionsIF *setOwner, MessageQueueIF *useThisQueue)

Constructor of the action helper

Parameters:

  • setOwner – Pointer to the owner of the interface

  • useThisQueue – messageQueue to be used, can be set during initialize function as well.

ReturnValue_t handleActionMessage(CommandMessage *command)

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.

Parameters:

command – Pointer to a command message received by the owner

Returns:

returnvalue::OK if the message is a action message, CommandMessage::UNKNOW_COMMAND if this message ID is unkown

ReturnValue_t initialize(MessageQueueIF *queueToUse_ = nullptr)

Helper initialize function. Must be called before use of any other helper function

Parameters:

queueToUse_ – Pointer to the messageQueue to be used, optional if queue was set in constructor

Returns:

Returns returnvalue::OK if successful

void step(uint8_t step, MessageQueueId_t reportTo, ActionId_t commandId, ReturnValue_t result = returnvalue::OK)

Function to be called from the owner to send a step message. Success or failure will be determined by the result value.

Parameters:

  • step – Number of steps already done

  • reportTo – The messageQueueId to report the step message to

  • commandId – ID of the executed command

  • result – Result of the execution

void finish(bool success, MessageQueueId_t reportTo, ActionId_t commandId, ReturnValue_t result = returnvalue::OK)

Function to be called by the owner to send a action completion message

Parameters:

  • success – Specify whether action was completed successfully or not.

  • reportTo – MessageQueueId_t to report the action completion message to

  • commandId – ID of the executed command

  • result – Result of the execution

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 a SerializeIF* pointer and serializes it into the IPC store.

Parameters:

  • reportTo – MessageQueueId_t to report the action completion message to

  • replyId – ID of the executed command

  • data – Pointer to the data

Returns:

Returns returnvalue::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)

Function to be called by the owner if an action does report data. Takes the raw data and writes it into the IPC store.

Parameters:

  • reportTo – MessageQueueId_t to report the action completion message to

  • replyId – ID of the executed command

  • data – Pointer to the data

Returns:

Returns returnvalue::OK if successful, otherwise failure code

void setQueueToUse(MessageQueueIF *queue)

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.

Parameters:

queue – Queue to be used by the helper

HasActionsIF

class HasActionsIF

Interface for component which uses actions.

This interface is used to execute actions in the component. Actions, in the sense of this interface, are activities with a well-defined beginning and end in time. They may adjust sub-states of components, but are not supposed to change the main mode of operation, which is handled with the HasModesIF described below.

The HasActionsIF allows components to define such actions and make them available for other components to use. Implementing the interface is straightforward: There’s a single executeAction call, which provides an identifier for the action to execute, as well as arbitrary parameters for input. Aside from direct, software-based actions, it is used in device handler components as an interface to forward commands to devices. Implementing components of the interface are supposed to check identifier (ID) and parameters and immediately start execution of the action. It is, however, not required to immediately finish execution. Instead, this may be deferred to a later point in time, at which the component needs to inform the caller about finished or failed execution.

Subclassed by DeviceHandlerBase, ExtendedControllerBase

Public Functions

virtual MessageQueueId_t getCommandQueue() const = 0

Function to get the MessageQueueId_t of the implementing object

Returns:

MessageQueueId_t of the object

virtual ReturnValue_t executeAction(ActionId_t actionId, MessageQueueId_t commandedBy, const uint8_t *data, size_t size) = 0

Execute or initialize the execution of a certain function. The ActionHelpers will execute this function and behave differently depending on the returnvalue.

Returns:

-EXECUTION_FINISHED Finish reply will be generated -Not returnvalue::OK Step failure reply will be generated