using System; using System.Collections.Generic; using System.Collections.ObjectModel; using System.Text; using System.Threading.Tasks; using System.Xml; using Rssdp.Infrastructure; namespace Rssdp { /// /// Base class representing the common details of a (root or embedded) device, either to be published or that has been located. /// /// /// Do not derive new types directly from this class. New device classes should derive from either or . /// /// /// public abstract class SsdpDevice { #region Fields private string _Udn; private string _DeviceType; private string _DeviceTypeNamespace; private int _DeviceVersion; private SsdpDevicePropertiesCollection _CustomProperties; private CustomHttpHeadersCollection _CustomResponseHeaders; private IList _Devices; #endregion #region Events /// /// Raised when a new child device is added. /// /// /// public event EventHandler DeviceAdded; /// /// Raised when a child device is removed. /// /// /// public event EventHandler DeviceRemoved; #endregion #region Constructors /// /// Derived type constructor, allows constructing a device with no parent. Should only be used from derived types that are or inherit from . /// protected SsdpDevice() { _DeviceTypeNamespace = SsdpConstants.UpnpDeviceTypeNamespace; _DeviceType = SsdpConstants.UpnpDeviceTypeBasicDevice; _DeviceVersion = 1; this.Icons = new List(); _Devices = new List(); this.Devices = new ReadOnlyCollection(_Devices); _CustomResponseHeaders = new CustomHttpHeadersCollection(); _CustomProperties = new SsdpDevicePropertiesCollection(); } /// /// Deserialisation constructor. /// /// Uses the provided XML string and parent device properties to set the properties of the object. The XML provided must be a valid UPnP device description document. /// A UPnP device description XML document. /// Thrown if the argument is null. /// Thrown if the argument is empty. protected SsdpDevice(string deviceDescriptionXml) : this() { if (deviceDescriptionXml == null) throw new ArgumentNullException("deviceDescriptionXml"); if (deviceDescriptionXml.Length == 0) throw new ArgumentException("deviceDescriptionXml cannot be an empty string.", "deviceDescriptionXml"); using (var ms = new System.IO.MemoryStream(System.Text.UTF8Encoding.UTF8.GetBytes(deviceDescriptionXml))) { var reader = XmlReader.Create(ms); LoadDeviceProperties(reader, this); } } #endregion #region Public Properties #region UPnP Device Description Properties /// /// Sets or returns the core device type (not including namespace, version etc.). Required. /// /// Defaults to the UPnP basic device type. /// /// /// public string DeviceType { get { return _DeviceType; } set { _DeviceType = value; } } public string DeviceClass { get; set; } /// /// Sets or returns the namespace for the of this device. Optional, but defaults to UPnP schema so should be changed if is not a UPnP device type. /// /// Defaults to the UPnP standard namespace. /// /// /// public string DeviceTypeNamespace { get { return _DeviceTypeNamespace; } set { _DeviceTypeNamespace = value; } } /// /// Sets or returns the version of the device type. Optional, defaults to 1. /// /// Defaults to a value of 1. /// /// /// public int DeviceVersion { get { return _DeviceVersion; } set { _DeviceVersion = value; } } /// /// Returns the full device type string. /// /// /// The format used is urn::device:: /// public string FullDeviceType { get { return String.Format("urn:{0}:{3}:{1}:{2}", this.DeviceTypeNamespace ?? String.Empty, this.DeviceType ?? String.Empty, this.DeviceVersion, this.DeviceClass ?? "device"); } } /// /// Sets or returns the universally unique identifier for this device (without the uuid: prefix). Required. /// /// /// Must be the same over time for a specific device instance (i.e. must survive reboots). /// For UPnP 1.0 this can be any unique string. For UPnP 1.1 this should be a 128 bit number formatted in a specific way, preferably generated using the time and MAC based algorithm. See section 1.1.4 of http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf for details. /// Technically this library implements UPnP 1.0, so any value is allowed, but we advise using UPnP 1.1 compatible values for good behaviour and forward compatibility with future versions. /// public string Uuid { get; set; } /// /// Returns (or sets*) a unique device name for this device. Optional, not recommended to be explicitly set. /// /// /// * In general you should not explicitly set this property. If it is not set (or set to null/empty string) the property will return a UDN value that is correct as per the UPnP specification, based on the other device properties. /// The setter is provided to allow for devices that do not correctly follow the specification (when we discover them), rather than to intentionally deviate from the specification. /// If a value is explicitly set, it is used verbatim, and so any prefix (such as uuid:) must be provided in the value. /// public string Udn { get { if (String.IsNullOrEmpty(_Udn) && !String.IsNullOrEmpty(this.Uuid)) return "uuid:" + this.Uuid; else return _Udn; } set { _Udn = value; } } /// /// Sets or returns a friendly/display name for this device on the network. Something the user can identify the device/instance by, i.e Lounge Main Light. Required. /// /// A short description for the end user. public string FriendlyName { get; set; } /// /// Sets or returns the name of the manufacturer of this device. Required. /// public string Manufacturer { get; set; } /// /// Sets or returns a URL to the manufacturers web site. Optional. /// public Uri ManufacturerUrl { get; set; } /// /// Sets or returns a description of this device model. Recommended. /// /// A long description for the end user. public string ModelDescription { get; set; } /// /// Sets or returns the name of this model. Required. /// public string ModelName { get; set; } /// /// Sets or returns the number of this model. Recommended. /// public string ModelNumber { get; set; } /// /// Sets or returns a URL to a web page with details of this device model. Optional. /// /// /// Optional. May be relative to base URL. /// public Uri ModelUrl { get; set; } /// /// Sets or returns the serial number for this device. Recommended. /// public string SerialNumber { get; set; } /// /// Sets or returns the universal product code of the device, if any. Optional. /// /// /// If not blank, must be exactly 12 numeric digits. /// public string Upc { get; set; } /// /// Sets or returns the URL to a web page that can be used to configure/manager/use the device. Recommended. /// /// /// May be relative to base URL. /// public Uri PresentationUrl { get; set; } #endregion /// /// Returns a list of icons (images) that can be used to display this device. Optional, but recommended you provide at least one at 48x48 pixels. /// public IList Icons { get; private set; } /// /// Returns a read-only enumerable set of objects representing children of this device. Child devices are optional. /// /// /// public IList Devices { get; private set; } /// /// Returns a dictionary of objects keyed by . Each value represents a custom property in the device description document. /// public SsdpDevicePropertiesCollection CustomProperties { get { return _CustomProperties; } } /// /// Provides a list of additional information to provide about this device in search response and notification messages. /// /// /// The headers included here are included in the (HTTP headers) for search response and alive notifications sent in relation to this device. /// Only values specified directly on this instance will be included, headers from ancestors are not automatically included. /// public CustomHttpHeadersCollection CustomResponseHeaders { get { return _CustomResponseHeaders; } } #endregion #region Public Methods /// /// Adds a child device to the collection. /// /// The instance to add. /// /// If the device is already a member of the collection, this method does nothing. /// Also sets the property of the added device and all descendant devices to the relevant instance. /// /// Thrown if the argument is null. /// Thrown if the is already associated with a different instance than used in this tree. Can occur if you try to add the same device instance to more than one tree. Also thrown if you try to add a device to itself. /// public void AddDevice(SsdpEmbeddedDevice device) { if (device == null) throw new ArgumentNullException("device"); if (device.RootDevice != null && device.RootDevice != this.ToRootDevice()) throw new InvalidOperationException("This device is already associated with a different root device (has been added as a child in another branch)."); if (device == this) throw new InvalidOperationException("Can't add device to itself."); bool wasAdded = false; lock (_Devices) { device.RootDevice = this.ToRootDevice(); _Devices.Add(device); wasAdded = true; } if (wasAdded) OnDeviceAdded(device); } /// /// Removes a child device from the collection. /// /// The instance to remove. /// /// If the device is not a member of the collection, this method does nothing. /// Also sets the property to null for the removed device and all descendant devices. /// /// Thrown if the argument is null. /// public void RemoveDevice(SsdpEmbeddedDevice device) { if (device == null) throw new ArgumentNullException("device"); bool wasRemoved = false; lock (_Devices) { wasRemoved = _Devices.Remove(device); if (wasRemoved) { device.RootDevice = null; } } if (wasRemoved) OnDeviceRemoved(device); } /// /// Raises the event. /// /// The instance added to the collection. /// /// protected virtual void OnDeviceAdded(SsdpEmbeddedDevice device) { var handlers = this.DeviceAdded; if (handlers != null) handlers(this, new DeviceEventArgs(device)); } /// /// Raises the event. /// /// The instance removed from the collection. /// /// protected virtual void OnDeviceRemoved(SsdpEmbeddedDevice device) { var handlers = this.DeviceRemoved; if (handlers != null) handlers(this, new DeviceEventArgs(device)); } /// /// Writes this device to the specified as a device node and it's content. /// /// The to output to. /// The to write out. /// Thrown if the or argument is null. protected virtual void WriteDeviceDescriptionXml(XmlWriter writer, SsdpDevice device) { if (writer == null) throw new ArgumentNullException("writer"); if (device == null) throw new ArgumentNullException("device"); writer.WriteStartElement("device"); if (!String.IsNullOrEmpty(device.FullDeviceType)) WriteNodeIfNotEmpty(writer, "deviceType", device.FullDeviceType); WriteNodeIfNotEmpty(writer, "friendlyName", device.FriendlyName); WriteNodeIfNotEmpty(writer, "manufacturer", device.Manufacturer); WriteNodeIfNotEmpty(writer, "manufacturerURL", device.ManufacturerUrl); WriteNodeIfNotEmpty(writer, "modelDescription", device.ModelDescription); WriteNodeIfNotEmpty(writer, "modelName", device.ModelName); WriteNodeIfNotEmpty(writer, "modelNumber", device.ModelNumber); WriteNodeIfNotEmpty(writer, "modelURL", device.ModelUrl); WriteNodeIfNotEmpty(writer, "presentationURL", device.PresentationUrl); WriteNodeIfNotEmpty(writer, "serialNumber", device.SerialNumber); WriteNodeIfNotEmpty(writer, "UDN", device.Udn); WriteNodeIfNotEmpty(writer, "UPC", device.Upc); WriteCustomProperties(writer, device); WriteIcons(writer, device); WriteChildDevices(writer, device); writer.WriteEndElement(); } /// /// Converts a string to a , or returns null if the string provided is null. /// /// The string value to convert. /// A . protected static Uri StringToUri(string value) { if (!String.IsNullOrEmpty(value)) return new Uri(value, UriKind.RelativeOrAbsolute); return null; } #endregion #region Private Methods #region Serialisation Methods private static void WriteCustomProperties(XmlWriter writer, SsdpDevice device) { foreach (var prop in device.CustomProperties) { writer.WriteElementString(prop.Namespace, prop.Name, SsdpConstants.SsdpDeviceDescriptionXmlNamespace, prop.Value); } } private static void WriteIcons(XmlWriter writer, SsdpDevice device) { if (device.Icons.Count > 0) { writer.WriteStartElement("iconList"); foreach (var icon in device.Icons) { writer.WriteStartElement("icon"); writer.WriteElementString("mimetype", icon.MimeType); writer.WriteElementString("width", icon.Width.ToString()); writer.WriteElementString("height", icon.Height.ToString()); writer.WriteElementString("depth", icon.ColorDepth.ToString()); writer.WriteElementString("url", icon.Url.ToString()); writer.WriteEndElement(); } writer.WriteEndElement(); } } private void WriteChildDevices(XmlWriter writer, SsdpDevice parentDevice) { if (parentDevice.Devices.Count > 0) { writer.WriteStartElement("deviceList"); foreach (var device in parentDevice.Devices) { WriteDeviceDescriptionXml(writer, device); } writer.WriteEndElement(); } } private static void WriteNodeIfNotEmpty(XmlWriter writer, string nodeName, string value) { if (!String.IsNullOrEmpty(value)) writer.WriteElementString(nodeName, value); } private static void WriteNodeIfNotEmpty(XmlWriter writer, string nodeName, Uri value) { if (value != null) writer.WriteElementString(nodeName, value.ToString()); } #endregion #region Deserialisation Methods private void LoadDeviceProperties(XmlReader reader, SsdpDevice device) { ReadUntilDeviceNode(reader); while (!reader.EOF) { if (reader.NodeType == XmlNodeType.EndElement && reader.Name == "device") { reader.Read(); break; } if (!SetPropertyFromReader(reader, device)) reader.Read(); } } private static void ReadUntilDeviceNode(XmlReader reader) { while (!reader.EOF && (reader.LocalName != "device" || reader.NodeType != XmlNodeType.Element)) { reader.Read(); } } [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Maintainability", "CA1502:AvoidExcessiveComplexity", Justification = "Yes, there is a large switch statement, not it's not really complex and doesn't really need to be rewritten at this point.")] private bool SetPropertyFromReader(XmlReader reader, SsdpDevice device) { switch (reader.LocalName) { case "friendlyName": device.FriendlyName = reader.ReadElementContentAsString(); break; case "manufacturer": device.Manufacturer = reader.ReadElementContentAsString(); break; case "manufacturerURL": device.ManufacturerUrl = StringToUri(reader.ReadElementContentAsString()); break; case "modelDescription": device.ModelDescription = reader.ReadElementContentAsString(); break; case "modelName": device.ModelName = reader.ReadElementContentAsString(); break; case "modelNumber": device.ModelNumber = reader.ReadElementContentAsString(); break; case "modelURL": device.ModelUrl = StringToUri(reader.ReadElementContentAsString()); break; case "presentationURL": device.PresentationUrl = StringToUri(reader.ReadElementContentAsString()); break; case "serialNumber": device.SerialNumber = reader.ReadElementContentAsString(); break; case "UDN": device.Udn = reader.ReadElementContentAsString(); SetUuidFromUdn(device); break; case "UPC": device.Upc = reader.ReadElementContentAsString(); break; case "deviceType": SetDeviceTypePropertiesFromFullDeviceType(device, reader.ReadElementContentAsString()); break; case "iconList": reader.Read(); LoadIcons(reader, device); break; case "deviceList": reader.Read(); LoadChildDevices(reader, device); break; case "serviceList": reader.Skip(); break; default: if (reader.NodeType == XmlNodeType.Element && reader.Name != "device" && reader.Name != "icon") { AddCustomProperty(reader, device); break; } else return false; } return true; } private static void SetDeviceTypePropertiesFromFullDeviceType(SsdpDevice device, string value) { if (String.IsNullOrEmpty(value) || !value.Contains(":")) device.DeviceType = value; else { var parts = value.Split(':'); if (parts.Length == 5) { int deviceVersion = 1; if (Int32.TryParse(parts[4], out deviceVersion)) { device.DeviceTypeNamespace = parts[1]; device.DeviceType = parts[3]; device.DeviceVersion = deviceVersion; } else device.DeviceType = value; } else device.DeviceType = value; } } private static void SetUuidFromUdn(SsdpDevice device) { if (device.Udn != null && device.Udn.StartsWith("uuid:", StringComparison.OrdinalIgnoreCase)) device.Uuid = device.Udn.Substring(5).Trim(); else device.Uuid = device.Udn; } private static void LoadIcons(XmlReader reader, SsdpDevice device) { while (!reader.EOF) { while (!reader.EOF && reader.NodeType != XmlNodeType.Element) { reader.Read(); } if (reader.LocalName != "icon") break; while (reader.Name == "icon") { var icon = new SsdpDeviceIcon(); LoadIconProperties(reader, icon); device.Icons.Add(icon); reader.Read(); } } } private static void LoadIconProperties(XmlReader reader, SsdpDeviceIcon icon) { while (!reader.EOF) { if (reader.NodeType != XmlNodeType.Element) { if (reader.NodeType == XmlNodeType.EndElement && reader.Name == "icon") break; reader.Read(); continue; } switch (reader.LocalName) { case "depth": icon.ColorDepth = reader.ReadElementContentAsInt(); break; case "height": icon.Height = reader.ReadElementContentAsInt(); break; case "width": icon.Width = reader.ReadElementContentAsInt(); break; case "mimetype": icon.MimeType = reader.ReadElementContentAsString(); break; case "url": icon.Url = StringToUri(reader.ReadElementContentAsString()); break; } reader.Read(); } } private void LoadChildDevices(XmlReader reader, SsdpDevice device) { while (!reader.EOF && reader.NodeType != XmlNodeType.Element) { reader.Read(); } while (!reader.EOF) { while (!reader.EOF && reader.NodeType != XmlNodeType.Element) { reader.Read(); } if (reader.LocalName == "device") { var childDevice = new SsdpEmbeddedDevice(); LoadDeviceProperties(reader, childDevice); device.AddDevice(childDevice); } else break; } } private static void AddCustomProperty(XmlReader reader, SsdpDevice device) { // If the property is an empty element, there is no value to read // Advance the reader and return if (reader.IsEmptyElement) { reader.Read(); return; } var newProp = new SsdpDeviceProperty() { Namespace = reader.Prefix, Name = reader.LocalName }; int depth = reader.Depth; reader.Read(); while (reader.NodeType == XmlNodeType.Whitespace || reader.NodeType == XmlNodeType.Comment) { reader.Read(); } if (reader.NodeType != XmlNodeType.CDATA && reader.NodeType != XmlNodeType.Text) { while (!reader.EOF && (reader.NodeType != XmlNodeType.EndElement || reader.Name != newProp.Name || reader.Prefix != newProp.Namespace || reader.Depth != depth)) { reader.Read(); } if (!reader.EOF) reader.Read(); return; } newProp.Value = reader.Value; // We don't support complex nested types or repeat/multi-value properties if (!device.CustomProperties.Contains(newProp.FullName)) device.CustomProperties.Add(newProp); } #endregion //private bool ChildDeviceExists(SsdpDevice device) //{ // return (from d in _Devices where device.Uuid == d.Uuid select d).Any(); //} #endregion } }