skip navigation
URC Consortium Logo

You are here: MyURC.org > TR > uch1.0-20080814 > Draft

Universal Control Hub 1.0 (DRAFT)

Draft Technical Report 2008-08-14

This version: http://myurc.org/TR/uch1.0-20080814/
Latest version: http://myurc.org/TR/uch1.0/
Previous draft version: (none)
Latest approved version: (none)
Editor: Gottfried Zimmermann

Copyright 2008, Universal Remote Console Consortium (URCC)

Abstract

This URCC Technical Report specifies the "Universal Control Hub" (short UCH) architecture. This approach is a profiling of the Universal Remote Console (URC) technology (as specified by ISO/IEC 24752) in the context of a Remote User Interface scenario (as specified by CEA-2014-A).

The UCH allows the application of the URC technology in an environment with non-URC compliant controllers and non-URC compliant targets. In this approach, the URC technology is implemented "in a box", with the Universal Control Hub acting as gateway between various controllers and various targets.

This document is intended to provide a specification for the development of Universal Control Hubs. It supersedes earlier attempts of describing the UCH approach, for example those posted on the MyURC website [UCH 2005][UCH 2006].

The reader of this document will benefit greatly if already familiar with the URC standards (ISO/IEC 24752, parts 1, 2, 4, and 5).

Status of this Document

This is a public Draft Technical Report, developed by the editor, hereby made available for review by URCC members and the public.

Comments on this document should be sent to the editor.

Publication as a Draft Technical Report does not imply endorsement by the URCC membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Change Log [to be removed before final release]

NOTE: The change log is in reverse chronological order.

2008-08-14 Gottfried Zimmermann:

Open Issues [to be removed before final release]

  1. addCompatibleUI: Maybe we should allow the use of arbitrary applicationIds if a UI does not exactly match to one target?
  2. Should we define error codes/messages for rejected open session requests?
  3. Should there be a separate method when a dynamic resource changes, without changing the value of the corresponding socket element?
  4. How can TAs deliver dynamic resources for values of external types? Would be useful for "friendly names" of networked devices being delivered as dynamic labels in play-1.uis and play-2.uis.
  5. Allow to specify a resDefaultProps map for resource preferences? Could be an additional argument to getResources().
  6. Make targetDescription and targetDescriptionUri a mandatory property of targetProps, and remove getTargetDescription() and getTargetDescriptionUri()?
  7. Should we care about <fork> and <lifetime> in a UIList? How would this affect addCompatibleUI()?
  8. The content of <protocolInfo> should just be a block of data, no subelements
  9. How can the UCH serve non-HTTP URIs through controllerRequest() and targetRequest()?
  10. Should the UCH take care of collecting updates if the UIPM wishes to poll for updates instead of receiving events? This would require an API change for UIPMs.
  11. Can the TA deliver dynamic resources for a type? This would be helpful for the "friendly name" issue with UPnP AV media servers and renderers.
  12. How to deal with descriptors when using the getResources() method?
  13. Should getValues() include parameters 'depth' and 'includeSets' (see URC-HTTP spec, open issues)?
  14. Duplicate properties in resProps for getResources() are interpreted as ANDed values. Should we also allow for alternative values in a query?
  15. What <uiID> should be used for control applications that control a subset of available targets?

Table of Contents

1. Scope

This Technical Report specifies the "Universal Control Hub" (short UCH). It is a profiling of the Universal Remote Console framework, as specified in ISO/IEC 24752.

In this profile, a gateway ("control hub") is used as a middle layer between a controller and a target device or service. The gateway translates between any controller and any target; neither the controller nor the target needs to be URC compatible.

2. Conformance

A Universal Control Hub (UCH) is conforming to this standard if it provides:

A User Interface Protocol Module (UIPM) is conforming to this standard if it provides:

A Target Discovery Module (TDM) is conforming to this standard if it provides:

A Target Adapter (TA) is conforming to this standard if it provides:

NOTE: Conformance to this standard does not imply conformance to any part of ISO/IEC 24752.

3. References

3.1. Normative References

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

[CEA-2014]
CEA-2014-A: Web-based Protocol and Framework for Remote User Interface on UPnP Networks and the Internet (Web4CE). P. Shrubsole, W. Dees, 2007.
[DCMI Metadata Terms]
Dublin Core Metadata Initiative MetadataTerms. Available at: http://dublincore.org/documents/dcmi-terms/.
[ISO/IEC 8601:2004]
Data elements and interchange formats - Information interchange - Representation of dates and times. International Standard, 2004.
[ISO/IEC 24752-1:2008]
Information Technology User Interfaces Universal Remote Console. Part 1: Framework. ISO, 2008.
[ISO/IEC 24752-2:2008]
Information Technology User Interfaces Universal Remote Console. Part 2: User Interface Socket Description. ISO, 2008.
[ISO/IEC 24752-4:2008]
Information Technology User Interfaces Universal Remote Console. Part 4: Target Description. ISO, 2008.
[ISO/IEC 24752-5:2008]
Information Technology User Interfaces Universal Remote Console. Part 5: Resource Description. ISO, 2008.
[Java Servlet API]
Servlet API Documentation (version 2.5 or later). Apache Software Foundation. http://java.sun.com/products/servlet/2.5/docs/servlet-2_5-mr2/index.html
[RES-PROP-VOCAB]
URC Consortium: Resource Property Vocabulary. Latest version available at: http://myurc.org/TR/res-prop-vocab/.
[RFC 2119]
RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner, March 1997. Available at: http://www.ietf.org/rfc/rfc2119.txt.
[RFC 2616]
RFC 2616: Hypertext Transfer Protocol HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, 1999. Available at: http://www.ietf.org/rfc/rfc2616.txt.
[RFC 3986]
IETF RFC 3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005, http://www.ietf.org/rfc/rfc3986.txt.
[UPnP RUI]
UPnP Remote UI Client and Server V1.0 Standardized DCPs:
RemoteUIClientDevice V1.0. Y. Saint-Hilaire, M. Walker, K. B. Min, 2004. Available at: http://www.upnp.org/standardizeddcps/documents/RemoteUIClientDevice1.0.pdf.
RemoteUIClientService V1.0. Y. Saint-Hilaire, M. Walker, J. van Ee, 2004. Available at: http://www.upnp.org/standardizeddcps/documents/RemoteUIClientService1.0.pdf.
RemoteUIServerDevice V1.0. M. Walker, K. B. Min, 2004. Available at: http://www.upnp.org/standardizeddcps/documents/RemoteUIServerDevice1.0.pdf.
RemoteUIServerService V1.0. J. van Ee, M. Walker, 2004. Available at: http://www.upnp.org/standardizeddcps/documents/RemoteUIServerService1.0.pdf.

3.2. Informative References

