root/vtcross/trunk/src/include/vtcross/libvtcross.h @ 536

/*
 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. 
*/

/*! CROSS Cognitive Radio API
 *
 * This header exports all public functions that comprise the CROSS function
 * library.  These are the functions that are used by the host application to
 * control the CROSS radio.  
 *
 * PUT MORE STUFF HERE
 */

#ifndef LIBCROSS_H
#define LIBCROSS_H

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

#include "components.h"
#include "containers.h"


/*! \brief Tell the system where the Shell component is located. 
 *
 * Sets the location of the shell component that the client code will be
 * communicating with. Note that this can be a local or remote destination.
 */
void SetCrossShellLocation(std::string hostname, std::string port);


/*! \brief  Parses XML configuration file and uses it to configure the radio. 
 *
 * This function *must* be called when the radio first starts up, and may be
 * called at any point after that to reconfigure the radio.
 */
bool ParseRadioConfiguration();


/*! \brief Lists current radio configuration options loaded from the XML.
 *
 * TODO How are we listing these?  Are we simply returning them to stdout?
 * Logging them? Returning strings?  Need to figure this out...
 */
void ListCurrentRadioConfiguration();


/*! \brief View data from the current status of the radio. 
 *
 * This function allows client code to capture radio properties at any certain
 * instant.  Note, however, that these properties could be changing at very
 * rapid rates. There is no guarantee that the return results from these
 * functions will still be valid by the time the client code receives them.
 */
Observable* GetRadioObservables();
Parameter* GetRadioParameters();
Utility* GetRadioUtilities();


/*! \brief View components currently connected to the radio by id. 
 *
 * TODO Should there be another way to list components? If you have 10 cognitive
 * engines, how are you going to know which is which just by id?
 */
uint32_t* GetConnectedCognitiveEngines();
uint32_t* GetConnectedPolicyEngines();
uint32_t* GetConnectedManagementServiceLayers();
uint32_t* GetConnectedComponents();


/*! \brief  Given a certain set of observables, ask the radio to find the 
 * optimum radio parameters and return them. 
 *
 * TODO I'm a little confused about this function... why would anyone need to
 * use this?  Shouldn't this be internal to the radio operation? 
 */
Parameter* GetOptimalParameters(Observable *radioObservables, uint32_t numObservables, 
                Parameter *currentParameters, uint32_t numCurrentParameters);


/*! \brief  Update the radio regarding its performance.
 *
 * TODO
 */
bool UpdateParameterPerformance(Parameter *p, uint32_t numParameters, Observable *o, \
        uint32_t numObservables);

/*! \brief Deactivate/Activate/Disconnect a component by id.
 */
bool ActivateComponent(uint32_t id);
bool DeactivateComponent(uint32_t id);
bool DisconnectComponent(uint32_t id);

/*! \brief Set the active mission of the CROSS radio.
 */
uint32_t SetActiveMission(char * activeMission);

/*! \brief Shut down the radio.
 *
 * This function will deactivate and disconnect all radio components before
 * finally shutting down the shell and stopping radio operations.
 */
bool Shutdown();

/*! \brief Return total number of currently recognized transmission parameters.
 */
uint32_t GetNumParameters();
uint32_t GetNumObservables();
uint32_t GetNumUtilities();


#endif