UPnP::DeviceManager - A UPnP Device host implementation.
use UPnP;
my $dm = UPnP::DeviceManager->new;
my $device = $dm->registerDevice(DescriptionFile => 'description.xml',
ResourceDirectory => '.');
my $service = $device->getService('urn:schemas-upnp-org:service:TestService:1');
$service->dispatchTo('MyPackage::MyClass');
$service->setValue('TestVariable', 'foo');
$dm->handle;
Implements a UPnP Device host. This module implements the various aspects of the UPnP architecture from the standpoint of a host of one or more devices:
Since the UPnP architecture leverages several existing protocols such
as TCP, UDP, HTTP and SOAP, this module requires several Perl modules
that implement these protocols. These include
IO::Socket::INET,
LWP::UserAgent, HTTP::Daemon and
SOAP::Lite (http://www.soaplite.com).
A Device implementor will generally create a single instance of
the UPnP::DeviceManager class and register one or more devices
with it.
UPnP::DeviceManager object. Accepts the following
key-value pairs as optional arguments (default values are listed
below):
NotificationPort Port from which SSDP notifications are made 4003
A DeviceManager only becomes functional after devices are registered
with it using the registerDevice method and the sockets it creates
are serviced. Socket management can be done in one of two ways: by
invoking the handle method; or by externally selecting the
DeviceManage's sockets, invoking the handleOnce method as each
becomes ready for reading, and invoking the heartbeat method on a
time to send out any pending device notifications.
DevicePort Port on which the device serves requests 4004
DescriptionURI The relative URI for the description document /description.xml
LeaseTime The length of the device's lease 1800
The call also takes the following required arguments:
Description A string containing the XML device description
DescriptionFile The path to a file containing the XML device description
ResourceDirectory The path to a directory containing resources referred
to in the device description
Only one of the Description or DescriptionFile arguments should be specified.
If successful, returns a
UPnP::DeviceManager::Device object.
The device itself does not advertise itself till its start method
is invoked.
handleOnce method by users who want to run
their own select loop. This list of sockets should be selected for
reading and handleOnce is invoked for each socket as it beoms ready
for reading. This method should only be called after all devices
have been registered.
select). This method is used by developers
who want to run their own select loop.
select loop.
select loop, handling individual sockets as they become available
for reading and invoking the heartbeat call at the required
interval. Returns only when a call to stopHandling is made
(generally from a Device callback or a signal handler). This
method is an alternative to using the sockets, handleOnce
and heartbeat methods.
select loop run by handle. This method is generally
invoked from a Device callback or a signal handler.
A UPnP::DeviceManager::Device object is obtained by registering a
device with a DeviceManager. This class should not be directly
instantiated.
UPnP::ControlPoint::Service
objects corresponding to the services implemented by this device.
ID parameter, the corresponding
UPnP::ControlPoint::Service object
is returned. Otherwise returns undef.
A UPnP::DeviceManager::Service is generally obtained from a
UPnP::DeviceManager::Device object
using the services or getServiceById methods. This class should
not be directly instantiated.
$service->dispatchTo('Thermometer');
...
package Thermometer;
sub GetTemperature {
my $class = shift;
my $scale = shift;
Code to look up temperature and return in the given scale...
return $temp;
}
A mutually exclusive alternative to directly dispatching to a module
is to use the onAction callback method.
The value of the state variable is remembered by the service
instance. Device implementors who do not need to dynamically look up
their state variables using the onQuery callback below can set the
values of state variables before starting a device. All state queries
will then be automatically dealt with.
CALLBACK parameter must be a CODE ref. This is a
mutually exclusive alternative to directly dispatching actions to a
Perl module. The callback is invoked anytime the DeviceManager
receives a control SOAP call. Parameters to the callback are the
service object, the action name and the parameters sent over SOAP. The
equivalent to the hypothetical thermometer implementation described
above is:
$service->onAction(\&actionSub);
...
sub actionSub {
my $service = shift;
my $action = shift;
if ($action eq 'GetTemperature') {
my $scale = shift;
Code to look up temperature and return in the given scale...
return $temp;
}
return undef;
}
CALLBACK parameter must be a CODE ref. This is an
alternative to setting the values of state variables up-front and
allows state to be looked up dynamically. The callback will be invoked
once per state variable query. For event subscriptions, the callback
will be invoked for each of the evented state variables. Paramters to
the callback are the service, the name of the state variable and the
last known value of the variable (returned from a previous call to the
onQuery callback or set using the setValue method).
$service->onAction(\&querySub);
sub onquery {
my ($service, $name, $val) = @_;
Code to look up value of state variable...
return $newval;
}
UPnP documentation and resources can be found at http://www.upnp.org.
The SOAP::Lite module can be found at http://www.soaplite.com.
UPnP Device management implementations in other languages include the UPnP SDK for Linux (http://upnp.sourceforge.net/), Cyberlink for Java (http://www.cybergarage.org/net/upnp/java/index.html) and C++ (http://sourceforge.net/projects/clinkcc/), and the Microsoft UPnP SDK (http://msdn.microsoft.com/library/default.asp).
Vidur Apparao (vidurapparao@users.sourceforge.net)
Copyright (C) 2004 by Vidur Apparao
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8 or, at your option, any later version of Perl 5 you may have available.