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

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

#include <stdint.h>

#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.
 */
Observable* GetRadioObservables();
Parameter* GetRadioParameters();
Utility* 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? 
 */
Parameter* GetOptimalParameters(Observable *radioObservables, uint32_t numObservables, 
                Parameter *currentParameters, uint32_t numCurrentParameters);


/* 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(Parameter *radioParameters, \
        Observable *radioObservables, Utility *radioUtilies);


/* Deactivate/Activate/Disconnect a component by id.
 */
bool ActivateComponent(uint32_t id);
bool DeactivateComponent(uint32_t id);
bool DisconnectComponent(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();

/* Return total number of currently recognized transmission parameters.
 */
uint32_t GetNumParameters();


#endif