Cling - The UPnP stack for Java and Android

Cling is an effort to create a UPnP-compatible software stack in Java. The project's goals are strict specification compliance, complete, clean and extensive APIs, as well as rich SPIs for easy customization.

Cling is Free Software, distributed under the terms of the GNU Lesser General Public License or at your option the Common Development and Distribution License.

We recommend you start with the README.txt.

Then download the Cling distribution or start with a Maven project in your pom.xml:

<repositories>
  <repository>

<id>4thline-repo</id>

<url>http://4thline.org/m2</url>

<snapshots>

 <enabled>false</enabled> <!-- Or true, if you like to use unreleased code -->

</snapshots>
  </repository> </repositories>  <dependencies>
  <dependency>

<groupId>org.fourthline.cling</groupId>

<artifactId>cling-core</artifactId>

<version>2.1.1</version>
  </dependency> </dependencies>

Read the first chapter of the manual for a simple Cling usage example. Have a look at the Android application examples.

Please post Cling usage questions on stackoverflow.com with the appropriate tags.

The main Cling modules are:

Cling Core

An embeddable Java library that implements the UPnP Device Architecture 1.0. Use Cling Core to expose services with a UPnP remoting interface, or to write control point applications that discover UPnP devices and utilize their services. You can also integrate Cling Core as an Android UPnP/DLNA library in your applications (platform level 15/4.0 required).

Cling Support

Optional classes and useful infrastructure for developing and controlling UPnP services with Cling Core; extensions that simplify working with UPnP media servers and renderers, NAT port mapping on routers, etc.

Cling Workbench

A desktop application for browsing UPnP devices and interacting with their services.

Cling MediaRenderer

Standalone UPnP MediaRenderer, based on gstreamer.

Building Cling

Install Maven 3.2.3 or newer.
Install the Android SDK and set the ANDROID_HOME environment variable to the SDK install directory.
Clone the Cling source:

git clone https://github.com/4thline/cling.git

Change into the cling/ directory.
Install everything into your local ~/.m2 Maven repository (this will take a few minutes if all dependencies have to be downloaded for the first time).

mvn clean install

If your build fails with Android/dex packaging errors, you forgot the clean.

Use Cling in your pom.xml with:

<dependencies>
<dependency>
  <groupId>org.fourthline.cling</groupId>
  <artifactId>cling-core</artifactId>
  <version>2.1.2-SNAPSHOT</version>
</dependency> </dependencies>

Building OS X Workbench DMG

hdiutil create -srcfolder \
  workbench/target/cling-workbench-2.1.2-SNAPSHOT/Cling\ Workbench.app \
  workbench/target/cling-workbench-2.1.2-SNAPSHOT/Cling\ Workbench.dmg

Publishing a release

Build release and tag on Github.

Update Maven repository:

mvn clean install mvn deploy

Projects and applications using Cling

If your project or product is using Cling and you'd like to add it to this page, open an issue and we'll add you to the list.

BubbleDS - A UPnP control point for Android and LinnDS streamer appliances.
BubbleUPnP - A generic UPnP/DLNA media control point and renderer for Android.
Jinzora UPnP - The Jinzora music management and streaming server can be accessed through a UPnP MediaServer gateway written with Cling. The Android client also uses Cling to access the MediaServer.
MovieBrowser UPnP - A movie manager to use with your favorite player on your Android tablet. Manage your videos anywhere on your network (Samba & UPnP/DLNA) and watch them with your favorite player or using the unique Play-To feature (Android airplay).
Private Dancer - A UPnP/DLNA Media Renderer for Android. It is designed to be used on a device attached to speakers and power. Unlike other UPnP Android applications, Private Dancer is designed for always-on (headless) use.
MediaHouse - Stream music, videos, movies and pictures from PC, NAS or any other device running UPnP/DLNA compliant media server to your Android phone/handset/tablet.
Digital Photo Frame Slideshow - Turn your Android device in a digital photo viewer showing a slideshow of local files, photos from network shares (Samba/SMB) or pictures from a UPnP server.
I-Frame Home - Full HD digital photo frame, picture-like design, displays files located in internal memory, LAN or Internet.
MediaConnect - Enables you to connect mediaservers with mediaplayers and also remote control these mediaplayers within a WLAN.
MediaConnect - MediaConnect enables you to connect mediaservers with mediaplayers and also remote control these mediaplayers within a WLAN.
ShuffleBox - Use your smartphone or tablet as a remote control and play music on your laptop, mobile phone or any other DNLA device.
DroidUPnP - A FREE SOFTWARE UPnP control point application for Android. DroidUPnP discover your home UPnP device, content provider and renderer. It allows you to browse your UPnP content directory, select the media you want to use and allows you to play it on your connected television or any UPnP renderer compatible device. It also allows you to use your Android device as a UPnP content provider.
YAACC -An Android UPnP controller, FREE SOFTWARE as GPL. It allows you to discover, use and control UPnP devices in your network in order to stream media files. Since it's a subset of UPnP it also is capable of communicating with DLNA devices.

