2 UPnP Devices and Services

9.2.900

Racket

2 UPnP Devices and Services🔗ℹ

The main module provides general UPnP device discovery and a generic service interface.

2.1 Discovering devices🔗ℹ

procedure
(upnp-default-ipv4-address) → string?

Returns a non-loopback local IPv4 address selected by the operating system for normal outbound IPv4 traffic. No datagram is sent. The selected address is normally also the interface through which SSDP multicast should be sent. Loopback and wildcard addresses are rejected.

procedure
(query-upnp-devices [ kinds
#:interface interface
#:dns? dns?
#:mx mx
#:timeout timeout
#:repeat repeat])
→ (listof upnp-device?)
  kinds : (or/c 'all symbol? (listof symbol?)) = 'all
  interface : (or/c #f string?) = #f
  dns? : boolean? = #f
  mx : (integer-in 1 5) = 3
  timeout : (or/c #f positive-real?) = #f
  repeat : exact-positive-integer? = 3

Discovers and describes matching UPnP devices.

'all returns all described devices. A symbol such as 'media-renderer selects one known kind, and a list selects several kinds. When interface is a local IPv4 address, SSDP multicast is sent through that interface. When it is #f, upnp-default-ipv4-address is used automatically. If automatic detection fails, discovery falls back to the interface selected by the operating system. Reverse DNS lookup is only attempted when dns? is true.

mx is the SSDP response delay advertised in the M-SEARCH request. The default receive window is mx plus one second. An explicit timeout overrides that receive window and must be at least mx. repeat controls how many M-SEARCH requests are sent; the requests are spaced 250 milliseconds apart.

procedure
(upnp-device-kinds) → (listof (cons/c symbol? string?))

Returns the friendly device kinds understood by query-upnp-devices, together with short descriptions. Devices with an unrecognised device type are classified as 'unknown and retain their original UPnP type.

2.2 Device values🔗ℹ

procedure
(upnp-device? value) → boolean?
value : any/c

Recognises a described UPnP device.

procedure
(upnp-device-kind device) → symbol?
device : upnp-device?

Returns a friendly kind such as 'media-renderer, 'scanner, or 'unknown.

procedure
(upnp-device-name device) → string?
device : upnp-device?

Returns the friendly name, with model name and address as fallbacks.

procedure
(upnp-device-udn device) → (or/c #f string?)
device : upnp-device?

Returns the Unique Device Name from the device description.

procedure
(upnp-device-address device) → string?
device : upnp-device?

Returns the address from which the SSDP response was received.

procedure
(upnp-device-dns-name device) → (or/c #f string?)
device : upnp-device?

Returns the optional reverse-DNS name.

procedure
(upnp-device-manufacturer device) → (or/c #f string?)
device : upnp-device?

Returns the advertised manufacturer.

procedure
(upnp-device-model device) → (or/c #f string?)
device : upnp-device?

Returns a combined model name and model number.

procedure
(upnp-device-type device) → (or/c #f string?)
device : upnp-device?

Returns the original device-type URN.

procedure
(upnp-device-services device) → (listof upnp-service?)
device : upnp-device?

Returns the services belonging directly to the device.

2.3 Generic services🔗ℹ

procedure
(upnp-service? value) → boolean?
value : any/c

Recognises a UPnP service.

procedure
(upnp-service-kind service) → symbol?
service : upnp-service?

Returns a friendly service kind or 'unknown.

procedure
(upnp-service-type service) → (or/c #f string?)
service : upnp-service?

Returns the original service-type URN.

procedure
(upnp-service-id service) → (or/c #f string?)
service : upnp-service?

Returns the advertised service identifier.

procedure
(upnp-service-kinds) → (listof (cons/c symbol? string?))

Returns the known friendly service kinds and descriptions.

procedure
(upnp-device-service device kind) → (or/c #f upnp-service?)
device : upnp-device?
kind : symbol?

Returns the highest advertised version of the requested service kind belonging to device, or #f when the service is absent.

procedure
(upnp-service-actions service) → (listof string?)
service : upnp-service?

Downloads the service’s SCPD document and returns its advertised action names. The result is cached for the service value.

procedure
(upnp-service-supports-action? service
action) → boolean?
service : upnp-service?
action : (or/c string? symbol?)

Reports whether the SCPD advertises action.

procedure
(upnp-service-call service action [arguments]) → hash?
  service : upnp-service?
  action : (or/c string? symbol?)
  arguments : list? = '()

Invokes a SOAP action. arguments is an association list containing UPnP argument names and values. The immutable result hash uses the exact output argument names as string keys. This function is intended for vendor-specific services and standard services for which no typed module has been written.

A failed SOAP request raises exn:fail:upnp?.

procedure
(exn:fail:upnp? value) → boolean?
value : any/c

Recognises a UPnP SOAP error.

procedure
(exn:fail:upnp-code error) → (or/c #f exact-integer?)
error : exn:fail:upnp?

Returns the numeric UPnP error code, when supplied by the device.

procedure
(exn:fail:upnp-description error) → (or/c #f string?)
error : exn:fail:upnp?

Returns the UPnP error description, when supplied by the device.

2.4 Example🔗ℹ

(define renderers
  (query-upnp-devices 'media-renderer
                      #:interface "10.7.3.118"
                      #:dns? #t))

(for ([device (in-list renderers)])
  (printf "~a (~a)\n"
          (upnp-device-name device)
          (upnp-device-address device)))

1	Introduction
2	UPn P Devices and Services
3	DIDL-Lite Metadata
4	Media Renderers
5	Media Servers
6	Publishing Media Files
7	AVTransport
8	Rendering Control
9	Connection Manager
10	Content Directory
	Index

2.1	Discovering devices
2.2	Device values
2.3	Generic services
2.4	Example