[Kde-hardware-devel] UPnP: integration with coherence

[Armijn Hemel]

On Wed, 2008-12-03 at 01:14 +0100, Armijn Hemel wrote:
> > > Hm, it might be best if I first draft a plan, where I explain what
> needs
> > > to be done. 
> > 
> > yes.
> > 
> > > Any objections against ASCII art? :-)
> > 
> > hehe. nope =)
> 
> OK, will do so. It might take a little while to finish, since right
> now
> I'm into GPL enforcement mode and we (gpl-violations.org) have a large
> backlog we need to get rid of first.
> 
> Hopefully before the new year.

I've made a draft, which I hope makes sense. It's attached.

What I want to describe: a pure daemon approach is not sensible. A pure
library approach isn't either. A combination of both, with some daemon
dealing with all kinds of state and a library to catch application
specific stuff is the way to go (in my opinion).

armijn

-- 
-------------------------------------------------------------------------
armijn at uulug.nl | http://www.uulug.nl/ | UULug: Utrecht Linux Users Group
-------------------------------------------------------------------------
-------------- next part --------------
UPnP for KDE

Universal Plug and Play (UPnP) is a omnipresent network technology, that is in use on millions of networks and desktops. Support of it in the free software desktop so far has not been too good and rather fragmented. Applications that implement UPnP often have been rewritten from scratch, without usability in mind, even when this would be convenient (torrent clients and chat clients for example both benefit from being able to work with the UPnP Internet Gateway Device profile).

There are four main data flows in UPnP:

1. discovery of devices on the network
2. description of services
3. control of services through SOAP
4. eventing of state variables on the network

Each of these data flows works differently. The first one uses multicast and unicast UDP, the second one uses HTTP, the third one uses SOAP, the fourth one uses HTTP callbacks to URLs that are registered.

Each of the scenarios is described below using a few examples.

The architecture I envision is the following:

* there is some broker that deals with all management details (which devices are on the network, which services do they implement, and so on). This is mostly incoming data.
* there are UPnP profile specific client libraries, that capture the application SOAP specific stuff (outgoing data)

This prevents that the broker has to deal with application specific details and prevents application specific libraries to implement the whole
management layer.

Data flows 1, 2 and 4 are management, while 3 is application specific.

Scenario: discovering devices on the network

On a network with UPnP devices announce when they are joining (and sometimes leaving) the network. Programs/devices can also explicitely query the network for information about other devices. In Windows XP and Vista the devices that are found are often displayed in the "My Computer"/"This Computer"/"Computer" window, next to harddisks, with an icon. Clicking on the icon opens a web browser and redirects the user to the advertized URL (in devices that behave normally this is the URL of the management interface).

Announcements are sent to 239.255.255.250 port 1900 (UDP) for multicast announcements, or with a UDP unicast when the network is explicitely queried. The destination port is the same port that was used for sending. Reuse of sockets makes this a lot less of a headache :-)

One device can implement several services. For each service an announcement is sent.

Since KDE is by design a multi user desktop it would not make since to have port 1900 owned by the one user sitting behind the desktop. With multi seat X you would have more desktops on one physical machine. You would either have to share this port between a users, or have a broker program that processes the information and routes it to the right programs.

Scenario: description of services

Every service on the network publishes an XML file that describes which actions are implemented in each service and where commands should be sent to and where event subscriptions should be sent to. The location of this file can be found in the announcements from the discovery process. The XML files are downloaded from the device using normal HTTP. The information in this file is used by the control process and eventing.

Scenario: control of services through SOAP

Example: requesting a portmapping from a router

A typical home network looks like this:

                         +---+
                     /---| A |
                     |   +---+
INTERNET---router----+
                     |   +---+
                     \---| B |
                         +---+

There are two machines: A and B, which are desktops. The router performs NAT on traffic to and from the Internet. The router has implemented the UPnP Internet Gateway Device profile, specifically for managing port mappings.

Some applications, like torrent applications and chat programs, benefit from having the functionality of portmapping. There are some stacks that have odd quirks and require that you format your SOAP requests in the right format.

There are no special requirements for programs to use a special broker for this, since the could all be captured in a client side library that
can work around the quirks. All that the client program should get from the broker that keeps track of which services are available is a URL
where commands should be sent to. It should get this information by querying the broker by sending a request for a certain profile.

Having it this way avoids hardcoding a lot of functionality about profiles in the broker, which still being able to work around all the stack
specifics in a special purpose library.


Scenario: Finding out about the state of devices

   +---+
   | M |
   +---+
     |
-----+----------+-------------
                |
              +---+
              | A |
              +---+

The above network has two machines: A (a desktop) and M (a UPnP enabled device). The user on computer A is interested in the UPnP state of M. This state can be queried directly, or it can be kept up to date using a mechanism called eventing. Eventing works a bit like this (of course,
things are always slightly more complicated in real life, but not much):

The user on computer A registers a callback URL with M, expressing an interest in being updated when something changes. Whenever there is a change M sends a HTTP POST request to the callback URL registered by A, with a piece of XML with the current values.

This piece of XML is then parsed and the right values are sent to the user on computer A.

Please note: the specifications are not clear if the callback URL should actually point to A, or that the callback is allowed to point to a completely different machine too.

If, for now, we assume that the callbacks point to computer A, then there are a few observations:

* A has to run a HTTP server that can process incoming HTTP POST requests
* A has to parse the XML and send it to the right process