2 UPnP Devices and Services

9.2

Racket

2 UPnP Devices and Services🔗ℹ

(require racket-upnp)

package: base

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

2.1 Discovering devices🔗ℹ

procedure
(query-upnp-devices [ kinds
#:interface interface
#:dns? dns?])
→ (listof upnp-device?)
  kinds : (or/c 'all symbol? (listof symbol?)) = 'all
  interface : (or/c #f string?) = #f
  dns? : boolean? = #f

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. Reverse DNS lookup is only attempted when dns? is true.

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	Media Renderers
4	Media Servers
5	Publishing Media Files
6	AVTransport
7	Rendering Control
8	Connection Manager
9	Content Directory
	Index

2.1	Discovering devices
2.2	Device values
2.3	Generic services
2.4	Example