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

/*
 Copyright 2009 Virginia Polytechnic Institute and State University  

 Licensed under the Apache License, Version 2.0 (the "License"); 
 you may not use this file except in compliance with the License. 
 You may obtain a copy of the License at 
 
 http://www.apache.org/licenses/LICENSE-2.0 

 Unless required by applicable law or agreed to in writing, software 
 distributed under the License is distributed on an "AS IS" BASIS, 
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 See the License for the specific language governing permissions and 
 limitations under the License. 
*/

/* 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* SML_Config, const char* serverName, const char* serverPort, int16_t clientPort);

        /* Connect and register with the shell component at the passed hostname
         * and port.
         */
        void ConnectToShell(const char* serverName, \
                const char* serverPort);
        void SendComponentType();
        void MessageHandler(int32_t ID);
        void Shutdown();
        void Reset();
        void RegisterComponent();
        void DeregisterComponent();

        /* Starts the SML Server and watches it for incoming messages
         */
        void StartSMLServer();

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

        /* Receive information regarding a completed 'experience' and pass it on
         * to the appropriate cognitive engine.
         */
        void TransferExperience(int32_t ID);
        
        /* Listen for other components registering their available services with
         * the SML. 
         */
        void ReceiveServices(int32_t ID);
        void DeregisterServices(int32_t ID);

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

        void RegisterCognitiveEngine(int32_t ID);
        void DeregisterCognitiveEngine(int32_t ID);

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

        /* Load/Relead the XML configuration file. 
         */
        void ReloadConfiguration();
        void LoadConfiguration(const char *SML_Config, Mission* &mList);

        /* Create and initialize the DB to hold the services
         */
        void CreateServicesDB();
        void CreateDataDB();

        void PerformActiveMission();
        void TransactData(int32_t sourceID);


        /* The socket file descriptor information for the shell which this SML
         * is connected to.
         */
        int32_t shellSocketFD;
        CE_Reg *CE_List;
        int32_t cogEngSrv;
        int16_t CEPort;
        uint16_t numberOfCognitiveEngines;
        uint32_t Current_ID; 
        Mission *miss;
        bool CE_Present;
        int32_t activeMission;

        int16_t SMLport;
};


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

        /* Overloaded constructor that creates a cognitive engine object and
         * connects it to either the shell or an SML, depening on the SML bool.
         */
        CognitiveEngine(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:
        /* 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.
         */
        Parameter *GetSolution(Observable *observables, Parameter *currentParameters);
        Parameter *GetSolution(Observable *observables, Parameter *currentParameters, std::string service);

        /* Receive a feedback from the radio regarding the performance of a
         * certain set of parameters, possibly associated with a service.
         *
         * Feedback is a single set of performance statistics that is achieved
         * corresponding to a specific set of transmission parameters.  Feedback
         * helps a Cognitive Engine make better future decisions based upon 
         * more accurate performance statistics. 
         */
        void ReceiveFeedback(Observable *observables,\
                Parameter *parameters);
        void ReceiveFeedback(Observable *observables, \
                Parameter *parameters, std::string service);


                /* BuildCognitiveEngine performs the CE implementation specific work
                 * that defines the internals of a CE.  For example, a CBR CE engine
                 * would build the case-base reasoner or create the database, a neural
                 * network based CE may perform the initial training, a GA based CE
                 * may build the chromosome structure.
                 */
                void BuildCognitiveEngine();

        /* 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;
        
        // TODO Need a description for these fields.  Are these radio utilites,
        // parameters, and observables global to the whole system?
        Utility *uList;
        Parameter *pList;
        Observable *oList;
        struct Radio_Info *radioInfo;
};

/* 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);
        
        void SetActiveMission(int32_t socketFD);

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

        bool SendRadioConfiguration(int32_t socketFD);
        bool SendRadioExperience(int32_t socketFD);

                bool UpdateParameterPerformance(int32_t socketFD);

        bool SML_present;
        bool PE_present;
        bool CE_present;
       
        int32_t numberOfCognitiveEngines; 
        int16_t primaryPort;
        int16_t policyPort;
        int16_t commandPort;

        int32_t ceSocketFD;
        int32_t commandSocketFD;
        int32_t policySocketFD;

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

#endif