[IDL]
Information technology - Open Distributed Processing - Interface Definition Language. ISO/IEC 14750:1999, available (for purchase) at http://www.iso.org. Alternative document, "IDL Syntax & Semantics", available (freely) as chapter 3 of the CORBA specification, at http://www.omg.org/technology/documents/formal/corba_2.htm.
[UCH 2005]
Universal Control Hub & Pluggable User Interfaces. Jan. 2005. http://myurc.org/publications/2005-Univ-Ctrl-Hub.php
[UCH 2006]
Universal Control Hub & Task-Based User Interfaces. Jan. 2006. http://myurc.org/publications/2006-Univ-Ctrl-Hub.php
[URC-HTTP]
URC-HTTP Protocol. Latest specification available at: http://myurc.org/TR/urc-http-protocol/

4. Acknowledgments

5. Conventions in this Document

In this document the words SHALL, SHOULD and MAY have meanings as defined in [RFC 2119].

6. Runtime Model for UIPMs, TDMs and TAs

6.1. Overview

Components of the Universal Control Hub

Figure: Components of the UCH (description of figure). Note that Controller, UIPM, TDM, TA and Target may occur multiple times. For simplicity, only one instance is shown in the figure.

6.2. Considerations on API Design

Basically there are two ways to design the APIs for the UCH: object-oriented or function-oriented.

6.2.1. Object-Oriented Design

In the object-oriented approach, data and behavior is encapsulated as "objects". Functions are understood as "methods" pertaining to objects such as targets, sessions, and socket elements.

Regarding the UCH design, this approach has the following benefits:

6.2.2. Function-Oriented Design

In the function-oriented approach, data is passed as parameters of functions, preferably as primitive data types such as strings and numbers.

Regarding the UCH design, this approach has the following benefits:

6.2.3. Approach: Facade

The approach taken by this specification is aligned with the function-oriented design approach. It allows for using the object-oriented approach inside the UCH or its loadable modules, but uses a faade approach for communication between the standardized components of a UCH.

For example, a Target Adapter could maintain a session object internally, but exposes it to the UCH by a session identifier. A similar approach is taken for targets which are represented to User Interface Protocol Modules (UIPMs) by target identifiers.

6.3. Modules Loaded at Runtime

The UCH provides the runtime environment for User Interface Protocol Modules (UIPMs), Target Discovery Modules (TDMs) and Target Adapters (TAs).

A UIPM and TA shall be available as separate code files, and in a form that allows the UCH to dynamically load and install its code.

A TDM may be integrated into the UCH, or may be available as a separate file and in a form that allows the UCH to dynamically load and install its code.

EXAMPLE A DLL ("dynamic link library") file on Windows, or an SO ("shared object") file on a Unix platform.

This specification does not define whether UIPMs, TDMs and TAs run as separate processes or threads, or whether their memory space is separated. This is implementation-specific.

6.4. Optional Functions

Some functions are specified as optional, i.e. the module may or may not implement it. However, the module shall implement a stub of the function in any case, and shall throw a NotImplementedException if it doesn't support the optional function.

NOTE: A stub implementation is needed because some programming languages require strong typing, and would not allow for a class to be cast to an interface that its set of functions doesn't match for.

6.5. Concurrency

The functions specified in section Interaction Between UIPM and UCH, section Interaction Between Target Discovery Module (TDM) and UCH, and section Interaction Between Target Adapter and UCH shall be executed

6.6. Property Map

Targets and resources (in the following just called "object"), including loadable modules (UIPMs, TDMs and TAs) shall be described through metadata. The UCH may retrieve such metadata from a resource server, or from local configuration data, or from somewhere else.

At runtime, the UCH shall represent an object's metadata as a property map. A property map is a set of key-value pairs, both of type string.

Unless otherwise noted, duplicate properties are allowed if their values differ. In general, multiple values are to be interpreted as additional values for the property (i.e. the set of key-value pairs that have identical keys represents a list of values for the key).

The UCH provides a module's property map to the module itself at initialization time. This allows for customization of a generic module based on a particular runtime context.

In addition, the UCH may utilize the property map of any object, for example for determining the most appropriate UIPM for a set of available targets.

6.6.1. Property Names

A property name shall be a URI [RFC 3986], consisting of a namespace and a local property name. This allows for an extensible set of properties.

A core set of properties and their meanings are defined in [RES-PROP-VOCAB].

Other (non-core) property names may be used to describe objects, as long as the property names do not conflict with the core set defined in [RES-PROP-VOCAB]. In order to avoid potential conflicts with future versions of core properties and with other non-core properties, the use of author-owned URIs as namespaces for non-core property names is strongly recommended.

6.6.2. Implementation Considerations

Implementation of property maps are platform-specific. Programming languages with hash maps should use hash maps with strings as keys and string arrays as values (to accommodate multiple values of the same property). Otherwise pairs of string arrays should be used.

6.7. Target Instance Identifier

The UCH shall provide identifiers for target instances (see ISO/IEC 24752-1, section 6.1.2 Target instance identifier). The target instance identifiers shall be globally unique.

Target instance identifiers are strings, and shall not contain whitespace characters. Their format may be specific to the underlying target platform. The string "all" is reserved and shall not be used as target instance identifier.

NOTE: In this specification, a target instance identifier is commonly named 'targetId'.

The UCH should use target instance identifiers that are persistent even after periods of target unavailability, and after the UCH has restarted.

NOTE: For targets running on UPnP, the UDN is a suitable target instance identifier.

Static and dynamic resources may be defined to be specific to target instances. Static resources may use the <forTargetInstance> element (ISO/IEC 24752-5, section 6.7.3.6) to indicate a particular target instance. For dynamic resources, a TA may indicate their specificity to a particular target instance in the updateDynRes() function via the 'targetId' parameter (see section void updateDynRes(string[] sessionIds, string[] eltIds)).

6.8. Session Identifier

The UCH shall provide identifiers for sessions which are unique within the UCH.

The UCH should not reuse session identifiers of sessions that have been terminated.

6.9. Paths

Particular values of socket elements or components thereof are referenced by path strings.

The following table lists possible forms of paths, as used by the APIs specified in subsequent sections of this document.

Path Form Name

Syntax(es)

Description

root path

/

all Socket elements (and their components, if any)

path without indices

/set1/set2/id

id

alternative formats for non-dimensional Socket element or set

path with given indices

/set1[index1]/set2/
id[index2][index3]

one component of a dimensional Socket element or set, i.e. that has a 'dim' attribute or that is contained (directly or indirectly) in a set that has a 'dim' attribute

path with empty indices

/set1[]/set2/id[][]

all components of the Socket element or set id.

May be mixed with form "path with given indices", thus partially specifying a set of indices, e.g.: "/set1[index1]/set2/id[index2][]", "/set1[]/set2/id[index2][index3]", "/set1[index1]/set2/id[][index3]".

path with range of indices

/set1[index1a index1b]/set2/id[index2a index2b][index3a index3b]

specific components of the Socket element or set id, within a specific range of index values (index1a <= index1 <= index1b, index2a <= index2 <= index2b, index3a <= index3 <= index3b).

This form can only be applied for indices whose type is totally ordered (i.e. the index type must be based on an XSD type with the fundamental facet 'ordered' having a value of "total" or "partial"; if "partial", only those index values that can be compared with the boundaries will be included in the response).

