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

/* Virginia Tech Cognitive Radio Open Source Systems
 * Virginia Tech, 2009
 *
 * LICENSE INFORMATION GOES HERE
 */

/* VTCROSS Cognitive Radio API
 *
 * This header exports all public functions that comprise the VTCROSS function
 * library.  
 *
 * PUT MORE STUFF HERE
 */

#ifndef LIBVTCROSS_H
#define LIBVTCROSS_H

#ifdef GCC_EXPERIMENTAL
    #include <cstdint>
#else
    #include <stdint.h>
#endif

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


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


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


/* 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.
 */
Observables* GetRadioObservables();
Parameters* GetRadioParameters();
Utilities* GetRadioUtilities();


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


/* Look up component information by id. 
 *
 * Note that the return type is of abstract base class component, which can then
 * be used to reference whatever sub-component type was referenced by the id.
 */
Component* GetComponentInformation(uint32_t id);


/* 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? 
 */
Parameters* GetOptimalParameters(Observables *radioObservables);


/* Update the radio regarding its performance for a certain set of transmission
 * parameters, observables, and utilities.
 *
 * TODO Where in the function parameters are we accurately representing the
 * radio's performance?
 */
bool UpdateParameterPerformance(Parameters *radioParameters, \
        Observables *radioObservables, Utilies *radioUtilies);


/* Deactivate/Activate/Disconnect a component by id.
 *
 * TODO This seems silly?  If id's are independent of component type, why not
 * just have one deactivate function that takes an id and operates on it? Why do
 * we need 3 separate functions? They are all components...
 */
bool DeactivateCE(uint32_t id);
bool DeactivatePE(uint32_t id);
bool DeactivateSML(uint32_t id);
bool ActivateCE(uint32_t id);
bool ActivatePE(uint32_t id);
bool ActivateSML(uint32_t id);
bool DisconnectCE(uint32_t id);
bool DisconnectPE(uint32_t id);
bool DisconnectSML(uint32_t id);


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

#endif