Changeset 30 in pacpusframework for trunk/include/Pacpus


Ignore:
Timestamp:
Jan 8, 2013, 5:32:28 PM (12 years ago)
Author:
sgosseli
Message:

Major: improve the documentation of ComponentBase and use the new include style.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/Pacpus/kernel/ComponentBase.h

    r3 r30  
    1 // *********************************************************************
    2 // created:     2006/02/07 - 11:59
    3 // filename:    component.h
    4 //
    5 // author:      Gerald Dherbomez
    6 //
    7 // purpose:     generic ComponentBase class. This is an abstract class
    8 //
    9 // todo:        - see if some methods can be private with ComponentManager
    10 //              friendship
    11 //              - include the copy of Xml node in param here
    12 //              - see if there is a possibility to avoid the constraint
    13 //              on parameters in the constructor of derived class
    14 // *********************************************************************
     1/**
     2 *
     3 * Distributed under the UTC Heudiascy Pacpus License, Version 1.0.
     4 * Copyright (c) UTC Heudiasyc 2010 - 2013. All rights reserved.
     5 *
     6 * See the LICENSE file for more information or a copy at:
     7 *   http://www.hds.utc.fr/~kurdejma/LICENSE_1_0.txt
     8 *
     9 */
     10 
     11#ifndef DEF_PACPUS_COMPONENTBASE_H
     12#define DEF_PACPUS_COMPONENTBASE_H
    1513
    16 #ifndef COMPONENTBASE_H
    17 #define COMPONENTBASE_H
    18 
    19 #include "kernel/ComponentManager.h" // FIXME: remove this line when all components include it
    20 #include "kernel/pacpus.h"
    21 #include "XmlComponentConfig.h"
     14#include <Pacpus/kernel/ComponentManager.h>
     15#include <Pacpus/kernel/pacpus.h>
     16#include <Pacpus/kernel/XmlComponentConfig.h>
    2217
    2318#include <QString>
    2419
    25 namespace pacpus {
     20namespace pacpus
     21{
     22  class ComponentManager;
    2623
    27 class ComponentManager;
    28 
    29 class PACPUSLIB_API ComponentBase
    30 {
     24  /** ComponentBase
     25   * @brief Base class of a Pacpus component.
     26   */
     27  class PACPUSLIB_API ComponentBase
     28  {
    3129    friend class ComponentManager;
    32 
    33 public:
    34     // Here is the enumeration of the state that can take a component
    35     // The 3 last states suppose that the component is started
    36     enum COMPONENT_STATE
    37     {
     30    public:
     31      /**
     32       * Enumeration of the state that can take a component, the three last states suppose
     33       * that the component is started.
     34       */
     35      enum COMPONENT_STATE
     36      {
    3837        STOPPED,
    3938        NOT_MONITORED,
    4039        MONITOR_OK,
    4140        MONITOR_NOK
    42     };
     41      };
    4342
    44     // The different identifying the configuration of the component
    45     enum COMPONENT_CONFIGURATION
    46     {
     43      /** Resulting state of a component after its configuration. */
     44      enum COMPONENT_CONFIGURATION
     45      {
    4746        CONFIGURED_OK,
    4847        NOT_CONFIGURED,
    4948        CONFIGURATION_DELAYED,
    5049        CONFIGURED_FAILED
    51     };
     50      };
    5251
    53     // constructor - your derived component must have only one parameter
    54     // in its constructor which is name
    55     ComponentBase(QString name);
     52      /** Ctor of ComponentBase.
     53       * @param name Name of your component.
     54       */
     55      ComponentBase(const QString& name);
    5656
    57     // destructor
    58     virtual ~ComponentBase();
     57      /** Dtor of ComponentBase. */
     58      virtual ~ComponentBase();
    5959
    60     // return the state of the component
    61     COMPONENT_STATE getState();
     60      /** Return the state of the component.
     61       * @return Value of the current state.
     62       */
     63      COMPONENT_STATE getState();
    6264
    63     // return true if the component is configured, false else
    64     inline bool isConfigured()
    65     {
    66         return (CONFIGURED_OK == configuration_);
    67     }
     65      /** Check whether the component if configurer or not.
     66       * @return True if the component is configured, otherwise false.
     67       */
     68      bool isConfigured() const;
    6869
    69 protected:
    70     // define the state of the component
    71     void setState(COMPONENT_STATE state);
     70    protected:
     71      /** Change the state of the component.
     72       * @param state New component state.
     73       */
     74      void setState(COMPONENT_STATE state);
    7275
    73     // pure virtual function - what to do when the component starts?
    74     virtual void startActivity() = 0;
     76      /** Called when the component starts, you must override this function. */
     77      virtual void startActivity() = 0;
    7578
    76     // pure virtual function - what to do when the component stops?
    77     virtual void stopActivity() = 0;
     79      /** Called when the component stops, you must override this function. */
     80      virtual void stopActivity() = 0;
    7881
    79     // This function is called by the ComponentManager when it loads the XML file
    80     // It gives to the component the XML node corresponding to its
    81     // So the component can handle some properties defined in the XML config file
    82     // via XmlComponentConfig methods
    83     virtual COMPONENT_CONFIGURATION configureComponent(pacpus::XmlComponentConfig config) = 0;
     82      /** Called by the ComponentManager, it configure the component thanks a XML node.
     83       * @param config Component's XML node.
     84       * @return State of the configuration.
     85       * FIXME: 'config' should be const, but we can't change the prototype without breaking
     86       * old stuff.
     87       */
     88      virtual COMPONENT_CONFIGURATION configureComponent(XmlComponentConfig config) = 0;
    8489
    85     // The XML node that is got in the configureComponent method
    86     pacpus::XmlComponentConfig param;
     90      // The XML node that is got in the configureComponent method
     91      XmlComponentConfig param;
    8792
    88     // the name of the component. It is this one in the XML config file
    89     QString componentName;
     93      // the name of the component. It is this one in the XML config file
     94      QString componentName;
    9095
    91     // is the component is recording data?
    92     bool recording;
     96      // is the component is recording data?
     97      bool recording;
    9398
    94     // provided for compatibility with old DBITE framework
    95     bool THREAD_ALIVE;
     99      // provided for compatibility with old DBITE framework
     100      bool THREAD_ALIVE;
    96101
    97     // is the component active?
    98     bool mIsActive;
     102      // is the component active?
     103      bool mIsActive;
    99104
    100     // a pointer to the manager of components
    101     ComponentManager * mgr;
     105      // a pointer to the manager of components
     106      ComponentManager * mgr;
    102107
    103 private:
    104     // called by the ComponentManager to start the component
    105     int startComponent();
     108    private:
     109      // called by the ComponentManager to start the component
     110      int startComponent();
    106111
    107     // called by the ComponentManager to stop the component
    108     int stopComponent();
     112      // called by the ComponentManager to stop the component
     113      int stopComponent();
    109114
    110     // store the state of the component
    111     COMPONENT_STATE componentState_;
     115      // store the state of the component
     116      COMPONENT_STATE componentState_;
    112117
    113     // is the component configured (ie configureComponent method was called)
    114     COMPONENT_CONFIGURATION configuration_;
    115 };
     118      // is the component configured (ie configureComponent method was called)
     119      COMPONENT_CONFIGURATION configuration_;
     120  };
     121}
    116122
    117 } // namespace pacpus
    118 
    119 #endif // COMPONENTBASE_H
     123#endif
Note: See TracChangeset for help on using the changeset viewer.