Crate cotton_ssdp

Implementing SSDP, the Simple Service Discovery Protocol

The cotton-ssdp crate encapsulates a client and server for the Simple Service Discovery Protocol (SSDP), a mechanism for discovering available resources (services) on local networks. A resource might be a streaming-media server, or a router, or a network printer, or anything else that someone might want to search for or enumerate on a network.

What is advertised, or discovered, is, for each resource, a unique identifier for that particular resource (Unique Service Name, USN), an identifier for the type of resource (Notification Type, NT), and the location of the resource in the form of a URL.

SSDP is mainly used by UPnP (Universal Plug-‘n’-Play) systems, such as for media libraries and local streaming of music and video – but the mechanism is quite generic, and could as easily be used for any type of device or resource that must be discoverable over a network, including in ad hoc settings which don’t necessarily have expert network administrators close at hand.

There is no Internet RFC as such for SSDP – merely some expired drafts. The protocol is, instead, documented in the UPnP Device Architecture documents.

This crate provides two different high-level interfaces for working with SSDP, Service and AsyncService. Either one can be used both to discover other devices (Service::subscribe) and to advertise resources itself (Service::advertise).

Client code using the MIO crate should use plain Service; client code using the Tokio crate might wish to use AsyncService instead, which integrates with that system. Client code with a custom polling loop – neither MIO nor Tokio – should instead probably aim to build an equivalent to Service using the lower-level facilities in engine::Engine.

Example code is available both for asynchronous Tokio use: ssdp-search (on Github) and reactor-style MIO use: ssdp-search-mio (on Github).

Todo:

• Make mio/tokio features
• Make advertise/subscribe features
• Cow<'static> for input strings?
• Hasher instead of thread_rng; hash over network interfaces sb unique
• Vary phase 1,2,3 timings but keep phase 0 timings on round numbers (needs absolute wall time)
• Monotonic time instead of Instant::now (lifetime?) Solved differently
• smoltcp/no_std, see https://github.com/rust-lang/rust/pull/104265
• IPv6, see UPnP DA appendix A

Re-exports

pub use event::Advertisement;

pub use event::Notification;

Modules

engine

Low-level SSDP API used inside Service and AsyncService

event

Inbound and outbound SSDP events, high-level

refresh_timer

Common code for triggering refreshes of Service and AsyncService

udp

Traits used to abstract over various UDP socket implementations

Structs

AsyncServiceasync

High-level asynchronous SSDP service using tokio.

Servicesync

High-level reactor-style SSDP service using mio.