Commit 0f790d6f authored by Dipl.-Ing. Jonas Stienen's avatar Dipl.-Ing. Jonas Stienen

Merge branch 'big_2017_api_change' into develop

parents 10325886 2db532f7
/*
* --------------------------------------------------------------------------------------------
*
* VVV VVV A Virtual Acoustics (VA) | http://www.virtualacoustics.org
* VVV VVV AAA Licensed under the Apache License, Version 2.0
* VVV VVV AAA
* VVV VVV AAA Copyright 2015-2017
* VVVVVV AAA Institute of Technical Acoustics (ITA)
* VVVV AAA RWTH Aachen University
*
* --------------------------------------------------------------------------------------------
*/
/*!
@page VANet
@section vanet_sec VANet
VANet provides a transparent network communication of calls to the VA interface. It is useful to control a VA server remotely and is the standard way to communicate with VA for inter-process methods and bindings for other scripting languages.
@section vanet_license_sec License
Copyright 2015-2017 Institute of Technical Acoustics (ITA), RWTH Aachen University
Licensed under the Apache License, Version 2.0 (the "License");
you may not use the OpenDAFF software package 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.
You should also have received a copy of the License with the VA software package.
@section vanet_getting_started_sec Getting started
If you are a C++ developer and want to integrate VANet into your application, the first contact point should be the #IVANetClient.
If you want to provide a VA server connection, have a look at #IVANetServer.
*/
#ifndef IW_VANET
#define IW_VANET
#include "VANetDefinitions.h"
#include "VANetAudioStreamServer.h"
#include "VANetClient.h"
#include "VANetServer.h"
#include "VANetUtils.h"
#include "VANetVersion.h"
#endif // IW_VANET
......@@ -16,7 +16,6 @@
#include <VANetDefinitions.h>
#include <VABaseDefinitions.h>
#include <VABase.h>
#include <VASamples.h>
......@@ -40,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
......@@ -17,41 +17,38 @@
#include <VANetDefinitions.h>
#include <string>
class IVACore;
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
virtual IVACore* GetCoreInstance() const = 0;
//! 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, int iServerPort = VANET_DEFAULT_PORT, int iHeadChannelMode = VA_HC_USE_EXISTING, int IExceptionHandlingMode = EXC_CLIENT_THROW, bool bBufferSynchronizedCommands = true ) = 0;
virtual void SetExceptionHandlingMode( int nMode ) = 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
};
int iType; // Typ der Ereignisses
std::string sServer; //
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();
};
......
......@@ -20,150 +20,191 @@
#include <list>
// Forward declarations
class IVACore;
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
virtual int Initialize( const std::string& sInterface, int iServerPort = VANET_DEFAULT_PORT, int iFreePortMin = 10000, int iFreePortMax = 11000, int iMaxNumClients = -1 ) = 0;
*
* @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
*/
virtual int Initialize( const std::string& sInterface, int iServerPort, const tPortList& liFreePorts, int iMaxNumClients = -1 ) = 0;
// Vorhandene Serververbindungen trennen und Server beenden
// (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;
//! 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
virtual IVACore* GetCoreInstance() const = 0;
// Zu steuernde VACore-Instanz zuweisen
// (NULL entfernt den Kern)
virtual void SetCoreInstance( IVACore* 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
//! Core instance getter
/**
* Get the attached core interface pointer.
*
* @return Interface pointer, or nullptr
*/
virtual IVAInterface* GetCoreInstance() const = 0;
//! 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;
//! 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
inline CEvent()
//! Default constructor sets event to no event type
inline CEvent()
: iType( EVENT_NOTHING )
{};
inline CEvent( 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,12 +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.
VANET_API void SplitServerString(const std::string& sServerString,
std::string& sAddress,
int& iPort,
int iDefaultPort=VANET_DEFAULT_PORT);
//! 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
......@@ -4,6 +4,7 @@ set( RelativeDir "include" )
set( RelativeSourceGroup "include" )
set( DirFiles
VANet.h
VANetAudioStreamServer.h
VANetClient.h
VANetDefinitions.h
......
......@@ -29,4 +29,3 @@ bool CVANetAudioStreamServer::Initialize( const std::string& sBindInterface, con
{
return m_pImpl->InitializeInternal( sBindInterface, iBindPort );
}
......@@ -44,4 +44,4 @@ bool CVANetAudioStreamServerImpl::InitializeInternal( const std::string& sBindIn
const double dSyncTimeInterval = 0.001f; // 1 ms
return m_pSampleServer->Start( sBindInterface, iBindPort, dSyncTimeInterval );
}
\ No newline at end of file
}