From OpenHome

ohTopology

Contents 1 Overview 2 Watchable System 2.1 Overview 2.2 Watchable Thread 2.3 Schedule Method (asynchronous callback) 2.4 Execute Method (synchronous callback) 2.5 Assert Method 3 Topology1 Classes 3.1 Classes 3.1.1 Topology1 3.1.2 ProxyProduct 4 Topology2 Classes 4.1 Topology2 4.2 Topology2Source 4.3 Topology2Group 5 Topology3 Classes 5.1 Topology3 5.2 Topology3Group 6 Topology4 Classes 6.1 Topology4 6.2 Topology4Room 6.3 Topology4GroupWatcher 7 Topology5 Classes 7.1 Topology5 7.2 Topology5Room 7.3 Topology5Group 7.4 Topology5Source 7.5 Topology5GroupWatcher

Overview

ohTopologyC is a software stack which provides a means of controlling devices, on a local network, via their UPnP service actions. Devices are grouped them 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 ohTopologyC 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/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 ohTopologyC 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 (asynchronous callback)

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 (synchronous callback)

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 (using ASSERT) if the current thread is the watchable thread.

Topology1 Classes

Classes

Topology1

Topology1 collects a list of devices (with Product Service) from Network and adds itself as a watcher of this list. When a device is added to the list a ProxyProduct (proxy to device's Product service) is created and added to the Topology1 Products list. This list is exposed, for consumption by Topology2, as an IWatchableUnordered.

ProxyProduct

Topology2 Classes

Topology2

Topology2 watches Topology1::Products and updates Topology2Group list whenever a ProxyProduct is added/removed from Topology1::Products

Topology2Source

Topology2Group

Topology3 Classes

Topology3

Topology3 watches Topology2::Groups and updates Topology3Group list whenever a Topology2Group is added/removed from Topology2::Groups

Topology3Group

Topology4 Classes

Topology4

Topology4 watches Topology3::Groups and updates Topology4Room list whenever there is a change to the Room property of any Topology3Group. The Room property of each Topology3Group is monitored by a dedicated Topology4GroupWatcher.

Topology4Room

Topology4GroupWatcher

Updates Topology4 upon Room property change of Topology3Group.

Topology5 Classes

Topology5

Topology5 watches Topology4::Rooms, updating its Topology5Room list whenever a Topology4Room is added/removed.

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 employed to monitor Name and Sources of each group. 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.

Topology5Group

Topology5Source

Topology5GroupWatcher

Monitors the two properties, Name and Sources, of Topology3Group, updating (CreateTree) Topology5Room when any poperty change occurs.