Noteworthy forks of Cling

jUPnP - Forked from pre-2.0, this code base still contains the OSGi feature, which has been removed in Cling 2.0.
DIAL Support - Based on alpha 2.0 code, this UPnP/DLNA library for Java and Android contains modifications to discover DIAL devices.

FAQ

Which version of the UPnP specification does Cling implement?

Cling Core is compatible with the UPnP Device Architecture 1.0.

Can I use Cling to access a UPnP/DLNA MediaServer in Android?

Yes, you can write a control point application for Android with Cling Core as a UPnP library. You can find additional utilities for browsing and parsing a MediaServer content directory in the Cling Support module.

Can I use Cling in my commercial application or device?

Cling is licensed under the LGPL, so there are no restrictions on the use of the unmodified Cling JAR files/binaries. You can use the unmodified JAR files/binaries in any application or device, for any purpose. The following distribution (for free or for pay) restrictions apply:

If you distribute Cling with your application or device, you have to include a notice like "contains LGPL software" and a link to the Cling homepage, so your users also get the benefit of Free Software.
You have to allow replacement of the Cling library in your distributed application. This means allowing replacement of the Cling JAR or JVM binary class file(s) in, for example, a WAR or EAR package.
For Cling 1.x, the following exception for static linking of an executable (see LGPLv3 clause 4 or LGPLv2 clause 6b) applies to Cling usage within Android applications and the DEX instead of the JVM binary format: Converting Cling's binary JVM class files to the DEX format, and distributing a combined work as an Android APK does not affect the licensing of other resources within that DEX or APK archive. You must however allow re-packaging/conversion of the DEX and APK with tools such as dex2jar. Anyone receiving your APK must be able to replace the Cling binary code with a compatible version. You can not lock your APK with any kind of obfuscation or DRM scheme, or otherwise prevent unpacking and reassembly of the DEX containing Cling binaries. Alternatively, consider dynamic loading of libraries on Android.
For Cling 2.x, you may at your option license Cling under CDDL instead of the LGPL. You can convert to DEX and package Cling 2.x within an APK without affect on other files in that APK. You can obfuscate the source in the APK and lock it with digital restrictions. If you modify Cling source code, and you distribute a binary compiled from this modified source code, you have to distribute your changed source code as well under the LGPL or CDDL (upon request). Typically this means you contribute your changes back to the Cling project, to be included in an official Cling release.

What are the dependencies of Cling Core?

Cling Core is distributed as a single JAR file. It only has one other dependency, the seamless-* libraries. All JAR files are typically packaged next to each other in the ZIP distribution. You have to add them to your classpath.

How can I access the services of a device?

First write a control point and a RegistryListener as explained in the manual. Then call device.getServices() when a device has been discovered.

Cling doesn't work if I start my application on Tomcat/JBoss/Glassfish/etc?!

You'll get an error on startup, this error tells you that Cling couldn't use the Java JDK's HTTPURLConnection for HTTP client operations. This is an old and badly designed part of the JDK: Only "one application" in the whole JVM can configure it. You have to switch Cling to an alternative HTTP client, e.g. the other bundled implementation based on Apache HTTP Core. This is explained in more detail in the user manual.

Is IPv6 supported?

No, the default configuration of the UPnP stack in Cling Core will filter all network interfaces and IP addresses that are not IPv4. Some other parts of the Cling Core library might also assume that addresses are IPv4 and the whole library has not been tested in an IPv6 only environment. You are welcome to test Cling on IPv6 with a custom UpnpServiceConfiguration and NetworkAddressFactory and contribute back any necessary changes.

I don't see debug log messages on Android?

The java.util.logging implementation on Android is broken, it does not allow you to print debug-level messages easily. See this discussion for a simple solution.

Where can I find the source for Cling 1.x and teleal-common?

Here.

Wich version of Android (API) is supported by Cling?

Cling 1.0 supports Android 2.1. With Cling 2.0, we currently require platform level 15 (Android 4.0.3).

I get a lock acquisition timeout exception?

Your service receives a subscription, then this happens:

RuntimeException at org.teleal.cling.protocol.sync.ReceivingSubscribe.responseSent(ReceivingSubscribe.java:177)

Your service was already being used by something else and didn't give up the lock during the 500 millisecond default wait time. Increase the wait time by overriding DefaultServiceManager in LocalService. Or don't block the service action/methods for a long time.

cling