# DEPRECATED
This repo is kept for reference only, there is no further development planned.

IPC CommonAPI C++ D-Bus
-----------------------
:Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
:doctitle: IPC CommonAPI C++ D-Bus
:version:

Copyright
+++++++++
Copyright (C) 2014, BMW AG.
Copyright (C) 2014, GENIVI Alliance, Inc.

This file is part of GENIVI Project IPC Common API C++ D-Bus.
 
Contributions are licensed to the GENIVI Alliance under one or more Contribution License Agreements or MPL 2.0.

License
+++++++ 
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/.

The files MurmurHash3.h, MurmurHash3.cpp, pugiconfig.hpp, pugixml.cpp and pugixml.hpp are subject to the terms of the MIT License (MIT). If a copy of the MIT was not distributed with this file, you can obtain one at http://opensource.org/licenses/MIT.

Version
+++++++
{version}

Further information
+++++++++++++++++++
Source code and latest news can be found at http://projects.genivi.org/commonapi/.

Common API Overview
~~~~~~~~~~~~~~~~~~~

Common API C++ and its mechanism specific bindings (e.g. Common API D-Bus) provide a set of libraries and tools to work with 
RPC communication in a way independent of which mechanism is used. It currently consists of four sub-projects:

*CommonAPI* - This is the base C++ library, which provides the application interface for users and can load runtime bindings such as DBus.
 
*CommonAPI-Tools* - The Eclipse based tools for CommonAPI. This is essentially the code generator for the generation of C++ code from Franca IDL. 

*CommonAPI-D-Bus* - This is the D-Bus binding C++ library, which provides the necessary code to communicate over D-Bus. This is invisible to the application code, and simply needs to be linked against. 

*CommonAPI-D-Bus-Tools* - The eclipse based tools for CommonAPI D-Bus. This is the code generator for Franca IDL to Common API D-Bus C++ code.

Build Instructions
~~~~~~~~~~~~~~~~~~~

Linux
+++++

To build this package the CommonAPI library and a version of libdbus patched with the marshaling patch must be available through PkgConfig. Instructions for making a patched version of libdbus available in /usr/local:

----
# wget http://dbus.freedesktop.org/releases/dbus/dbus-1.4.16.tar.gz

# tar -xzf dbus-1.4.16.tar.gz

# cd dbus-1.4.16

# patch -p1 < /path/to/dbus-DBusMessage-add-support-for-custom-marshaling.patch

# ./configure --prefix=/usr/local

# make -C dbus 

# sudo make -C dbus install
# sudo make install-pkgconfigDATA
----

The path to CommonAPI and patched libdbus pkgconfig files must be added to the +PKG_CONFIG_PATH+ for the entire build process.

For example, if CommonAPI and patched dbus are available in /usr/local, set the +PKG_CONFIG_PATH+ variable as follows:

----
# export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH" 
----

Now use Autotools to build this package with the above requirements available through Pkgconfig:

----
# autoreconf -i
# ./configure
# make
# sudo make install (or alternative install process, eg. checkinstall on debian-based distributions, such as Ubuntu)
----

Building and executing the Unit Tests:

----
# export GTEST_CONFIG=/path/to/gtest-1.6.0/scripts/gtest-config
# autoreconf -i
# ./configure
# make check
----

