Doxy-style comments

parent 1971d284
......@@ -45,11 +45,11 @@ If you want to provide a VA server connection, have a look at #VANetServer.
#ifndef IW_VANET
#define IW_VANET
#include <VANetDefinitions.h>
#include <VANetAudioStreamServer.h>
#include <VANetClient.h>
#include <VANetServer.h>
#include <VANetUtils.h>
#include <VANetVersion.h>
#include "VANetDefinitions.h"
#include "VANetAudioStreamServer.h"
#include "VANetClient.h"
#include "VANetServer.h
#include "VANetUtils.h"
#include "VANetVersion.h"
#endif // IW_VANET
......@@ -39,17 +39,34 @@ class VANET_API CVANetAudioStreamServer
{
public:
//! Create a network audio stream
/**
* @param[in] dSampleRate Sampling rate
* @param[in] iBlockLength Block length
*/
CVANetAudioStreamServer( const double dSampleRate, const int iBlockLength );
//! Destructor
virtual ~CVANetAudioStreamServer();
//! Initialize server and start listening on network port
/**
* @param[in] sBindAddress Bind address of socket
* @param[in] iBindPort Bind port of socket
*
* @return True, if initialization was successful
*/
bool Initialize( const std::string& sBindAddress, const int iBindPort );
//! Provide a frame of samples on request (overload this method)
virtual void Process( CVASampleBuffer& oFrame, const CVAAudiostreamState& ) = 0;
/**
* Networked stream process callback function, please overload and implement.
* @param[out] oFrame Target frame buffer with sampels to be generated
* @param[in] oState Stream state of audio processing
*/
virtual void Process( CVASampleBuffer& oFrame, const CVAAudiostreamState& oState ) = 0;
private:
CVANetAudioStreamServerImpl* m_pImpl;
CVANetAudioStreamServerImpl* m_pImpl; //!< Implementation instance pointer
};
#endif // IW_VANET_AUDIO_STREAM_SERVER
......@@ -20,38 +20,35 @@
class IVAInterface;
class CVANetNetworkProtocol;
//! Networked transparend calls to VA interface view TCP/IP as a client
/**
* Diese Klasse definiert die Schnittstelle fr Netzwerk-Client des VACore.
* Es wird die vollstndige Schnittstelle IVACore ber das Netzwerk repliziert.
* Instanzen mssen mittels der factory method Create() erzeugt werden.
*
* Der Client erzeugt (nach erfolgreicher Verbindung) eine Client-seitige
* Implementierung der Schnittstelle IVACore, welche mittels der Methode
* GetCoreInstance() abgerufen werden kann. Alle Befehle, die auf dieser
* Instanz aufgerufen werden, leitet der Client dann an den zugeordneten
* Server weiter.
*
* TODO:
* - Der Client muss auch VACoreEvents von der Server-Seite weiterleiten
* - Redefinieren der Attach/DetachCoreEventHandler im Protokoll
*/
* This class defines an interface for network clients to IVAInterface.
* Almost the entire interface is replicated via network.
*
* Create an instance using the factory method Create().
*
* Client creates a client-side implementation of the interface on success.
* You can get access to the (transparently networked) interface using
* GetCoreInstance(). Any method call will be forwarded to the corresponding
* server.
*
*/
class VANET_API IVANetClient
{
public:
//! Rckgabewerte / Fehlerzustnde
//! Error types
enum ErrorType
{
VA_NO_ERROR = 0, //!< Kein Fehler / Erfolgreich
VA_SERVER_CONNECTION_FAILED, //!< Verbindung zum Server fehlgeschlagen - Falsche Addresse, oder Server luft nicht
VA_SERVER_NOT_RESPONDING, //!< Verbindung zum Server wurde aufgebaut, aber keine Antwort erhalten
VA_SERVICE_IN_USE, //!< Netzwerkdienst wird bereits von anderem Client benutzt
VA_CONNECTION_ERROR, //!< Ein unbekannter netzwerkfehler ist aufgetreten
VA_PROTOCOL_INCOMPATIBLE, //!< Das Netzwerkprotokoll von Client und Server ist inkompatibel
VA_UNKNOWN_ERROR,
VA_NO_ERROR = 0, //!< No error / success
VA_SERVER_CONNECTION_FAILED, //!< Connection faild - wrong address or no server running
VA_SERVER_NOT_RESPONDING, //!< Connection established, but server is not responding
VA_SERVICE_IN_USE, //!< Network service is already used by another client
VA_CONNECTION_ERROR, //!< Unknown network error occurred
VA_PROTOCOL_INCOMPATIBLE, //!< Incompatible network protocol versions (declined connection)
VA_UNKNOWN_ERROR, //!< Any other unrecognized error
};
//HeadChannel Modi
//! Head channel modi
enum HeadChannelMode
{
VA_HC_USE_EXISTING = 0,
......@@ -59,79 +56,134 @@ public:
VA_HC_SEPARATE_UDP
};
// Exception Handling Modi
//! Exception handling modi
enum ExceptionHandlingMode
{
EXC_CLIENT_THROW, // for all functions, immediately transmit exception and throws it
//EXC_ASYNC_PRINT, // functions without return value immediately return,
// // and any exceptions are asynchronously transmitted to
// // the client and printed there
EXC_SERVER_PRINT, // functions without return value immediately return,
// and the exception is printed on the server
EXC_CLIENT_THROW, //!< for all functions, immediately transmit exception and throws it
EXC_SERVER_PRINT, //!< functions without return value immediately return, and the exception is printed on the server
};
// Factory method
//! Factory method
/**
* @return Pointer to new net client
*/
static IVANetClient* Create();
//! Destructor
virtual ~IVANetClient();
// Client-seitige VACore-Instanz zurckgeben
//! Return client-side interface (networked calls)
/**
* @return Interface pointer
*/
virtual IVAInterface* GetCoreInstance() const = 0;
// Gibt zurck, ob eine Verbindung zu einem Server besteht
//!< Server connection getter
/**
* @return True, if connection is established
*/
virtual bool IsConnected() const = 0;
// Gibt die Adresse des verbundenen Servers zurck
// (Rckgabe: leerer String, falls nicht verbunden)
//! Server address getter
/**
* @return Server address string
*/
virtual std::string GetServerAddress() const = 0;
// Client initialisieren und mit einem Server verbinden
// (Rckgabe: Statuscode)
virtual int Initialize( const std::string& sServerAddress, const int iServerPort = VANET_DEFAULT_PORT, const int iHeadChannelMode = VA_HC_USE_EXISTING, const int IExceptionHandlingMode = EXC_CLIENT_THROW, const bool bBufferSynchronizedCommands = true ) = 0;
//! Initialize client and connect server
/**
* @param[in] sServerAddress Server address string
* @param[in] iServerPort Server port (defaults to VANet definition)
* @param[in] iHeadChannelMode Server port (defaults to VANet definition)
* @param[in] iExceptionHandlingMode Define exception mode handling
* @param[in] bBufferSynchronizedCommands Buffer synchronized commands on client side
*
* @return Status code
*
*/
virtual int Initialize( const std::string& sServerAddress, const int iServerPort = VANET_DEFAULT_PORT, const int iHeadChannelMode = VA_HC_USE_EXISTING, const int iExceptionHandlingMode = EXC_CLIENT_THROW, const bool bBufferSynchronizedCommands = true ) = 0;
//! Exception mode setter
/**
* @param[in] nMode Exception mode
*/
virtual void SetExceptionHandlingMode( const int nMode ) = 0;
//! Exception mode getter
/**
* @return Exception mode
*/
virtual int GetExceptionhandlingMode() const = 0;
// Vorhandene Serververbindung beenden
// (Rckgabe: Statuscode)
//! Disconnect an established connection
/**
* @return Status code
*/
virtual int Disconnect() = 0;
//! Connection event class
class CEvent
{
public:
//! Event types
enum EventTypes
{
EVENT_NOTHING = 0,
EVENT_SERVER_DISCONNECT, // Gewollter Verbindungsabbruch
EVENT_SERVER_LOST // Ungewollter Verbindungsabbruch
EVENT_NOTHING = 0, //!< No event type
EVENT_SERVER_DISCONNECT, //!< Intended connection abort
EVENT_SERVER_LOST //<! Unintended connection loss
};
std::string sServer; //
int iType;
std::string sServer; //!< Event server
int iType; //!< Event type
//! Default constructor with no event type
inline CEvent()
: iType( EVENT_NOTHING )
{
};
inline CEvent( int iInitType, const std::string& sInitServer )
//! Constructor of special type
/**
* @param[in] iInitType Initialization type
* @param[in] sInitServer Initialization server identifier
*/
inline CEvent( const int iInitType, const std::string& sInitServer )
: iType( iInitType )
, sServer( sInitServer )
{
};
};
//! Interface for handling conection events using the provided hook / callback
class IEventHandler
{
public:
//! Destructor
inline virtual ~IEventHandler() {};
//! Handler hook
/**
* @param[in] oEvent Event information
*/
virtual void HandleEvent( const IVANetClient::CEvent& oEvent ) = 0;
};
//! Connection event handler attachment
/**
* @param[in] pHandler Pointer to handler instance
* @return True, if attachment possible
*/
virtual bool AttachEventHandler( IVANetClient::IEventHandler* pHandler ) = 0;
//! Connection event handler detachment
/**
* @param[in] pHandler Pointer to handler instance
* @return True, if detachment possible
*/
virtual bool DetachEventHandler( IVANetClient::IEventHandler* pHandler ) = 0;
protected:
//! No default construction
IVANetClient();
};
......
......@@ -22,148 +22,189 @@
// Forward declarations
class IVAInterface;
//! VA server interface
/**
* Diese Klasse definiert die Schnittstelle fr Netzwerk-Servers des VACore.
* Es wird die vollstndige Schnittstelle IVACore ber das Netzwerk repliziert.
* Instanzen mssen mittels der factory method Create() erzeugt werden.
*
* Der Server wird erzeugt und an eine Netzwerkschnittstelle+Port gebunden.
* Dem Server muss eine IVACore-Instanz genannt werden, an welche er die
* Netzwerkbefehle weiterleitet.
*
* Solange der Server aktiviert ist und ihm eine IVACore-Instanz zugeordnet ist,
* akzeptiert er eine (einzelne!) Client-Verbindung und leitet deren Befehle weiter.
* Ist bereits ein Client verbunden, schlgt die Verbindungsaufnahme fehl.
*
* Regel: Nur ein Client zu einer Zeit
*
* TODO:
* - Der Client muss auch VACoreEvents von der Server-Seite weiterleiten. Mechanismus entwickeln + implementieren
*/
* This class defines an interface for a TCP/IP network server with
* a managed VA core.
*
* Use the factory method Create() to instantiate a server, then set a
* VA core interface instance using SetCoreInstance().
*
* Calls from a network client will be transmitted over TCP/IP transparently,
* and will be forwarded to the actual core.
*
* The server network functionality allows multiple client connections, however
* updates are synchronized making them potentially less efficient.
*/
class VANET_API IVANetServer
{
public:
typedef std::pair< int, int > tPortRange;
typedef std::list<tPortRange> tPortList;
typedef std::pair< int, int > tPortRange; //!< Port range typedef
typedef std::list< tPortRange > tPortList; //!< List of ranges typedef for multi client support
enum
//! Server state
enum ServerState
{
VA_NO_ERROR = 0,
VA_ALREADY_INITIALIZED,
VA_NOT_INITIALIZED,
VA_CONNECTION_FAILED,
VA_NO_ERROR = 0, //!< No error
VA_ALREADY_INITIALIZED, //!< Already initialized
VA_NOT_INITIALIZED, //!< Not initialized
VA_CONNECTION_FAILED, //!< Connection failed
};
// Factory method
//! Factory method to create a server
/**
* Use this method to create an instance of a server, because default constructor is protected.
*/
static IVANetServer* Create();
virtual ~IVANetServer();
// TODO: Eventuell Event-Handler fr Netzwerk spter implementieren
//void AttachNetworkEventHandler(IVANetworkEventHandler* pNetworkEventHandler);
//void DetachNetworkEventHandler(IVANetworkEventHandler* pNetworkEventHandler);
//! Destructor
virtual ~IVANetServer();
//! Initialize server
/**
* Server initialisieren
*
* Parameter: sInterface Netzwerkschnittstelle auf welcher der Server arbeitet
* iServerPort Netzwerkport auf welcher der Server seinen Dienst anbietet
* iFreePortMin Begin Portbereich fr Kommunikation mit den Clients
* iFreePortMax Ende Portbereich fr Kommunikation mit den Clients
* iMaxNumClients Zahl der maximalen gleichzeitig verbundenen Netzwerk-Clients,
* wobei -1 fr unlimitiere Verbindungszahl steht
*
* Rckgabe: Statuscode
*/
// @todo: enforce setting real core in initialize call
*
* @param[in] sInterface Network TCP/IP interface where server will listen
* @param[in] iServerPort Network TCP/IP socket port
* @param[in] iFreePortMin Port range beginning for communication
* @param[in] iFreePortMax Port range end for communication
* @param[in] iMaxNumClients Maximum number of allowed clients (-1 allows infinit connections)
*
* @return Status code
*
*/
virtual int Initialize( const std::string& sInterface, const int iServerPort = VANET_DEFAULT_PORT, const int iFreePortMin = 10000, const int iFreePortMax = 11000, const int iMaxNumClients = -1 ) = 0;
//! Initialize server
/**
* Server initialisieren
*
* Parameter: sInterface Netzwerkschnittstelle auf welcher der Server arbeitet
* iServerPort Netzwerkport auf welcher der Server seinen Dienst anbietet
* liFreePorts Liste der Ports fr Kommunikation mit den Clients
* iMaxNumClients Zahl der maximalen gleichzeitig verbundenen Netzwerk-Clients,
* wobei -1 fr unlimitiere Verbindungszahl steht
*
* Rckgabe: Statuscode
*/
*
* @param[in] sInterface Network TCP/IP interface where server will listen
* @param[in] iServerPort Network TCP/IP socket port
* @param[in] liFreePorts Port range list for communication
* @param[in] iMaxNumClients Maximum number of allowed clients (-1 allows infinit connections)
*
* @return Status code
*
*/
virtual int Initialize( const std::string& sInterface, const int iServerPort, const tPortList& liFreePorts, const int iMaxNumClients = -1 ) = 0;
// Vorhandene Serververbindungen trennen und Server beenden
// (Rckgabe: Statuscode)
//! Finalizes server and disconnects clients
/**
* @return Status code
*/
virtual int Finalize() = 0;
// Alle vorhandenen Verbindungen abbrechen und den Kern zurcksetzen
//! Reset all connections
virtual void Reset() = 0;
// Gibt die Netzwerk-Schnittstelle des Servers zurck
//! Server address getter
/**
* @return Server address string
*/
virtual std::string GetServerAdress() const = 0;
// Gibt den Netzwerk-Port des Servers zurck
//! Server port getter
/**
* @return Server port
*/
virtual int GetServerPort() const = 0;
// Zugewiesene VACore-Instanz zurckgeben
//! Core instance getter
/**
* Get the attached core interface pointer.
*
* @return Interface pointer, or nullptr
*/
virtual IVAInterface* GetCoreInstance() const = 0;
// Zu steuernde VACore-Instanz zuweisen
// (NULL entfernt den Kern)
//! Core instance setter
/**
* If you have instantiated a VA core, use this method to attach a core
* to the server.
*
* @param[in] pCore Interface pointer
*/
virtual void SetCoreInstance( IVAInterface* pCore ) = 0;
//// Gibt zurck, ob der Server aktiviert ist
//// und eingehende Befehle an den zugewiesenen Kern weiterleitet
//virtual bool IsActive() const=0;
//// Aktiviert/Deaktiviert den Server.
//// Nur wenn dieser aktiviert ist, leitet er
//// eingehende Befehle an den zugewiesenen Kern weiter
//virtual void SetActive(bool bActive)=0;
// Gibt zurck, ob ein Client verbunden ist
//! Returns true if at least one client is connected
/**
* @return True, if at least one client is connected
*/
virtual bool IsClientConnected() const = 0;
// Gibt zurck, ob ein Client verbunden ist
//! Returns number of connected clients
/**
* @return Number of connected clients
*/
virtual int GetNumConnectedClients() const = 0;
// Gibt den Namen/Host des Clients mit der entsprechenden ID
//! Returns hostname of given client
/**
* @param[in] iClientIndex Client index integer
* @return Client host name, e.g. "127.0.0.1"
*/
virtual std::string GetClientHostname( const int iClientIndex ) const = 0;
//! Server communication event class
class CEvent
{
public:
enum
enum EventType
{
EVENT_NOTHING = 0,
EVENT_CLIENT_CONNECT, // Verbindungsaufbau eines Clients
EVENT_CLIENT_DISCONNECT, // Gewollter Verbindungsabbruch eines Clients
EVENT_CLIENT_LOST // Ungewollter Verbindungsabbruch eines Clients
EVENT_NOTHING = 0, //!< No event type
EVENT_CLIENT_CONNECT, //!< Client initialized a connection
EVENT_CLIENT_DISCONNECT, //!< Client requests a disconnect
EVENT_CLIENT_LOST //!< Unintended client connection loss
};
int iType; // Typ der Ereignisses
std::string sClient; //
int iType; //!< Event type
std::string sClient; //!< Client string
//! Default constructor sets event to no event type
inline CEvent()
: iType( EVENT_NOTHING )
{};
inline CEvent( const int iInitType, const std::string& sInitParam )
//! Constructor with event type and client string
/**
* @param[in] iInitType Initialize with this event type
* @param[in] sClient Client string
*/
inline CEvent( const int iInitType, const std::string& sClient )
: iType( iInitType )
, sClient( sInitParam )
, sClient( sClient )
{};
};
//! Server communication event handler class
class IEventHandler
{
public:
//! Destructor
inline virtual ~IEventHandler() {};
//! Event handler hook / callback method
/**
* @param[in] oEvent Event information
*/
virtual void HandleEvent( const IVANetServer::CEvent& oEvent ) = 0;
};
};
//! Connection event handler attachment
/**
* @param[in] pHandler Pointer to handler instance
* @return True, if attachment possible
*/
virtual bool AttachEventHandler( IVANetServer::IEventHandler* pHandler ) = 0;
//! Connection event handler detachment
/**
* @param[in] pHandler Pointer to handler instance
* @return True, if detachment possible
*/
virtual bool DetachEventHandler( IVANetServer::IEventHandler* pHandler ) = 0;
protected:
//! Disabled default constructor, use Create() factory method instead.
IVANetServer();
};
......
......@@ -18,9 +18,15 @@
#include <string>
// Einen Server-String in Addresse und Port zerlegen ("localhost:12340" => localhost, 12340)
// Lst eine CVAException aus falls das Parsen fehlschlgt. Falls kein Port angegeben wurde,
// ("localhost") bekommt iPort den Wert des default port zugewiesen.
//! Split a server string of address and port ("localhost:12340" => localhost, 12340)
/**
* @note Raises CVAException if parsing went wrong.
* @param[in] sServerString Coded server string aka "localhost:12340"
* @param[out] sAddress Server adress
* @param[out] iPort Server socket port
* @param[in] iDefaultPort Default port in case server string has no port
*
*/
VANET_API void SplitServerString( const std::string& sServerString, std::string& sAddress, int& iPort, const int iDefaultPort = VANET_DEFAULT_PORT );
#endif // IW_VANET_UTILS
......@@ -18,22 +18,30 @@
#include <string>
//! Net version
/**
* Diese Datenklasse beschreibt Versionsinformationen ber die VA-Net Bibliothek
*/
* Describes the network version of library.
*
*/
class VANET_API CVANetVersionInfo
{
public:
std::string sVersion; // Version als Zeichenkette (z.B. "1.02")
std::string sDate; // Datum der Erstellung bzw. Verffentlichung
std::string sFlags; // Liste der Eigenschaften (flags) (z.B. "Command queueing")
std::string sComments; // Zustzliche Kommentate (z.B. "X-mas release");
std::string sVersion; //!< Version as string (e.g. "1.02")
std::string sDate; //!< Date of creation / publiching date
std::string sFlags; //!< List of properties (flags) (e.g. "debug", "SSE2")
std::string sComments; //!< Additional comments
//! Als Zeichenkette zurckgeben
//! Formatted string
/**
* @return Formatted string
*/
std::string ToString() const;
};
//! Versionsnummer der VA-Net Bibliothek abrufen
//! Get version of network library
/**
* @param[out] pVersionInfo Object where to store version info
*/
void VANET_API GetVANetVersionInfo( CVANetVersionInfo* pVersionInfo );
#endif // IW_VANET_VERSION
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment