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

Universal Control Hub 1.0 (DRAFT)

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:

• Initial release as draft for review. 

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:

• Support for the UIPM API, as specified in section API of UIPM (IUIPM);
• Implementation of the UIPM Listener interface, as specified in section API of UIPM Listener (IUIPMListener);
• Support for TDM API, as specified in section Target Discovery Module Interface (ITDM),
• Implementation of the TDM Listener interface, as specified in section Target Discovery Manager Listener Interface (ITDMListener),
• Support for TA API, as specified in section Target Adapter Interface (ITA),
• Implementation of the TA Listener interface, as specified in section Target Adapter Listener Interface (ITAListener).
• Implementation of a discovery mechanism, as specified in section Discovery of the UCH and Its Remote User Interfaces.

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

• Implementation for the UIPM API, as specified in section API of UIPM (IUIPM);
• Support for the UIPM Listener interface, as specified in section API of UIPM Listener (IUIPMListener);

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

• Implementation of the TDM API, as specified in section Target Discovery Module Interface (ITDM),
• Support for the TDM Listener interface, as specified in section Target Discovery Manager Listener Interface (ITDMListener),

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

• Implementation of the TA API, as specified in section Target Adapter Interface (ITA),
• Support for the TA Listener interface, as specified in section Target Adapter Listener Interface (ITAListener).

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

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:

• More natural for object-oriented languages (Java, C++)
• Slightly better performance for object-oriented languages (e.g. using session pointers rather than session ids and hash tables for managing sessions)

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:

• Works for all languages (including non-object-oriented like C)
• Element values are passed as strings (no types or type checking)
• More suitable for cross-language interfaces (e.g. using JavaScript as glue code between Java and Flash)
• Only one interface to implement, and one to listen to
• More in line with URC-HTTP protocol

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

• synchronously if they have a return type (not "void");
• synchronously or asynchronously if they have no return type ("void").

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

• key: Key (string) for the value.
• Return value: Value stored under the given key. The caller may need to cast the returned object into the correct type. The return value is NULL if no entry exists for the given key.

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.

• key: Key (string) for the value.
• value: value to be stored under the key.

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.

• uipmListener: Object in the UCH implementing the IUIPMListener interface (see section API of UIPM Listener (IUIPMListener)). The UIPM will call the uipmListener's functions to communicate with the UCH.
• uipmProps: Property map for UIPM configuration, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. See also section Property Map.
• uchProps: Property map for the UCH, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. See also section Property Map.
• UIPMFatalException: In case the UIPM cannot initialize itself, it throws a UIPMFatalException. In this case the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• Return value: Property map for the UIPM at runtime. The UIPM shall return the uipmProps map it got when init() was called (see section void init(IUIPMListener uipmListener, Map uipmProps, Map uchProps) throws UIPMFatalException), optionally with additional properties added. See also section Property Map and [RES-PROP-VOCAB].

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.

• targetId: Globally unique target instance identifier.
• UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down. From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• targetId: Globally unique target instance identifier.
• UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down. From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• sessionId: UCH-internal session identifier.
• forwardInfo: Map (property-value pairs) with the following properties:
  • forwardType: "D"=destructive, "S"=spawn.
  • NOTE: After a destructive forward request, the UIPM should close the current session by calling closeSession(), see section void closeSession(string sessionId).
  • targetId (shall be present if target instance identifier available): Same meaning as defined in section void sessionForwardRequest(string sessionId, Map forwardInfo).
  • targetName (shall be present if target instance identifier not available): Same meaning as defined in section void sessionForwardRequest(string sessionId, Map forwardInfo).
  • socketName (shall be present): Same meaning as defined in section void sessionForwardRequest(string sessionId, Map forwardInfo).
  • authorizationCode (may be present): Same meaning as defined in section void sessionForwardRequest(string sessionId, Map forwardInfo).
• UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down. From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). The exception shall include a text string describing the problem that occurred.

7.2.1.7. void sessionAborted(string sessionId) throws UIPMFatalException

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

• sessionId: UCH-internal session identifier.
• UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down. From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). The exception shall include a text string describing the problem that occurred.

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().

• sessionIds: Array with UCH-internal session identifiers. The status change applies to all sessions that are included in the array.
• paths: as specified in section void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, boolean[] hasDynRes).
• operations: as specified in section void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, boolean[] hasDynRes).
• values: as specified in section void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, boolean[] hasDynRes).
• hasDynRes: as specified in section void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, boolean[] hasDynRes).
• UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down. From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• functionName: Any of the name of the optional functions below, without parentheses.
• Return value: true=function implemented, false=function not available.

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().

• request: Request object (specific to programming language and URI scheme used), containing all information regarding the request that the controller sent.
  • For Java implementations, the request object shall implement:
    • javax.servlet.http.HttpServletRequest for the HTTP scheme [Java Servlet API]
    • javax.servlet.ServletRequest for other URI schemes [Java Servlet API]
  • For C/C++ implementations, the request object shall implement:
    • A Map object with the following keys (values are strings):
      • "RequestPath": abs_path part of URL, as defined in [RFC 2616].
      • "QueryString": query part of URL, as defined in [RFC 2616].
      • "RequestBody": Post data (content) of an HTTP request
      • Any general, request or entity header fields, as specified by [RFC 2616], [RFC 2109] or [RFC 2965]. Examples of field names: "Cache-Control", "Connection"; "Accept", "Accept-Charset", "Accept-Encoding", "Accept-Language", "Authorization", "User-Agent"; "Allow", "Content-Encoding", "Content-Language", "Content-Type", "Cookies", "Set-Cookies".
        • For each header or entity field in the request, the UCH shall provide one key-value pair in the map, with the key being the header name (with the trailing ':' being truncated), and the value being the exact content string as given for the header in the request (with the trailing line break being truncated).
        • NOTE: [RFC 2109] is obsolete by [RFC 2965]. However, in practice, many implementations are still using [RFC 2109].
  • For .NET/C# implementations, the request object shall implement:
    • System.Net.HttpListenerRequest
• response: Response object (specific to programming language and URI scheme used), containing information regarding the response to the controller.
  • For Java implementations, the response object shall implement:
    • javax.servlet.http.HttpServletResponse for the HTTP scheme [Java Servlet API]
    • javax.servlet.ServletResponse for other URI schemes [Java Servlet API]
  • For C/C++ implementations, the response object shall implement:
    • A Map object with the following properties with string values:
      • "ResponseBody": Post data (content) for the HTTP response, as defined in [RFC 2616].
      • "HttpStatus": HTTP status code for the HTTP response, as defined in [RFC 2616].
      • Any general, response or entity header fields, as specified by [RFC 2616], [RFC 2109] or [RFC 2965]. Examples of field names: "Cache-Control", "Connection"; "Accept-Ranges", "Age", "Server", "WWW-Authenticate", "Authorization"; "Allow", "Content-Encoding", "Content-Language", "Content-Type", "Cookies", "Set-Cookies".
        • For each key-value pair in the map, the UCH shall include a header field in the response, with the header being the key (a ':' shall be appended by the UCH), and its content being the exact value string (a line break shall be appended by the UCH).
        • NOTE: [RFC 2109] is obsolete by [RFC 2965]. However, in practice, many implementations are still using [RFC 2109].
  • For .NET/C# implementations, the response object shall implement:
    • System.Net.HttpListenerResponse
• UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down. From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• Return value: Array with globally unique target instance identifiers.

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.

• targetId: Globally unique target instance identifier.
• Return value: Name (URI) of the target.

7.3.1.3. Map getTargetProps(string targetId)

Get a property map for a target.

• targetId: Globally unique target instance identifier.
• Return value: Property map of target at runtime, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. See also section Property Map.

7.3.1.4. string getTargetDescriptionUri(string targetName)

Get the URI for retrieving the target description.

• targetName: Name (URI) of the target.
• Return value: Absolute URI for the target description. The URI may point to a local or a global location, but must be resolvable.

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.

• uri: URI of HTTP request (may include query parameters).
• postData: Data for POST method as string. NULL if GET method requested.
• Return value: Received document as string.
• UCHException: An HTTP error occurred. Should contain the error message as text, e.g. "404 Not found".

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.

• targetName: Name (URI) of the target.
• Return value: Array with socket names (URI) of the target type.

7.3.1.7. string getSocketDescriptionUri(string targetName, string socketName)

Get the URI for retrieving the socket description.

• targetName: Name (URI) of the target.
• socketName: Name (URI) of the socket.
• Return value: Absolute URI for the socket description. The URI may point to a local or a global location, but must be resolvable.

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.

• sessionId: UCH-internal session identifier.
• Return value: socket name (URI).

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.

• targetId: Globally unique target instance identifier.
• Return value: Friendly name 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.

• targetName: Name (URI) of the target.
• Return value: Map with:
  • keys: locator ids (strings)
  • values: locator types (strings), one of {"audio", "visual", "other"} (see ISO/IEC 24752-4:2008, section 6.7).

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.

• targetId: Globally unique target instance identifier.
• locatorId: 'id' attribute of the locator, as specified in returned map of getLocators() (see section Map getLocators(string targetName)).

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.

• targetId: Globally unique target instance identifier.
• socketName: Name (URI) of a socket.
• eltId: element identifier, as specified by the 'id' attribute of a socket element in the socket description.

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.

• sessionId: UCH-internal session identifier. May be NULL (in which case dynamic atomic resources are not included in the returned result).
• NOTE: sessionId should be specified by the caller, if available, since atomic resources that are dynamic can only be included in the result if the session is known by the UCH.
• resProps: Map with Property-value pairs, duplicate properties with different values are allowed (they are interpreted as values that all need to be present on a resource, resulting in an implicit AND operation on the property values). Property names are URIs [RFC 3986].
  • For atomic resources, an extensible set of RDF properties is defined in ISO/IEC 24752-5, Resource Description. Note that this assumes a flattened structure of an atomic resource description, for a single context only.
  • Requests for atomic resources shall have a property "http://myurc.org/ns/res#type" with value "http://myurc.org/restypes#atomic".
  • For other resources, RDF properties and their URIs may be defined by other standards or documents, preferably under the URC Consortium. See [RES-PROP-VOCAB] for a list of core properties in the URC ecosystem.
• EXAMPLE: The following map instance requests an English text label (atomic resource) for the value "true" of the 'power' element in the socket description "http://example.com/socket", and the label being published by "MyCorp".
  • Property="http://myurc.org/ns/res#eltRef", ["http://example.com/socket#power"]
  • Property="http://myurc.org/ns/res#role", Values=["http://myurc.org/ns/res#label"]
  • Property="http://myurc.org/ns/res#forLang", Values=["en"]
  • Property="http://myurc.org/ns/res#valRef", Values=["true"]
  • Property="http://purl.org/dc/elements/1.1/type", Values=["Text"]
  • Property="http://purl.org/dc/elements/1.1/publisher", Values=["MyCorp"]
• Note that the values in this map are arrays of strings. Thus multiple (ANDed) values can be assigned to one property, if appropriate.
• Return value: Array of maps, each containing the requested resource (in their pertaining type - e.g. string for textual resource), and the complete set of metadata assigned to it. The maps are in the order of the requests (i.e. for every request item in the 'resProps' array, there shall be a response item in the returned array). If no match can be found for a request item, the corresponding response item shall be NULL.
  • The actual resource object shall be assigned to the key "content" (in a platform-specific type reflecting the nature of the resource, e.g. string, image), or retrievable by URI reference (e.g. in "file:" format for locally stored files) given as value of the key "contentAt". Note that it is up to the UCH to decide which resources to provide as object, and which to provide as URI reference (this may depend on the MIME type of the resource).
  • Caching may apply in an implementation-specific way.

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.

• uipm: UIPM object (caller) that is opening a session with the UCH.
• targetId: Globally unique target instance identifier
• socketName: Name (URI) of the socket that the UIPM wants to connect to.
• clientProps: Property map of the client requesting a session opening, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. See also section Property Map.
  • Note that the property http://myurc.org/ns/res#authorizationCode may be used to convey an authorization code for opening the session. The authorization code may have been provided by a previous session that requested a forward to the specified socket.
• Return value: Map (property-value pairs) with the following properties:
  • result: "A"=accept, "R"=reject, "F"=forward.
  • sessionId (shall be present if result="A"): UCH-internal identifier for the new session.
  • targetId or targetName (either one shall be present if result="F"): as specified in section void sessionForwardRequest(string sessionId, Map forwardInfo).
  • socketName (shall be present if result="F"): as specified in section void sessionForwardRequest(string sessionId, Map forwardInfo).
  • authorizationCode (may be present if result="F"): as specified in section void sessionForwardRequest(string sessionId, Map forwardInfo).

7.3.1.15. void closeSession(string sessionId)

The UIPM closes a session with the UCH.

• sessionId: UCH-internal session identifier.

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

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

• sessionId: UCH-internal session identifier.
• paths: Array of paths, each item of any of the forms specified in section Paths.
• Return value: Map containing path-values corresponding (in their order) to the elements of argument paths. However, invalid paths shall be omitted in the returned map.

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.

• sessionId: UCH-internal session identifier.
• eltIds: Array of element ids ('id' attribute values of socket elements or sets).
• indexNos: Array of 0-based index numbers (0 specifies the first index). Note that the index number refers to the dimensions of a single socket element or set, not to its path (i.e. indices of dimensional ancestor sets do not count here).
  • EXAMPLE: A set with id="set" and dim="xsd:integer xsd:string" has two indices. getIndices(sessionId, ["set"], [1]) would request the available values for the second index (which is of type xsd:string).
• Return value: Array with index ranges, each array item corresponding (in their order) to the elements of arguments 'eltIds' and 'indexNos'. Each item shall be either NULL (for an invalid eltIds item or indexNos item) or an array containing the requested index values as items, which should be in ascending order as specified by their pertaining types, if applicable.

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.

• sessionId: UCH-internal session identifier.
• paths: Array of paths, each item of any of the forms specified in section Path. This array is cross-indexed with the values and the operations array, i.e. they have the same size, and items with the same index are corresponding.
• operations: Array of operation codes. The following codes are allowed:
  • "S"=set value of variable or local command parameter (not with path for command state, and not referencing a notification)
  • "A"=add indices (only with path with given indices)
  • "R"=remove indices (only with path without indices, path with given indices)
  • "I"=invoke (only with path for command state). Pertaining local parameters shall be, and global parameters may be specified by preceding array elements (with an "S" operation) of the same call.
  • "K"=acknowledge (only with path without indices, or path with given indices, referencing a notification)
  • NOTE: Invalid operation codes and operation codes that are not applicable to the pertaining paths should be ignored by the UCH.
• reqValues: Array of requested values, as strings. Corresponding items for operation "A" (add indices) may be NULL. Corresponding items for operations "R" (remove indices) and "K" (acknowledge) shall be NULL.
• Return value: Map contains all path-values that were updated in response to the request, but only those that occurred in-session to parameter 'sessionId'. This includes new values for variables, new states for commands, and new states for notifications. Note that the indices of the returned map do not necessarily correspond to the indices of the arguments path, operations and reqValues.
  • NOTE: Out-of-session changes may be propagated to the UIPM through updateValues(), even before setValuesRequest() has been finished().

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.

• Return value: ip address of UCH as string.

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.

• uipm: UIPM object (caller) that is requesting service for a URI with the UCH. The controllerRequest() function of this object will be called upon a controller request to the specified URI.
• scheme: URI scheme, such as "http", "ftp", "urn", "vnc", etc.
• port: number of port for listening to controller requests. 0 if no preference for port number.
• portIsFlexible: true if the UCH may modify the port number, otherwise false. Must be true if parameter port is 0.
• basePath: base path for the URI, e.g. "/UCH/flash".
• basePathIsFlexible: true indicates that the UCH may modify the base path in case the specified path is already taken. false indicates that the UCH may not modify the base path if the path is already taken the function returns NULL.
• Return value: URI for which the UCH has started service for the UIPM (e.g. "http://192.168.0.10/UCH/URC/"). If the URI is based on a hierarchical folder system, the URI shall end with a folder delimiter ('/' in case of http and ftp). Note that, if the path is flexible, the path may have been modified by the UCH (e.g. modify "Flash" to "Flash01", etc.). Returns NULL if the UCH cannot service the specified URI.
• UCHException: Invalid request.

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().

• uri: URI that the UCH is requested to stop servicing. URI has been returned by the UCH in a previous call to startUriService().
• UCHException: Invalid request.

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.

• targetId: Globally unique target instance identifier for the target that the UI controls. Value "all" allowed if the UI controls all target instances together. If the UI is for a subset of available target instances, addCompatibleUI() has to be called multiple times, once for each targetId.
  • NOTE: The value "all" is not allowed in conjunction with a protocolShortName of "URC-HTTP" (see [URC-HTTP]).
• socketNames: Names (URIs) of the sockets that the UI connects to. Empty array if the UI connects to all available sockets.
  • NOTE: An empty array of socket names is represented as element content "all" for <socketName> in the UIList (see section UIList).
• protocolShortName: Short name for the UI protocol used, to be used as value of the 'shortName' attribute of the <protocol> element in the UIList [UPnP RUI].
  • Examples: "URC-HTTP", "HTTP/HTML", "CE-HTML-1.0", "VNC".
• uris: URIs for controllers to communicate with the UIPM (e.g. opening a control session). All URIs shall contain identical scheme, port and base URL (that was previously assigned to the UIPM by the UCH, see section string startUriService(IUIPM uipm, string scheme, int port, boolean portIsFlexible, string basePath, boolean basePathIsFlexible)). The UCH will include the URIs in the UIList as element content of the <uri> tags [UPnP RUI].
• protocolInfo: Map with property-value pairs to be advertised by the UCH as subelements of the <protocolInfo> element in a UIList (see section UIList). Property names shall be strings, each reflecting the tag name of a pertaining XML element (default namespace assumed). Values shall be strings. The default rules for properties names (see section Property Names) do not apply to protocolInfo.
• Return value: true = UCH has added UI to UIList. false = UCH could not add the UI to the UIList.
• UCHException: Invalid request.

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

• <uiID> contains the targetId. The UCH shall merge multiple calls to addCompatibleUI() with the same targetId into one <uiID> block (with separate <protocol> subelements for each call).
• <name> contains the friendly name of the target, if provided by the TDM in targetDiscovered() (as value of property http://myurc.org/ns/res#friendlyName in targetProps); otherwise the target's label as defined for the corresponding targetName (URI). If provided, the target's label should accommodate the user's language preferences (see section User-Preferred Language).

  NOTE: The friendly name of a target is a human-readable name of the target instance. This is typically a user-configurable label, such as "bedroom TV".

• The 'uris' parameter shall result in one or multiple <uri> elements, each containing one URI for the protocol.
• <targetName> shall contain the name (URI) of the target with the specified targetId.
• <socketName> shall provide the names of the involved sockets (if any), as given by the socketNames parameter. If no socket name is provided, no <socketName> element shall exist. If multiple socket names are provided, multiple <socketName> elements shall exist. The 'friendlyName' attribute on each <socketName> element may bear the 'id' attribute value of the corresponding <socket> element in the target description. Alternatively, it may bear an atomic resource label for the socket (in which case it should match the user-preferred language, see section User-Preferred Language).
• Other subelements of <protocolInfo> shall be included, as specified in the protocolInfo map argument.

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.

• uris: array of URIs to pull from the UIList. This must be identical as used for a previous call to addCompatibleUI().
• UCHException: Invalid URIs. The exception shall include a text string describing the problem that occurred.

7.3.1.24. IUCHStore getLocalUCHStore()

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

• Return value: Local UCH Store.

7.3.1.25. Map getUCHProps()

Get property map of the UCH.

• Return value: Property map for the UCH at runtime, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur.

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.

• functionName: Any of the name of the optional functions below, without parentheses. EXAMPLE: "validateValue".
• Return value: true=function implemented, false=function not available.

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.

• sessionId: UCH-internal session identifier.
• path: Path of a pertaining socket variable or local parameter (or component thereof), as specified in section Paths.
• value: Value to be checked against the variables/parameter's type and runtime constraints.
• Return value: true=valid value, false=invalid value.
• UCHNotImplementedException: Thrown if UCH does not support this function.

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.

• sessionId: UCH-internal session identifier.
• path: Path of a pertaining socket set or element (or component thereof), as specified in section Paths.
• dependency: One of the following strings:
  • "relevant"
  • "write"
  • "insert" (only allowed if path specifies a dimensional set or element)
• Return value: Current value of the specified dependency. NULL if 'insert' dependency asked for a non-dimensional set of element.
• UCHNotImplementedException: Thrown if UCH does not support this function.

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.

• sessionId: UCH-internal session identifier.
• path: Path of a pertaining socket set or element (or component thereof), as specified in section Paths.
• Return value: URI pointing to the socket element/set, consisting of a domain URI and the element's identifier (as fragment identifier), separated by a '#' character.
  • EXAMPLE: "http://example.com/socket#power".

7.3.2.4. boolean isSessionSuspendable(string sessionId) throws UCHNotImplementedException

Asks whether the given session can be suspended.

• sessionId: UCH-internal session identifier.
• Return value: true=session can be suspended, false=session cannot be suspended.
• UCHNotImplementedException: Thrown if UCH does not support this function.

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.

• sessionId: UCH-internal identifier of an active session (not already suspended).
• suggestedTimeout: Timeout (in seconds) the UIPM suggests indicating a time period for the target to keep the session for subsequent resume operation.
• Return value: Tentative timeout (in seconds) from the target / 0 if the target has rejected the request. The target intends to hold the session for subsequent resume operation for the timeout period. However, this is not a guaranteed value the target may terminate the session at any time for any reason.
• UCHNotImplementedException: Thrown if UCH does not support this function.

7.3.2.6. boolean isSessionResumable(string sessionId) throws UCHNotImplementedException

Asks whether the given session can be resumed.

• sessionId: UCH-internal session identifier.
• Return value: true=session can be resumed, false=session cannot be resumed.
• UCHNotImplementedException: Thrown if UCH does not support this function.

7.3.2.7. boolean resumeSession(string sessionId) throws UCHNotImplementedException

The target is requested to resume the given session.

• sessionId: UCH-internal identifier of a suspended session.
• Return value: true=session resumed, false=session could not be resumed. If false, the session has terminated, and the UIPM shall not call resumeSession() or closeSession() any more on this session.
• UCHNotImplementedException: Thrown if UCH does not support this function.

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.

• uipm: UIPM object (caller) that wants to be removed.

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().

• tdmListener: Object in the UCH implementing the ITDMListener interface (see section Target Discovery Manager Listener ). The TDM will call the tdmListener's functions to communicate with the UCH.
• tdmProps: Property map for TDM, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. See also section Property Map.
• uchProps: Property map for the UCH, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur.
• TDMFatalException: In case the TDM cannot initialize itself, it throws a TDMFatalException. In this case the UCH should call no function of the TDM anymore, and may unload the TDM (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• Return value: Property map for the TDM at runtime, with properties as specified in [RES-PROP-VOCAB]. This shall be the tdmProps map it got when init() was called (see section void init(ITDMListener tdmListener, Map tdmProps, Map uchProps) throws TDMFatalException), optionally with additional properties added. See also section Property Map.

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.

• TDMFatalException: In case the TDM encounters an error condition that prevents discovery and cannot be fixed, it throws a TDMFatalException. In this case the UCH should call no function of the TDM anymore, and may unload the TDM (without calling finalize). The exception includes a text string describing the problem that occurred.

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.

• TDMFatalException: The TDM has encountered an error condition that cannot be fixed. In this case the UCH should call no function of the TDM anymore, and may unload the TDM (without calling finalize). The exception includes a text string describing the problem that occurred.

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.

• targetProps: Property map for the target at runtime. Any property as specified for Targets in [RES-PROP-VOCAB] may be present, but none is required by the TDM (the TA is responsible for completing the missing properties later, though). Additional (implementation-specific) properties may occur. Note that targetProps should contain adequate information for registering the target with the Target Adapter so that it can uniquely identify and connect to it in a network. See also section Property Map.
• taProps: Property map for target adapter (TA) that should help the UCH to find an appropriate TA at runtime. Any property as specified for TAs in [RES-PROP-VOCAB] may be present, but none is required (since these properties are used for querying a TA). Other (implementation-specific) properties may occur.
  • Special case: If the property http://myurc.org/ns/res#name is present, the UCH shall retrieve and use the TA with the given identifier (no need for querying).
• Return value: The UCH shall return the targetId (string) that it has assigned the newly discovered target. This may be identical to the property 'http://myurc.org/ns/res#instanceId' in targetProps, if globally unique. NULL if the UCH does not instantiate a Target Adapter for this target, and does not want to be notified when the target will be discarded.
  • NOTE: The TDM is responsible for storing the targetId for the discovered target. It will be needed for signaling the disappearance of the target via the function targetDiscarded().

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.

• targetId: Globally unique target instance identifier

8.3.1.3. IUCHStore getLocalUCHStore()

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

• Return value: Local UCH 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.

• Return value: ip address of UCH as string.

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.

• tdm: TDM object (caller) that is requesting service for a URI with the UCH. The targetRequest() function of this object will be called upon a request to the specified URI.
• scheme: URI scheme, such as "http", "ftp", "urn", "vnc", etc.
• port: number of port for listening to requests. 0 if no preference for port number.
• portIsFlexible: true if the UCH may modify the port number, otherwise false. Must be true if parameter port is 0.
• basePath: base path for the URI.
• basePathIsFlexible: true indicates that the UCH may modify the base path in case the specified path is already taken. false indicates that the UCH may not modify the base path if the path is already taken the function returns NULL.
• Return value: URI for which the UCH has started service for the TDM (e.g. "http://192.168.0.10/TDM/"). If the URI is based on a hierarchical folder system, the URI shall end with a folder delimiter ('/' in case of http and ftp). Note that, if the path is flexible, the path may have been modified by the UCH (e.g. modify "TDM" to "TDM01", etc.). Returns NULL if the UCH cannot service the specified URI.
• UCHException: Invalid request.

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().

• uri: URI that the UCH is requested to stop servicing. URI has been returned by the UCH in a previous call to startUriService().
• UCHException: Invalid request.

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.

• Return value: Property map for the UCH at runtime, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur.

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.

• functionName: Any of the name of the optional functions below, without parentheses. EXAMPLE: "removeTDM".
• Return value: true=function implemented, false=function not available.

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.

• tdm: TDM object (caller) that wants to be removed.

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.

• taListener: Object in the UCH implementing ITAListener interface (see section Target Adapter Listener). The TDM will call the tdmListener's functions to communicate with the UCH.
• taProps: Property map for TA configuration, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. See also section Property Map.
• uchProps: Property map for the UCH, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. See also section Property Map.
• TAFatalException: In case the TA cannot initialize itself, it throws a TAFatalException. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• Return value: Property map for the TA at runtime. This shall be the taProps map it got when init() was called (see section void init(ITAListener taListener, Map taProps, Map uchProps) throws TAFatalException), optionally with additional properties added. See also section Property Map and [RES-PROP-VOCAB].

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.

• targetId: Globally unique target instance identifier. The TA is responsible for remembering the targetId in connection with the specific target.
• targetProps: Property map for target, as passed on by the TDM that discovered the target (see section string targetDiscovered(Map targetProps, Map taProps)).
• TAException: If the TA, for any reason, cannot find or connect to the target, it throws a TAException. In this case the UCH may try to register the target with a different TA. The exception shall include a text string describing the problem that occurred.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• targetId: Globally unique target instance identifier.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

9.2.1.6. string[] getRegisteredTargetIds() throws TAFatalException

Get the target identifiers that the TA is currently representing.

• Return value: Array with Globally unique target instance identifiers.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

9.2.1.7. Map getLocators(string targetName)

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

• targetName: Name (URI) of the target.
• Return value: Map with:
  • keys: locator ids (strings)
  • values: locator types (strings), one of {"audio", "visual", "other"} (see ISO/IEC 24752-4:2008, section 6.7).

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.

• targetId: Globally unique target instance identifier.
• locatorId: 'id' attribute of the locator, as specified in Target Description
• TAException: If the TA, for any reason, cannot find or trigger the locator, it throws a TAException. The exception shall include a text string describing the problem that occurred.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• targetId: Globally unique target instance identifier.
• Return value: Name (URI) of the target.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

9.2.1.10. string getTargetDescriptionUri(string targetName) throws TAFatalException

Get the URI for retrieving the target description.

• targetName: Name (URI) of the target.
• Return value: URI for the target description. The URI may point to a local or a global location, but must be resolvable. If relative, its base shall be the base URL of the location where the TA was retrieved from (implementation-specific).
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

9.2.1.11. Map getTargetProps(string targetId) throws TAFatalException

Get the target's properties.

• targetId: Globally unique target instance identifier.
• Return value: Property map for target, with properties as specified in [RES-PROP-VOCAB]. Additional (implementation-specific) properties may occur. Note that the TA may have to complete the properties map it got from the TDM via registerTarget (see section void registerTarget(string targetId, Map targetProps) throws TAException, TAFatalException) by adding required properties. See also section Property Map.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• targetName: Name (URI) of the target.
• Return value: Array with the names (URIs) of the target's sockets.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

9.2.1.13. string getSocketName(string sessionId) throws TAFatalException

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

• sessionId: UCH-internal session identifier.
• Return value: socket name (URI).
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.

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.

• targetId: UCH-internal target identifier.
• socketName: name (URI) of the socket.
• Return value: Friendly name of the socket.

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

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

• targetId: Globally unique target instance identifier. Note that this is needed since the TA may represent multiple targets of the same kind.
• socketName: Socket name (URI).
• Return value: Array with UCH-internal session identifiers.
• TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed. In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). The exception shall include a text string describing the problem that occurred.