* enhanced documentation

16 files changed, 295 insertions, 54 deletions

diff --git a/AudioManagerDaemon/docx/02_x_dependecies.dox b/AudioManagerDaemon/docx/02_x_dependecies.dox
new file mode 100644
index 0000000..f334e37
--- /dev/null
+++ b/AudioManagerDaemon/docx/02_x_dependecies.dox
@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \author Christian Mueller (christian.ei.mueller@bmw.de)
+ *
+ */
+ 
+ /*!
+\page dep Dependencies
+\section deps Dependency Graph
+\image html dependencies.png
+\section deptest Depedency Graph for Tests
+\image html dependencies_test.png
+\section depgen Generated Dependency Graph
+\image html dependency_created.png
+*/
\ No newline at end of file
diff --git a/AudioManagerDaemon/docx/03_x_uml_model.dox b/AudioManagerDaemon/docx/03_x_uml_model.dox
new file mode 100644
index 0000000..93077ca
--- /dev/null
+++ b/AudioManagerDaemon/docx/03_x_uml_model.dox
@@ -0,0 +1,49 @@
+ /*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \author Christian Mueller (christian.ei.mueller@bmw.de)
+ *
+ */
+
+/*!
+\page uml UML Model auf the AudioManager
+\section svn Audio Manager Branch
+The SVN link to the AudioManager branch can be found here: https://svn.genivi.org/uml-model/genivi/branch/eg-mg-audiomanager
+The last valid version that is compliant can be found on the trunk.\n
+For more information about the EA model, please see here:  https://collab.genivi.org/wiki/display/genivi/Audio+Management+UML+Model
+After the EA Model is updated via "Get All latest", the relevant parts for Audio Management are:\n
+- Requirements on System Level
+\code
+GENIVI Model -> Requirements View -> Media and Graphics -> Audio Management
+\endcode
+- Use Cases on System Level
+\code
+GENIVI Model -> Use Case View -> Audio Management
+\endcode
+- Requirements on Component Level
+\code
+GENIVI Model -> Logical View -> SW platform Requirements -> Multimedia -> AudioManagement
+\endcode
+- Use Cases on Component Level
+\code
+GENIVI Model -> Logical View -> Use Case Realizations -> AudioManagement
+\endcode
+- Component Diagram
+\code
+GENIVI Model -> Logical View -> SW Platform Components -> Audio Management
+\endcode
+- Implementation Class & Component diagrams:
+\code
+GENIVI Implementation -> Implementation View -> Audio Management
+\endcode
+*/
diff --git a/AudioManagerDaemon/docx/04_components.dox b/AudioManagerDaemon/docx/04_components.dox
index 4735740..09acd1a 100644
--- a/AudioManagerDaemon/docx/04_components.dox
+++ b/AudioManagerDaemon/docx/04_components.dox
@@ -26,7 +26,10 @@
  \section audiomanagercomponents AudioManagerDaemon
 
  This component is owned and maintained by Genivi. It is the central audio framework component. There can be only one daemon in a system (singleton).\n
- The AudioManagerDaemon is subject to this documentation
+ The AudioManagerDaemon is subject to this documentation.
+ \subsection daemonover Daemon Overview
+ Here is an class overview of the AudioManagerDaemon:
+ \image html daemon_insight.png
 
  \section commander AudioManagerCommandPlugin
 
@@ -36,7 +39,8 @@
  CommandPlugin at a time.
  Since the implementation of this component is project specific, only examples are included.\n
  An example Dbus Implementation can be found in the folder PluginCommandInterfaceDbus.
- \n
+
+ \subsection commandIface Interfaces
  All commands that must be fulfilled by an AudioManagerCommandPlugin are described in am::IAmCommandSend.\n
  All commands that are presented to AudioManagerCommandPlugin by the AudioManagerDaemon are described in am::IAmCommandReceive.\n
 
@@ -47,7 +51,8 @@
  Among this there are commands to read/write the database and to perform actions on the Audiodomains like connect or disconnect. There must be only one
  Controller in the system at a time, like the AudioManagerCommandPlugins, the Controller is loaded at startup by the daemon\n
  A simple example Implementation can be found in the folder PluginControlInterface.
