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

/* 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 <cstring>
#include <stdint.h>
#include <string>

#include "containers.h"
#include "socketcomm.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.  Note that this implementation is global for all component
         * types, so is implemented here.  Should a component need to override
         * it, that is possible via dynamic binding or overloading.
         */
        virtual std::string GetRemoteComponentType(int32_t componentSocketFD)
        {
            SendMessage(componentSocketFD, "request_component_type");

            char buffer[256];
            memset(buffer, 0, 256);
            ReadMessage(componentSocketFD, buffer);

            return std::string(buffer);
        }

        /* Send an indentfying string for this object's component type in
         * response to a GetRemoteComponentType query.
         */
        virtual void SendComponentType() = 0;

        /* Wait for a command signal containing task instructions.
         */
        virtual void WaitForSignal() = 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() = 0;
        virtual void DeregisterComponent() = 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.
 */
class Engine : public Component
{
    public:
        /* Connect to the remote control component, which will always be either
         * the VTCROSS shell or SML.  Based on the status of the SML_present
         * bool, this function will also register the component or services.
         *
         * TODO I feel like the name of this function could be changed to be a
         * little more descriptive?
         */
        virtual void ConnectToRemoteComponent(const char* serverName, \
                const char* serverPort, const bool SML) = 0;

        /* Register or deregister services that this engine provides with the
         * service management layer.
         */
        virtual void RegisterServices() = 0;
        virtual void DeregisterServices() = 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();

        /* Overloaded constructor that creates an SML and connects it to the
         * shell with the passed hostname and port.
         */
        ServiceManagementLayer(const char* serverName, const char* serverPort);

        /* Connect and register with the shell component at the passed hostname
         * and port.
         */
        void ConnectToShell(const char* serverName, \
                const char* serverPort);

        void SendComponentType();
        void WaitForSignal();
        void Shutdown();
        void Reset();
        void RegisterComponent();
        void DeregisterComponent();

    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();

        /* The socket file descriptor information for the shell which this SML
         * is connected to.
         */
        int32_t shellSocketFD;
};


/* 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 and
         * connects it to either the shell or an SML, depening on the SML bool.
         */
        PolicyEngine(const char* serverName, const char* serverPort, \
                const bool SML);

        void SendComponentType();
        void ConnectToRemoteComponent(const char* serverName, \
                const char* serverPort, const bool SML);
        void WaitForSignal();
        void Shutdown();
        void Reset();
        void RegisterComponent();
        void DeregisterComponent();

        void RegisterServices();
        void DeregisterServices();

    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(struct Parameter pList[], struct Radio_Info *radio_info, \
                int32_t decision_array[]);

        /* Validate a set of transmission parameters received from the radio.
         */
        void ValidateParameters();

        /* The SML_present bool reflects whether or not the remote component
         * this object is connected to is an SML.  If it isn't, then it must be
         * a shell.  The socketFD stores the socket file descriptor for this
         * connection.
         */
        bool SML_present;
        int32_t commandSocketFD;
};


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

        void SendComponentType();
        void ConnectToRemoteComponent(const char* serverName, \
                const char* serverPort, const bool SML);
        void WaitForSignal();
        void Shutdown();
        void Reset();
        void RegisterComponent();
        void DeregisterComponent();

        void RegisterServices();
        void DeregisterServices();

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

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

        /* 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);

        /* The SML_present bool reflects whether or not the remote component
         * this object is connected to is an SML.  If it isn't, then it must be
         * a shell.  The socketFD stores the socket file descriptor for this
         * connection.
         */
        bool SML_present;
        int32_t commandSocketFD;
};

/* Cognitive Radio Shell class declaration. 
 */
class CognitiveRadioShell 
{
    public:
        CognitiveRadioShell();
        ~CognitiveRadioShell();

        /* Overloaded constructor that creates a CR Shell object and loads the
         * passed radio configuration XML file.
         */
        CognitiveRadioShell(const char* radioConfig, int16_t primaryPort, \
            int16_t policyPort, int16_t commandPort);

        /* Ask for the component type of a remote component via sockets, or
         * respond to such a query sent to the shell itself.
         */
        std::string GetRemoteComponentType(int32_t socketFD);
        void SendComponentType(int32_t socketFD);

        void Shutdown();
        void Reset();
        
        /* Start all the socket servers */
        void StartShellServer();

        int32_t LoadRadioConfiguration(const char* radioConfig, Parameter* &pList, \
            Utility* &uList, Observable* &oList, Radio_Info* radioInfo);
    private:
        /* Parse and load/reload policies into the policy engine.
         */
        void LoadPolicies();
        void ReloadPolicies();

        /* Register and Deregister the different components.
         */
        void RegisterCognitiveEngine(int32_t socketFD);
        void DeregisterCognitiveEngine(int32_t socketFD);
        void RegisterPolicyEngine(int32_t socketFD);
        void DeregisterPolicyEngine(int32_t socketFD);
        void RegisterSML(int32_t socketFD);
        void DeregisterSML(int32_t socketFD);

        /* Handle a message that is received from a component.
         */
        void HandleMessage(int32_t socketFD);
       
        /* Send optimization request to primary port FD.
         */
        void GetOptimalParameters(int32_t socketFD);

        void SendRadioConfiguration(int32_t socketFD);
        void SendRadioExperience(int32_t socketFD);
 
        bool SML_present;
        bool PE_present;
        bool CE_present;
       
        int32_t numberOfCognitiveEngines; 
        int16_t primaryPort;
        int16_t policyPort;
        int16_t commandPort;

        Utility *utils;
        Parameter *params;
        Observable *observables;
        struct Radio_Info *radio_info;
};

#endif