Class SsdpDeviceLocatorBase
Allows you to search the network for a particular device, device types, or UPnP service types. Also listenings for broadcast notifications of device availability and raises events to indicate changes in status.
Inherited Members
Namespace: Rssdp.Infrastructure
Assembly: cs.temp.dll.dll
Syntax
public abstract class SsdpDeviceLocatorBase : DisposableManagedObjectBase, IDisposable, ISsdpDeviceLocatorConstructors
SsdpDeviceLocatorBase(ISsdpCommunicationsServer)
Default constructor.
Declaration
protected SsdpDeviceLocatorBase(ISsdpCommunicationsServer communicationsServer)Parameters
| Type | Name | Description |
|---|---|---|
| ISsdpCommunicationsServer | communicationsServer | The ISsdpCommunicationsServer implementation to use for network communications. |
Properties
ActivitySource
Provides the diagnostic ActivitySource used by this locator for distributed tracing.
Declaration
protected ActivitySource ActivitySource { get; }Property Value
| Type | Description |
|---|---|
| System.Diagnostics.ActivitySource |
IsSearching
Returns a boolean indicating whether or not a search is currently in progress.
Declaration
public bool IsSearching { get; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
Remarks
Only one search can be performed at a time, per SsdpDeviceLocatorBase instance.
NotificationFilter
Sets or returns a string containing the filter for notifications. Notifications not matching the filter will not raise the DeviceAvailable or DeviceUnavailable events.
Declaration
public string NotificationFilter { get; set; }Property Value
| Type | Description |
|---|---|
| System.String |
Remarks
Device alive/byebye notifications whose NT header does not match this filter value will still be captured and cached internally, but will not raise events about device availability. Usually used with either a device type of uuid NT header value.
If the value is null or empty string then, all notifications are reported.
Example filters follow;
See Also
Methods
Dispose(Boolean)
Disposes this object and all internal resources. Stops listening for all network messages.
Declaration
protected override void Dispose(bool disposing)Parameters
| Type | Name | Description |
|---|---|---|
| System.Boolean | disposing | True if managed resources should be disposed, or false is only unmanaged resources should be cleaned up. |
Overrides
OnDeviceAvailable(DiscoveredSsdpDevice, Boolean)
Raises the DeviceAvailable event.
Declaration
protected virtual void OnDeviceAvailable(DiscoveredSsdpDevice device, bool isNewDevice)Parameters
| Type | Name | Description |
|---|---|---|
| DiscoveredSsdpDevice | device | A DiscoveredSsdpDevice representing the device that is now available. |
| System.Boolean | isNewDevice | True if the device was not currently in the cahce before this event was raised. |
See Also
OnDeviceUnavailable(DiscoveredSsdpDevice, Boolean)
Raises the DeviceUnavailable event.
Declaration
protected virtual void OnDeviceUnavailable(DiscoveredSsdpDevice device, bool expired)Parameters
| Type | Name | Description |
|---|---|---|
| DiscoveredSsdpDevice | device | A DiscoveredSsdpDevice representing the device that is no longer available. |
| System.Boolean | expired | True if the device expired from the cache without being renewed, otherwise false to indicate the device explicitly notified us it was being shutdown. |
See Also
SearchAsync(String, CancellationToken)
Performs a search for the specified search target (criteria) and default search timeout.
Declaration
public Task<IEnumerable<DiscoveredSsdpDevice>> SearchAsync(string searchTarget, CancellationToken cancellationToken = default(CancellationToken))Parameters
| Type | Name | Description | ||||||
|---|---|---|---|---|---|---|---|---|
| System.String | searchTarget | The criteria for the search. Value can be;
|
||||||
| System.Threading.CancellationToken | cancellationToken | An optional System.Threading.CancellationToken that can be used to cancel the search request. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<DiscoveredSsdpDevice>> | A task whose result is an System.Collections.Generic.IEnumerable<T> of DiscoveredSsdpDevice instances, representing all found devices. |
SearchAsync(String, TimeSpan, CancellationToken)
Performs a search for the specified search target (criteria) and search timeout.
Declaration
public async Task<IEnumerable<DiscoveredSsdpDevice>> SearchAsync(string searchTarget, TimeSpan searchWaitTime, CancellationToken cancellationToken = default(CancellationToken))Parameters
| Type | Name | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| System.String | searchTarget | The criteria for the search. Value can be;
|
||||||||
| System.TimeSpan | searchWaitTime | The amount of time to wait for network responses to the search request. Longer values will likely return more devices, but increase search time. A value between 1 and 5 seconds is recommended by the UPnP 1.1 specification, this method requires the value be greater 1 second if it is not zero. Specify TimeSpan.Zero to return only devices already in the cache. |
||||||||
| System.Threading.CancellationToken | cancellationToken | An optional System.Threading.CancellationToken that can be used to cancel the search request. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<DiscoveredSsdpDevice>> | A task whose result is an System.Collections.Generic.IEnumerable<T> of DiscoveredSsdpDevice instances, representing all found devices. |
Remarks
By design RSSDP does not support 'publishing services' as it is intended for use with non-standard UPnP devices that don't publish UPnP style services. However, it is still possible to use RSSDP to search for devices implemetning these services if you know the service type.
SearchAsync(CancellationToken)
Performs a search for all devices using the default search timeout.
Declaration
public Task<IEnumerable<DiscoveredSsdpDevice>> SearchAsync(CancellationToken cancellationToken = default(CancellationToken))Parameters
| Type | Name | Description |
|---|---|---|
| System.Threading.CancellationToken | cancellationToken | An optional System.Threading.CancellationToken that can be used to cancel the search request. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<DiscoveredSsdpDevice>> | A task whose result is an System.Collections.Generic.IEnumerable<T> of DiscoveredSsdpDevice instances, representing all found devices. |
SearchAsync(TimeSpan, CancellationToken)
Performs a search for all devices using the specified search timeout.
Declaration
public Task<IEnumerable<DiscoveredSsdpDevice>> SearchAsync(TimeSpan searchWaitTime, CancellationToken cancellationToken = default(CancellationToken))Parameters
| Type | Name | Description |
|---|---|---|
| System.TimeSpan | searchWaitTime | The amount of time to wait for network responses to the search request. Longer values will likely return more devices, but increase search time. A value between 1 and 5 seconds is recommended by the UPnP 1.1 specification, this method requires the value be greater 1 second if it is not zero. Specify TimeSpan.Zero to return only devices already in the cache. |
| System.Threading.CancellationToken | cancellationToken | An optional System.Threading.CancellationToken that can be used to cancel the search request. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<DiscoveredSsdpDevice>> | A task whose result is an System.Collections.Generic.IEnumerable<T> of DiscoveredSsdpDevice instances, representing all found devices. |
StartListeningForNotifications()
Starts listening for broadcast notifications of service availability.
Declaration
public void StartListeningForNotifications()Remarks
When called the system will listen for 'alive' and 'byebye' notifications. This can speed up searching, as well as provide dynamic notification of new devices appearing on the network, and previously discovered devices disappearing.
Exceptions
| Type | Condition |
|---|---|
| System.ObjectDisposedException | Throw if the IsDisposed ty is true. |
See Also
StopListeningForNotifications()
Stops listening for broadcast notifications of service availability.
Declaration
public void StopListeningForNotifications()Remarks
Does nothing if this instance is not already listening for notifications.
Exceptions
| Type | Condition |
|---|---|
| System.ObjectDisposedException | Throw if the IsDisposed property is true. |
See Also
Events
DeviceAvailable
Raised for when
- An 'alive' notification is received that a device, regardless of whether or not that device is not already in the cache or has previously raised this event.
- For each item found during a device SearchAsync(CancellationToken) (cached or not), allowing clients to respond to found devices before the entire search is complete.
- Only if the notification type matches the NotificationFilter property. By default the filter is null, meaning all notifications raise events (regardless of ant
This event may be raised from a background thread, if interacting with UI or other objects with specific thread affinity invoking to the relevant thread is required.
Declaration
public event EventHandler<DeviceAvailableEventArgs> DeviceAvailableEvent Type
| Type | Description |
|---|---|
| System.EventHandler<DeviceAvailableEventArgs> |
See Also
DeviceUnavailable
Raised when a notification is received that indicates a device has shutdown or otherwise become unavailable.
Declaration
public event EventHandler<DeviceUnavailableEventArgs> DeviceUnavailableEvent Type
| Type | Description |
|---|---|
| System.EventHandler<DeviceUnavailableEventArgs> |
Remarks
Devices should broadcast these types of notifications, but not all devices do and sometimes (in the event of power loss for example) it might not be possible for a device to do so. You should also implement error handling when trying to contact a device, even if RSSDP is reporting that device as available.
This event is only raised if the notification type matches the NotificationFilter property. A null or empty string for the NotificationFilter will be treated as no filter and raise the event for all notifications.
The DiscoveredDevice property may contain either a fully complete DiscoveredSsdpDevice instance, or one containing just a USN and NotificationType property. Full information is available if the device was previously discovered and cached, but only partial information if a byebye notification was received for a previously unseen or expired device.
This event may be raised from a background thread, if interacting with UI or other objects with specific thread affinity invoking to the relevant thread is required.