In order to execute the unit tests, the test framework "Google Test" (available at https://code.google.com/p/googletest/) needs to be available on your system. Google Test comes with a subfolder called "scripts", there you will find a file called "gtest-config". The path to this script has to be set via the environment variable GTEST_CONFIG. After having done so, CommonAPI and CommonAPI-D-Bus can be built and the make command "check" can be executed.

"make check" builds and executes all tests. As the tests are developed as regression tests, the test output is limited to "OK" and "ERROR" for each test performed.

Windows
+++++++

To build the Windows version of the dbus following steps have to be done:

- Download dbus from http://www.freedesktop.org/wiki/Software/dbus/ e.g. dbus-1.8.0.tar.gz and unpack the archive into a directory
- For building the dbus CMake is needed. Download CMake from http://cmake.org/cmake/resources/software.html. The result of the download is e.g. cmake-2.8.12.2-win32-x86.zip. Unpack the archive into a directory.
- For building the dbus +expat+ is needed. +Expat+ can be downloaded from http://expat.sourceforge.net/ e.g. Download expat-win32bin-2.1.0.exe from http://sourceforge.net/projects/expat/files/expat_win32/2.1.0/. Install expat.
- Now the dbus patch is needed. Download the patch from http://gnuwin32.sourceforge.net/packages/patch.htm e.g. patch-2.5.9-7-setup.exe and install the patch.
- Install the CommonAPI dbus patch e.g. <patch_to_patch>\patch.exe -p1 < <patch_to_CommonAPI-D-Bus>\dbus-DBusMessage-add-support-for-custom-marshaling.patch.
* Build dbus via the CMake command line tool:
** Open the developer command line for VS2013
** Change into root directory of the unpacked dbus archive e.g. dbus-1.8.0
** Create a new directory dbus-build-dir e.g. mkdir dbus-build-dir
** Change into this new created directory e.g. cd dbus-build-dir
** Create the Visual Studio files for building the dbus:

----
cmake -DEXPAT_INCLUDE_DIR="<expat-path>\Source\lib"
		-DEXPAT_LIBRARY="<expat-path>\Bin\libexpat.lib" -G "Visual Studio 12" <DBusSourcenPath>\cmake
----

e.g. C:\Work\cmake-2.8.12.2-win32-x86\bin\cmake.exe
	-DEXPAT_INCLUDE_DIR="C:\Program Files (x86)\Expat 2.1.0\Source\lib"
	-DEXPAT_LIBRARY="C:\Program Files (x86)\Expat 2.1.0\Bin\libexpat.lib"
	-G "Visual Studio 12" C:\Work\dbus-1.8.0\cmake

The Visual Studio files are created in the directory dbus-build-dir. Open the solution dbus.sln and build all projects. Info for dbus-1.8.0: In file printf.c the #include "test-utils.h" must be changed to #include "test/test-utils.h".

To build now the Windows version with Visual Studio 2013, you can use the solution file CommonAPI-DBus.sln. It is configured to build CommonAPI-DBus as a static library.

Before opening the solution file CommonAPI-DBus.sln the following environment variables must be set:

* DBUS_DIR: directory containing the patched DBus sources e.g. <path_to_folder>\dbus-1.8.0
* DBUS_BUILD_DIR: directory containing the build DBus e.g. <path_to_folder>\dbus-1.8.0\dbus-build-dir
* COMMONAPI_DIR: directory containing the CommonAPI e.g. <path_to_folder>\ascgit017.CommonAPI

To run the tests, you need to add the location of your built dbus-1d.dll or dbus-1.dll (depending on Debug or Release built) to the PATH environment variable.

[NOTE]
For building the tests the environment variable GTEST must be set (see README of CommonAPI).
Furthermore the files DemoPoll.h and DemoPoll.cpp are needed (part of gnulib).

Linking
~~~~~~~

Against CommonAPI
+++++++++++++++++

CommonAPI-D-Bus requires successful activation of all static initialization code on library load. Therefore it is necessary to activate certain linker flags to ensure this is always the case. These are specified in the pkg-config files, but are also listed here. In case of dynamic linking (.so) --no-as-needed must be specified for the CommonAPI-D-Bus library:
----
-Wl,--no-as-needed -lCommonAPI-DBus -Wl,--as-needed 
----

In case of static linking --whole-archive must be specified:
----
-Wl,--whole-archive libCommonAPI-DBus.a -Wl,--no-whole-archive 
----

Generated Proxies and Stubs
+++++++++++++++++++++++++++

Generated proxies and stubs also require successful activation of all static initialization code on load. If they are provided in either a static or dynamic library to the application they must also be linked wrapped in the flags described above.

For linking the proxies and stubs on Windows notice the following information:

* In case an error C4996 occurs disable this warning via the project settings.
* Following code must be added to the file containing the call _CommonAPI::Runtime::load()_:
** #define COMMONAPI_INTERNAL_COMPILATION
** #include <CommonAPI/DBus/DBusRuntime.h>
  
After loading of the runtime (std::shared_ptr<CommonAPI::Runtime> runtime = CommonAPI::Runtime::load();) the following code must be added:

----
// access the middlewareInfo in order to get a call to DBusRuntime. This forces the windows linker not to remove DBusRuntime from resulting binary
std::cout << "Middleware Name: " << CommonAPI::DBus::DBusRuntime::middlewareInfo_.middlewareName_ << std::endl;
----

Configuring CommonAPI
~~~~~~~~~~~~~~~~~~~~~

Well known name
+++++++++++++++

The well known name that may be used to identify and dynamically load the D-Bus middleware binding is "DBus".


Defining D-Bus Service Parameters
+++++++++++++++++++++++++++++++++

Normally, a CommonAPI address, format

----
<Domain>:<ServiceID>:<InstanceID>
----

is mapped to a D-Bus address the following way:

----
# D-Bus Interface Name = ServiceID 
# D-Bus Connection Name = InstanceID
# D-Bus Object Path = InstanceID with a preceding '/' and all '.' replaced with '/' 
----
For Domain, only the value "local" is allowed in this context, and it has no influence on the associated D-Bus service address values.

In case a proxy or a service should not use the default mapping, it is possible to define config files that use the CommonAPI Address as a key in order to map any combination of D-Bus address values to it. The config files can be defined locally per binary, globally per binary or globally for all binaries.

If more than one config file is defined and a CommonAPI address is defined more than once across several config files, the locally defined values override the global ones. If a CommonAPI address is defined more than once within a single file, the first definition found will be the only definition used.

[NOTE]
Only one managing interface can be defined per D-Bus object path!

CommonAPI D-Bus Config files have to be named this way:

----
# Binary local: "<FqnOfBinary>_dbus.conf", e.g. "/usr/bin/myBinary_dbus.conf" if the binary is "/usr/bin/myBinary"
# Binary global: "/etc/CommonApiDBus/<NameOfBinary>_dbus.conf", e.g. "/etc/CommonApiDBus/myBinary_dbus.conf"
# Global: "/etc/CommonApiDBus/dbusAddresses.conf"
----

Each config file may have an arbitrary number of entries of the following format, with each entry being separated from the others by a newline:

----
[<CommonAPI Address>]
dbus_connection=<valid D-Bus Connection Name>
dbus_object=<valid D-Bus Object Path>
dbus_interface=<valid D-Bus Interface Name>
dbus_predefined=<true/false>
----

All "dbus_*"-values are optional. For each such omitted value the default value as described above will be used. For "dbus_predefined", the default value is "false".

"dbus_predefined" should be used if the associated service of a proxy is a legacy service that does not provide the "org.freedesktop.DBus.ObjectManager" interface.

* If "dbus_predefined" is set to "false" (which is default), a proxy will try to verify the existence of the specific interface at the specific connection name and object path, using the "org.freedesktop.DBus.ObjectManager" interface, before it is marked as available.
* If "dbus_predefined" is set to "true", a proxy is marked as available as soon as the connection name of the associated
  service is visible. No further checks will be performed.

Defining D-Bus Factory Parameters
+++++++++++++++++++++++++++++++++

If a section in a config file starts with "factory$", it defines a factory configuration, which can be referred to at factory creation. The name of the factory configuration follows the $ sign.

----
[factory$<Factory Name>]
dbus_bustype=<valid D-Bus Bustype>
----

All "dbus_*"-values are optional. For each such omitted value the default value as described below will be used. 

# dbus_bustype may be set to "session" or "system" for communication on the user's session bus or on the system wide bus. The default value is "session"

Remarks on Windows Version
~~~~~~~~~~~~~~~~~~~~~~~~~~

Restrictions
++++++++++++

* Calling disconnect and later connect on the same DBusConnection somehow damages the libdbus connection. On Linux implementation this all works fine.
* The DBusLoadTest revealed that a number of more than about 50 proxies slows down the dbus communication significantly. That's why we run the DBusLoadTest on windows with just 50 instead of 100 proxies.

Working on the code & contribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- First get the code from the git:
----
git clone
---- 

- Get an overview of all branches:
----
git branch
----

- Switch to the branch you want to work on (master is the feature branch) and verify that it has switched (* changed)
----
git checkout <your branch>
git branch
----

- Best practice is to create a local branch based on the current branch:
----
git branch working_branch
----

Start working, best practice is to commit smaller, compilable pieces during the development process that makes it easier to handle later on.

- If you want to commit you changes, send them to the author, you can create a patch like this:
----
git format-patch working_branch <your branch>
----

This creates a set of patches that are published via the mailing list. The patches will be discussed and then merged & uploaded on the git by the maintainer.

Patches can be accepted under MPL 2.0 (see section License). Please be sure that the signed-off-by is set correctly. For more, check out http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html