- \n
+
+ \subsection controlIface Interfaces
  All commands that must be fulfilled by an AudioManagerController are described in am::IAmControlSend.\n
  All commands that are presented to AudioManagerController by the AudioManagerDaemon are described in am::IAmControlReceive.\n
 
@@ -60,46 +65,21 @@
  know anything about the real system plugins - he sends his commands to sources and sinks. The daemon does the dispatching of these commands.
  The interface is mainly asynchronous.\
  Sample plugins can be found in the directory, for example PluginRoutingInterfaceAsync.\n
- \n
+
+ \subsection routingIface Interfaces
  All commands that must be fulfilled by an AudioManagerRoutingPlugin are described in am::IAmRoutingSend.\n
  All commands that are presented to AudioManagerRoutingPlugins by the AudioManagerDaemon are described in am::IAmRoutingReceive.\n
 
- \page elementspage Elements of the AudioManagement
-
- The audiomanagement in principle consists of the following elements:
-
- \section source Sources
- This is where audio comes from, for examples tuner, mediaplayer. But sources can also be part of a building block that processes audio, examples
- are here crossfaders or gateways. Several Sinks can be connected to one source.\n
- \subsection sourceattributes Attributes
- - am::am_SourceType_s describes the attributes that are accessible from the AudioManagerCommandPlugins.\n
- - am::am_Source_s describes the general attributes.\n
-
- \section sinks Sinks
- This is where audio flows to, for examples amplifier, headphones. But sources can also be part of a building block that processes audio,
- examples are here crossfaders or gateways. Several Sources can be connected to one sink.\n
- \subsection sinkattributes Attributes
- - am::am_SinkType_s describes the attribiutes that are accessible form the AudioManagerCommandPlugins.\n
- - am::am_Sink_s describes the general attributes.\n
-
- \section gw Gateways
- Gateways are described here: \ref gateway
- A specialitry of a gateways is the convertionmatrix. It indicates which sinksoundformats can be transferred in which sourcesoundformats. A convertion
- matrix looks like this:
- \image html GatewayMatrix.png
- \subsection gwattributes Attributes
- - am::am_Gateway_s describe the attribiutes of a gateway\n
+ \subsection subrouter Bus topology
+ The AudioManagerDaemon expects a bus behind each of the plugins. On one of these buses there can be several domains. In order to
+ reflect this, a domain has always a bus(plugin) and a node that it belongs to. So if a message needs to be transmitted to a domain,
+ it will always be sent to a node on a bus.
+ Here is a diagram showing the topology from the view of the AudioManagerDaemon:
+ \image html bus_topology.png
+ \subsection busname Busname
+ Since a plugin represents a bus for the AudioManagerDaemon, each plugin it has its unique name, the busname that is returned by
+ am::IAmRoutingSend::returnBusName. The AudioManagerDaemon used this information to link a plugin with a domain. All other elements like
+ sinks, sources etc are linked to domains. This is how the hierarchy looks like that is used:
+ \image html routing_hierarchy.png
 
