/*
 * 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 Linke (christian.linke@bmw.de)
 *
 */

/*!
\page architecturepage Architecture Overview

The architecture concept bases on the partition of management (logic) and routing (action). Sinks and sources are clustered
into independent parts which are capable of exchanging audio with each other (AudioDomains). Between these AudioDomains,
Audio can be interchanged via Gateways. \n
Since the routing and the management shall be independent from the actual used system, it is realized as an OwnedComponent,
the AudioManager. Each AudioDomain has a Routing Adapter which implements some necessary logic and is the interface between
the AudioManager and the AudioDomains.

\section domains Audio Domains

\image html AudioDomains.gif
An Audio Domain consists of sinks and sources that can exchange audio with each other. To make the most out of the concept,
AudioDomains shall be chosen in such a way that they are implemented by already existing audio routing engines.

The AudioManager assumes that there are no restrictions in interconnection of sinks and sources. One or more sources can be
connected to one sink and one or more sinks can be connected to one source. Since real hardware or software might end up in
having restrictions, the knowledge of this must exist in the AudioManager and handled by him accordingly. This shall be
accomplished via a plug-in mechanism. An AudioDomain is not tied to a hardware or software implementation. It can be software
or hardware or even a combination of both. \n

Examples for possible audio domains:\n
PulseAudio, Alsa, Jack, DSP, FPGA, MOST, In-chip switching matrix\n

The clustering and usage of the AudioDomains will vary from each product. Care must be taken while choosing the right AudioDomains
in regards to system load (due to resampling), latency and of course flexibility.\n
In special implementations of the AudioDomain, it is capable of operation a certain time without interaction to the AudioManager.
This is needed to fulfill the requirements for Early & Late Audio, more information can be found below.
am::am_Domain_s describe the attribiutes of a domain.

\section routing_adaptor Routing Adapter

Via this adapter, the interconnection from the AudioManager to the AudioDomains is accomplished. An AudioDomain shall have exactly
one RoutingAdapter. In the terms of GENIVI, a RoutingAdapter is an AbstractComponent, this means that we define an API and a certain
behavior in UML models but do not maintain components itself. Existing implementations from Proof of Concepts are shipped as example
Adapters "as is" but cannot be seen as maintained components.\n
The implementation of a routing adapter can and will vary from each project to another since the combination of sinks and sources,
the used hardware etc has influence on the adapters. Besides interchanging and abstracting information between the AudioManager and
the sinks and sources, the Adapters also need to implement some business logic in order to interact with the AudioManager.
This include for example the registering of components, managing the current state, error handling etc.\n
In the special case of an EarlyDomain, the routing adapter also has to manage start-up and rundown including persistence for his
domain while the AudioManager is not started or already stopped. During this periods of time, these special adapters have to be able
to fulfill basic tasks like changing volumes, for example (this implies that the Adapter is implemented on a different piece of
hardware, e.g. vehicle processor).

\section gateway Gateway

\image html Gateway.gif

Gateways are used to let audio flow between two domains. They always have a direction and can only transport one stream at a time.
Several gateways connecting the same domains together can exist in parallel so that more than one source can be connected to more
than one sink from the same domains at the same time.\n
In principle, gateways have the ability to convert the connectionFormat of an audiostream, for example the sink could receive audio
in a digital form and output it as analog (sound card). In order to express the conversion capabilities of a gateway, a matrix of
all source/sink connectionFormats is given (details below). The sources and sinks of a gateway are registered like ordinary sources
and sinks where the domains have the responsibility to register "their" sinks and sources.\n
For every gateway, a controlDomain is defined, this is the domain that registered the gateway. At the time of registering, the ID of
the "other end" of the gateway might be unknown. To handle this situation, a domain can "peek" Domains, Sources and Sinks. When
something is peeked, it means that an ID is reserved for a unique name without registering it.\n
If a gateway is deregistered, the source or sink of the controlling domain is deregistered as well - not the one in the "other" domain.
*/