This form can be mixed with the "path with given indices" form, and the "path with empty indices" form. EXAMPLE: "/set1[index1]/set2/id[index2a index2b][]".

path for command state

/set1/set2/cmdid[state]

id[state]

/set1[index1]/set2/
cmdid[index2][index3][state]

"state" field of a command (component) only applicable for commands of type "uis:basicCommand" or "uis:timedCommand" use first or second form for non-dimensional commands; and last form for dimensional commands.

path for command timeToComplete

/set1/set2/cmdid[ttc]

cmdid[ttc]

/set1[index1]/set2/
cmdid[index2][index3][ttc]

"timeToComplete" field of a command (component) only applicable for commands of type "uis:timedCommand" use first or second form for non-dimensional commands; and last form for dimensional commands.

path for local command parameter

/set1/set2/cmdid/parid

parid

/set1[index1]/set2/
cmdid[index2][index3]/parid

local parameter of a command (component) use first or second form for non-dimensional commands; and last form for dimensional commands.

path for partial XML content

eltPath#xmlPath

partial content of an XML-coded Socket element value (i.e. a Socket element with a complex XSD form).

eltPath references a Socket element, in any of the following path forms: "path without indices", "shortcut path" or "path with given indices".

xmlPath has any one of the following syntaxes:

"root" for requesting an XML fragment containing the root element only.

"childrenOf(nodeId)" for requesting an XML fragment containing the child nodes of the XML element with id="nodeId".

"parentOf(nodeId)" for requesting an XML fragment containing the parent node of the XML element with id="nodeId".

"id(nodeId)" for requesting an XML fragment containing the XML element with id="nodeId". The fragment will contain the nodeId element including its attributes, but not its child nodes.

6.10. Values

All values are passed as strings.

NULL represents the undefined value.

NOTE: Optional socket elements that are not available in a socket at runtime have the undefined value.

6.11. Resources

A UIPM should not itself contact a resource server to query for resources. Instead, it should use the appropriate function getResources() to have the UCH do the query and retrieval for it. It is implementation-specific where the UCH will go for resource retrieval including a local configuration mechanism, a local resource server, a global resource server, or any combination of these.

Atomic resources (even if they are dynamic) are common to all sessions on the same socket, and common to all components (index combinations) of a socket element.

However, they may be different for different target instances (specified by the http://myurc.org/ns/res#forTargetInstance property).

6.12. Local Data Store

In some cases different modules (UIPMs, TDMs, TAs) and the UCH core may wish to share data with each other. For this purpose, a shared Map is provided by the UCH, called "local data store". Modules may store data as key-value pairs in the local UCH store, which may be accessed by other (related) modules that know the corresponding keys.

It is recommended that keys are used that will likely not conflict with data written by other modules at runtime. Manufacturers of modules should use keys in the form of URIs that they own, such as URLs under their domain name. EXAMPLE: "http://example.com/uipm/portno".

Note that the local data store is not persistent. Data will not survive a UCH restart. Also, upon removal of a module (TA or UIPM) from the system, the UCH may delete data written by that module.

Note also that the local UCH store is not a safe place for communicating sensitive information such as authorization keys, since it can be read by the UCH, and all UIPMs, TDMs and TAs.

The UCH shall provide a local data store object as a map with distinct keys. No duplicate keys are allowed (i.e. setting a value for an already existing key will overwrite the previous data for that key).

The local data store shall implement the functions as defined hereby for IUCHStore:

6.12.1. Object getValue(string key)

Get a stored value from the local data store (a map, see section Local Data Store).

6.12.2. void setValue(string key, Object value)

Set a (new) value for the given key. If the key didn't exist in the map before, it will be created. If the key is already existing, the map stores the new value under the key, and the old value is lost.

7. Interaction Between UIPM and UCH

7.1. UIPM Loading and Unloading

A UIPM may be retrieved from local or remote resources (e.g. resource server).

The UCH should load a UIPM when the UIPM's set of applicable targets is a subset of the currently available targets in the UCH. The set of applicable targets is specified by the aggregation of all existing "http://myurc.org/ns/res#forTargetName" property values for a UIPM [RES-PROP-VOCAB].

The UCH may unload a UIPM at any time, but should call its finalize() function (section void finalize()) prior to unloading. A UCH should unload a UIPM if it is not applicable (anymore) to the current set of available targets. A UCH should unload a UIPM after the UIPM has called removeUIPM() (see section void removeUIPM(IUIPM uipm)).

7.2. API of UIPM (IUIPM)

7.2.1. Mandatory Functions

7.2.1.1. void init(IUIPMListener uipmListener, Map uipmProps, Map uchProps) throws UIPMFatalException

After a UIPM has been installed and loaded, the UCH shall call init() prior to any other UIPM function. This allows the UIPM to initialize itself.

7.2.1.2. void finalize()

Tell the UIPM to clean up its own memory. The UIPM does not need to clean up for the sessions or user interface items it has created within the UCH the UCH will take care about this itself.

The UCH should call finalize() before it uninstalls or unloads the UIPM. However, finalize() shall not be called after init() has thrown a UIPMFatalException.

7.2.1.3. Map getUIPMProps()

Get property map of the UIPM.

7.2.1.4. void targetDiscovered(string targetId) throws UIPMFatalException

This function is called when a new target has been discovered after initialization of the UIPM.

7.2.1.5. void targetDiscarded(string targetId) throws UIPMFatalException

This function is called when a target has been discarded after initialization of the UIPM.

7.2.1.6. void sessionForwardRequest(string sessionId, Map forwardInfo) throws UIPMFatalException

The target requests the client (UIPM/controller) to open a session with a different socket. There are two types of forward requests: A "destructive forward request" asks the client to close the current session. A "spawn forward request" does not affect the current session.

7.2.1.7. void sessionAborted(string sessionId) throws UIPMFatalException

The target has terminated a session (which may be in active or suspended mode).

7.2.1.8. void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, boolean[] hasDynRes) throws UIPMFatalException

The target's status has changed, affecting one or more sessions.

NOTE: The arrays paths, operations, values and hasDynRes shall be of the same size.

NOTE: A UCH that watches dependencies may trigger an update for a variable that has a 'calculate' dependency defined if one if the parameters in its 'calculate' dependency has changed. The UCH may either add the update to the arrays as part of an "accumulated update", or as a separate call to updateValues().

7.2.1.9. boolean isImplemented(string functionName)

This function allows the UCH to check whether any of the optional functions are implemented by the UIPM.

7.2.2. Optional Functions

7.2.2.1. void controllerRequest(Object request, Object response) throws UIPMFatalException

NOTE: The controllerRequest() function is currently specific to HTTP requests and responses. Future versions of this document may accommodate additional URI schemes.

A UIPM may implement the controllerRequest() function. If it does not implement it, it shall not call the UCH's startUriService() function.

The UCH calls controllerRequest() if it has received a request from a controller to a URI that the UIPM has claimed for itself by a previous call to startUriService(). The UCH is responsible for creating the request and (partially empty) response objects prior to calling controllerRequest().

