Class SsdpDevice

Base class representing the common details of a (root or embedded) device, either to be published or that has been located.

Inheritance
System.Object
SsdpDevice
SsdpEmbeddedDevice
SsdpRootDevice
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Rssdp
Assembly: cs.temp.dll.dll
Syntax
public abstract class SsdpDevice
Remarks

Do not derive new types directly from this class. New device classes should derive from either SsdpRootDevice or SsdpEmbeddedDevice.

Constructors

SsdpDevice()

Derived type constructor, allows constructing a device with no parent. Should only be used from derived types that are or inherit from SsdpRootDevice.

Declaration
protected SsdpDevice()

SsdpDevice(String, XmlReaderSettings)

Deserialisation constructor.

Declaration
protected SsdpDevice(string deviceDescriptionXml, XmlReaderSettings xmlReaderSettings)
Parameters
Type Name Description
System.String deviceDescriptionXml

A UPnP device description XML document.
XmlReaderSettings xmlReaderSettings

An instance used to determine rules for reading and processing the device description document XML.
Remarks

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.

Exceptions
Type Condition
System.ArgumentNullException

Thrown if the deviceDescriptionXml argument is null.
System.ArgumentException

Thrown if the deviceDescriptionXml argument is empty.

Properties

CustomProperties

Returns a dictionary of SsdpDeviceProperty objects keyed by FullName. Each value represents a custom property in the device description document.

Declaration
public SsdpDevicePropertiesCollection CustomProperties { get; }
Property Value
Type Description
SsdpDevicePropertiesCollection

CustomResponseHeaders

Provides a list of additional information to provide about this device in search response and notification messages.

Declaration
public CustomHttpHeadersCollection CustomResponseHeaders { get; }
Property Value
Type Description
CustomHttpHeadersCollection
Remarks

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 SsdpDevice instance will be included, headers from ancestors are not automatically included.

Devices

Returns a read-only enumerable set of SsdpDevice objects representing children of this device. Child devices are optional.

Declaration
public IEnumerable<SsdpDevice> Devices { get; }
Property Value
Type Description
System.Collections.Generic.IEnumerable<SsdpDevice>
See Also

DeviceType

Sets or returns the core device type (not including namespace, version etc.). Required.

Declaration
public string DeviceType { get; set; }
Property Value
Type Description
System.String
Remarks

Defaults to the UPnP basic device type.

See Also

DeviceTypeNamespace

Sets or returns the namespace for the DeviceType of this device. Optional, but defaults to UPnP schema so should be changed if DeviceType is not a UPnP device type.

Declaration
public string DeviceTypeNamespace { get; set; }
Property Value
Type Description
System.String
Remarks

Defaults to the UPnP standard namespace.

See Also

DeviceVersion

Sets or returns the version of the device type. Optional, defaults to 1.

Declaration
public int DeviceVersion { get; set; }
Property Value
Type Description
System.Int32
Remarks

Defaults to a value of 1.

See Also

FriendlyName

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.

Declaration
public string FriendlyName { get; set; }
Property Value
Type Description
System.String
Remarks

A short description for the end user.

FullDeviceType

Returns the full device type string.

Declaration
public string FullDeviceType { get; }
Property Value
Type Description
System.String
Remarks

The format used is urn:DeviceTypeNamespace:device:DeviceType:DeviceVersion

Icons

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.

Declaration
public IList<SsdpDeviceIcon> Icons { get; }
Property Value
Type Description
System.Collections.Generic.IList<SsdpDeviceIcon>

Manufacturer

Sets or returns the name of the manufacturer of this device. Required.

Declaration
public string Manufacturer { get; set; }
Property Value
Type Description
System.String

ManufacturerUrl

Sets or returns a URL to the manufacturers web site. Optional.

Declaration
public Uri ManufacturerUrl { get; set; }
Property Value
Type Description
System.Uri

ModelDescription

Sets or returns a description of this device model. Recommended.

Declaration
public string ModelDescription { get; set; }
Property Value
Type Description
System.String
Remarks

A long description for the end user.

ModelName

Sets or returns the name of this model. Required.

Declaration
public string ModelName { get; set; }
Property Value
Type Description
System.String

ModelNumber

Sets or returns the number of this model. Recommended.

Declaration
public string ModelNumber { get; set; }
Property Value
Type Description
System.String

ModelUrl

Sets or returns a URL to a web page with details of this device model. Optional.

Declaration
public Uri ModelUrl { get; set; }
Property Value
Type Description
System.Uri
Remarks

Optional. May be relative to base URL.

PresentationUrl

Sets or returns the URL to a web page that can be used to configure/manager/use the device. Recommended.

Declaration
public Uri PresentationUrl { get; set; }
Property Value
Type Description
System.Uri
Remarks

May be relative to base URL.

SerialNumber

Sets or returns the serial number for this device. Recommended.

Declaration
public string SerialNumber { get; set; }
Property Value
Type Description
System.String

Services

Returns a read-only enumerable set of SsdpService objects representing services associated with this device.

Declaration
public IEnumerable<SsdpService> Services { get; }
Property Value
Type Description
System.Collections.Generic.IEnumerable<SsdpService>
See Also

Udn

Returns (or sets*) a unique device name for this device. Optional, not recommended to be explicitly set.

Declaration
public string Udn { get; set; }
Property Value
Type Description
System.String
Remarks

* 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.

Upc

Sets or returns the universal product code of the device, if any. Optional.

