root/vtcross/trunk/src/include/vtcross/components.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 base declarations for all 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.
 *
 * Note that any new component type declaration MUST include this header and
 * extend a parent component type.
 */

#ifndef COMPONENTS_H
#define COMPONENTS_H


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

#include "containers.h"
#include "socketcomm.h"


/*! \brief The Component class is the top-level abstract base class in CROSS.
 *
 * 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:
        /*! \brief Asks a component to identify itself. 
         *
         * 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);
        }

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

        /*! \brief Shutdown the component. */
        virtual void Shutdown() = 0;

        /*! \brief Reset the component and reload configurations. */
        virtual void Reset() = 0;

        /*! \brief Compenent registration procedures. */
        virtual void RegisterComponent() = 0;
        virtual void DeregisterComponent() = 0;
};


/*! \brief Engine abstract base class declaration.
 *
 * 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:
        /*! \brief Connect to a remote controlling component. 
         *
         * Connect to the remote control component, which will always be either
         * the CROSS 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;
        
        /*! \brief Wait for a command signal containing task instructions.
         *
         * This is the general run-time loop from which all radio operation
         * occurs.  Once the Engine has started up and initialized, it will
         * remain in this function until it receives a command to perform some
         * action. */
        virtual void WaitForSignal() = 0;

        /*! \brief Functions for interacting with the service management layer. 
         *
         * Register or deregister services that this engine provides with the
         * service management layer. */
        virtual void RegisterServices() = 0;
        virtual void DeregisterServices() = 0;
};

#endif