7.3. API of UIPM Listener (IUIPMListener)

How to access the UCH (socket layer) from a UIPM.

7.3.1. Mandatory Functions

7.3.1.1. string[] getAvailableTargetIds()

Get the identifiers of the available targets.

7.3.1.2. string getTargetName(string targetId)

Get the name (URI) of a target. Note that the target name is not necessarily unique within the UCH since there may be multiple copies of one target type (with the same target name).

NOTE: The name (URI) of a target is the value of the 'about' attribute of the <target> element in a target description.

7.3.1.3. Map getTargetProps(string targetId)

Get a property map for a target.

7.3.1.4. string getTargetDescriptionUri(string targetName)

Get the URI for retrieving the target description.

NOTE: The function getDocument() (see section string getDocument(string uri, string postData) throws UCHException) can be used to retrieve the actual Target Description document.

7.3.1.5. string getDocument(string uri, string postData) throws UCHException

Get description document through HTTP GET or POST (HTTP proxy function). Default values should be used for HTTP header data.

NOTE: getDocument() can be used to retrieve local or remote documents.

7.3.1.6. string[] getSocketNames(string targetName)

Get the socket names (URIs) for a target type. Note that this is a convenience function for the UIPM since the socket names are specified in the target description.

7.3.1.7. string getSocketDescriptionUri(string targetName, string socketName)

Get the URI for retrieving the socket description.

NOTE: The function getDocument() (see section string getDocument(string uri, string postData) throws UCHException) can be used to retrieve the actual Socket Description document.

NOTE: Strictly, targetName is not needed since a socket description is already identified by its socket name. However, UCH implementations may be simpler if they don't need to keep track of a cross-target list of socket names.

7.3.1.8. string getSocketName(string sessionId)

Get the socket name (URI) for a specified session.

7.3.1.9. string getSocketFriendlyName(string targetId, string socketName)

Get the friendly name for a socket on a target instance. This is a short, human-readable name for the socket, and may be user-configured.

NOTE: For example, the friendly name can be used as part of the URI for a user interface.socketName: name (URI) of the socket.

7.3.1.10. Map getLocators(string targetName)

Get a map with locator ids and locator types for a specific target type.

7.3.1.11. void invokeLocator(string targetId, string locatorId)

Invoke the specified locator function on the specified target. Note that it is not necessary to have a session open with the target.

7.3.1.12. boolean isElementAvailable(string targetId, string socketName, string eltId)

Check whether a specified socket element is available at runtime.

NOTE: Socket elements with an attribute optional="true" may not be available at runtime. Other socket elements are always available.

Return value: true= element available, false=element not available.

7.3.1.13. Map[] getResources(string sessionId, Map[] resProps)

Get any kind of resource from the UCH. The UCH should relay the request to a resource server or TA if it cannot handle it locally (this is implementation-specific). The caller shall specify the properties of the requested resource as much as possible. A specific matching algorithm is implementation-specific. See also section Resources.

7.3.1.14. Map openSessionRequest(IUIPM uipm, string targetId, string socketName, Map clientProps)

Request for opening a session with the specified target and socket.

7.3.1.15. void closeSession(string sessionId)

The UIPM closes a session with the UCH.

7.3.1.16. Map getValues(string sessionId, string[] paths)

The UIPM asks for the values/states of specified socket elements or components thereof.

7.3.1.17. Object[] getIndices(string sessionId, string[] eltIds, integer[] indexNos)

The UIPM asks for the available values for a particular index of a dimensional socket element or set.

NOTE: This function looks at the actual value for a specific index of a socket element, isolated from other indices that are part of all actual paths for the given element. For sparse arrays, the index value may not occur in any possible combination with values of other indices.

7.3.1.18. Map setValuesRequest(string sessionId, string[] paths, string[] operations, string[] reqValues)

The UIPM requests to change the target state in one or more operations on specified socket elements or components thereof. The requested operations are coded as cross-indexed arrays of paths, operation identifiers and requested new values. "Cross-indexed" means that array elements with the same index belong together.

NOTE: The UCH may validate the requests and block those that would violate a socket element's type or dependencies (see section boolean setValidation(ITA ta, boolean activate), setValidation function). Blocking means that the UCH removes invalid requests before passing them on to the pertaining TA.

7.3.1.19. string getIpAddress()

Get the IP address of the UCH. A UIPM may need this information to set up its own listener for a port that is not serviced by the UCH.

7.3.1.20. string startUriService(IUIPM uipm, string scheme, int port, boolean portIsFlexible, string basePath, boolean basePathIsFlexible) throws UCHException

The UIPM requests the UCH to start servicing a URI which is made up of a given scheme, port, and base path. If successful, the UCH will forward all messages that have this URI as its base, to controllerRequest(). If the UIPM indicates that the base path is flexible, the UCH can modify the base path in case it is not available any more.

NOTE: This function does not advertise the URI through its UI List a separate call to addCompatibleUI() is needed for that.

7.3.1.21. void stopUriService(string uri) throws UCHException

The UIPM requests the UCH to stop servicing a URI that was requested to be serviced in a previous call to startUriService().

7.3.1.22. boolean addCompatibleUI(string targetId, string[] socketNames, string protocolShortName, string[] uris, Map protocolInfo) throws UCHException

Tell the UCH to add a user interface item (advertised by the UIPM) to its UIList (see section UIList) which is exposed to controllers on request. If the UIPM wants to advertise multiple user interfaces at the same time, it needs to call addCompatibleUI() multiple times.

The UCH shall map these parameter values to an entry in the UIList (see section UIList) as follows:

7.3.1.23. void removeCompatibleUI(string[] uris) throws UCHException

Tells the UCH to remove user interface URIs from the UIList that were previously added by one call to addCompatibleUI(). Note that the UCH may have to remove the pertaining <protocol> or <ui> element from the UList if no <uri> element is remaining in it.

7.3.1.24. IUCHStore getLocalUCHStore()

Get the local UCH store (a map, see section Local Data Store).

7.3.1.25. Map getUCHProps()

Get property map of the UCH.

7.3.1.26. boolean isImplemented(string functionName)

This function allows the UIPM to check whether any of the optional functions are implemented by the UIPMListener.

7.3.2. Optional Functions

7.3.2.1. boolean validateValue(string sessionId, string path, string value) throws UCHNotImplementedException

The UCH validates a given value for a given path with regard to the pertaining XSD type, or runtime constraints by dependencies. The following runtime constraints are considered: length, minLength, maxLength, pattern, minInclusive, maxInclusive, minExclusive, maxExclusive.

7.3.2.2. boolean getDependencyValue(string sessionId, string path, string dependency) throws UCHNotImplementedException

Get the actual value of a dependency, pertaining to a socket set or element.

NOTE: This function does not work for 'calculate' dependencies. See function updateValues() in section void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, boolean[] hasDynRes) for how a UCH may use the 'calculate' dependency.

7.3.2.3. string getElementRef(string sessionId, string path) throws UCHNotImplementedException