Declaration
public string Upc { get; set; }
Property Value
Type Description
System.String
Remarks

If not blank, must be exactly 12 numeric digits.

Uuid

Sets or returns the universally unique identifier for this device (without the uuid: prefix). Required.

Declaration
public string Uuid { get; set; }
Property Value
Type Description
System.String
Remarks

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.

Methods

AddDevice(SsdpEmbeddedDevice)

Adds a child device to the Devices collection.

Declaration
public void AddDevice(SsdpEmbeddedDevice device)
Parameters
Type Name Description
SsdpEmbeddedDevice device

The SsdpEmbeddedDevice instance to add.
Remarks

If the device is already a member of the Devices collection, this method does nothing.

Also sets the RootDevice property of the added device and all descendant devices to the relevant SsdpRootDevice instance.

Exceptions
Type Condition
System.ArgumentNullException

Thrown if the device argument is null.
System.InvalidOperationException

Thrown if the device is already associated with a different SsdpRootDevice 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.
See Also

AddService(SsdpService)

Adds a service to the Services collection.

Declaration
public void AddService(SsdpService service)
Parameters
Type Name Description
SsdpService service

The SsdpService instance to add.
Remarks

If the service is already a member of the Services collection, this method does nothing.

Services should be added to the device before it is added to a publisher.

Exceptions
Type Condition
System.ArgumentNullException

Thrown if the service argument is null.
See Also

OnDeviceAdded(SsdpEmbeddedDevice)

Raises the DeviceAdded event.

Declaration
protected virtual void OnDeviceAdded(SsdpEmbeddedDevice device)
Parameters
Type Name Description
SsdpEmbeddedDevice device

The SsdpEmbeddedDevice instance added to the Devices collection.
See Also

OnDeviceRemoved(SsdpEmbeddedDevice)

Raises the DeviceRemoved event.

Declaration
protected virtual void OnDeviceRemoved(SsdpEmbeddedDevice device)
Parameters
Type Name Description
SsdpEmbeddedDevice device

The SsdpEmbeddedDevice instance removed from the Devices collection.
See Also

OnServiceAdded(SsdpService)

Raises the ServiceAdded event.

Declaration
protected virtual void OnServiceAdded(SsdpService service)
Parameters
Type Name Description
SsdpService service

The SsdpService instance added to the Services collection.
See Also

OnServiceRemoved(SsdpService)

Raises the ServiceRemoved event.

Declaration
protected virtual void OnServiceRemoved(SsdpService service)
Parameters
Type Name Description
SsdpService service

The SsdpService instance removed from the Services collection.
See Also

RemoveDevice(SsdpEmbeddedDevice)

Removes a child device from the Devices collection.

Declaration
public void RemoveDevice(SsdpEmbeddedDevice device)
Parameters
Type Name Description
SsdpEmbeddedDevice device

The SsdpEmbeddedDevice instance to remove.
Remarks

If the device is not a member of the Devices collection, this method does nothing.

Also sets the RootDevice property to null for the removed device and all descendant devices.

Exceptions
Type Condition
System.ArgumentNullException

Thrown if the device argument is null.
See Also

RemoveService(SsdpService)

Removes a service from the Services collection.

Declaration
public void RemoveService(SsdpService service)
Parameters
Type Name Description
SsdpService service

The SsdpService instance to remove.
Remarks

If the service is not a member of the Services collection, this method does nothing.

Exceptions
Type Condition
System.ArgumentNullException

Thrown if the service argument is null.
See Also

SanitizeXmlString(String)

Removes characters from xml that are not valid in XML.

Declaration
protected static string SanitizeXmlString(string xml)
Parameters
Type Name Description
System.String xml

A string containing the XML document to be sanitized.
Returns
Type Description
System.String
Remarks

Some devices embed invalid data, such as C style strings with character zero terminators, in their device description documents. While technically invalid, removing these can allow processing the document correctly.

StringToUri(String)

Converts a string to a System.Uri, or returns null if the string provided is null.

Declaration
protected static Uri StringToUri(string value)
Parameters
Type Name Description
System.String value

The string value to convert.
Returns
Type Description
System.Uri

A System.Uri.

WriteDeviceDescriptionXml(XmlWriter, SsdpDevice)

Writes this device to the specified as a device node and it's content.

Declaration
protected virtual void WriteDeviceDescriptionXml(XmlWriter writer, SsdpDevice device)
Parameters
Type Name Description
XmlWriter writer

The to output to.
SsdpDevice device

The SsdpDevice to write out.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if the writer or device argument is null.

Events

DeviceAdded

Raised when a new child device is added.

Declaration
public event EventHandler<DeviceEventArgs> DeviceAdded
Event Type
Type Description
System.EventHandler<DeviceEventArgs>
See Also

DeviceRemoved

Raised when a child device is removed.

Declaration
public event EventHandler<DeviceEventArgs> DeviceRemoved
Event Type
Type Description
System.EventHandler<DeviceEventArgs>
See Also

ServiceAdded

Raised when a new service is added.

Declaration
public event EventHandler<ServiceEventArgs> ServiceAdded
Event Type
Type Description
System.EventHandler<ServiceEventArgs>
See Also

ServiceRemoved

Raised when a service is removed.

Declaration
public event EventHandler<ServiceEventArgs> ServiceRemoved
Event Type
Type Description
System.EventHandler<ServiceEventArgs>
See Also

See Also