~liz/yooper

4467fc5855e96e9b29837d8a343ee23fd9b40d38 — Ellie Frost 2 years ago 866a62e
Add a bunch of documentation
4 files changed, 35 insertions(+), 1 deletions(-)

M yooper/src/description.rs
M yooper/src/discovery.rs
M yooper/src/lib.rs
M yooper/src/ssdp/mod.rs
M yooper/src/description.rs => yooper/src/description.rs +29 -0
@@ 1,3 1,6 @@
//! Description is the second step of UPnP, after [Discovery](../Discovery).
//! Using the location retrieved from discovery, retrieve an XML document over HTTP.
//! This document enumerates the capabilities of the given device.
#[cfg(test)]
mod tests;



@@ 8,6 11,7 @@ use std::str::FromStr;

#[derive(PartialEq, Debug)]
pub struct DeviceType {
    /// Will be None for standard devices specified by the UPnP Forum.
    vendor_domain: Option<String>,
    device_type: String,
    version: String,


@@ 49,6 53,7 @@ impl FromStr for DeviceType {

#[derive(Debug, PartialEq)]
pub struct ServiceType {
    /// Will be None for standard services specified by the UPnP Forum.
    vendor_domain: Option<String>,
    service_type: String,
    version: String,


@@ 77,6 82,7 @@ impl FromStr for ServiceType {

#[derive(Debug, PartialEq)]
pub struct ServiceId {
    /// Will be None for standard services specified by the UPnP Forum
    pub vendor_domain: Option<String>,
    pub service_id: String,
}


@@ 119,27 125,41 @@ impl FromStr for UniqueDeviceName {
    }
}

/// A Logical device.
/// One physical "Device" may contain multiple logical Devices.
#[derive(Debug, PartialEq, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Device {
    /// UPnP Device Type
    #[serde(with = "display_fromstr", rename = "deviceType")]
    pub device_type: DeviceType,
    /// Short description for end user. Should be < 64 characters.
    #[serde(rename = "friendlyName")]
    pub friendly_name: String,
    /// Manufacturer's name. Should be <64 characters.
    pub manufacturer: String,
    ///Web site for Manufacturer
    #[serde(rename = "manufacturerURL")]
    pub manufacturer_url: Option<String>,

    /// Long description for the end user. Should be < 128 characters
    pub model_description: Option<String>,
    /// Should be < 128 characters
    pub model_name: Option<String>,
    /// Should be < 32 characters
    pub model_number: Option<String>,
    #[serde(rename = "modelURL")]
    pub model_url: Option<String>,

    /// Shourd be < 64 characters
    pub serial_number: Option<String>,
    /// universally-unique identifier for the device.
    /// Shall be the same over time for a specific device.
    /// Shall max the field value of the NT header in discovery messages
    #[serde(with = "display_fromstr", rename = "UDN")]
    pub unique_device_name: UniqueDeviceName,
    #[serde(rename = "UPC")]
    /// Universal product code.
    pub upc: Option<String>,

    // TODO(EKF): IconList


@@ 157,9 177,12 @@ pub struct Device {
    pub devices: Vec<Device>,

    #[serde(rename = "presentationURL")]
    /// A page to display to the end user
    pub presentation_url: Option<String>,
}

/// Logical functional unit, Smallest  units of control.
/// Exposes actions and models the state of a physical device with state variables.
#[derive(Debug, PartialEq, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Service {


@@ 168,15 191,19 @@ pub struct Service {
    #[serde(with = "display_fromstr")]
    pub service_id: ServiceId,

    /// URL for service description. Relative to device description URL
    #[serde(rename = "SCPDURL")]
    pub scpd_url: String,

    /// Relative to device description URL
    #[serde(rename = "controlURL")]
    pub control_url: String,
    /// Relative to device description URL
    #[serde(rename = "eventSubURL")]
    pub event_sub_url: String,
}

/// This document contains the root device description and metadata
#[derive(Debug, PartialEq, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Description {


@@ 217,6 244,8 @@ where
    DeviceOuter::deserialize(d).map(|d| d.device)
}

/// Retrieve and parse a device description.
/// See the location field from [discovery::Device](../discovery/struct.Device.html#structfield.location).
pub async fn describe(location: String) -> Result<Device, Error> {
    let body = reqwest::get(&location).await?.text().await?;


M yooper/src/discovery.rs => yooper/src/discovery.rs +3 -0
@@ 1,3 1,6 @@
//! Discovery is the the first step of UPnP.
//! Using multicast, ask all devices on the network to announce themselves.
//! From this list, you can then [Describe them](../description) to find out more about their capabilities
use std::collections::HashMap;
use std::net::{Ipv4Addr, SocketAddr};


M yooper/src/lib.rs => yooper/src/lib.rs +2 -0
@@ 1,3 1,5 @@
//! Yooper is a library for discovering and controlling UPnP devices on your network.
//! The modules represent the phases of UPnP: First Discovery, then Description.
#[cfg(feature = "description")]
pub mod description;
pub mod discovery;

M yooper/src/ssdp/mod.rs => yooper/src/ssdp/mod.rs +1 -1
@@ 1,4 1,4 @@
//! A set of libraries for working with SSDP, the service discovery portion of UPnP
//! A library for working with SSDP, the service discovery portion of UPnP
pub mod message;
pub mod packet;