Repository files navigation

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

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

• kotlin 1.3 or later
• Java 7 or later

• This library only provides ControlPoint.There is no way to make Device. If you need it, please select another library.

Plan for the next version.

• Full support for Kotlin coroutines
• Support for ControlPoint and Device
• Multi-module for selectable feature

Android App

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

Sample App

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

• KDoc for 3.x.x (English)
• Javadoc for 2.x.x (Japanese)

jCenter will close in May. In 3.1.3 moved to mavenCentral from jcenter.
Please note that thegroupID has changed

Download from mavenCentral.

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

Versions below 3.1.3 were distributed with jCenter.However, jCenter will close and old versions are not migrated to mavenCentral.If you need an older version, please use the Github Pages repository.

repositories {    maven { url=URI("https://ohmae.github.com/maven") }}

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

To create instance with default parameter.

val cp=ControlPointFactory.create()

ControlPointFactory.create() has many initialization parameters.

In addition, Builder is also available.Please use them according to your preference. It is convenient when using from Java.

val cp=ControlPointFactory.builder()    .setInterfaces(interfaces)    .setCallbackHandler { handler.post(it) }....    .build()

To specify the network interface,

val cp=ControlPointFactory.create(    interfaces=listOf(NetworkInterface.getByName("eth0")))

By default, ControlPoint will work with the dual stack of IPv4 and IPv6.To operate with IPv4 only, specify the protocol,

val cp=ControlPointFactory.create(    protocol=IP_V4_ONLY)

You can change the callback thread.For example in Android, you may want to run callbacks with MainThread.

val cp=ControlPointFactory.create(    callbackHandler= { handler.post(it) })

Or If use executor,

val cp=ControlPointFactory.create(    callbackExecutor=object:TaskExecutor{privateval executor=Executors.newSingleThreadExecutor()overridefunexecute(task:Runnable):Boolean {            executor.execute(task)        }overridefunterminate() {            executor.shutdownNow()        }    })

If EventSubscription is not required,

val cp=ControlPointFactory.create(    subscriptionEnabled=false)

The server thread for receiving events does not start and resources can be reduced.

If you want to receive multicast events,

val cp=ControlPointFactory.create(    multicastEventingEnabled=true)

This feature is experimental.Compatibility cannot be confirmed because no other implementation has been found.

val cp=ControlPointFactory.create().also {// adding listener if necessary.    it.addDiscoveryListener(...)    it.addNotifyEventListener(...)    it.initialize()    it.start()}...

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.

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

val mediaServer= cp.getDevice(UDN)// get device by UDNval browse= mediaServer.findAction("Browse")// find "Browse" actionbrowse?.invoke(mapOf("ObjectID" to"0","BrowseFlag" to"BrowseDirectChildren","Filter" to"*","StartingIndex" to"0","RequestedCount" to"0","SortCriteria" to""    ),    onResult= {val resultXml= it.get("Result")// get result...    },    onError= {// on error...    })

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

// add listener to receive eventaddEventListener( eventListener { service, seq, properties->    properties.forEach {        eventArea.text="${eventArea.text}${service.serviceType} :$seq :${it.first} :${it.second}\n"    }})val mediaServer= cp.getDevice(UDN)// get device by UDNval cds= mediaServer.findServiceById("urn:upnp-org:serviceId:ContentDirectory")// find Service by IDcds.subscribe()// Start subscribe...cds.unsubscribe()// End subscribe

Of course, this will not work if disabled at initialization.

cp.stop()cp.terminate()

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

This library uselog library,

To enable debug log.

Logger.setLogLevel(Logger.VERBOSE)Logger.setSender(Senders.create())

In this case output toSystem.out

To send log to a library,eg. Simply change the output method.

Logger.setSender(DefaultSender.create({ level, tag, message->    message.split('\n').forEach {        android.util.Log.println(level, tag, it)    }}))

eg. To handle exception

Logger.setSender { level, message, throwable->if (level>=Log.DEBUG) {SomeLogger.send(...)    }}

Please seelog library for more details

• ERROR
  • Log indicating the possibility of a problem occurring.
• WARN
  • Log indicating the possibility of a problem occurring, but also often output in normal operation.
• INFO
  • Logs that may help analyze the problem, but may be output in large amounts.
• DEBUG
  • Logs that output in normal operation for debugging.
• VERBOSE
  • More detail logs that output in normal operation for debugging.

• Kotlin
  • org.jetbrains.kotlin:kotlin-stdlib-jdk7
• log
  • net.mm2d.log:log

This project is being developed with IntelliJ IDEA Ultimate,thanks to be approved to Jetbrains Free Open Source Licenses.

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

MIT License