greyupnp.ssdp — Tools for working with SSDP

This module contains various tools for using SSDP for service discovery. In most cases, the search() function will be the only feature that you will need to import. However, if you need more control over SSDP usage, then there are more basic tools described further down in the module.

High-level usage

search(target_types=None, timeout=12, tries=3)

Performs a search via SSDP to discover resources.

Parameters:

• target_types (sequence of strings) –

  A sequence of resource types to search for. For convenience, this can also be a single string. If provided, then this function will make individual requests searching for specific targets - this is sometimes required as some devices will not respond unless they are specifically requested by the search.

  If not given, then a search won’t be broadcast, but we will still listen for SSDP notification responses.

• timeout (int / float) – Overall time in seconds for how long to wait for before no longer listening for responses.
• tries (int) – How many times to send out a search request - this will be spread out over the timeout period.

Yields:

Discovery instances describing each result found - any duplicate results will be filtered out by this function.

class Discovery(headers)

This class describes a discovered resource, from either a SSDP search response or SSDP advertisement.

The headers from the response which describes the discovered resource are available as the ‘headers’ attribute.

You can also access any header (in a case insensitive manner) as an attribute on the object.

You can access the location of the resource via the “location” attribute.

headers

Case-insensitive dictionary of header name to header value pairs extracted from the response.

__init__(headers)

Create instance from SSDP response headers.

Parameters:headers – Dictionary containing header name to header value mappings.

type

The resource type, describing either a service or device.

parsed

An urlparsed object (returned by urlparse()) of the location of the discovery.

has_host(host)

Indicates if the discovered resource is on the described host - this is determined by looking at the location field.

Parameters:host – Either a hostname (e.g. “localhost”) or a host-port pair (e.g. “localhost:80”). Returns:true if this resource is on the provided host.

Mid-level usage

Here are some more details.

make_socket()

Creates a socket suitable for SSDP searches.

The socket will have a default timeout of 0.2 seconds (this works well for the :py:func:search function which interleaves sending requests and reading responses.

request_via_socket(sock, search_target)

Send an SSDP search request via the provided socket.

Parameters:

• sock – A socket suitable for use to send a broadcast message - preferably one created by make_socket().
• search_target (string) – A resource type target to search for.

responses_from_socket(sock, timeout=10)

Yield SSDP search responses and advertisements from the provided socket.

Parameters:

• sock – A socket suitable for use to send a broadcast message - preferably one created by make_socket().
• timeout (int / float) – Overall time in seconds for how long to wait for before no longer listening for responses.

Yields:

dict of string -> string – Case-insensitive dictionary of header name to header value pairs extracted from the response.

Low-level usage

And lastly….

MCAST_IP = '239.255.255.250'

The IP used to broadcast multicast packets to.

MCAST_PORT = 1900

The port used to broadcast multicast packets to.

MCAST_IP_PORT = '239.255.255.250:1900'

The IP+port used to broadcast multicast packets to.

encode_request(request_line, **headers)

Creates the data for a SSDP request.

Parameters:

• request_line (string) – The request line for the request (e.g. "M-SEARCH * HTTP/1.1").
• headers (dict of string -> string) – Dictionary of header name - header value pairs to present in the request.

Returns:

The encoded request.

Return type:

bytes

decode_response(data)

Decodes the data from a SSDP response.

Parameters:data (bytes) – The encoded response. Returns:Case-insensitive dictionary of header name to header value pairs extracted from the response. Return type:dict of string -> string

Glossary

resource type

resource types

A string identifier which describes a discovered resource, such as "uuid:device-UUID" or "urn:schemas-upnp-org:device:deviceType:ver". It will usually either refer to a UPnP service or device.