mmupnp

Universal Plug and Play (UPnP) ControlPoint library for Java.

Feature

Pure Java implementation.
Available in both Java application and Android apps.
Easy to use
High response

Of course, this also can be used from kotlin.

Requirements

Java 8 or later (or Java 6 or later with retrolambda)
Android Gradle Plugin 3.0.0 or later

Restrictions

This library support only ControlPoint functions. There is no way to make Device. If you need it, please select another library.
Some functions that are not widely used are not implemented.
- Multicast eventing

Example of use

Android App

DMS Explorer -- [Google Play] [Source Code]

Sample App

How to use

You can download this library from jCenter. (since Ver.1.7.0)

repositories {
    jcenter()
}

Add dependencies, as following.

dependencies {
    implementation 'net.mm2d:mmupnp:1.8.1'
}

Test release

This library is currently under development of 2.0.0. Currently alpha version, and I'm making destructive change.

It is distributed in this maven repository.

repositories {
    maven {
        url 'https://ohmae.github.com/mmupnp/maven'
    }
}
dependencies {
    implementation 'net.mm2d:mmupnp:2.0.0-alpha6'
}

Initialize and Start

ControlPoint cp = ControlPointFactory.create();
cp.initialize();
// adding listener if necessary.
cp.addDiscoveryListener(...);
cp.addNotifyEventListener(...);
cp.start();
...

If you want to specify the network interface, describe the following.

NetworkInterface ni = NetworkInterface.getByName("eth0");
ControlPoint cp = ControlPointFactory.create(ni);

By default ControlPoint will work with dual stack of IPv4 and IPv6. If you want to operate with IPv4 only, specify the protocol as follows.

ControlPoint cp = ControlPointFactory.create(Protocol.IP_V4_ONLY);

You can specify callback and thread of IO processing. For example in Android, you may want to run callbacks with MainThread. In that case write as follows.

Params params = new Params().setCallbackExecutor(new TaskExecutor() {
    @Override
    public boolean execute(@Nonnull final Runnable task) {
        return handler.post(task);
    }

    @Override
    public void terminate() {
    }
});
ControlPoint cp = ControlPointFactory.create(params);

M-SEARCH

Call ControlPoint#search() or ControlPoint#search(String).

cp.search();                   // Default ST is ssdp:all

cp.search("upnp:rootdevice"); // To use specific ST. In this case "upnp:rootdevice"

These methods send one M-SEARCH packet to all interfaces.

Invoke Action

For example, to invoke "Browse" (ContentDirectory) action...

...
Device mediaServer = cp.getDevice(UDN);           // get device by UDN
Action browse = mediaServer.findAction("Browse"); // find "Browse" action
Map<String, String> arg = new HashMap<>();        // setup arguments
arg.put("ObjectID", "0");
arg.put("BrowseFlag", "BrowseDirectChildren");
arg.put("Filter", "*");
arg.put("StartingIndex", "0");
arg.put("RequestedCount", "0");
arg.put("SortCriteria", "");
Map<String, String> result = browse.invoke(arg);  // invoke action
String resultXml = result.get("Result");          // get result
...

Event Subscription

For example, to subscribe ContentDirectory's events...

...
// add listener to receive event
cp.addNotifyEventListener(new NotifyEventListener(){
  public void onNotifyEvent(Service service, long seq, String variable, String value) {
    ...
  }
});
Device mediaServer = cp.getDevice(UDN);          // get device by UDN
Service cds = mediaServer.findServiceById(
  "urn:upnp-org:serviceId:ContentDirectory");    // find Service by ID
cds.subscribe(); // Start subscribe
...
cds.unsubscribe(); // End subscribe

Stop and Terminate

...
cp.stop();
cp.removeDiscoveryListener(...);
cp.removeNotifyEventListener(...);
cp.terminate();

It is not possible to re-initialize. When you want to reset, try again from the constructor call.

Debug log output

This library use log library,

If you want to enable debug log.

Log.initialize(true, true);

If you want send log to some library. eg.

Log.setPrint { level, tag, message ->
    if (level >= Log.DEBUG) {
        SomeLogger.send("$tag $message")
    }
}

Please see log library for more details

Documents

I described Javadoc comments. Please refer to it for more information.

Javadoc in Japanese

Author

大前良介 (OHMAE Ryosuke) http://www.mm2d.net/

License

MIT License

ArcXIII/mmupnp