You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
151 lines
6.5 KiB
151 lines
6.5 KiB
# Copyright (c) 2012-2016, Ferry Boender <ferry.boender@gmail.com>
|
|
#
|
|
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
# of this software and associated documentation files (the "Software"), to deal
|
|
# in the Software without restriction, including without limitation the rights
|
|
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
# copies of the Software, and to permit persons to whom the Software is
|
|
# furnished to do so, subject to the following conditions:
|
|
#
|
|
# The above copyright notice and this permission notice shall be included in
|
|
# all copies or substantial portions of the Software.
|
|
#
|
|
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
# SOFTWARE.
|
|
|
|
# Todo:
|
|
# - Allow persistance of discovered servers.
|
|
# - The control point should wait at least the amount of time specified in the
|
|
# MX header for responses to arrive from devices.
|
|
# - Date/datetime
|
|
# - Store all properties
|
|
# - SSDP.discover(st): Allow to discover only certain service types
|
|
# - .find() method on most classes.
|
|
# - async discover (if possible).
|
|
# - Read parameter types and verify them when doing a call.
|
|
# - Marshall return values to the correct databases.
|
|
# - Handle SOAP error:
|
|
# <?xml version="1.0"?>
|
|
# <s:Envelope
|
|
# xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
|
|
# s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
|
|
# <s:Body>
|
|
# <s:Fault>
|
|
# <faultcode>s:Client</faultcode>
|
|
# <faultstring>UPnPError</faultstring>
|
|
# <detail>
|
|
# <UPnPError xmlns="urn:schemas-upnp-org:control-1-0">
|
|
# <errorCode xmlns="">714</errorCode>
|
|
# <errorDescription xmlns="">No such entry in array</errorDescription>
|
|
# </UPnPError>
|
|
# </detail>
|
|
# </s:Fault>
|
|
# </s:Body>
|
|
# </s:Envelope>
|
|
# - Test params and responses with XML entities in them "<", "&", etc.
|
|
# - AllowedValueRange
|
|
# <allowedValueRange>
|
|
# <minimum>minimum value</minimum>
|
|
# <maximum>maximum value</maximum>
|
|
# <step>increment value</step>
|
|
# </allowedValueRange>
|
|
# - Name params as 'NewFoo', or not (See spec)?
|
|
|
|
"""
|
|
This module provides an UPnP Control Point (client), and provides an easy
|
|
interface to discover and communicate with UPnP servers. It implements SSDP
|
|
(Simple Service Discovery Protocol), SCPD (Simple Control Point Definition) and
|
|
a minimal SOAP (Simple Object Access Protocol) implementation.
|
|
|
|
The usual flow for working with UPnP servers is:
|
|
|
|
- Discover UPnP servers using SSDP.
|
|
|
|
SSDP is a simple HTTP-over-UDP protocol. An M-SEARCH HTTP request is broad-
|
|
casted over the network and any UPnP servers should respond with an HTTP
|
|
response. This response includes an URL to an XML file containing information
|
|
about the server. The SSDP.discover() method returns a list of Server
|
|
instances. If you already know the URL of the XML file, you can skip this
|
|
step and instantiate a Server instance directly.
|
|
|
|
- Inspect Server capabilities using SCPD.
|
|
|
|
The XML file returned by UPnP servers during discovery is read and information
|
|
about the server and the services it offers is stored in a Server instance. The
|
|
Server.services property contains a list of Service instances supported by that
|
|
server.
|
|
|
|
- Inspect Services capabilities using SCPD.
|
|
|
|
Each Server may contain more than one Services. For each Service, a separate
|
|
XML file exists. The Service class reads that XML file and determines which
|
|
actions a service supports. The Service.actions property contains a list of
|
|
Action instances supported by that service.
|
|
|
|
- Inspect an Action using SCPD.
|
|
|
|
An Action instance may be inspected to determine which arguments need to be
|
|
passed into it and what it returns. Information on the type and possible
|
|
values of each argument can also be queried.
|
|
|
|
- Call an Action using SOAP.
|
|
|
|
An Action instance may then be called using the Action.call(arguments) method.
|
|
The Action class will verify the correctness of arguments, possibly
|
|
converting them. A SOAP call is then made to the UPnP server and the results
|
|
are returned.
|
|
|
|
Classes:
|
|
|
|
* SSDP: Discover UPnP servers using the SSDP class.
|
|
* Server: Connect to an UPnP server and retrieve information/capabilities using the Server class.
|
|
* Service: Query a Server class instance for the various services it supports.
|
|
* Action: Query a Service class instance for the various actions it supports and call them.
|
|
|
|
Various convenience methods are provided at almost all levels. For instance,
|
|
the find_action() methods can directly find a method (by name) in an UPnP
|
|
server/service. The call() method can be used at most levels to directly call
|
|
an action.
|
|
|
|
The following example discovers all UPnP servers on the local network and then
|
|
dumps all their services and actions:
|
|
|
|
------------------------------------------------------------------------------
|
|
import upnpclient
|
|
|
|
ssdp = upnpclient.SSDP()
|
|
servers = ssdp.discover()
|
|
|
|
for server in servers:
|
|
print "%s: %s" % (server.friendly_name, server.model_description)
|
|
for service in server.services:
|
|
print " %s" % (service.service_type)
|
|
for action in service.actions:
|
|
print " %s" % (action.name)
|
|
for arg_name, arg_def in action.argsdef_in:
|
|
valid = ', '.join(arg_def['allowed_values']) or '*'
|
|
print " in: %s (%s): %s" % (arg_name, arg_def['datatype'], valid)
|
|
for arg_name, arg_def in action.argsdef_out:
|
|
valid = ', '.join(arg_def['allowed_values']) or '*'
|
|
print " out: %s (%s): %s" % (arg_name, arg_def['datatype'], valid)
|
|
------------------------------------------------------------------------------
|
|
|
|
Useful Links:
|
|
|
|
* https://embeddedinn.wordpress.com/tutorials/upnp-device-architecture/
|
|
* http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf
|
|
"""
|
|
from upnpclient import const, errors, marshal, soap, ssdp, upnp, util # noqa: F401
|
|
from .upnp import (
|
|
Device, Action, Service, UPNPError, InvalidActionException, ValidationError, UnexpectedResponse)
|
|
from .ssdp import discover
|
|
|
|
__all__ = [
|
|
"Device", "Action", "Service", "UPNPError", "InvalidActionException", "ValidationError",
|
|
"discover", "UnexpectedResponse"
|
|
]
|