root/vtcross/trunk/src/include/vtcross/cross_shell.h @ 518

/*
 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 declaration for the CROSS Shell component, which is
 * a critical part of every CROSS system. 
 */

#ifndef CROSS_SHELL_H
#define CROSS_SHELL_H


#include "components.h"


/*! \brief Cognitive Radio Shell class declaration. 
 *
 * The CROSS Cognitive Radio Shell (CRS) is the central control component of
 * most CROSS radios.  It is a requirement for any CROSS radio, regardless of
 * the presence or lack thereof of the SML.
 */
class CognitiveRadioShell 
{
    public:
        /*! \brief Default CRS costructor. */
        CognitiveRadioShell();

        /*! \brief Default CRS destructor. */
        ~CognitiveRadioShell();

        /*! \brief Preferred CRS constructor.
         *
         * 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);

        /*! \brief Request the component type of a remote component. */
        std::string GetRemoteComponentType(int32_t socketFD);

        /*! \brief Respond to a request to identify component type. */
        void SendComponentType(int32_t socketFD);

        /*! \brief Shutdown the CRS.
         *
         * Since the CRS is the central control component of the CROSS radio,
         * shutting down the CRS will shutdown the entire radio.
         */
        void Shutdown();

        /*! \brief Restart the CRS.
         *
         * Restart the CRS component - reloads configuration files, and
         * re-initializes the CRS component.
         */
        void Reset();
        
        /*! \brief Start the CRS's socket server. 
         *
         * This function will make the CRS create a socket server and begin
         * listening for incoming connections from other components.
         */
        void StartShellServer(); 

        /*! \brief Load the radio configuration.
         *
         * This function reads in the radio's XML configuration file, which is
         * typically located on the same system as the CRS, although it can also
         * be passed to the CRS from the radio host platform if necessary.
         */
        int32_t LoadRadioConfiguration(const char* radioConfig, Parameter* &pList, \
            Utility* &uList, Observable* &oList, Radio_Info* radioInfo);
    private:
        /*! \brief Handle component registration activities.
         *
         * Register and Deregister the different components.
         * TODO Are multiple functions really necessary?  They are all basically
         * doing the same thing...
         */
        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);
        
        /*! \brief Set the active mission.
         *
         * This function handles a request by the radio host platform to set or
         * change the current active mission in the service management layer.
         * This command is basically passed through the CRS to the SML.
         */
        void SetActiveMission(int32_t socketFD);

        /* Handle a message that is received from a component.
         */
        int32_t HandleMessage(int32_t socketFD);
       
        /*! \brief Send optimization request to CE.
         *
         * The host application requested that parameters be optimized - pass
         * the parameters and command to the CE.
         *
         * TODO How is the CE being selected if multiple CEs are available?
         */
        void GetOptimalParameters(int32_t socketFD);

        /*! TODO
         */
        bool SendRadioConfiguration(int32_t socketFD);
        bool SendRadioExperience(int32_t socketFD);

        /*! TODO
         */
        bool UpdateParameterPerformance(int32_t socketFD);

        /*! TODO
         */
        bool SML_present;
        bool PE_present;
        bool CE_present;
       
        /*! TODO
         */
        int32_t numberOfCognitiveEngines; 

        /*! TODO
         */       
        int16_t primaryPort;
        int16_t policyPort;
        int16_t commandPort;

        /*! TODO
         *
         * I'm confused as to what exactly these are for... there can be
         * multiple CEs and PEs, and the CRS _IS_ the command component.
         * --BCH
         */
        int32_t ceSocketFD;
        int32_t commandSocketFD;
        int32_t policySocketFD;

        /*! TODO
         */
        Utility *utils;
        Parameter *params;
        Observable *observables;

        /*! TODO
         */
        struct Radio_Info *radio_info;
};

#endif