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

/* 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"
#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;


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

        void SendComponentType();
        void ConnectToRemoteComponent(const char* serverName, \
                const char* serverPort);
        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);
        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);
        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;
};

#endif