Get the elementRef URI that points to a particular socket element/set. The elementRef can be used as part of the query for the label of the socket element/set, see function getResources(), section Map[] getResources(string sessionId, Map[] resProps).

NOTE: This is a convenience function for light-weight UIPMs.

7.3.2.4. boolean isSessionSuspendable(string sessionId) throws UCHNotImplementedException

Asks whether the given session can be suspended.

7.3.2.5. long suspendSession(string sessionId, long suggestedTimeout) throws UCHNotImplementedException

The target is requested to suspend the given session with a suggested timeout value.

7.3.2.6. boolean isSessionResumable(string sessionId) throws UCHNotImplementedException

Asks whether the given session can be resumed.

7.3.2.7. boolean resumeSession(string sessionId) throws UCHNotImplementedException

The target is requested to resume the given session.

7.3.2.8. void removeUIPM(IUIPM uipm)

The UIPM requests the UCH to be finalized and unloaded. UIPMs should call this function if they cannot operate anymore because of the currently available set of targets or other reasons.

The UCH may follow this request. In any case, the UCH shall call finalize() on the UIPM before it unloads the UIPM.

8. Interaction Between Target Discovery Module (TDM) and UCH

A Target Discovery Module (TDM) is responsible for discovering targets and providing information on discovered targets to the UCH. A TDM may be specific for a single target, or generic for a whole class of targets (e.g. UPnP targets).

8.1. TDM Loading and Unloading

A TDM may be retrieved from local or remote resources (e.g. resource server).

Loading of a TDM is out of scope for this specification. The UCH may load a Target Discovery Module (TDM) in a proprietary way, for example as part of the executable file, or as shared library referenced by a configuration file.

The UCH may unload a TDM at any time, but should call its finalize() function (section void finalize()) prior to unloading. The UCH should unload a TDM after the TDM has called removeTDM() (see section void removeTDM(ITDM tdm)).

8.2. Target Discovery Module Interface (ITDM)

This section specifies how the UCH will communicate with a TDM once it is installed and loaded into the application.

8.2.1. Mandatory Functions

8.2.1.1. void init(ITDMListener tdmListener, Map tdmProps, Map uchProps) throws TDMFatalException

After the TDM has been installed and loaded, the UCH calls init() prior to any other TDM function. This allows the TDM to initialize itself. Note that discovery of targets shall only start upon calling startDiscovery().

8.2.1.2. void finalize()

The UCH should call finalize() before it uninstalls or unloads the TDM. However, finalize() shall not be called after init() has thrown a TDMFatalException.

The UCH should call stopDiscovery() prior to finalize(). In any case, the TDM shall stop discovery upon finalize() is called.

8.2.1.3. Map getTDMProps()

Get property map of the TDM.

8.2.1.4. void startDiscovery() throws TDMFatalException

This function signals the TDM to start discovery of targets, until stopDiscovery() is called. Shall be ignored if the TDM is already in target discovery mode.

NOTE: The TDM will now look for new and disappearing targets, until either stopDiscovery() or finalize() is called.

8.2.1.5. void stopDiscovery() throws TDMFatalException

This function signals the TDM to stop discovery of targets, until startDiscovery() is called. Shall be ignored if the TDM is not in target discovery mode.

8.2.2. Optional Functions

8.2.2.1. void targetRequest(Object request, Object response) throws TDMFatalException

NOTE: The targetRequest() function is currently specific to HTTP requests and responses. Future versions of this document may accommodate additional URI schemes.

A TDM may implement the targetRequest() function. If it does not implement it, it shall not call the UCH's startUriService() function.

The UCH calls targetRequest() if it has received a request from a target to a URI that the TDM has claimed for itself by a previous call to startUriService(). The UCH is responsible for creating the request and response objects prior to calling targetRequest().

The request and response parameters of targetRequest() have exactly the same meaning as the request and response parameters of controllerRequest(), respectively (see section void controllerRequest(Object request, Object response) throws UIPMFatalException).

8.3. Target Discovery Manager Listener Interface (ITDMListener)

8.3.1. Mandatory Functions

8.3.1.1. string targetDiscovered(Map targetProps, Map taProps)

A TDM has discovered a new target, and provides information on the discovered target, and on the target adapter to be loaded for it. In response, the UCH will install and load an appropriate Target Adapter (TA) for the new target. If the corresponding TA is already installed (same identifier), the new target shall be registered with the already installed TA.

8.3.1.2. void targetDiscarded(string targetId)

A TDM calls this function when a target has disappeared from the network. Depending on the target and its networking platform, this can mean that the target was powered off, or just disconnected from the network.

8.3.1.3. IUCHStore getLocalUCHStore()

Get the local UCH store (a map, see section Local Data Store).

8.3.1.4. string getIpAddress()

Get the IP address of the UCH. A TDM may need this information to set up its own listener for a port that is not serviced by the UCH.

8.3.1.5. string startUriService(ITDM tdm, string scheme, int port, boolean portIsFlexible, string basePath, boolean basePathIsFlexible) throws UCHException

The TDM requests the UCH to start servicing a URI which is made up of a given scheme, port, and base path. If successful, the UCH will forward all messages that have this URI as its base, to targetRequest(). If the TDM indicates that the base path is flexible, the UCH can modify the base path in case it is not available any more.

8.3.1.6. void stopUriService(string uri) throws UCHException

The TDM requests the UCH to stop servicing a URI that was requested to be serviced in a previous call to startUriService().

8.3.1.7. Map[] getResources(string sessionId, Map[] resProps)

Same as function IUIPMListener.getResources(), see section Map[] getResources(string sessionId, Map[] resProps).

8.3.1.8. string getDocument(string uri, string postData) throws UCHException

Same as function IUIPMListener.getDocument(), see section string getDocument(string uri, string postData) throws UCHException.

8.3.1.9. Map getUCHProps()

Get property map of the UCH.

8.3.1.10. boolean isImplemented(string functionName)

This function allows the TDM to check whether any of the optional functions are implemented by the TDMListener.

8.3.2. Optional Functions

8.3.2.1. void removeTDM(ITDM tdm)

The TDM requests the UCH to be finalized and unloaded. TDMs should call this function if they cannot operate anymore because of external events or other reasons.

The UCH may follow this request. In any case, the UCH shall call finalize() on the TDM before it unloads the TDM.

9. Interaction Between Target Adapter and UCH

A Target Adapter (TA) represents one or multiple targets to the UCH. It is being installed and loaded upon the discovery of a first target that it can represent. The UCH will register new targets with the TA as they are discovered by the TDM; and unregister after they have disappeared. After having opened a session on a target's socket, the TA is responsible for managing the values of the pertaining socket instance.

NOTE: Target registration (and un-registration) is a separate step because one TA may represent multiple targets. Also, one target (type) may occur as multiple instances in a network (with different targetIds) the associated TA must be able to deal with this situation.

9.1. TA Loading and Unloading

A TA may be retrieved from local or remote resources (e.g. resource server).

The UCH should load a TA when the TA's properties match the set of properties provided by a TDM upon target discovery (see section string targetDiscovered(Map targetProps, Map taProps)). See [RES-PROP-VOCAB] for details on resource properties.