- \section crossfaders Crossfaders
- Cross-faders are special elements that can perform cross-fading between two sources connected to the sinks of the crossfader. The audio of either source
- or both (mixed, during the fade) is put out at the source of the fader. Cross-fading within a source (for example from one song to another) is out of
- scope audio management and must be performed in the source.\n
- A crossfader has two sinks and one source, where one sink is the "hot" one. It is in the duty of the AudioManagerController to connect the correct
- sources to the sinks in order to perform a cross-fade. When fading is started, the hotSink changes from either HS_SINKA or HS_SINKB to HS_INTERMEDIATE,
- when the fading is finished, it changes to HS_SINKA or HS_SINKB (the sink that was "cold" before).Fading itself is done in the RoutingAdapters, the
- implementation has to ensure the smooth and synchronous change of volumes. With different rampTypes, different kinds of cross-fade ramps can be supported.
- The actual status of the "hot" sink is reported by the routingAdapter. Care has to be taken that the correct "hot" end of the crossfader is given
- at registration time.\n
- \subsection cfattributes Attributes
- - am::am_Crossfader_s describes the attribiutes of a Crossfader
-*/
\ No newline at end of file
+*/
diff --git a/AudioManagerDaemon/docx/04_x_elements.dox b/AudioManagerDaemon/docx/04_x_elements.dox
new file mode 100644
index 0000000..7098297
--- /dev/null
+++ b/AudioManagerDaemon/docx/04_x_elements.dox
@@ -0,0 +1,57 @@
+ /*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \author Christian Mueller (christian.ei.mueller@bmw.de)
+ *
+ */
+ 
+/*!
+\page elementspage Elements of the AudioManagement
+
+ The audiomanagement in principle consists of the following elements:
+
+ \section source Sources
+ This is where audio comes from, for examples tuner, mediaplayer. But sources can also be part of a building block that processes audio, examples
+ are here crossfaders or gateways. Several Sinks can be connected to one source.\n
+ \subsection sourceattributes Attributes
+ - am::am_SourceType_s describes the attributes that are accessible from the AudioManagerCommandPlugins.\n
+ - am::am_Source_s describes the general attributes.\n
+
+ \section sinks Sinks
+ This is where audio flows to, for examples amplifier, headphones. But sources can also be part of a building block that processes audio,
+ examples are here crossfaders or gateways. Several Sources can be connected to one sink.\n
+ \subsection sinkattributes Attributes
+ - am::am_SinkType_s describes the attribiutes that are accessible form the AudioManagerCommandPlugins.\n
+ - am::am_Sink_s describes the general attributes.\n
+
+ \section gw Gateways
+ Gateways are described here: \ref gateway
+ A specialitry of a gateways is the convertionmatrix. It indicates which sinksoundformats can be transferred in which sourcesoundformats. A convertion
+ matrix looks like this:
+ \image html GatewayMatrix.png
+ \subsection gwattributes Attributes
+ - am::am_Gateway_s describe the attribiutes of a gateway\n
+
+ \section crossfaders Crossfaders
+ Cross-faders are special elements that can perform cross-fading between two sources connected to the sinks of the crossfader. The audio of either source
+ or both (mixed, during the fade) is put out at the source of the fader. Cross-fading within a source (for example from one song to another) is out of
+ scope audio management and must be performed in the source.\n
+ A crossfader has two sinks and one source, where one sink is the "hot" one. It is in the duty of the AudioManagerController to connect the correct
+ sources to the sinks in order to perform a cross-fade. When fading is started, the hotSink changes from either HS_SINKA or HS_SINKB to HS_INTERMEDIATE,
+ when the fading is finished, it changes to HS_SINKA or HS_SINKB (the sink that was "cold" before).Fading itself is done in the RoutingAdapters, the
+ implementation has to ensure the smooth and synchronous change of volumes. With different rampTypes, different kinds of cross-fade ramps can be supported.
+ The actual status of the "hot" sink is reported by the routingAdapter. Care has to be taken that the correct "hot" end of the crossfader is given
+ at registration time.\n
+ \subsection cfattributes Attributes
+ - am::am_Crossfader_s describes the attribiutes of a Crossfader
+*/
\ No newline at end of file
diff --git a/AudioManagerDaemon/docx/14_x_mainloop.dox b/AudioManagerDaemon/docx/14_x_mainloop.dox
new file mode 100644
index 0000000..cf327bc
--- /dev/null
+++ b/AudioManagerDaemon/docx/14_x_mainloop.dox
@@ -0,0 +1,49 @@
+ /*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \author Christian Mueller (christian.ei.mueller@bmw.de)
+ *
+ */
+
+/*!
+\page mainl Mainloop concept
+\section mconcept Mainloop
+The AudioManager comes with a build in mainloop that can be utilized by the plug-ins to serve their needs of communication and thread-safe calling.
+The mainloop, implemented in CAmSocketHandler works like this:\n
+\image html Mainloop.png
+
+\section sec Using the Mainloop
+Adding and removing callbacks and timers work via the am::CAmSocketHandler.\n
+To add a callback, use am::CAmSocketHandler::addFDPoll, to remove one, use am::CAmSocketHandler::removeFDPoll.\n
+To add a timer callback, use am::CAmSocketHandler::addTimer, use am::CAmSocketHandler::removeTimer and am::CAmSocketHandler::restartTimer and
+am::CAmSocketHandler::stopTimer.\n
+The mainloop is started via am::CAmSocketHandler::start_listenting and stopped via am::CAmSocketHandler::stop_listening.
+Example code can be found in am::CAmDbusWrapper.
+
+\section util Utilizing The Mainloop as Threadsafe Call Method
+The AudioManager itself is singlethreaded, so any calls from other threads inside the plugins directly to the interfaces is forbidden, the
+behavior is undefined. The reason for this is that communication and routing plugins are often only communication interfaces that can are ideally used
+with the am::CAmSocketHandler.\n
+am::CAmSerializer creates an intermediate object on the heap holding all informations of the function to be called and a pointer to the object to be called.
+After that, the class writes to a pipe witch triggers the mainloop to call the callback am::CAmSerializer::receiverCallback from the maincontext. The
+callback uses the intermediate object to do the actual call. \n
+\warning asynchronous calls can be used within the main thread, but synchronous not -> the call would block forever !\n
+For each thread that needs to use synchronous calls independent an own instance of am::CAmSerializer needs to be used.
+\subsection async Asynchronous calls
+\image html Deferred_Call_async.png
+\subsection sync Synchronous calls
+\image html Deferred_Call_sync.png
+
+
+
+ */
diff --git a/AudioManagerDaemon/docx/15_x_eclipse.dox b/AudioManagerDaemon/docx/15_x_eclipse.dox
new file mode 100644
index 0000000..1a06c64
--- /dev/null
+++ b/AudioManagerDaemon/docx/15_x_eclipse.dox
@@ -0,0 +1,91 @@
+ /*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \author Christian Mueller (christian.ei.mueller@bmw.de)
+ *
+ */
+ 
+
+/*!
+\page eclip Download Compile Debug
+\section dw Get the source
+For compiling the source, you need to use git and the following packages:\n
+\code
+sudo apt-get install libdbus-1-dev libsqlite3-dev doxygen libgtest-dev google-mock git cmake build-essential python2.6-dev
+\endcode
+Getting the source got works with following command
+\code
+git clone https://<kavi-account>:<kavi-password>@git.genivi.org/srv/git/AudioManager
+\endcode
+\section build Compile
+In order to build the project (out of source build), please follow these instructions on the commandline:
+\code
+mkdir /build
+cd build
+cmake ..
+\endcode
+if you want to influence the build options, you can use ccmake for example (apt-get install ccmake)
+\code
+ccmake ..
+\endcode
+You will get a menue that let's you select different options for the build. Compiling with a simple
+\code
+make
+\endcode
+after the script finished, you should have:
+- a bin/ folder which contains all executables and the libraries:
+- a build/ folder which has all build objects (erase that if you need a clean build)
+- a doc/ folder in case you turned the documentation on
+
+in order to install the AudioManager, you can do
+\code
+sudo make install
+\endcode
+package generation is supported via CPack. To build packages, you have to
+\code
+make genivi_package
+\endocde
+this will create one package if your CMake version is < 2.8.5 (all binaries stripped):
+\code
+AudioManager-<git verison>-Linux.deb
+\endcode
+if your version is above, you will get 4 packages (all binaries stripped) :
+\code
+AudioManager-<git verison>-Linux-bin.deb                [AudioManager binary]
+AudioManager-<git verison>-Linux-dev.deb                [header files needed to compile plugins]
+AudioManager-<git verison>-Linux-sampleplugins.deb      [sample plugins]
+AudioManager-<git verison>-Linux-tests.deb              [tests including tests for sample plugins,
+installed in the ~/AudioMAnagerTests]
+\endcode
+to create a tar.gz file of all sources (not including .git, build and bin folder,config files), you can do:
+\code
+make package_source
+\endcode
+This will create the following package:
+\code
+AudioManager-<git verison>-Source.tar.gz
+\endcode
+All packages will be placed in a folder called packages
+\section ec Using Eclipse
+First you need to get eclipse, for example by downloading it from http://www.eclipse.org/ use the C++ CDT version.
+Import the project with\n
+File-> import project\n
+Select "existing code as makefile project" and choose the root folder auf the AudioManager\n
+In order to build with eclipse you need to tell eclipse where the makefile can be found:\n
+In project properties enter as build command:
+\code
+"make -j4 -C build" as build command
+\endcode
+\section deb Debugging with eclipse
+For debugging you need to modify debug configurations, choose the audiomanager as binary, the debugging should work.
+*/
diff --git a/AudioManagerDaemon/docx/16_readme.dox b/AudioManagerDaemon/docx/16_readme.dox
index d23d2ff..8e280e5 100644
--- a/AudioManagerDaemon/docx/16_readme.dox
+++ b/AudioManagerDaemon/docx/16_readme.dox
@@ -17,5 +17,5 @@
 /*!
 \page comp Compiling & Co
 \section readme Readme
-\include ../README
+\include README
 */
