Home

Awesome

Cling EOL: This project is no longer actively maintained, code may be outdated. If you are interested in maintaining and developing this project, comment here.


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 <a href="http://www.gnu.org/licenses/lgpl-2.1.html">GNU Lesser General Public License</a> <b>or at your option</b> the <a href="http://opensource.org/licenses/CDDL-1.0">Common Development and Distribution License</a>.

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.2</version>
    </dependency>
</dependencies>

Read <a href="http://4thline.org/projects/cling/core/manual/cling-core-manual.xhtml#chapter.GettingStarted">the first chapter of the manual</a> for a simple Cling usage example. Have a look at the <a href="https://github.com/4thline/cling/tree/master/demo/android">Android application examples</a>.

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

See the forum archive for older discussions.

Cling Modules

Cling Core

An embeddable Java library that implements the <a href="http://www.upnp.org/resources/documents.asp">UPnP Device Architecture 1.0</a>. 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 <a href="http://4thline.org/projects/cling/core/manual/cling-core-manual.xhtml#chapter.Android">Cling Core as an Android UPnP/DLNA library in your applications</a> (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, <a href="http://4thline.org/projects/cling/support/manual/cling-support-manual.xhtml#section.PortMapping">NAT port mapping on routers</a>, etc.

Cling Workbench

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

Cling MediaRenderer

Standalone <a href="http://www.upnp.org/resources/documents.asp">UPnP MediaRenderer</a>, based on gstreamer.

Building Cling

git clone https://github.com/4thline/cling.git
mvn clean install

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

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

Building OS X Workbench DMG

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

Publishing a release

Build release and tag on Github.

Update Maven repository:

mvn clean install
mvn clean deploy -DskipTests

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.

Noteworthy forks of Cling

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:

<a href="mailto:license(at)4thline.com">Contact us</a> if you have questions about the licensing of Cling and/or require a proprietary license.

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 <a href="http://4thline.org/projects/cling/core/manual/cling-core-manual.xhtml#section.BinaryLightClient">in the manual</a>. 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 <a href="http://4thline.org/projects/cling/core/manual/cling-core-manual.xhtml#section.BasicAPI.UpnpService.Configuration"> the user manual</a>.

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 <tt>UpnpServiceConfiguration</tt> and <tt>NetworkAddressFactory</tt> 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?

<a href="http://4thline.org/projects/download/archive/">Here.</a>

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.