Introduction:
-------------

Media-service-upnp is a high level media content API that allows
client applications to discover, browse and search UPNP and DLNA media
servers.  Media-service-upnp is a d-Bus service implemented on top
of the GUPnP libraries.  It is designed to be used by media
applications such as Digital Media Players (DMPs) or Digital Media
Controllers (DMCs).  Media-service-upnp offers such applications a
number of benefits.

1. It provides a language and toolkit neutral API that can be used by
   any programming environment that supports d-Bus bindings.

2. It exposes high level APIs that are specifically designed for
   exploring media servers.

3. It reduces network traffic by communicating with Digital Media
   Servers (DMSs) on behalf of its clients.  This means that the
   device upon which media-service-upnp runs, only downloads and parses
   a DMS's device and service description files once, regardless of
   the number of media applications making use of its services.

4. (TODO) It will isolate clients from the differing behaviour of
   Digital Media Servers.  For example, some servers support
   searching while others do not.  When media-service-upnp receives a
   request from a client that is not supported by the target server,
   it will perform the request locally.  This feature greatly
   simplifies the task of writing media applications, as from the
   client's point of view, there is just one uniform DMS behaviour.


Compilation
------------

Media-service-upnp is built using autotools and gcc.  It also has a
number of dependencies on third party libraries, notably glib, gupnp,
gssdp and gupnp-av.  Both development versions of these libraries
and autotools need to be installed before media-service-upnp can be
compiled.  On Ubuntu 11.10 autotools and the glib development libraries can be
installed with the following commands.

sudo apt-get install autoconf
sudo apt-get install libglib2.0-dev

The GUPnP libraries in Ubuntu are a little out of date so it is best to
download the latest versions of these projects from their source code
repositories:

git://git.gnome.org/gupnp
git://git.gnome.org/gssdp
git://git.gnome.org/gupnp-av

However, media-service-upnp should compile against older versions of
GUPnP, although you might see some warnings.  On Ubuntu the development
versions of the GUPnP libraries can be installed as follows:

sudo apt-get install libgupnp-1.0-dev
sudo apt-get install libgupnp-av-1.0-dev
sudo apt-get install libgssdp-1.0-dev

The development version of d-Bus is also required.  This can be
installed on Ubuntu by typing:

sudo apt-get install libdbus-1-dev

Although media-service-upnp does not link against the d-Bus libraries,
the development version of this package is required by its build
system to determine where to install the .service files.


Working with the source code repository
---------------------------------------

Media-service-upnp can be downloaded, compiled and installed as
follows:

   Clone repository
     # git clone git://github.com/01org/media-service-upnp.git
     # cd media-service-upnp

   Configure and build
     # ./autoreconf -i
     # ./configure
     # make

   Final installation
     # sudo make install

These instructions are suitable for users who simply want to install
and run media-service-upnp.  However, developers wishing to contribute
to the project should follow a separate "Configure and build" step.

   Configure and build
     # ./bootstrap-configure
     # make

The script "bootstrap-configure" cleans the repository, calls
autreconf and then invokes configure with proper settings for
development.  These settings include the enabling of
maintainer mode and debugging.

Developers can remove autogenerated files with the following command

     # make maintainer-clean

Configure Options:
------------------

--enable-werror

This option is disabled by default.  To enable use --enable-werror.
When enabled, all warnings are treated as errors during compilation.
Should be enabled during development to ensure that errors do not
creep into the code base.  This option is enabled by
bootstrap-configure.

--enable-debug

This option is disabled by default.  To enable use
--enable-debug. When enabled, the make files produce debug builds.
This option is enabled by bootstrap-configure.

--enable-optimization

This option is enabled by default. To disable use
--disable-optimization. When enabled it turns on compiler
optimizations. Disable = -O0, enable = -O2.