/*
 * CommandCoderBase.h
 *
 * The Command Coder is responsible for on demand data delivery for the Front End Electronics.
 *
 * The Command Coder must implement the following interface:
 *
 * The data are determined by means of the target name and an integer number (tag). The target
 * name must not be longer than 20 characters and must be null terminated. A typical target name looks
 * like: "tst-fee_0_1_3" where "tst" would be replaced by a detector name (trd, tpc, etc.). The name
 * must be in lower case letters.
 *
 * The interface must deliver data in several steps in the following order:
 *
 * TODO <please proof read>
 * zero:
 * 	   uint32_t getVersion();
 *
 *     declared in CoCoFacade.h and implemented in CoCoFacade.cpp is explicitly not
 *     'virtual' and must not be changed or overwritten. This method
 *     will be called during instantiation of the InterCom Layer.
 *     The supported Command Coder interface and the actual version number can be found here</br>
 *     https://www.ztt.fh-worms.de/download/alice/</br>
 *     If the version number is not supported the instantiation will be halted and
 *     the mismatching version numbers will be logged.
 *
 * First:
 *     virtual int32_t createDataBlock(char *target, int tag)
 *
 *     will be called. "target" and "tag" determine the data in a unique manner.
 *     An array of type "uint32_t*" with the appropriate data must be prepared.
 *     The length of this array must be returned by this member function.
 *
 *     if the return value is negative TODO ???
 *
 * Second:
 *     "virtual uint32_t getWatchDogTimeOut()"
 *
 *     will be called. If this member function has been overridden a positive integer
 *     number determining the time span in seconds is expected. The watch dog
 *     running in the (JAVA) InterCom Layer (JICL) will notify via log file and
 *     DIM service channel if the expected acknowledge from the initialized
 *     FeeServer was not received within this time span. If this member function has not
 *     been overridden the default time span of 120 seconds will be used.
 *
 * Third:
 *     "virtual uint32_t* getDataBlock()"
 *
 *     will be called. The reference to the data block prepared in the first step
 *     must be delivered. The JICL then reads the number of uint32_t values
 *     received as return value in step one. The Command Coder must not delete[]
 *     the integer array within the body of the getDataBlock() member function. A sensible
 *     implementation could release (or reuse) memory in the following createDataBlock
 *     call.
 *
 * NB: The memory management is in the responsibility of the Command Coder and
 * must be strictly implemented. The memory of the Command Coder is within the
 * heap of the JICL. A memory leak could therefore eventually cause termination
 * of the Command Coder and JICL.
 *
 */

#ifndef COMMANDCODERBASE_HH
#define COMMANDCODERBASE_HH

#include <vector>
#include <string>

class CommandCoderBase {
public:

	/**
	 * createDataBlock create the desired configuration block for the
	 * Altro/RCU.
	 *
	 * @param target the FeeServer target name
	 * @param tag the tag to identify a configuration in the database
	 * @return the size of the created data block. This is the number of uint32_t
	 *		data packets in the array returned in the subsequent getDataBlock call.
	 * 		If an error occurs the member function will return a negative value or zero
	 *      as error code.
	 *      This number will be logged and an acknowledge with this number will be
	 *      published in the DIM channel with this target name.
	 *      If this target is not known to the ICL only the logging takes place.
	 */
	virtual int32_t createDataBlock(char *target, int tag) = 0;

	/**
	 * getDataBlock returns the created configuration block.
	 *
	 * @return a pointer to a number of uint32_t values representing the configuration block.
	 * The number of values is the value returned by the last call to createDataBlock.
	 */
	virtual uint32_t* getDataBlock() = 0;

	/**
	 * getWatchDogTimeOut returns a timeout in seconds for the data block created in the last call to
	 * createDataBlock.
	 *		The default value is 120.
	 *		For each created data block the value returned by this function determines how long the JICL
	 *		waits for an ACK before assuming the FeeServer is unresponsive.
	 *		The default value of 120 seconds is acceptable but may not work in some cases.
	 *
	 *    In the long delay case the JICL may mark a FeeServer as unresponsive before it has a chance to
	 *    answer. Even worse no acknowledge will be routed through the JICL for too late coming events.
	 *    Conversely in the case of a very short delay the JICL may bind timer related resources for
	 *    an unnecessary duration. In these cases this member function can be overridden to return a different
	 *    value. This can be some appropriate constant value or a computed value that is appropriate for the
	 *    data block created in the last call to createDataBlock.
	 *
	 *    No acknowledge will be expected for the negative delay  "-1". This is useful for reboot commands,
	 *    where the front end electronic is not able to send an acknowledge.
	 *
	 * @return the timeout in seconds for the created data packet, or "-1" for suppressing the time out facility.
	 */
	virtual int32_t getWatchDogTimeOut() {
		// -2 signals the JICL that the value "controlFeroTimeoutInSeconds=xx"
		// found in the setup file "Property.txt" should be used. If no value
		// in "Property.txt" has been set, than the default value (120 seconds)
		// will be used.
		return -2;
	}

	/**
	 * getError returns a possibly empty vector of error messages associated with processing the current data
	 * block. The implementation is responsible for the managing the memory possibly associated with these
	 * error messages.
	 *
	 * @return the error messages in a constant std::vector<std::string> reference.
	 */
	virtual const std::vector<std::string>& getError() = 0;

	/**
	 * getCoCoInfo returns the version of the CoCo.
	 *
	 * @return the version as a std::string reference.
	 */
	virtual const std::string& getCoCoInfo() = 0;

	/*
	 * Destructor
	 */
	virtual ~CommandCoderBase() {
	}
};

#endif