The UCH may unload a TA at any time, but should call its finalize() function (section void finalize()) prior to unloading. A UCH should unload a TA if it has no targets registered (anymore). A UCH should unload a TA after the TA has called removeTA() (see section void removeTA(ITA ta)).

9.2. Target Adapter Interface (ITA)

9.2.1. Mandatory Functions

9.2.1.1. void init(ITAListener taListener, Map taProps, Map uchProps) throws TAFatalException

When the TA is installed and loaded, the UCH calls init() prior to any other TA function. This allows the TA to initialize itself. Note that the observation of a specific target needs a separate function call, i.e. registerTarget().

NOTE: The UCH shall be prepared for the TA calling functions of the TA Listener during the execution of init(). For example, the TA may call setValidation (see section boolean setValidation(ITA ta, boolean activate)) to set the validation mode of the UCH.

9.2.1.2. void finalize()

The UCH should call finalize() before it uninstalls or unloads the TA. However, finalize() shall not be called after init() has thrown a TAFatalException.

If the UCH has targets registered with a TA (see section void registerTarget(string targetId, Map targetProps) throws TAException, TAFatalException), it should unregister them (see section void unregisterTarget(string targetId) throws TAFatalException) prior to calling finalize(). In any case, the TA shall unregister all targets when finalize() is called.

9.2.1.3. Map getTAProps()

Get property map of the TA.

9.2.1.4. void registerTarget(string targetId, Map targetProps) throws TAException, TAFatalException

The TA gets a mandate to represent a given target with a given targetId. From now on, until unregister() is called for this target, the TA shall expose the target's sockets to the UCH.

9.2.1.5. void unregisterTarget(string targetId) throws TAFatalException

Stop exposing a target to the UCH. This function is typically called when a target has disappeared from the network. If sessions are open on this target, the TA shall close these sessions (via sessionAborted, see section Target Adapter Listener Interface (ITAListener)) prior to returning from unregisterTarget.

9.2.1.6. string[] getRegisteredTargetIds() throws TAFatalException

Get the target identifiers that the TA is currently representing.

9.2.1.7. Map getLocators(string targetName)

Get a map with locator ids and locator types for a specific target type.

9.2.1.8. void invokeLocator(string targetId, string locatorId) throws TAException, TAFatalException

Invoke the specified locator function on a target. This requires a prior call to registerTarget on this target. But it is not necessary to have a session open with this target.

9.2.1.9. string getTargetName(string targetId) throws TAFatalException

Get the name (URI) of a target. Note that there may be multiple copies of targets (different targetIds) with the same target name.

9.2.1.10. string getTargetDescriptionUri(string targetName) throws TAFatalException

Get the URI for retrieving the target description.

9.2.1.11. Map getTargetProps(string targetId) throws TAFatalException

Get the target's properties.

9.2.1.12. string[] getSocketNames(string targetName) throws TAFatalException

Get the names (URIs) of a target's sockets.

NOTE: This function is provided for the convenience of light-weight UCHs. In general, a UCH could glean this information from the Target Description.

9.2.1.13. string getSocketName(string sessionId) throws TAFatalException

Get the socket name (URI) for a specified session.

9.2.1.14. string getSocketFriendlyName(string targetId, string socketName)

Get the friendly name for a socket. This is a short, human-readable name for the socket, and may be user-configured.

NOTE: A TA may use the id attribute value of the <socket> element in the target description as the socket's friendly name.

9.2.1.15. string[] getSessionIds(string targetId, string socketName) throws TAFatalException

Get the set of session identifiers for a given socket name (URI).

9.2.1.16. string getSocketDescriptionUri(string targetId, string socketName) throws TAFatalException

Get the URI for retrieving the socket description.

9.2.1.17. Map openSessionRequest(string targetId, string socketName, Map clientProps) throws TAFatalException

The UCH asks for permission to open a session with a specified client on a specified socket. Note that this function asks for permission only, and is not supposed to actually open a session.

9.2.1.18. void sessionOpened(string targetId, string sessionId, string socketName, Map clientProps) throws TAFatalException

If the TA has accepted an open session request (see above), and if the UCH succeeded in the necessary steps to open a session with the client, the UCH will call sessionOpened and provide the sessionId pertaining to the new session.

9.2.1.19. void sessionClosed(string sessionId) throws TAFatalException

The UCH signals the TA that a session has been closed with one of the TA's targets, caused by a UIPM or the UCH itself (e.g. due to session timeout). The TA should do the necessary clean-up internally and with the target.

9.2.1.20. Map setValuesRequest(string sessionId, boolean isValidated, string[] paths, string[] operations, string[] reqValues) throws TAFatalException

The client requests to change the target state in one or more operations on specified socket elements or components thereof. The requested operations are coded as cross-indexed arrays of paths, operation identifiers and requested new values. "Cross-indexed" means that array elements with the same index belong together.

9.2.1.21. Map getValues(string sessionId, string[] paths) throws TAFatalException

The client asks for the values/states of specified socket elements or components thereof.

9.2.1.22. Object[] getIndices(string sessionId, string[] eltIds, integer[] indexNos)

The UCH asks for the available values for a particular index of a dimensional socket element or set.

See section Object[] getIndices(string sessionId, string[] eltIds, integer[] indexNos).

9.2.1.23. Map[] getDynRes(string sessionId, Map[] resProps) throws TAFatalException

Get a dynamic atomic resource from the TA, pertaining to a given session. The UCH shall specify the properties of the requested resource as much as possible. A specific matching algorithm is implementation-specific. See also section Resources.

9.2.1.24. boolean isElementAvailable(string targetId, string socketName, string eltId) throws TAFatalException

This function allows the UCH to check whether a given socket element is available or not.

NOTE: Socket elements with an attribute optional="true" may not be available at runtime. Other socket elements are always available.

9.2.1.25. boolean isImplemented(string functionName)

This function allows the UCH to check whether any of the optional functions are implemented by the TA.

9.2.2. Optional Functions

9.2.2.1. boolean suspendSessionRequest(string sessionId) throws TAFatalException, TANotImplementedException

The UCH asks for permission to suspend a session. Note that this function asks for permission only, and is not supposed to actually suspend the session.

9.2.2.2. long sessionSuspended(string sessionId, long suggestedTimeout) throws TAException, TAFatalException, TANotImplementedException

The UCH signals the TA that the client has suspended a session with one of the TA's targets. The TA should do the necessary actions internally and with the target. The session is now suspended until a subsequent call to resumeSessionRequest(), or until the TA terminates the session for timing out or other reasons, in which case the TA shall call sessionAborted().

NOTE: A suspended session is in "sleep mode". During suspension, the TA will not send any updates to the UCH, and the UCH will not request to change the status of the target. The suspension can be terminated by any of the following actions: UCH calls resumeSessionRequest() and sessionResumed(); UCH calls sessionClosed(); UCH calls unregisterTarget() on the pertaining target; TA terminates session and calls sessionAborted().

9.2.2.3. boolean resumeSessionRequest(string sessionId) throws TAFatalException, TANotImplementedException

