/ 
UPnP-ControlPoint-0.5
/ UPnP::DeviceManager

NAME

UPnP::DeviceManager - A UPnP Device host implementation.

SYNOPSIS

  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;

DESCRIPTION

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:

  • Discovery

    Devices registered with the DeviceManager will automatically advertise themselves and respond to UPnP searches.

  • Description

    Devices register themselves with description documents. These descriptions are served via HTTP to interested ControlPoints.

  • Control

    Devices respond to action invocations and state queries from ControlPoints.

  • Eventing

    Changes to device state result in events sent to interested subscribers.

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).

METHODS

UPnP::DeviceManager

A Device implementor will generally create a single instance of the UPnP::DeviceManager class and register one or more devices with it.

new ( [ARGS] )

Creates a 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.

registerDevice ( [ARGS] )

Registers a device with the DeviceManager. This call takes the following optional key-value pairs as arguments (default values are listed below):

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.

devices

Returns a list of registered devices.

sockets

Returns a list of sockets that need to be serviced for the DeviceManager to correctly function. This method is generally used in conjunction with the 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.

handleOnce ( SOCKET )

Handles the function of reading from a DeviceManager socket when it is ready (as indicated by a select). This method is used by developers who want to run their own select loop.

heartbeat

Sends any pending notifications and returns a timeout value after which this method should be invoked again. This method is used by developers who want to run their own select loop.

handle

Takes over handling of all ControlPoint sockets. Runs its own 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.

stopHandling

Ends the select loop run by handle. This method is generally invoked from a Device callback or a signal handler.

UPnP::DeviceManager::Device

A UPnP::DeviceManager::Device object is obtained by registering a device with a DeviceManager. This class should not be directly instantiated.

start

Called to start a device. Sends out the SSDP initial announcement of the device's presence and allows the device to respond to SSDP queries.

stop

Called to stop a device. Sends out an SSDP byebye announcement.

Called to manually send out an SSDP announcement for the device, its child devices, and its services. Can be called if SSDP announcements should be sent out more frequently than the device's lease time. Otherwise, announcements are sent automatically when the device's lease runs out.

leastTime

The lease length of the device.

services

A list of UPnP::ControlPoint::Service objects corresponding to the services implemented by this device.

getService ( ID )

If the device implements a service whose serviceType or serviceId is equal to the ID parameter, the corresponding UPnP::ControlPoint::Service object is returned. Otherwise returns undef.

UPnP::DeviceManager::Service

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.

dispatchTo ( MODULE )

Used to specify the name of a module which implements all control actions for this service. When an action invocation comes in, the corresponding function in the module will be invoked. The parameters to the function are the module name (Ed: should get rid of this SOAP::Lite vestige) and the parameters passed in the SOAP invocation. The function should return a list of all out parameters to be sent to the invoker. For example, a hypothetical UPnP thermometer might implement a GetTemperature action:

  $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.

setValue ( [NAME => VALUE]+ )

Used to set the values of state variables for the service. The parameters to this call should be name-value pairs for one or more evented state variables for the service. Results in GENA notifications to any subscribers to this service.

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.

onAction ( CALLBACK )

Can be used to specify a callback function for dealing with action invocations. The 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;
  }
onQuery ( CALLBACK )

Can be used to specify a callback function for dealing with state queries. The 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;
  }

SEE ALSO

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?url=/library/en-us/upnp/upnp/universal_plug_and_play_start_page.asp).

AUTHOR

Vidur Apparao (vidurapparao@users.sourceforge.net)

COPYRIGHT AND LICENSE

Copyright (C) 2004-2005 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.