UPnP::ControlPoint - A UPnP ControlPoint implementation.
use UPnP::ControlPoint;
my $cp = UPnP::ControlPoint->new;
my $search = $cp->searchByType("urn:schemas-upnp-org:device:TestDevice:1",
\&callback);
$cp->handle;
sub callback {
my ($search, $device, $action) = @_;
if ($action eq 'deviceAdded') {
print("Device: " . $device->friendlyName . " added. Device contains:\n");
for my $service ($device->services) {
print("\tService: " . $service->serviceType . "\n");
}
}
elsif ($action eq 'deviceRemoved') {
print("Device: " . $device->friendlyName . " removed\n");
}
}
Implements a UPnP ControlPoint. This module implements the various aspects of the UPnP architecture from the standpoint of a ControlPoint:
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 ControlPoint implementor will generally create a single instance of
the UPnP::ControlPoint class (though more than one can exist within
a process assuming that they have been set up to avoid port
conflicts).
UPnP::ControlPoint object. Accepts the following
key-value pairs as optional arguments (default values are listed
below):
SearchPort Port on which search requests are received 8008
SubscriptionPort Port on which event notification are received 8058
SubscriptionURL URL on which event notification are received /eventSub
MaxWait Max wait before search responses should be sent 3
While this call creates the sockets necessary for the ControlPoint to
function, the ControlPoint is not active until its sockets are
actually serviced, either by invoking the handle
method or by externally selecting using the ControlPoint's
sockets and invoking the
handleOnce method as each becomes ready for
reading.
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.
select). This method is used by developers
who want to run their own select loop.
select loop, handling individual sockets as they become available
for reading. Returns only when a call to
stopHandling is made (generally from a
ControlPoint callback or a signal handler). This method is an
alternative to using the sockets and
handleOnce methods.
select loop run by handle. This method is generally
invoked from a ControlPoint callback or a signal handler.
TYPE parameter is a string inidicating a device
or service type. Specifically, it is the string that will be put into
the ST header of the SSDP M-SEARCH request that is sent out. The
CALLBACK parameter is a code reference to a callback that is
invoked when a device matching the search criterion is found (or a
SSDP announcement is received that such a device is entering or
leaving the network). This method returns a
UPnP::ControlPoint::Search object.
The arguments to the CALLBACK are the search object, the device
that has been found or newly added to or removed from the network, and
an action string which is one of 'deviceAdded' or 'deviceRemoved'. The
callback is invoked separately for each device that matches the search
criterion.
sub callback {
my ($search, $device, $action) = @_;
if ($action eq 'deviceAdded') {
print("Device: " . $device->friendlyName . " added.\n");
}
elsif ($action eq 'deviceRemoved') {
print("Device: " . $device->friendlyName . " removed\n");
}
}
searchByType, this method sends
out a SSDP M-SEARCH request with a ST header of
upnp:rootdevice. All responses to the search (and subsequent SSDP
announcements to the network) are filtered by the UDN parameter
before resulting in CALLBACK invocation. The parameters to the
callback are the same as described in searchByType.
searchByType, this method sends out a
SSDP M-SEARCH request with a ST header of
upnp:rootdevice. All responses to the search (and subsequent SSDP
announcements to the network) are filtered by the NAME parameter
before resulting in CALLBACK invocation. The parameters to the
callback are the same as described in searchByType.
SEARCH parameter is a
UPnP::ControlPoint::Search object
returned by one of the search methods. This method stops forwarding
SSDP events that match the search criteria of the specified search.
A UPnP::ControlPoint::Device is generally obtained using one of the
UPnP::ControlPoint search methods and should
not be directly instantiated.
undef if this device
is a root device.
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::ControlPoint::Service is generally obtained from a
UPnP::ControlPoint::Device object
using the services or getServiceById methods. This class should
not be directly instantiated.
UPnP::Common::Action
objects corresponding to the actions implemented by this service.
UPnP::Common::Action object
corresponding to the action specified by the NAME parameter.
Returns undef if no such action exists.
UPnP::Common::StateVariable
objects corresponding to the state variables implemented by this
service.
UPnP::Common::StateVariable
object corresponding to the state variable specified by the NAME
parameter. Returns undef if no such state variable exists.
UPnP::ControlPoint::ControlProxy
object that can be used to invoke actions on the service.
NAME. Returns the value of the
variable. Returns undef if no such state variable exists or the
variable is not evented.
CALLBACK parameter is invoked when GENA
events are received from the service. This call returns a
UPnP::ControlPoint::Subscription
object corresponding to the subscription. The subscription can later
be canceled using the unsubscribe method. The parameters to the
callback are the service object and a list of name-value pairs for all
of the state variables whose values are included in the corresponding
GENA event:
sub eventCallback {
my ($service, %properties) = @_;
print("Event received for service " . $service->serviceId . "\n");
while (my ($key, $val) = each %properties) {
print("\tProperty ${key}'s value is " . $val . "\n");
}
}
subscribe. This method
is equivalent to calling the unsubscribe method on the subscription
object itself and is included for symmetry and convenience.
A UPnP::Common::Action is generally obtained from a
UPnP::ControlPoint::Service object
using its actions or getAction methods. It corresponds to an
action implemented by the service. Action information is retrieved
from the service's description document. This class should not be
directly instantiated.
UPnP::Common::Argument object that
corresponds to the action argument that is specified in the service
description document as the return value for this action. Returns
undef if there is no specified return value.
UPnP::Common::Argument objects
corresponding to the arguments of the action.
UPnP::Common::Argument objects
corresponding to the input arguments of the action.
UPnP::Common::Argument objects
corresponding to the output arguments of the action.
A UPnP::Common::Argument is generally obtained from a
UPnP::Common::Action object using its
arguments, inArguments or outArguments methods. An instance
of this class corresponds to an argument of a service action, as
specified in the service's description document. This class should not
be directly instantiated.
A UPnP::Common::StateVariable is generally obtained from a
UPnP::ControlPoint::Service object
using its stateVariables or getStateVariable methods. It
corresponds to a state variable implemented by the service. State
variable information is retrieved from the service's description
document. This class should not be directly instantiated.
A proxy that can be used to invoke actions on a UPnP service. An
instance of this class is generally obtained from the controlProxy
method of the corresponding
UPnP::ControlPoint::Service
object. This class should not be directly instantiated.
An instance of this class is a wrapper on a SOAP::Lite proxy. An
action is invoked as if it were a method of the proxy
object. Parameters to the action should be passed to the method. They
will automatically be coerced to the correct type. For example, to
invoke the Browse method on a UPnP ContentDirectory service to get
the children of the root directory, one would say:
my $proxy = $service->controlProxy;
my $result = $proxy->Browse('0', 'BrowseDirectChildren', '*', 0, 0, "");
The result of a action invocation is an instance of the
UPnP::ControlPoint::ActionResult
class.
An instance of this class is returned from an action invocation made
through a
UPnP::ControlPoint::ControlProxy
object. It is a loose wrapper on the SOAP::SOM object returned from
the call made through the SOAP::Lite module. All methods not
recognized by this class will be forwarded directly to the
SOAP::SOM class. This class should not be directly instantiated.
NAME parameter specifies which out argument value should be
returned. The type of the returned value depends on the type
specified in the service description file.
A UPnP::ControlPoint::Search object is returned from any successful
calls to the UPnP::ControlPoint search
methods. It has no methods of its own, but can be used as a token to
pass to any subsequent stopSearch calls. This class should not be
directly instantiated.
A UPnP::ControlPoint::Search object is returned from any successful
calls to the
UPnP::ControlPoint::Service
subscribe method. This class should not be directly instantiated.
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 ControlPoint 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.