From OpenHome

(Difference between revisions)
Jump to: navigation, search
(Topology3)
(Topology3Group)
Line 57: Line 57:
===Topology3Group ===
===Topology3Group ===
-
Topology3Group exposes all of the properties and actions of its underlying '''Topology2Group''' plus a '''Sender''' property. The Sender property holds a reference to a '''Sender''' object that reflects the Songcast sender device that the group's receiver source is listening to.
+
Topology3Group exposes all of the properties and actions of its underlying '''Topology2Group''' plus a '''Sender''' property. The Sender property holds a reference to a '''Sender''' object that reflects the Songcast sender device that the group's receiver source is listening to. The '''SenderEmpty''' object is used when no sender is selected or the selected sender is inactive.
===ReceiverWatcher===
===ReceiverWatcher===

Revision as of 10:29, 6 March 2015

Contents

ohTopology

Overview

ohTopology is a software stack which provides a means of controlling devices, on a local network, via their UPnP service actions. Devices are grouped based on their Room names and presented as a tree structure based on their interconnectivity. It consists of a number of distinct layers. Each layer focuses on exposing specific properties and actions that are intended to be utilised by the layers above. Clients of ohTopology need only interface directly with the highest layer of the stack to gain access to the properties and actions exposed by the lower layers.

Watchable System

Overview

Actions exposed by a layer can be called directly, but property values can only be monitored through a callback notification system (observer pattern). Properties are exposed as "watchable" values that may be monitored by "watcher" clients. When a (watchable) property changes, all of its watchers are automatically notified of the change and the property's new value. Watchers can be added and removed at any time. The IWatchable interface is used to expose single value properties and the IWatchableUnordered and IWatchableOrdered interfaces are used for multivalue property lists. Property client objects must conform to the appropriate Iwatchable/IWatchableUnordered/IWatchableOrdered interface for the property that they wish to observe.

Watchable Thread

Although ohTopology is designed to run on multithreaded platforms, actions are executed in a single thread through the use of a thread scheduler class, WatchableThread. Enforcing single threaded execution removes the burden of having to manage thread safety, simplifies debugging and reduces the risk of deadlock. The WatchableThread class provides three methods; Execute, Schedule and Assert.

Schedule Method

Schedule provides a mechanism for asynchronous callback. The specified callback is placed in a queue (FIFO) to be run on the watchable thread, in turn, at some point in the future. Schedule takes a functor, for the callback method, and a generic void* argument to be passed to the callback.

Execute Method

Execute provides a mechanism for synchronous callback. If called from the watchable thread it executes the callback immediately. Otherwise it schedules the callback, for execution on the watchable thread. In either case, it blocks until the callback has completed. Execute takes a functor for the callback method and a generic void* argument to be passed to the callback.

Assert Method

Assert provides a way of checking if the current thread is the watchable thread.

Injector

Network

Topology1

Overview

Topology1 collects a list of Product Service devices from Network and exposes a collection of Products.

Topology1

Topology1 watches a (Product Service) device list from Network and creates a corresponding list of ProxyProduct objects that is updated whenever the device list changes. The Products method exposes the ProxyProduct list as an IWatchableUnordered.

Topology2

Overview

Topology2 collects the list of Products from Topology1 and exposes a collection of Groups. Each Group exposes a Sources collection and pertinent properties and actions of the Product Service. Each Source exposes the standard set of Source properties.

Topology2

Topology2 watches Topology1::Products and creates a corresponding list of Topology2Group objects that is updated whenever Topology1::Products changes. The Groups method exposes the Topology2Group list as an IWatchableUnordered.

Topology2Source

Topology2Source exposes the three standard source properties: Name, Visible and Type. The Index method exposes the source's position in the source list of Topology2Group.

Topology2Group

Topology2Group watches the SourceXml property of its underlying ProxyProduct object. Source information retrieved from SourceXml is used to to create and update a list of Topology2Source objects. The Sources method exposes the Topology2Source list as an IWatchableUnordered.

Topology3

Overview

Topology3 collects the list of Groups from Topology2 and exposes a collection of Groups. Each Group exposes a Sources collection, pertinent actions and properties of the Product Service, and a Sender property.

Topology3

Topology3 watches Topology2::Groups to create and maintain a corresponding list of Topology3Group objects. A dedicated SenderWatcher is created for each Topology3Group to monitor the Metadata property of its Sender Service . A dedicated ReceiverWatcher is created for each Topology3Group to monitor both the Metadata and TransportState properties of its Receiver Service.

Topology3 marries receivers and senders by matching their Uri properties, reassigning the Sender property of each Topology3Group when changes are reported by the watchers. The Groups method exposes the Topology3Group list as an IWatchableUnordered.

Topology3Group

Topology3Group exposes all of the properties and actions of its underlying Topology2Group plus a Sender property. The Sender property holds a reference to a Sender object that reflects the Songcast sender device that the group's receiver source is listening to. The SenderEmpty object is used when no sender is selected or the selected sender is inactive.

ReceiverWatcher

ReceiverWatcher watches the Sources property of Topology3Group to find a source of type Receiver as an indicator of the existence of a Receiver service. If it exists, the Receiver service is subscribed to and its TransportState and Metadata properties are watched. When either of these two properties change Topology3 is notified via its ReceiverChanged method.

SenderWatcher

SenderWatcher subscribes to it's group's Sender service to watch its Metadata property. When this property changes Topology3 is notified via its SenderChanged method.

Topology4

Overview

Topology4 collects the list of Groups from Topology3 and exposes a new collection of Rooms. Each Room in the new collection exposes a collection of Groups with matching RoomName properties.

Topology4

Topology4 watches Topology3::Groups and creates a Topology4Room list that is updated whenever there is a change to the RoomName property of any Topology3Group. A dedicated Topology4GroupWatcher is created for each Topology3Group to watch its RoomName property. The Rooms method exposes the Topology4Room list as an IWatchableUnordered.

Topology4Room

Topology4GroupWatcher

Topology4GroupWatcher watches the RoomName property of a single Topology3Group and updates Topology4, removing the group from one room and adding it to another, whenever its RoomName property changes.

Topology5

Overview

Topology5 collects the list of Rooms from Topology4 and organises the Groups in each room, evaluating their interrelationship as a hierarchical tree, and exposes a list of Rooms. Each Room exposes a Roots list and a Sources list. A Root is defined as a product whose outputs are not connected to the inputs of any other product. In essence a Root is the main product in the Room whose outputs are connected to the speakers and typically, once configured correctly, each Room should contain only one Root.

Topology5

Topology5 watches Topology4::Rooms to create and maintain a corresponding list of Topology5Room objects.

Topology5Room

Topology5Room watches Topology4Room::Groups updating Topology3Group list whenever a Topology3Group is added/removed. The Standby, Name and Sources properties of each Topology3Group are then watched for changes. A dedicated Topology5GroupWatcher is created for each Topology3Group to watch its Name and Sources properties.

Although the Standby state of each group is boolean, Topology5Room exposes a tristate Standby property. This is to accommodate a third state "mixed" when there is an inconsistent Standby state across all groups in the room. The Topology3Group list is used to maintain a corresponding Topology5Group list, a subset of which is exposed as a Roots list. A Root (ITopology5Root) is defined as a Topology5Group that does not have a Parent group. A super list of all Sources of every Root in the Room is exposed as Sources.


The list is filtered to remove all Child groups, and a super list of all sources of all groups in each room is maintained that is filtered to remove any Parent sources. A Child group is defined as one whose outputs are connected to the inputs of another group. A Parent source is defined as one whose input is fed from the outputs of another (Child) group.

Topology5Group

Topology5Source

Topology5GroupWatcher

Monitors the two properties, Name and Sources, of Topology3Group, updating Topology5Room whenever a change occurs.

Services

Overview

Service

ServicePlaylist

ServiceRadio

ServiceSender

ServiceReceiver

ServiceVolume

ServiceInfo

ServiceProduct