The UCH asks for permission to resume a session. Note that this function asks for permission only, and is not supposed to actually resume the session.

9.2.2.4. void sessionResumed(string sessionId) throws TAException, TAFatalException, TANotImplementedException

The UCH signals the TA that the session has resumed. A call to this function shall only occur after a resume session request has been granted by the TA (see section boolean resumeSessionRequest(string sessionId)).

9.2.2.5. void targetRequest(Object request, Object response) throws TAFatalException

NOTE: The targetRequest() function is currently specific to HTTP requests and responses. Future versions of this document may accommodate additional URI schemes.

A TA may implement the targetRequest() function. If it does not implement it, it shall not call the UCH's startUriService() function.

The UCH calls targetRequest() if it has received a request from a target to a URI that the TA has claimed for itself by a previous call to startUriService(). The UCH is responsible for creating the request and response objects prior to calling targetRequest().

The request and response parameters of targetRequest() have exactly the same meaning as the request and response parameters of controllerRequest(), respectively (see section void controllerRequest(Object request, Object response) throws UIPMFatalException).

9.3. Target Adapter Listener Interface (ITAListener)

9.3.1. Mandatory Functions

9.3.1.1. void sessionForwardRequest(string sessionId, Map forwardInfo)

The TA requests the client to open a session with a different socket. There are two types of forward requests: A "destructive forward request" asks the client to close the current session. A "spawn forward request" does not affect the current session.

9.3.1.2. void abortSession(string sessionId)

The TA has terminated a session (which may be in active or suspended mode). From now on, the TA may have no knowledge about that session any more.

9.3.1.3. void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, boolean[] hasDynRes)

The TA signals a change in the target's status, affecting one or more sessions.

NOTE: The arrays paths, operations, values and hasDynRes shall be of the same size.

9.3.1.4. void updateDynRes(string[] sessionIds, string[] eltIds)

The TA signals that the set of atomic resources pertaining to a specific session and socket element has changed. Note that this function does not provide the new set of resources, but rather waits until the UCH request a specific dynamic resource via a subsequent call to getDynRes() (see section Map[] getDynRes(string sessionId, Map[] resProps) throws TAFatalException).

NOTE: The UCH may ignore this message if it opts to not cache dynamic resources (but rather ask for dynamic resources via getDynRes() on demand).

NOTE: This is an "in-session" function which may only be called if a session is open with the TA.

9.3.1.5. IUCHStore getLocalUCHStore()

Get the local UCH store (a map, see section Local Data Store).

9.3.1.6. boolean setValidation(ITA ta, boolean activate)

The TA tells the UCH to do validation for the TA or not. Validation means that the UCH will filter out requests for setting variable values, inserting or removing indices, invoking commands, and acknowledging notifications, based on type and dependency information from the socket description. See section Map setValuesRequest(string sessionId, string[] paths, string[] operations, string[] reqValues), setValuesRequest().

NOTE: A UCH implementation may or may not support validation. If it doesn't support validation, it shall always return false.

NOTE: By default, the UCH should not do validation.

9.3.1.7. string getIpAddress()

Get the IP address of the UCH. A TA may need this information to set up its own listener for a port that is not serviced by the UCH.

9.3.1.8. string startUriService(ITA ta, string scheme, int port, boolean portIsFlexible, string basePath, boolean basePathIsFlexible) throws UCHException

The TA requests the UCH to start servicing a URI which is made up of a given scheme, port, and base path. If successful, the UCH will forward all messages that have this URI as its base, to targetRequest(). If the TA indicates that the base path is flexible, the UCH can modify the base path in case it is not available any more.

9.3.1.9. void stopUriService(string uri) throws UCHException

The TA requests the UCH to stop servicing a URI that was requested to be serviced in a previous call to startUriService().

9.3.1.10. Map[] getResources(string sessionId, Map[] resProps)

Same as function IUIPMListener.getResources(), see section Map[] getResources(string sessionId, Map[] resProps).

9.3.1.11. string getDocument(string uri, string postData) throws UCHException

Same as function IUIPMListener.getDocument(), see section string getDocument(string uri, string postData) throws UCHException.

9.3.1.12. Map getUCHProps()

Get property map of the UCH.

9.3.1.13. boolean isImplemented(string functionName)

This function allows the TA to check whether any of the optional functions are implemented by the TAListener.

9.3.2. Optional Functions

9.3.2.1. void removeTA(ITA ta)

The TA requests the UCH to be finalized and unloaded. TAs should call this function if they cannot operate anymore because of external events or other reasons.

The UCH may follow this request. In any case, the UCH shall call finalize() on the TA before it unloads the TA.

10. Control Flows

For simplicity, the sequence diagrams below assume synchronous function execution. This does not imply that the specification mandates synchronous function execution. This is implementation-specific.

10.1. Target Discovery

Sequence diagram for target discovery

Figure: Sequence diagram for target discovery (description of figure)

10.2. Session Management

Sequence diagram for session management

Figure: Sequence diagram for session management (description of figure)

10.3. Session Forwarding

Sequence diagram for session forwarding

Figure: Sequence diagram for session forwarding (description of figure)

10.4. Target Aborts Session

Sequence diagram for target aborting session

Figure: Sequence diagram for target aborting session (description of figure)

10.5. Open Session Activities

Sequence diagram for open session acitivites

Figure: Sequence diagram for open session acitivites (description of figure)

11. Discovery of the UCH and Its Remote User Interfaces

This section specifies how a controller discovers a UCH in a network, and available remote user interfaces implemented by UIPMs.

This discovery mechanism applies for remote user interfaces that can be identified through a URI that is resolvable in a local network context. UIPMs may use other mechanisms to make themselves discoverable to controllers, but this is out of the scope of this specification.

The mechanism defined in this section is based on [UPnP RUI] and [CEA-2014], and uses target instances as a top-level structuring mechanism of available user interfaces in a local network.

NOTE: There may be multiple control hubs in a local network. It is up to the controller how to offer an integrated view, consisting of multiple UCHs and their offered control interfaces to the user.

11.1. RUI Server

A UCH shall expose itself as a Remote User Interface Server [CEA-2014] in a local network, through one of the following mechanisms:

NOTE: See [CEA-2014] for details on how the UIList document (XML block) can be retrieved from an RUI Server.

A UCH may opt to use HTTP code 301 (Moved Permanently) for one of the HTTP or HTTPS requests to redirect the client to the other protocol. In this case, the RUI Client may automatically redirect the request.

11.2. UIList

The UIList shall consist of user interfaces and their URIs, as advertised by the UIPMs through the addCompatibleUI() function (see section boolean addCompatibleUI(string targetId, string[] socketNames, string protocolShortName, string[] uris, Map protocolInfo) throws UCHException), in any order, as follows:

