NAME

UPnP::ControlPoint - A UPnP ControlPoint implementation.

SYNOPSIS

  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");
	}
  }

DESCRIPTION

Implements a UPnP ControlPoint. This module implements the various aspects of the UPnP architecture from the standpoint of a ControlPoint:

1. Discovery: A ControlPoint can be used to actively search for devices and services on a local network or listen for announcements as devices enter and leave the network. The protocol used for discovery is the Simple Service Discovery Protocol (SSDP).
2. Description: A ControlPoint can get information describing devices and services. Devices can be queried for services and vendor-specific information. Services can be queried for actions and state variables.
3. Control: A ControlPoint can invoke actions on services and poll for state variable values. Control-related calls are generally made using the Simple Object Access Protocol (SOAP).
4. Eventing: ControlPoints can listen for events describing state changes in devices and services. Subscription requests and state change events are generally sent using the General Event Notification Architecture (GENA).

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::ControlPoint

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

new ( [ARGS] )

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

sockets

Returns a list of sockets that need to be serviced for the ControlPoint 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.

handleOnce ( SOCKET )

Handles the function of reading from a ControlPoint socket when it is ready (as indicated by a select). 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. 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.

stopHandling

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

searchByType ( TYPE, CALLBACK )

Used to start a search for devices on the local network by device or service type. The 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");
	}
  }

searchByUDN ( UDN, CALLBACK )

Used to start a search for devices on the local network by Unique Device Name (UDN). Similar to 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.

searchByFriendlyName ( NAME, CALLBACK )

Used to start a search for devices on the local network by device friendy name. Similar to 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.

stopSearch ( SEARCH )

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

UPnP::ControlPoint::Device

A UPnP::ControlPoint::Device is generally obtained using one of the UPnP::ControlPoint search methods and should not be directly instantiated.

deviceType
friendlyName
manufacturer
manufacturerURL
modelDescription
modelName
modelNumber
modelURL
serialNumber
UDN
presentationURL
UPC: Properties received from the device's description document. The returned values are all strings.
location: A URI representing the location of the device on the network.
parent: The parent device of this device. The value undef if this device is a root device.
children: A list of child devices. The empty list if the device has no children.
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::ControlPoint::Service

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.

serviceType

serviceId

SCPDURL

controlURL

eventSubURL

Properties corresponding to the service received from the containing device's description document. The returned values are all strings except for the URL properties, which are absolute URIs.

actions

A list of UPnP::Common::Action objects corresponding to the actions implemented by this service.

getAction ( NAME )

Returns the UPnP::Common::Action object corresponding to the action specified by the NAME parameter. Returns undef if no such action exists.

stateVariables

A list of UPnP::Common::StateVariable objects corresponding to the state variables implemented by this service.

getStateVariable ( NAME )

Returns the UPnP::Common::StateVariable object corresponding to the state variable specified by the NAME parameter. Returns undef if no such state variable exists.

controlProxy

Returns a UPnP::ControlPoint::ControlProxy object that can be used to invoke actions on the service.

queryStateVariable ( NAME )

Generates a SOAP call to the remote service to query the value of the state variable specified by NAME. Returns the value of the variable. Returns undef if no such state variable exists or the variable is not evented.

subscribe ( CALLBACK )

Registers an event subscription with the remote service. The code reference specied by the 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");
	}
  }

unsubscribe ( SUBSCRIPTION )

Unsubscribe from a service. This method takes the "UPnP::ControlPoint::Subscription" object returned from a previous call to subscribe. This method is equivalent to calling the unsubscribe method on the subscription object itself and is included for symmetry and convenience.

UPnP::Common::Action

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.

name: The name of the action returned as a string.
retval: A 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.
arguments: A list of UPnP::Common::Argument objects corresponding to the arguments of the action.
inArguments: A list of UPnP::Common::Argument objects corresponding to the input arguments of the action.
outArguments: A list of UPnP::Common::Argument objects corresponding to the output arguments of the action.

UPnP::Common::Argument

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.

name: The name of the argument returned as a string.
relatedStateVariable: The name of the related state variable (which can be used to find the type of the argument) returned as a string.

UPnP::Common::StateVariable

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.

name: The name of the state variable returned as a string.
evented: Whether the state variable is evented or not.
type: The listed UPnP type of the state variable returned as a string.
SOAPType: The corresponding SOAP type of the state variable returned as a string.

UPnP::ControlPoint::ControlProxy

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.

UPnP::ControlPoint::ActionResult

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.

isSuccessful: Was the invocation successful or did it result in a fault.
getValue ( NAME ): Gets the value of an out argument of the action invocation. The 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.

UPnP::ControlPoint::Search

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.

UPnP::ControlPoint::Subscription

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.

SID: The subscription ID returned from the remote service, returned as a string.
timeout: The timeout value returned from the remote service, returned as a number.
expired: Has the subscription expired yet?
renew: Renews a subscription with the remote service by sending a GENA subscription event.
unsubscribe: Unsubscribes from the remote service by sending a GENA unsubscription event.

AUTHOR

Vidur Apparao (vidurapparao@users.sourceforge.net)

COPYRIGHT AND LICENSE

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.

To install UPnP::ControlPoint, copy and paste the appropriate command in to your terminal.

cpanm

cpanm UPnP::ControlPoint

CPAN shell

perl -MCPAN -e shell
install UPnP::ControlPoint

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)