Linux SDK for UPnP Devices (libupnp)

See LICENSE for details.

This file contains information about the above product in the following sections:

Release Contents
Package Contents
System Requirements
Build Instructions
Install/Uninstall Instructions
Product Release Notes
New Features
Support and Contact Information

1) Release Contents

The Linux SDK for UPnP Devices is an SDK for development of UPnP device and control point applications for Linux. It consists of the core UPnP protocols along with a UPnP-specific eXtensible Markup Language (XML) parser supporting the Document Object Model (DOM) Level 2 API and an optional, integrated mini web server for serving UPnP related documents.

2) Package Contents

The Linux SDK for UPnP Devices contains the following:

README          This file.  Contains the installation and build instructions.
LICENSE         The licensing terms the SDK is distributed under.
NEWS            Changes and new features.
ixml\doc        The files for generating the XML parser documentation from
                the source code.
ixml\inc        The public include files required to use the XML parser.
ixml\src        The source code to the XML parser library.
threadutil\inc  The public include files required to the threading 
                utility library.
threadutil\src  The source code to the threading utility library.
upnp\doc        The files for generating the SDK documentation from the
                source code.
upnp\inc        The public include files required to use the SDK.
upnp\src        The source files comprising the SDK, libupnp.so.
upnp\sample     A sample device and control point application, illustrating the
                usage of the SDK.

3) System Requirements

The SDK for UPnP Devices is designed to compile and run under the Linux operating system. It does, however, have dependencies on some packages that may not be installed by default. All packages that it requires are listed below. The name of the package and where it can be found is dependent on the distribution of Linux being used.

libpthread The header and library are installed as part of the glibc-devel

package (or equivalent).

Additionally, the documentation for the SDK can be auto-generated from the UPNP.H header file using DOC++, a documentation system for C, C++, IDL, and Java*. DOC++ generates the documentation in HTML or TeX format. Using some additional tools, the TeX output can be converted into a PDF file. To generate the documentation these tools are required:

DOC++       The homepage for DOC++ is http://docpp.sourceforge.net/.
            The current version as of this release of the SDK is
            version 3.4.9.  DOC++ is the only requirement for generating
            the HTML documentation.
LaTeX/TeX   To generate the PDF documentation, LaTeX and TeX tools are
            necessary.  The tetex and tetex-latex packages provide these
            tools.
dvips       dvips converts the DVI file produced by LaTeX into a PostScript*
            file.  The tetex-dvips package provides this tool.
ps2pdf      The final step to making the PDF is converting the PostStript
            into Portable Document Format.  The ghostscript package provides
            this tool.

For the UPnP library to function correctly, Linux networking must be configured properly for multicasting. To do this:

route add -net 239.0.0.0 netmask 255.0.0.0 eth0

where 'eth0' is the network adapter that the UPnP library will use. Without this addition, device advertisements and control point searches will not function.

libupnp has been built and tested on the following configurations:

MandrakeLinux 10.1 (kernel 2.6.8.1-12mdk, gcc 3.4.1, glibc-2.3.3)
Ubuntu 5.10 "Breezy Badger" (Linux kernel 2.6.12-9-386, gcc 4.0.2 20050808 prerelease, libc6 2.3.5-1ubuntu12)

4) Build Instructions

CORE LIBRARIES

The in the examples below, replace $(LIBUPNP) with "libupnp-x.y.z", with x, y, and z corresponding to the version of the library that you have.

All pieces of the SDK are configured and built from the $(LIBUPNP) directory.

% cd $(LIBUPNP)
% ./configure
% make

will build a version of the binaries without debug support, and with default options enabled (see below for options available at configure time).

To build the documentation, assuming all the necessary tools are installed (see section 3) :

To generate the HTML documentation:

% cd $(LIBUPNP)
% make html

To generate the PDF file:

% cd $(LIBUPNP)
% make pdf

A few options are available at configure time. Use "./configure --help" to display a complete list of options. Note that these options may be combined in any order.
After installation, the file <upnp/upnpconfig.h> will provide a summary of the optional features that have been included in the library.

% cd $(LIBUPNP)
% ./configure --enable-debug
% make

will build a debug version with symbols support.

To build the library with the optional, integrated mini web server (note that this is the default):

% cd $(LIBUPNP)
% ./configure --enable-webserver
% make

To build without:

% cd $(LIBUPNP)
% ./configure --disable-webserver
% make

The SDK for Linux also contains some additional helper APIs, declared in inc/tools/upnptools.h. If these additional tools are not required, they can be compiled out:

% cd $(LIBUPNP)
% ./configure --disable-tools
% make

By default, the tools are included in the library.

To further remove code that is not required, the library can be build with or with out the control point (client) or device specific code. To remove this code:

% cd $(LIBUPNP)
% ./configure --disable-client
% make

to remove client only code or:

% cd $(LIBUPNP)
% ./configure --disable-device
% make

to remove device only code.

By default, both client and device code is included in the library. The integrated web server is automatically removed when configuring with --disable-device.

To build the library without large-file support (enabled by default) :

% cd $(LIBUPNP)
% ./configure --disable-largefile
% make

To remove all the targets, object files, and built documentation:

% cd $(LIBUPNP)
% make clean

CROSS COMPILATION

To cross compile the SDK, a special "configure" directive is all that is required:

% cd $(LIBUPNP)
% ./configure --host=arm-linux
% make

This will invoke the "arm-linux-gcc" cross compiler to build the library.

SAMPLES

The SDK contains two samples: a TV device application and a control point that talks with the TV device. They are found in the $(LIBUPNP)/upnp/sample directory.

To build the samples :

% cd $(LIBUPNP)
% make check

will build the sample device "$(LIBUPNP)/upnp/upnp_tv_device" and sample control point "$(LIBUPNP)/upnp/upnp_tv_ctrlpt". Note : the sample device won't be built if --disable-device has been configured, and the sample control point won't be build if --disable-client has been configured.

To run the sample device, you need the "$(LIBUPNP)/upnp/sample/tvdevice/web" sub-directory. Example :

% cd $(LIBUPNP)/upnp/sample/tvdevice
% ../../upnp_tv_device

5) Install/Uninstall Instructions

Install

The top-level makefile for the UPnP SDK contains rules to install the necessary components. To install the SDK, as root:

make install

Uninstall

Likewise, the top-level makefile contains an uninstall rule, reversing the steps in the install:

make uninstall

6) Product Release Notes

The SDK for UPnP Devices v1.2.1a has these known issues:

The UPnP library may not work with older versions of gcc and libstdc++, causing a segmentation fault when the library loads. It is recommended that gcc version 2.9 or later be used in building library.
The UPnP library does not work the glibc 2.1.92-14 that ships with Red Hat 7.0. For the library to function, you must updated the glibc and glibc-devel packages to 2.1.94-3 or later. There is some issue with libpthreads that has been resolved in the 2.1.94 version.

7) New Features

See NEWS file.

8) Support and Contact Information

Intel is not providing support for the Linux SDK for UPnP Devices. Two mailing lists for the SDK are available on http://upnp.sourceforge.net/. Questions and problems should be addressed on the appropriate mailing list.

If you find this SDK useful, please send an email to upnp@intel.com and let us know.

Other brands, names, and trademarks are the property of their respective owners.