4 Home
crate-kit edited this page 2026-11-14 04:21:21 +00:00

pmossdp

pmossdp — SSDP (Simple Service Discovery Protocol)

Découverte des appareils UPnP sur le réseau local : annonces NOTIFY, recherches M-SEARCH et leurs réponses. La crate est volontairement légère (sockets bloquants, threads standard, aucune dépendance à un runtime asynchrone) pour pouvoir tourner aussi sur un agent embarqué.

Elle ne couvre que IPv4 et que SSDP : la description XML de l'appareil (LOCATION) et les services UPnP sont à la charge de l'appelant.

Deux rôles

Rôle Types Ce qu'il fait
Appareil (device) SsdpServer, SsdpDevice annonce des appareils (alive à l'enregistrement puis renouvelé à intervalle aléatoire, byebye au retrait), répond aux M-SEARCH
Point de contrôle SsdpClient, SsdpEvent envoie des M-SEARCH, reçoit les réponses et les annonces alive / byebye

Les deux rôles peuvent coexister dans un même processus (PMOMusic le fait) : le serveur et l'écoute des annonces du client se partagent le port 1900 (multicast), tandis que les recherches du client passent par un port éphémère (voir SsdpClient).

Exemple : annoncer un appareil

use pmossdp::{SsdpDevice, SsdpServer};

# fn main() -> std::io::Result<()> {
let mut ssdp = SsdpServer::new();
ssdp.start()?;

let device = SsdpDevice::new(
    "0f3c9a52-7b1e-4c43-9d57-2a1b6e0c8f10".into(),
    "urn:schemas-upnp-org:device:MediaRenderer:1".into(),
    "http://192.168.1.10:8080/desc.xml".into(),
    "Linux UPnP/1.1 MonApp/1.0".into(),
);
ssdp.add_device(device); // `alive` envoyé tout de suite ; `byebye` au retrait ou à la destruction
# Ok(())
# }

Exemple : chercher des appareils

use pmossdp::{SsdpClient, SsdpEvent};

# fn main() -> std::io::Result<()> {
let client = SsdpClient::new()?;
client.send_msearch("upnp:rootdevice", 3)?;
// Boucle bloquante, qui rend la main après `client.stop()` : la lancer dans un thread dédié.
client.run_event_loop(|event| {
    if let SsdpEvent::SearchResponse { location, .. } = event {
        println!("appareil trouvé : {location}");
    }
});
# Ok(())
# }

Interfaces réseau et mode hors ligne

Serveur : toutes les interfaces. Le serveur rejoint le groupe multicast sur chaque interface IPv4 active hors boucle locale, et envoie ses NOTIFY (annonces et byebye) sur chacune, avec une LOCATION dont l'hôte est l'adresse de la machine sur ce réseau (SsdpDevice::location_for). La réponse à un M-SEARCH porte l'adresse que la machine emploie pour joindre le demandeur (pmoutils::ip_utils::local_ip_towards), qui est aussi l'interface par laquelle la réponse repart. Cela vaut pour une LOCATION dont l'hôte est une adresse IPv4 hors boucle locale ; un nom d'hôte, ou une adresse imposée par SsdpDevice::with_fixed_location, reste tel quel. Les groupes sont rejoints sur les interfaces présentes au démarrage ; la liste des interfaces d'émission est relue à chaque envoi.

Client : une seule interface. L'écoute des annonces rejoint le groupe sur chaque interface, mais les M-SEARCH du client sortent par l'interface de l'adresse locale que donne pmoutils::guess_local_ip. Les interfaces d'écoute sont figées à la création du client.

Si l'adresse locale est introuvable (aucune route, machine hors ligne), l'interface multicast par défaut du système est utilisée et un avertissement tracing::warn! le signale : ni le serveur ni le client ne s'arrêtent.

UPnP 1.0 et 1.1

Par défaut, un appareil se présente comme en UPnP 1.0. SsdpDevice::with_config_id le déclare 1.1 : ses annonces, réponses et byebye portent alors BOOTID.UPNP.ORG et CONFIGID.UPNP.ORG. Le message ssdp:update n'est pas encore pris en compte par le client.

Arrêt

SsdpServer envoie les byebye et arrête ses threads à sa destruction. SsdpClient::stop fait rendre la main à SsdpClient::run_event_loop (l'arrêt est définitif pour ce client et ses copies).

Constantes SSDP

  • adresse multicast SSDP_MULTICAST_ADDR (239.255.255.250), port SSDP_PORT (1900) ;
  • validité des annonces MAX_AGE : 1800 secondes (30 minutes) ;
  • période des annonces du serveur : aléatoire, entre MAX_AGE / 4 et MAX_AGE / 2 (exclu), soit de 7 min 30 s à 15 min.

Journalisation

Via tracing : info! pour les annonces et enregistrements, warn! pour les échecs non fatals (interface refusée, écoute impossible, erreur de lecture), debug! pour le contenu des messages, trace! pour les messages reçus ignorés ou illisibles.

Modules

pmossdp

3 constants

client

1 enum, 1 struct

client::SsdpClient

3 functions

device

1 struct

device::SsdpDevice

6 functions

server

1 struct

server::SsdpServer

3 functions