= Libupnpp for Control Points
Libupnpp is a C++ wrapper for link:http://pupnp.sourceforge.net/[libupnp],
a.k.a Portable UPnP, which is a direct descendant of the Open Source SDK
released by Intel in support of UPnP development.
Libupnpp can be used to implement UPnP devices and services, or Control
Points.
The Control Point side of libupnpp, which is documented here, allows a C++
program to discover UPnP devices, and exchange commands and status with
them.
The library has a number of predefined modules for controlling specific
AVTransport or OpenHome audio services, and it is relatively easy to add
modules for other services externally (the internal modules have no more
access to library internals than an external module would).
Limitations:
- The underlying libupnp only supports a single IP interface.
- The libupnpp methods are blocking. Multithreading will be needed to
achieve parallelism in your program (in any case the underlying libupnp
uses threads, so multithreading support is a requirement).
link:refdoc/html/index.html[Reference documentation (doxygen)]
== The Library object
The library is represented by a global singleton with a number of utility
methods, mostly related to setting parameters for the underlying libupnp
library.
The link:refdoc/html/classUPnPP_1_1LibUPnP.html#a00ef52e413804a5f6dca74e2459749c7[instanciation call] takes a number of arguments to specify
non-default values, e.g. for the IP address or interface to use.
If you have no need for the non-default parameter values, or the utility
methods, there is no necessity to explicitly instanciate the library
object, this will be done internally as needed.
== Discovery
The UPnP Discovery framework allows searching for devices on a network and
maintaining a directory of active devices.
Libupnpp implements this function with the
link:refdoc/html/classUPnPClient_1_1UPnPDeviceDirectory.html[UPnPDeviceDirectory]
class, which is instanciated as a single object.
Example code for accessing a device for which you know the 'friendly name':
----
auto *superdir = UPnPClient::UPnPDeviceDirectory::getTheDir();
UPnPClient::UPnPDeviceDesc devicedesc;
bool ok = superdir->getDevByFName(name, devicedesc);
----
== Description
UPnP devices describe their capabilities in XML documents which can be
retrieved from them through HTTP.
In libupnpp, the content of the main description document for a given
device is provided by a
link:refdoc/html/classUPnPClient_1_1UPnPDeviceDesc.html[UPnPClient::UPnPDeviceDesc]
object.
When using the devices and services predefined by the library, this is
largely an opaque structure, which you will get through the discovery
interface, and pass to a Device or Service constructor.
== Devices
UPnP devices are entities which can contain other, embedded devices, and
services.
Embedded devices are quite rare, and in my experience badly supported by
common control points.
In general, the service is the interesting entity, and the wise approach is
the Pythonic "quacks like a duck" one: if a device has the service you
need, you can use it.
For example the predefined 'MediaRenderer' class in libupnpp does not even
bother to verify its own type when built from a description: it just
provides methods to query and retrieve handles to interesting services
usually found in a Media Renderer (both OpenHome and UPnP AV). In most
cases, not all services will be available, and the caller will compose an "a
la carte" object to serve its needs (e.g. using either UPnP AV Rendering
Control or OpenHome Volume for controlling volume, depending on
availability).
As another example, the 'myrdcvolume' program from the libupnpp samples
shows how to implement a service interface without using the predefined
ones. It does not bother with the device type either (actually it does not
bother at all with a device object), but just checks for the existence of
the appropriate service
(i.e. 'urn:schemas-upnp-org:service:RenderingControl'), and action
('Volume').
The library predefines two device classes, for Media Server devices and
Media Renderer ones. Both are convenience classes with utility code to
build the underlying service objects and retrieve handles for them.
== Services
Most UPnP functionality is provided through services, which are end points
implemented inside a device, callable through HTTP/SOAP.
libupnpp provides a set of easy C++ interfaces for most UPnP audio services
(some of which also work with video). You will usually not need to bother
constructing the service interface objects: rather you will let the device
classes do it and return a handle (but there is nothing to prevent you from
building the service objects directly).
There are two possible approaches for accessing a service which does not
have a predefined interface class in the library:
- Use the library helper functions for implementing a specific service
interface, by deriving from the base
link:refdoc/html/classUPnPClient_1_1Service.html[Service] class.
- Use the xref:TypedService[TypedService] generic string-based interface
class.
== Predefined Service classes
* link:refdoc/html/classUPnPClient_1_1RenderingControl.html[UPnP AV
Rendering Control]
* link:refdoc/html/classUPnPClient_1_1AVTransport.html[UpnP AV AVTransport]
* link:refdoc/html/classUPnPClient_1_1OHPlaylist.html[Open Home Playlist]
* link:refdoc/html/classUPnPClient_1_1OHInfo.html[Open Home Info]
* link:refdoc/html/classUPnPClient_1_1OHProduct.html[Open Home Product]
* link:refdoc/html/classUPnPClient_1_1OHRadio.html[Open Home Radio]
* link:refdoc/html/classUPnPClient_1_1OHTime.html[Open Home Time]
* link:refdoc/html/classUPnPClient_1_1OHVolume.html[Open Home Volume]
* link:refdoc/html/classUPnPClient_1_1OHReceiver.html[Open Home Songcast
Receiver]
* link:refdoc/html/classUPnPClient_1_1OHSender.html[Open Home Songcast Sender]
The role of most methods in these classes is to marshal the input data into
SOAP format, perform the SOAP call, then marshal and return the output
data. They are all synchronous.
[[TypedService]]
== String based interface
The link:refdoc/html/classUPnPClient_1_1TypedService.html[TypedService]
class provides access to the actions in a service through a simple
string-based interface.
The user only needs specify an action name and a list of arguments to call
an action. The class uses the service description retrieved from the
device to generate the actual SOAP call. Any returned data is provided
through a C++ name-value map.
The class also has an associated
link:refdoc/html/namespaceUPnPClient.html#ad3edfb36acb86cb98961233b127fc3df[helper
function] which provides a simplified interface to discovery.
While the class is less convenient to use than one customized to a single
service, which can provide full encoding/decoding between SOAP data and a
natural C++ interface, it avoids having to write the corresponding code. It
was mostly implemented as a convenient interface for the SWIG module, but
it can probably have other uses.
== Eventing
UPnP services can report changes in their state to Control Points through
events. In practise, the Control Point implements an internal HTTP server
to which the services connect to report events.
Event reporting is not active by default and needs to be activated by the
Control Point by 'subscribing' to the service.
Users of Service classes can receive asynchronous events by calling the
link:refdoc/html/classUPnPClient_1_1Service.html#a2d9aad17b90587f8c6a3791944edcdde[installReporter()]
method, to specify what functions should be called when an event arrives.
NOTE: The event functions are called from a separate thread
and some synchronization will usually be required.
Some details of event handling in libupnpp have changed as of version
0.16.
== Event handling in version 0.15 and before
Services implemented by the library always subscribe to events. This
happens in the object constructor, by a call to the class derived
registerCallback() method. Example:
----
avtransport.hxx:
class AVTransport : public Service {
...
AVTransport(const UPnPDeviceDesc& device,
const UPnPServiceDesc& service)
: Service(device, service) {
registerCallback();
}
...
avtransport.cxx:
void AVTransport::registerCallback()
{
Service::registerCallback(bind(&AVTransport::evtCallback, this, _1));
}
----
'Service::registerCallback()' performs the UPnP subscription and takes note
of the function to call when an event arrive.
This means that a subscription (needing a network exchange) is performed
each time a Service object is built, even if events are not actually needed
by the user.
The Service base class destructor erases the callback hook and cancels the
event subscription.
=== Event handling for version 0.16 and later
As of version 0.16 of the library, the event subscription is only performed
if and when 'installReporter()' is called. If you don't need events, you
will not incur their overhead.
== Logging
Both 'libupnp' and 'libupnpp' have configurable error and debug logging.
=== libupnp logging
The log from 'libupnp' is very detailed and mostly useful for low level
debugging of UPnP issues. The logging functions in 'libupnp' are
conditionnally compiled, and may not be enabled for your distribution (you
can check UPNP_HAVE_DEBUG in 'include/upnp/upnpconfig.h').
If the 'libupnp' logging functions are enabled, you can control them
through the
link:refdoc/html/classUPnPP_1_1LibUPnP.html#afb21929cea7859786d93dec1086563bc[LibUPnP::setLogFileName()]
and 'LibUPnP::setLogLevel()' methods.
=== libupnpp logging
'libupnpp' logging is distinct from the 'libupnp' functions, and always
enabled, at a configurable level of verbosity.
The log is initialized by a call to
link:refdoc/html/classLogger.html[Logger::getTheLog()]. The
verbosity level can be adjusted through 'setLogLevel()', and macros are
used to emit the actual messages. The printing is based on the C++ iostreams.
See libupnpp/log.h for more details.
Exemple:
----
if (Logger::getTheLog(logfilename) == 0) {
cerr << "Can't initialize log" << endl;
return 1;
}
Logger::getTheLog("")->setLogLevel(Logger::LLINF);
...
LOGINF("Message at level INFO, it outputs some value: " << value);
----
Of course you can use the 'LOGXX' macros in your own code.
== Implementing a Service class
If you want to access a service for which no predefined class exists in
libupnpp, you need to define its interface yourself, by deriving the
'libupnpp' link:refdoc/html/classUPnPClient_1_1Service.html[Service] class.
The methods in the base class and in the helper modules make it very easy
to write the derived class.
NOTE: libupnpp has no provision to use the service description XML document
to define the service client methods. However, the device side has a script
to turn a service description into an implementation device-side skeleton.
The derived class main constructor will take Device and Service description
structures are arguments and will need to call the base class
constructor. Example:
----
class OHPlaylist : public Service {
public:
OHPlaylist(const UPnPDeviceDesc& device, const UPnPServiceDesc& service)
: Service(device, service) {
}
...
----
If there are initialization steps which are specific to the service type,
they should be done inside the 'serviceInit()' method, which
should be called from the constructor (see below for a more detailed
description). Most services don't need 'serviceInit()', so an empty
implementation is provided by the base class.
Action methods are then just ordinary methods, which will call the base
class methods to perform the networky things.
Example of an action setting a value:
----
int RenderingControl::setMute(bool mute, const string& channel)
{
SoapOutgoing args(getServiceType(), "SetMute");
args("InstanceID", "0")("Channel", channel)
("DesiredMute", SoapHelp::i2s(mute?1:0));
SoapIncoming data;
return runAction(args, data);
}
----
The link:refdoc/html/classUPnPP_1_1SoapOutgoing.html[SoapOutgoing]
constructor takes a service type and action name arguments. Its 'operator ()'
accepts additional named string arguments.
The
link:refdoc/html/classUPnPClient_1_1Service.html#a7eee43639eff25893117ab52b0b036db[Service::runAction()]
method performs the SOAP call and provides any resulting data in a
link:refdoc/html/classUPnPP_1_1SoapIncoming.html[SoapIncoming] object, from
which named values can be easily extracted. There is no return data in the
above example, see below for an action using 'SoapIncoming::get()' to
extract data.
Example of an action retrieving a value (note there is nothing to prevent
an action to both set and retrieve data).
----
bool RenderingControl::getMute(const string& channel)
{
SoapOutgoing args(getServiceType(), "GetMute");
args("InstanceID", "0")("Channel", channel);
SoapIncoming data;
int ret = runAction(args, data);
if (ret != UPNP_E_SUCCESS) {
return false;
}
bool mute;
if (!data.get("CurrentMute", &mute)) {
LOGERR("RenderingControl:getMute: missing CurrentMute in response"
<< endl);
return false;
}
return mute;
}
----
There are utility methods in the base class for actions which either
transport no data, or send or receive a single value:
link:refdoc/html/classUPnPClient_1_1Service.html#a9ec23e2f36c2bbdefaac4991d80d6063[runTrivialAction()],
link:refdoc/html/classUPnPClient_1_1Service.html#a7cde71d714f07a6bb655760238e52e25[runSimpleAction()],
link:refdoc/html/classUPnPClient_1_1Service.html#a1de907ba9604a20aaf3611e71ded445d[runSimpleGet()]
=== Methods which may need reimplementation
----
virtual bool UPnPClient::Service::serviceTypeMatch(const std::string& tp)=0;
----
This is only needed for library version 0.16 and later. It is used by the
base class to find a matching service description in the device description
service list, which is done when calling
link:refdoc/html/classUPnPClient_1_1Service.html#afb13c0cc50b44c9c62e024961cf23b75[initFromDescription()].
The latter method is useful for building an object in two phases, first an
empty constructor, then initialization from the device description.
Derived classes compare the service types in the list with their own type
string.
----
virtual bool UPnPClient::Service::serviceInit(const UPnPDeviceDesc& device,
const UPnPServiceDesc& service);
----
This is the part of the initialization specific to the service type. When
it is called, the Service class is fully initialized. Most services
don't need to do anything in there. An example of use would be the
Rendering Control service calling the device to retrieve the range of
volume control values.
An empty implementation is provided by the base class.
The method is called from
link:refdoc/html/classUPnPClient_1_1Service.html#afb13c0cc50b44c9c62e024961cf23b75[initFromDescription()],
and, if it does anything, it should be called from the non-empty derived class
constructor too.
=== Eventing
Derived service classes can define a
link:refdoc/html/classUPnPClient_1_1Service.html#ac4ba122d2fe124eff620c62cbf5ac1a1[registerCallBack()]
method to register a function to be called when an event arrives.
'registerCallBack()' will be called by 'Service::installReporter()' when
the user register their interest in events. In turn, 'registerCallback()'
should call
link:refdoc/html/classUPnPClient_1_1Service.html#a8b8580b88b4fbfc1de18a14d7811169d[Service::registerCallBack(evtCBFunc)]
to register their actual callback routine.
Callback functions can be any 'std::function' taking appropriate arguments,
usually a member function of the service object.