<uilist xmlns="urn:schemas-upnp-org:remoteui:uilist-1-0">
  <ui>
    <uiID>targetId </uiID>
    <name>targetFriendlyName </name>
    <protocol shortName="protocolShortName ">
      <uri>remoteControlUri </uri>
      <protocolInfo>
        <targetName>targetName </targetName>
        <socketName friendlyName="socketFriendlyName ">socketName </socketName>
        ... other protocolInfo subelements specific to protocolShortName ...
      </protocolInfo>
    </protocol>
  </ui>
</uilist>

Whereby:

NOTE: [UPnP RUI] uses the concepts of "remote user interfaces" and "applications" in equivalent ways. In a UCH environment, target instances can be construed as "applications". However, one target instance ("application") may have multiple sockets which can be individually accessed and controlled. Still, the target instance is a reasonable parameter for top-level structuring of the UIList. But controllers should not assume that all <protocol> elements underneath a <ui> element are representing equivalent user interfaces.

NOTE: As in all XML documents, leading and trailing whitespaces in element content will get lost if not properly escaped. In particular, leading and trailing spaces, occurring in target identifiers and target friendly names, shall be encoded as '&#x20;'.

EXAMPLE: The following UIList exposes an "all-in-one" control application, and specific control applications for an "AV System" and a "Telephone". All applications provide the "HTTP/HTML" UI protocol. In addition, "AV System" and "Telephone" provide access through the "URC-HTTP" UI protocol . See [URC-HTTP] for details on the format of the <protocolInfo> subelement of <protocol shortName="URC-HTTP">. Note that some URIs have been split into two lines for presentation purposes they need to be in one line in the actual UIList document.

<uilist xmlns="urn:schemas-upnp-org:remoteui:uilist-1-0">
  <ui>
    <uiID> all </uiID>
    <name> All targets </name>
    <protocol shortName="HTTP/HTML">
      <uri>http://192.168.0.10/UCH/all/html</uri>
      <protocolInfo>
        <targetName> all </targetName>
      </protocolInfo>
    </protocol>
  </ui>
  <ui>
    <uiID> ABC001</uiID>
    <name>AV System </name>
    <protocol shortName="URC-HTTP">
      <uri> http://192.168.0.10/UCH/av/urc-http/play?ABC001 </uri>
      <protocolInfo>
        <targetName> http://res.myurc.org/upnp/av </targetName>
        <socketName> http://res.myurc.org/upnp/av/play-1.uis </socketName>
        <socketDescriptionAt> http://res.myurc.org/upnp/av/play-1.uis </socketDescriptionAt>
        <targetDescriptionAt> http://res.myurc.org/upnp/av/entertainment.td </targetDescriptionAt>
        <conformsTo> http://myurc.org/TR/urc-http-protocol-20080627 </conformsTo>
      </protocolInfo>
    </protocol>
    <protocol shortName="HTTP/HTML">
      <uri>http://192.168.0.10/UCH/av/html?http%3A%2F%2F192.168.0.10%2FUCH%2Fav%2Furc-http%2Fplay%3FABC001 </uri>
      <protocolInfo>
        <targetName> http://res.myurc.org/upnp/av</targetName>
        <socketName>http://res.myurc.org/upnp/av/play-1.uis</socketName>
      </protocolInfo>
    </protocol>
  </ui>
  <ui>
    <uiID> RRR0001</uiID>
    <name>Telephone</name>
    <description>Landline-based phone system.</description>
    <lifetime>60</lifetime>
    <protocol shortName="URC-HTTP">
      <uri> http://192.168.0.10/UCH/phone/urc-http?RRR0001 </uri>
      <protocolInfo>
        <targetName> http://res.myurc.org/anymodel/phone </targetName>
        <socketName> http://res.myurc.org/anymodel/phone.uis </socketName>
        <socketDescriptionAt> http://res.myurc.org/anymodel/phone.uis </socketDescriptionAt>
        <targetDescriptionAt> http://res.myurc.org/anymodel/phone.td </targetDescriptionAt>
        <conformsTo> http://myurc.org/TR/urc-http-protocol-20080627 </conformsTo>
      </protocolInfo>
    </protocol>
    <protocol shortName="HTTP/HTML">
      <uri> http://192.168.0.10/UCH/phone/html?http%3A%2F%2F192.168.0.10%2FUCH%2Fphone%2Furc-http%3FRRR0001 </uri>
      <protocolInfo>
        <targetName> http://res.myurc.org/anymodel/phone </targetName>
        <socketName> http://res.myurc.org/anymodel/phone.uis </socketName>
      </protocolInfo>
    </protocol>
  </ui>
</uilist>

11.3. 'shortName' Attribute

Based on the information from the installed TAs, a UCH shall identify the user interface protocols it exposes through its TAs, as attribute values of the 'shortName' attribute of the <protocol> elements. The following table summarizes the short names for UI protocols, as defined by [UPnP RUI] and [CEA-2014]. Other UI protocols (and corresponding shortNames) may be defined by other standards, thus extending this document.

shortName

URI scheme

Description

Comment

HTTP/HTML

HTTP:

The application supports remoting with HTML using HTTP as transport.

From [UPnP RUI]

RDP

RDP:

The application supports remoting with Microsoft RDP protocol.

From [UPnP RUI]

VNC

VNC:

The application supports remoting with AT&T VNC protocol.

From [UPnP RUI]

XRT2

The application supports remoting with Intel XRT2 protocol.

From [UPnP RUI]

LRDP

The application supports remoting with Nokias' LRDP protocol.

From [UPnP RUI]

XHT

The application supports remoting with Samsungs' XHT protocol.

From [UPnP RUI]

SGXML

The application supports remoting with Siemens' Gigaset XML protocol.

From [UPnP RUI]

UIF

The application supports remoting with Philips UI Fragments protocol.

From [UPnP RUI]

(Vendor-specific protocol name)

(Specified by UPnP vendor.)

From [UPnP RUI]

CE-HTML-1.0

HTTP:
HTTPS:

CE-HTML (extension of HTML), as defined in [CEA-2014]

The requirement from [CEA-2014] that there shall be at least one CE-HTML protocol per UI is not required for a UCH.

URC-HTTP

HTTP:
HTTPS:

URC-HTTP protocol

See [URC-HTTP] for details on how to implement the URC-HTTP protocol.

XRT

XRT:
XRTS:

XRT Self-Contained Remoting Protocol

Replaces "XRT2" from [UPnP RUI].

11.4. User-Preferred Language

The UCH should respect the user's language preferences when responding to a request for the UIList. The user's language preferences are specified in the HTTP request header "Accept-Language" .

12. Acknowledgments

Work on this document has been funded in part by the National Institute on Disability and Rehabilitation Research, US Dept of Education under Grant H133E030012 as part of the Universal Interface and Information Technology Access Rehabilitation Engineering Research Center of the University of Wisconsin -Trace Center. The content of this document does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.

Work on this document has been funded in part by the EU 6th Framework Program under grant FP6-033502 (project i2home). The content of this document does not necessarily reflect the views or policies of the European Commission, nor does mention of trade names, commercial products, or organizations imply endorsement by the European Commission.

The following persons have contributed to the content of this document:

This site is maintained by the University of Wisconsin Trace Center, a member of the Universal Remote Console Consortium.