/*
 * controller_AddOn.hpp
 *
 *  Created on: 01.06.2012
 *      Author: heber
 */

#ifndef CONTROLLER_ADDON_HPP_
#define CONTROLLER_ADDON_HPP_

// include config.h
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif


#include <boost/function.hpp>
#include <boost/program_options.hpp>

class ControllerCommand;
class ControllerCommandRegistry;
class ControllerInfo;
class ControllerOptions;
class FragmentController;

struct controller_AddOn;

/** This is the allocator function for the specific controller addon structure.
 *
 * The implementation should reside in its own module such that it can be
 * linked in unison with the \file controller.cpp and the derived implementation
 * of controller_AddOn to the executable controller.
 */
extern "C++" controller_AddOn *getAddOn();

/** This is the structure that contains functions to extend the functionality
 * of the basic controller with respect to certain jobs and commands.
 *
 * Here, we have four types of functions:
 * -# Allocator: Required to allocate to specific function which contains
 *    extended member variables and parsing functions.
 * -# Commands: Add more commands to the registry of the controller.
 * -# Options: Add more command-line options to require additional information
 *    from the user.
 * -# Parsers: Add parsing function to place parameter from command-line
 *    into internal structure allocated via Allocator.
 *
 * The allocated structure is the one which contains all information for the
 * execution of these commands. Note that some defaults are already parsed
 * and stored therein by the controller by default.
 *
 * \note All these functions are called within the basic controller, hence
 * all parameters are instances of this basic controller.
 */
struct controller_AddOn {
  /** Function to allocate a derived variant of ControllerOptions which might
   * be extended by own member variables and parsing functions.
   *
   * \return Pointer to allocated instance of ControllerOptions or derived.
   */
  virtual ControllerOptions *allocateControllerInfo()=0;

  /** Function to register new commands communicating with a server.
   *
   * \param registrator registrator function for the generated ControllerCommand
   * \param controller access to controller to bind to its functions
   * \param ControllerInfo All other options of the controller
   */
  virtual void addSpecificCommands(
      boost::function<void (ControllerCommand *)> &registrator,
      FragmentController &controller,
      ControllerOptions &ControllerInfo)=0;

  /** Function to add other command line options if more use input is required.
   *
   * \param option option_description entity that can be used to add another
   *  boost::program_options as follows:
   *  \code
   *   option("command,c", boost::program_options::, "description");
   *  \endcode
   */
  virtual void addSpecificOptions(
      boost::program_options::options_description_easy_init option)=0;

  /** Function to add a parsing function for placing info from the command line
   * option into \a ControllerInfo.
   *
   * \param ControllerInfo May be reinterpret_cast to true type as has been
   * allocated in controller_AddOn::allocateControllerInfo.
   * \param vm map of command line variables
   * \return 0 - ok, else - some failure code (which leads to program exit)
   */
  virtual int addOtherParsings(
      ControllerOptions &ControllerInfo,
      boost::program_options::variables_map &vm)=0;
};

#endif /* CONTROLLER_ADDON_HPP_ */