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

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

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


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


/* 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 *p, uint32_t numParameters, Observable *o, \
        uint32_t numObservables);

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

uint32_t SetActiveMission(char * activeMission);

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


#endif