\ No newline at end of file
diff --git a/AudioManagerDaemon/docx/images/Deferred_Call_async.png b/AudioManagerDaemon/docx/images/Deferred_Call_async.png
new file mode 100644
index 0000000..30ad24e
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/Deferred_Call_async.png
diff --git a/AudioManagerDaemon/docx/images/Deferred_Call_sync.png b/AudioManagerDaemon/docx/images/Deferred_Call_sync.png
new file mode 100644
index 0000000..51c46dc
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/Deferred_Call_sync.png
diff --git a/AudioManagerDaemon/docx/images/Mainloop.png b/AudioManagerDaemon/docx/images/Mainloop.png
new file mode 100644
index 0000000..979c133
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/Mainloop.png
diff --git a/AudioManagerDaemon/docx/images/bus_topology.png b/AudioManagerDaemon/docx/images/bus_topology.png
new file mode 100644
index 0000000..44486ff
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/bus_topology.png
diff --git a/AudioManagerDaemon/docx/images/dependencies.png b/AudioManagerDaemon/docx/images/dependencies.png
new file mode 100644
index 0000000..c8b980b
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/dependencies.png
diff --git a/AudioManagerDaemon/docx/images/dependencies_test.png b/AudioManagerDaemon/docx/images/dependencies_test.png
new file mode 100644
index 0000000..b0bc123
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/dependencies_test.png
diff --git a/AudioManagerDaemon/docx/images/dependency_created.png b/AudioManagerDaemon/docx/images/dependency_created.png
new file mode 100644
index 0000000..7eabbf8
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/dependency_created.png
diff --git a/AudioManagerDaemon/docx/images/routing_hierarchy.png b/AudioManagerDaemon/docx/images/routing_hierarchy.png
new file mode 100644
index 0000000..d9586e9
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/routing_hierarchy.png
diff --git a/AudioManagerDaemon/src/CAmRoutingSender.cpp b/AudioManagerDaemon/src/CAmRoutingSender.cpp
index e7594cf..255d563 100644
--- a/AudioManagerDaemon/src/CAmRoutingSender.cpp
+++ b/AudioManagerDaemon/src/CAmRoutingSender.cpp
@@ -35,17 +35,6 @@ namespace am
 
 #define REQUIRED_INTERFACE_VERSION_MAJOR 1  //!< major interface version. All versions smaller than this will be rejected
 #define REQUIRED_INTERFACE_VERSION_MINOR 0 //!< minor interface version. All versions smaller than this will be rejected
-/**
- * macro to call all interfaces
- *
- */
-#define CALL_ALL_INTERFACES(...) 														 \
-		std::vector<InterfaceNamePairs>::iterator iter = mListInterfaces.begin();	 	 \
-		std::vector<InterfaceNamePairs>::iterator iterEnd = mListInterfaces.end();	 	 \
-		for (; iter<iterEnd;++iter)													     \
-		{																				 \
-			(*iter).routingInterface->__VA_ARGS__;										 \
-		}
 
 CAmRoutingSender::CAmRoutingSender(const std::vector<std::string>& listOfPluginDirectories) :
         mHandleCount(0), //