Merge branch 'mueller_CSB_AbstractFunctionsAtTop' of KSat/fsfw into master

Added some comments in Commanding Service Base and moved abstract functions to the top for better visibility.

tmtcservices/CommandingServiceBase.h

@@ -64,7 +64,7 @@ public:
 	virtual ~CommandingServiceBase();
 
 	/***
-	 * This is the periodic called function
+	 * This is the periodically called function.
 	 * Handle request queue for external commands.
 	 * Handle command Queue for internal commands.
 	 * @param opCode is unused here at the moment
@@ -104,6 +104,69 @@ public:
 	};
 
 protected:
+	/**
+	 * Check the target subservice
+	 * @param subservice[in]
+	 * @return -@c RETURN_OK on success
+     *         -@c INVALID_SUBSERVICE if service is not known
+	 */
+	virtual ReturnValue_t isValidSubservice(uint8_t subservice) = 0;
+
+	/**
+	 * Once a TC Request is valid, the existence of the destination and its target interface is checked and retrieved.
+	 * The target message queue ID can then be acquired by using the target interface.
+	 * @param subservice
+	 * @param tcData Application Data of TC Packet
+	 * @param tcDataLen
+	 * @param id MessageQueue ID is stored here
+	 * @param objectId Object ID is extracted and stored here
+	 * @return - @c RETURN_OK on success
+	 *         - @c RETURN_FAILED
+	 *         - @c CSB or implementation specific return codes
+	 */
+	virtual ReturnValue_t getMessageQueueAndObject(uint8_t subservice,
+			const uint8_t *tcData, uint32_t tcDataLen, MessageQueueId_t *id,
+			object_id_t *objectId) = 0;
+
+	/**
+	 * After the Message Queue and Object ID are determined,
+	 * the command is prepared by using an implementation specific CommandMessage type
+	 * which is sent to the target object.
+	 * It contains all necessary information for the device to execute telecommands.
+	 * @param message[out] message to be sent to the object
+	 * @param subservice[in] Subservice of the current communication
+	 * @param tcData Additional data of the command
+	 * @param tcDataLen Length of the additional data
+	 * @param state[out] Setable state of the communication
+	 * @param objectId Target object ID
+	 * @return - @c RETURN_OK on success
+     *         - @c EXECUTION_COMPLETE if exectuin is finished 
+     *         - any other return code will be part of (1,4) start failure
+	 */
+	virtual ReturnValue_t prepareCommand(CommandMessage *message,
+			uint8_t subservice, const uint8_t *tcData, uint32_t tcDataLen,
+			uint32_t *state, object_id_t objectId) = 0;
+
+	/**
+	 * This function is responsible for the communication between the Command Service Base
+	 * and the respective PUS Commanding Service once the execution has started.
+	 * The PUS Commanding Service receives replies from the target device and forwards them by calling this function.
+	 * There are different translations of these replies to specify how the Command Service proceeds.
+	 * @param reply Command Message which contains information about the command
+	 * @param previousCommand Command_t of last command
+	 * @param state state of the communication
+	 * @param optionalNextCommand[out] An optional next command which can be set in this function
+	 * @param objectId Source object ID
+	 * @param isStep Flag value to mark steps of command execution
+	 * @return - @c RETURN_OK, @c EXECUTION_COMPLETE or @c NO_STEP_MESSAGE to generate TC verification success
+	 *         - @c INVALID_REPLY can handle unrequested replies
+	 *         - Anything else triggers a TC verification failure
+	 */
+	virtual ReturnValue_t handleReply(const CommandMessage *reply,
+			Command_t previousCommand, uint32_t *state,
+			CommandMessage *optionalNextCommand, object_id_t objectId,
+			bool *isStep) = 0;
+
 	struct CommandInfo {
 		struct tcInfo {
 			uint8_t ackFlags;
@@ -180,20 +243,6 @@ protected:
 	 */
 	void sendTmPacket(uint8_t subservice, SerializeIF* content,
 			SerializeIF* header = NULL);
-	virtual ReturnValue_t isValidSubservice(uint8_t subservice) = 0;
-
-	virtual ReturnValue_t prepareCommand(CommandMessage *message,
-			uint8_t subservice, const uint8_t *tcData, uint32_t tcDataLen,
-			uint32_t *state, object_id_t objectId) = 0;
-
-	virtual ReturnValue_t handleReply(const CommandMessage *reply,
-			Command_t previousCommand, uint32_t *state,
-			CommandMessage *optionalNextCommand, object_id_t objectId,
-			bool *isStep) = 0;
-
-	virtual ReturnValue_t getMessageQueueAndObject(uint8_t subservice,
-			const uint8_t *tcData, uint32_t tcDataLen, MessageQueueId_t *id,
-			object_id_t *objectId) = 0;
 
 	virtual void handleUnrequestedReply(CommandMessage *reply);
 
@@ -209,7 +258,8 @@ private:
 	 * It handles replies generated by the devices and relayed by the specific service implementation.
 	 * This means that it determines further course of action depending on the return values specified
 	 * in the service implementation.
-	 * This includes the generation of TC verification messages:
+	 * This includes the generation of TC verification messages. Note that
+	 * the static framework object ID @c VerificationReporter::messageReceiver needs to be set.
 	 *   - TM[1,5] Step Successs
 	 *   - TM[1,6] Step Failure
 	 *   - TM[1,7] Completion Success