root/vtcross/trunk/src/include/vtcross/components.h @ 181

/* Virginia Tech Cognitive Radio Open Source Systems
 * Virginia Tech, 2009
 *
 * LICENSE INFORMATION GOES HERE
 */

/* This header exports the declarations for all VT-CROSS radio components.  It
 * contains two pure abstract base classes, Component and Engine; Engine derives
 * from Component.  All functions contained within the abstract base classes are
 * dynamically linked and pure, and all child non-abstract classes derive using 
 * private inheritence.  Class functions of the abstract base classes are public
 * for two reasons: (1) To allow for public/protected inheritence in other 
 * implementations, (2) So that symbolic debuggers can navigate the call tree 
 * for typecasted objects of derivative classes.
 */

#ifndef COMPONENTS_H
#define COMPONENTS_H


#include <stdint.h>
#include <string>

#include "containers.h"


/* Component abstract base class that all component classes should inherit from,
 * including cognitive and policy engines, and the service management layer.
 * Defines only functions required by all component types.
 */
class Component
{
    public:
        /* Asks the component at the passed socket FD for its component type
         * string.
         */
        virtual void GetRemoteComponentType(int32_t socketFD) = 0;


        /* Wait for a command signal containing task instructions.
         */
        virtual void WaitForSignal(int32_t socketFD) = 0;


        /* Completely shutdown the radio and all operations.
         */
        virtual void Shutdown() = 0;


        /* Reset the radio and reload all configuration files.
         *
         * TODO are we remembering experiences in CEs?
         */
        virtual void Reset() = 0;


        /* Register or deregister a component with the primary radio shell.
         */
        virtual void RegisterComponent(int32_t socketFD) = 0;
        virtual void DeregisterComponent(int32_t socketFD) = 0;
};


/* Engine abstract base class from which all engine component types should
 * inherit (e.g. cognitive and policy engines). Inherits all functions from the
 * ABC Component publically.
 *
 * TODO perhaps this shouldn't be an abstract base class? Some functions, like
 * GetRemoteComponentType, are going to be the same for all child classes
 * anyways...
 */
class Engine : public Component
{
    public:
        /* Register or deregister services that this engine provides with the
         * service management layer.
         */
        virtual void RegisterServices(int32_t socketFD) = 0;
        virtual void DeregisterServices(int32_t socketFD) = 0;
};


/* Service Management Layer (SML) class declaration.  The functions listed here
 * are required by the VTCROSS API for service-oriented VTCROSS radio
 * architectures.
 */
class ServiceManagementLayer : public Component
{
    public:
        ServiceManagementLayer();
        ~ServiceManagementLayer();

        void GetRemoteComponentType(int32_t socketFD);
        void WaitForSignal(int32_t socketFD);
        void Shutdown();
        void Reset();
        void RegisterComponent(int32_t socketFD);
        void DeregisterComponent(int32_t socketFD);

    private: 
        /* Receive the radio configuration settings from the shell and pass them
         * on to another component.
         */
        void TransferRadioConfiguration();

        
        /* Receive information regarding a completed 'experience' and pass it on
         * to the appropriate cognitive engine.
         */
        void TransferExperience();

        
        /* Listen for other components registering their available services with
         * the SML. */
        void ReceiveServices();


        /* Change the active mission of the radio to a new one and adjust radio
         * behavoir appropriately.
         */
        void SetActiveMission();


        /* List all services provided to the radio by registered components.
         */
        void ListServices();


        /* Load/Relead the XML configuration file. 
         */
        void ReloadConfiguration();
        void LoadConfiguration();
};


/* Contains information regarding the SML in a VTCROSS system.  Note that if
 * there is no SML present, the engine should have no instantiation of this
 * struct.
 */
struct SML_Info {
    std::string hostname;
    std::string port;
    int32_t socketFD;
};


/* Policy Engine class declaration.  All public functions are inherited from
 * parent classes.
 */
class PolicyEngine : public Engine
{
    public:
        PolicyEngine();
        ~PolicyEngine();


        /* Overloaded constructor that creates a policy engine object with SML
         * information pre-defined.
         */
        PolicyEngine(const char* serverName, const char* portNumber);

        void GetRemoteComponentType(int32_t socketFD);
        void WaitForSignal(int32_t socketFD);
        void Shutdown();
        void Reset();
        void RegisterComponent(int32_t socketFD);
        void DeregisterComponent(int32_t socketFD);

        void RegisterServices(int32_t socketFD);
        void DeregisterServices(int32_t socketFD);

    private:
        /* Parse and load/reload policies into the policy engine.
         */
        void LoadPolicies();
        void ReloadPolicies();

        
        /* Return a decision made by the policy engine regarding a certain set
         * of transmission parameters.
         */
        void SendPEDecision(int32_t socketFD, struct Parameter pList[], \
                struct CE_Info *ce_info, int32_t decision_array[]);


        /* Validate a set of transmission parameters received from the radio.
         */
        void ValidateParameters(struct Parameter pList[], \
                struct CE_Info *ce_info, int decision_array[]);


        /* Contains information regarding the presence of a service management
         * layer.  If this pointer is NULL, then there is no SML present in the
         * radio system.
         */
        struct SML_Info *SML;
};


/* Cognitive Engine class declaration.  All public functions are inherited from
 * parent classes.
 */
class CognitiveEngine : public Engine
{
    public:
        CognitiveEngine();
        ~CognitiveEngine();

        void GetRemoteComponentType(int32_t socketFD);
        void WaitForSignal(int32_t socketFD);
        void Shutdown();
        void Reset();
        void RegisterComponent(int32_t socketFD);
        void DeregisterComponent(int32_t socketFD);

        void RegisterServices(int32_t socketFD);
        void DeregisterServices(int32_t socketFD);

    private:
        /* Receive the transmitted radio configuration from the radio itself
         * (the CE will not always be local to the radio).
         */
        void ReceiveRadioConfiguration(int32_t socketFD);


        /* Receive an 'experience' report from the radio.
         */
        void ReceiveExperience(int32_t socketFD);


        /* Find the most optimal set of transmission parameters given certain
         * observables and possibly a service if the SML component is present
         * and active.
         */
        void GetSolution(Observable *observables);
        void GetSolution(Observable *observables, std::string service);


        /* Receive a feedback from the radio regarding the performance of a
         * certain set of parameters, possibly associated with a service.
         *
         * TODO what is the difference between experiences and feedback,
         * exactly? we should explain that explicitly here.
         */
        void ReceiveFeedback(Observable *observables,\
                Parameter *parameters, Utility *utilities);
        void ReceiveFeedback(Observable *observables, \
                Parameter *parameters, std::string service);


        /* Contains information regarding the presence of a service management
         * layer.  If this pointer is NULL, then there is no SML present in the
         * radio system.
         */
        struct SML_Info *SML;

};

#endif