You are here: MyURC.org > TR > urc-http-protocol2.0-20080814 > Draft

URC-HTTP Protocol 2.0 (DRAFT)

Abstract

This URCC Technical Report specifies the "Universal Remote Console (URC) on HTTP" protocol (short "URC-HTTP protocol").  The URC-HTTP protocol can be implemented by Remote UI servers that are compliant to UPnP RemoteUI or CEA-2014. 

This protocol is optional for a UCH.  However, if a UCH implements this protocol, it shall implement it exactly as described in this specification.

The URC protocol can be used by controllers that need a semantic description of the user interface components.  Examples for such controllers are controllers and intelligent agents that allow for voice or natural language based interaction mechanisms, including task-oriented user interfaces.

The underlying concepts of the URC protocol are specified in ISO/IEC 24752, Universal Remote Console.

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 will be removed when this document becomes an approved Technical Recommendation.

2008-08-14 Gottfried Zimmermann:

• Complete overhaul to first draft (as referenced in CEA-2014). 

Open Issues [to be removed before final release]

1. Not specified: handling streaming (stream-typed variables)
2. Automatic updates on dependencies.
3. Suspend and resume session.
4. Add 'depth' attribute to Get Values and Get Updates messages, specifying the depth for the path?
5. Add 'includeSet' attribute to Get Values and Get Updates messages, allowing for inclusion of set paths in the return?
6. Need to add an out-of-session message to retrieve information specific to the remote control URI, as contained in the <protocol> element of the UIList.  (Convenient for clients that have the URI – so don't need to parse complete UIList and search for the given URI).
7. How to include descriptors in a Get Resources request?

---

Table of Contents

---

1. Scope

This URCC Technical Report specifies the "Universal Remote Console (URC) on HTTP" protocol (short URC-HTTP protocol).  The URC-HTTP protocol can be implemented by Remote UI servers that are compliant to UPnP RemoteUI or CEA-2014. 

This protocol is optional for a UCH.  However, if a UCH implements this protocol, it shall implement it exactly as described in this specification.

2. Conformance

A UCH is conforming to this standard if it implements:

• Support for character encoding, as specified in 5;
• Discovery, as specified in 7;
• All HTTP/HTTPS Request Messages, as specified in 8;
• An Update Channel, as specified in 9; and
• Support for URL rewriting for Session Management, as specified in 10.

A controller is conforming to this standard if it implements:

• Support for character encoding, as specified in 5;
• The following HTTP/HTTPS Requests with pertaining MIME types and status codes: Open Session, Close Session, Get Values.
• Support for URL rewriting for Session Management, as specified in 10.

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

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

[ISO/IEC 24752-1:2008]

ISO/IEC 24752-1:2008, Information Technology — User Interfaces — Universal Remote Console — Part 1: Framework

[ISO/IEC 24752-2:2008]

ISO/IEC 24752-2:2008, Information Technology — User Interfaces — Universal Remote Console — Part 2: User Interface Socket Description

[ISO/IEC 24752-4:2008]

ISO/IEC 24752-4:2008, Information Technology — User Interfaces — Universal Remote Console — Part 4: Target Description

[ISO/IEC 24752-5:2008]

ISO/IEC 24752-5:2008, Information Technology — User Interfaces — Universal Remote Console — Part 5: Resource Description

[CEA-2014-A]

CEA-2014-A: Web-based Protocol and Framework for Remote User Interface on UPnP™ Networks and the Internet (Web4CE).  P. Shrubsole, W. Dees, 2007.

[RES-PROP-VOCAB]

URC Consortium: Resource Property Vocabulary.  Latest version available at: http://myurc.org/TR/res-prop-vocab/.

[RFC 2109]

RFC 2109: HTTP State Management Mechanism. D. Kristol, L. Montulli, February 1997.  Available at: http://www.ietf.org/rfc/rfc2109.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.

[UCH]

Universal Control Hub. Latest specification available at: http://www.myurc.org/TR/uch/.

[XML Schema Definition]

W3C Recommendation: XML Schema Part 2: Datatypes Second Edition, 28 October 2004, http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/

4. Format Conventions in this Standard

Messages and their formats are specified in this standard as example code with placeholders. 

Placeholders are rendered in bold italics .  Their meaning is explained after the code template in which they are used, together with other constraints of the specified message format.

"[blank line]" denotes a blank line, consisting of a LF (line-feed) character (ASCII 10).

EOF is the (end-of-file) character (ASCII 31).

5. Coding

5.1. Character Encoding

For all messages defined in this standard, the "UTF-8" character encoding shall be used.

5.2. Character Escaping

The following characters shall be escaped when occurring in the XML part of a message:

• '&' shall be encoded as '&amp;'
•  '<' shall be encoded as '&lt;'
• '>' shall be encoded as '&gt;'
• The double quote character (") shall be encoded as '&quot;'
• The apostrophe character (') shall be encoded as '&apos;'

Additionally, the following characters shall be escaped if occurring as part of an index within paths:

•  '[' shall be encoded as '&#x5B;'
• ']' shall be encoded as '&#x5D;'
• The space character ' ' shall be encoded as '&#x20;'

5.3. Leading and Trailing Whitespaces

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 variable values and resource text, shall be encoded as '&#x20;'.

5.4. Undefined Value

The undefined value shall be encoded as the tilde character '~'.  Real (defined) string values consisting of a single tilde character shall be encoded as '&#x7E'.

NOTE: If a variable’s value or command’s state is undefined, either the socket element (variable or command) is not available in the session (see ‘optional’ attribute on variables on commands, ISO/IEC 24752-2), or the value/state is temporarily undefined. Controllers should not include socket elements in the user interface whose value/state is undefined (see ISO/IEC 24752-1).

6. Namespaces

The XML language defined by this standard does not support multiple namespaces.  All elements and attributes belong to the default namespace whose URI shall be "http://myurc.org/ns/urc-http". 

This namespace URI shall be implicitly assumed for all XML fragments defined by this standard, but shall not be included in any message between a controller and UCH and vice versa.

Neither UCHs nor controllers need to employ namespace-aware parsers.

7. UIList

A UCH shall advertise the user interface protocols that it offers through the UIList, either as level-0, level-1 or level-2 RUI Server.  The UIList shall comply with [UCH].

7.1. Advertising of URC-HTTP protocol

A UCH [UCH] supporting the URC-HTTP protocol (see following note) shall advertise this in its UIList. 

The following specific rules apply for URC-HTTP protocol entries in the UIList:

For every socket of a target instance (i.e. every combination of target instance and one of its sockets) that the UCH exposes through the URC-HTTP protocol, there shall be a <protocol> subelement (underneath the <ui> element representing the target instance), with shortName="URC-HTTP", as follows:

Whereby:

• The <ui>, <uiID> and <name> elements shall occur as specified in [UCH].
• For every socket that the target exposes, there shall be one <protocol> subelement with shortName="URC-HTTP".  (There may be other <protocol> subelements, but with different shortNames.)
• The <uri> subelement shall occur exactly once, with remoteControlUri being a remote control URI (that is specific to a target instance and socket name) for the URC-HTTP protocol.  This URI can be used by a controller to send URC-HTTP protocol conformant requests to the UCH pertaining to a specific target instance and UI Socket.  
• The <protocolInfo> subelement shall occur exactly once.  It shall contain the following subelements:
  • Exactly one <targetName> element with targetName as element content, specifying the name (URI) for the target (which shall not be "all").
  • Exactly one <socketName> element with SocketName as element content, specifying the name (URI) of the socket that the UI connects to (which shall not be "all").  <socketName> may have an attribute 'friendlyName', bearing a human-readable name for the socket.
  • Exactly one <socketDescriptionAt> element with SocketDescriptionURI as element content.  SocketDescriptionURI is a resolvable URI for retrieving the pertinent Socket Description (see ISO/IEC 24752-2).  This URI may point to a local file on the network (e.g. served by the Target device itself) or to a file on the Internet (e.g. served by a company's web server).
  • Exactly one <targetDescriptionAt> element with TargetDescriptionURI as element content.  TargetDescriptionURI is a resolvable URI for retrieving the pertaining Target Description (for the Target that the Socket belongs to).  A Target Description contains information about a device that can be controlled by the means of the URC framework and the UI Sockets that this device provides for remote control (see ISO/IEC 24752-4).  This URI may point to a local file on the network (e.g. served by the Target device itself) or to a file on the Internet (e.g. served by a company's web server).
  • Exactly one <conformsTo> element with a URI as element content, indicating the version of the URC-HTTP specification that the remoteControlUri implements.

NOTE: Of the above 5 <protocol> subelements, <targetName> and <socketName> are defined in [UCH] since they apply to any kind of user interface, as advertised by a UCH. However, if being used for describing a URC-HTTP based user interface, each of them must occur exactly once, since a <protocol shortName=”URC-HTTP”> element represents exactly one target and exactly one socket.

7.2. Advertising of URC-HTTP Client Wrapper Protocols

URC-HTTP clients are applications and scripts that are interfacing with the UCH via the URC-HTTP protocol provided by a URC-HTTP UIPM [UCH]. Some UIPM clients may be simple web pages (typically HTML pages with embedded scripts or objects running on any web browser) that can be retrieved from the UCH's web server.  Such a web page can be understood as "wrapping" the URC-HTTP protocol by offering a different protocol (the "wrapper protocol") to its clients.  A URC-HTTP client specifies its "wrapper protocol" by the property http://myurc.org/ns/res#protocolShortName (e.g. "HTTP/HTML").

A resource is a URC-HTTP client resource, if all of the following is true regarding its properties [RES-PROP-VOCAB]:

• http://myurc.org/ns/res#type = "http://myurc.org/restypes#uipm-client"
• http://myurc.org/ns/res#wrapsProtocolShortName = "URC-HTTP"
• http://myurc.org/ns/res#protocolShortName is specified

It is an applicable URC-HTTP client resource, if all of the following is true:

• A property http://myurc.org/ns/res#forTargetInstance (if specified) matches a target instance that is available.
• A property http://myurc.org/ns/res#forTargetName is either "all", "*" or matches a target name that is available.
• A property http://myurc.org/ns/res#forSocketName (if specified) is either "all", "*" or matches a socket name of a target that is available.
• Other restrictions of the URC-HTTP client resource apply, as expressed by its properties [RES-PROP-VOCAB].

A UCH supporting the URC-HTTP protocol (see note in the previous section) should make an applicable URC-HTTP client resource available, if accessible to the UCH, via its web server for retrieval by controllers, as follows:

• The UCH should store the client resource in the local network.

  NOTE: It is acceptable for a UCH to assign URIs and do advertisements (see below) for remote URC-HTTP client resources, without downloading and storing them locally.  In this case the UCH would download, unpack and pass them on to the controller upon a controller's request.

• If the client resource is a file package (property http://myurc.org/ns/res#mimeType), it should unpack the package into a separate directory, identify its index file (property http://myurc.org/ns/res#indexFile) and the MIME type of the index file (property http://myurc.org/ns/res#indexFileMimeType).
• The UCH should assign resolvable "remote control URIs" for every client resource (or its index file if it is a package), and for each applicable target instance (as specified by the property http://myurc.org/ns/res#forTargetName), and for each of the applicable sockets (as specified by the property http://myurc.org/ns/res#forSocketName, if available).  The remote control URIs shall have a list of applicable URC-HTTP remote control URIs (for applicable target instances and socket names) as query component [RFC 3986], delimited from each other by the '&' character.  Note that URI component coding restrictions apply as specified in [RFC 3986] and 5.
  • Exception: If the client resource applies to the set of all targets (i.e. property http://myurc.org/ns/res#forTargetName has the value "all"), the list of applicable URC-HTTP remote control URIs shall be omitted (i.e. the remote control URI has no query component).
  • Note that – with the above exception – multiple URC-HTTP remote control URIs occur only if the client resource's http://myurc.org/ns/res#forSocketName property occurs multiple times with different URI values, or if it has the value "all".  Background: Multiple values for property http://myurc.org/ns/res#forTargetName indicates alternative target names rather than a set of targets that the client resource binds to all at once.  However, multiple values for property http://myurc.org/ns/res#forSocketName indicate that the client resource binds to all socket names at the same time.
• A controller can retrieve the client resource (or its index file) through the assigned remote control URI, and the UCH should serve it with its specific MIME type (property http://myurc.org/ns/res#mimeType or http://myurc.org/ns/res#indexFileMimeType, respectively).  If no MIME type is specified for the client resource, the UCH should try to infer a MIME type based on the file extension or other heuristics.

NOTE: A UCH can have access to URC-HTTP client resources either through implementation-specific means (e.g. local configuration), and/or by querying and retrieving them from a resource server.

A UCH should advertise accessible URC-HTTP client resources that it makes available via its web server, by adding their assigned  remote control URIs (see above) in the UIList, as specified in [UCH], and as follows:

• The URC-HTTP client resources and their remote control URIs shall be included in the UIList underneath the <ui> element that adheres to the target instance that they control, as specified by the property http://myurc.org/ns/res#forTargetName.  If the property has a value of "all", the client resource shall be included underneath the target instance "all".
• The 'shortName' attribute on <protocol> shall be the value of the http://myurc.org/ns/res#protocolShortName property of the URC-HTTP client resource.
• The elements <targetName> and <socketName> shall reflect the target name (URI) and socket name (URI) that client resource will connect to when the assigned remote control URI is used (see above on assigning of URIs).  An element content of "all" indicates that the assigned URI will connect to all targets (only applicable underneath the <ui> element adhering to the "all" target instance), or to all socket names of a particular target instance, respectively.

NOTE: Since a URC-HTTP client resource provides a wrapper protocol of any kind (other than "URC-HTTP"), its advertising follows the format of the UIList, as specified in [UCH], and not the (stricter) profiled format for URC-HTTP user interface protocol providers, as specified in 7.1.

Example: See [UCH] under "UIList", in particular those <protocol> entries with shortName="HTTP/HTML".

8. HTTP/HTTPS Request Messages

8.1. General

8.1.1. Transport

In general, messages from the controller are sent to the UCH over HTTP or HTTPS. 

The UCH may opt to use only HTTP or only HTTPS. 

However, the UCH shall respond to both HTTP and HTTPS requests for the UIList (see 7).  The UCH may use HTTP code 301 (Moved Permanently) to redirect one of the requests to the other protocol [UCH].

At a minimum, all out-of-session messages (see 8.2) shall be available through the same protocol as the UIList.

8.1.2. MIME type

HTTP/HTTPS responses shall have a MIME type of "application/urc-http+xml", if applicable.

NOTE: This MIME type will be registered with IANA.

8.1.3. HTTP Status Codes

HTTP status codes apply, as specified in RFC 2616.  A specific subset of relevant HTTP status codes will be specified for each HTTP/HTTPS request type below. 

In addition, a UCH shall respond with error code 400 Bad Request, if it gets an HTTP/HTTPS request that is not defined.  However, a UCH shall not respond with error code 400 to indicate any superfluous query arguments in the URL, or any superfluous message body.  In these cases, the UCH shall simply ignore the superfluous information.

8.1.4. Path Forms

The following table lists possible forms of paths that can be used in HTTP/HTTPS request messages and their responses.  Subsequent sections with detailed HTTP/HTTPS message descriptions are referencing these path forms.

Path Form Name	Syntax(es)	Description
root path	/	all Socket elements (and their components, if any)
path without indices	/set1/set2/id	non-dimensional Socket element or set
shortcut path	id	non-dimensional Socket element or set (shortcut for "path without indices")
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.

8.1.5. Data Types

Coding for value transmission in HTTP/HTTPS messages shall follow the XML Schema Definition specification.  Values are case-sensitive.

In particular, the only values allowed for type boolean shall be "true" and "false".

8.2. Out-of-Session Messages

This section describes message types that a controller can use with or without an open session with the UCH.

8.2.1. Get Resources (Out-Of-Session)

A controller may query a list of static atomic resources from a UCH, independent from any session, as follows:

Whereby:

• hostname is the domain name for the UCH.  Note that the port number is omitted and defaults to 80 (for HTTP) or 443 (for HTTPS).
• <getResources> shall occur exactly once in the body of the HTTP/HTTPS request, specifying resource queries for atomic resources from the UCH.  It shall contain one or more <resource> subelements, each specifying a resource query for the delivery of atomic resources.  Note that the order of the <resource> subelements is significant since the UCH will respond with a list of resources in corresponding order.
• Each <resource> element may have any of the following attributes (in any order):
  • 'eltRef' attribute, with eltRef specifying a URI for the element that the resource is pertaining to.  This may be a URI with fragment identifier, referencing a socket element that the requested resource shall apply to, but other URI forms and references to other entities are allowed (e.g. reference to a socket to obtain its label).  See ISO/IEC 24752-5, section 6.7.3.1 for <eltRef>.

    NOTE: eltRef specifies the whole element reference as specified in an atomic resource description, typically in the form: uri#id.

    NOTE: The use of the element reference (eltRef) in the Get Resources request message is different from the use of element paths (path) in other messages such as Get Values.  Since a resource is defined for an element (and not for a specific instance of it) an element path must not be used for a resource query.

  • 'valRef' attribute, with value specifying the specific value that the requested resource shall apply to.  If missing, the requested resource shall not apply to a particular value.  See ISO/IEC 24752-5, section 6.7.3.2 for <valRef>.
  • 'opRef' attribute, with opUri specifying the operation URI that the requested resource shall apply to.  See ISO/IEC 24752-5, section 6.7.3.3 for <opRef>.  If missing, the requested resource shall not apply to a particular operation.  opRef and valRef shall not occur together; i.e. if opRef occurs, no valRef shall occur, and vice versa.
  • 'role' attribute, indicating the role of the requested resource, with roleUri as defined in ISO/IEC 24752-5, section 6.7.3.4 for <role>.
  • 'type' attribute, indicating the type of the requested resource, with type as defined in ISO/IEC 24752-5, section 6.5 for <dc:type>.
  • 'format' attribute, indicating the MIME type of the requested resource, with mimetype as defined in ISO/IEC 24752-5, section 6.6 for <dc:format>.
  • 'forLang' attribute, indicating the language of the requested resource, with langcode as defined in ISO/IEC 24752-5, section 6.7.3.5 for <forLang>.
  • 'forTargetInstance' attribute, indicating the target instance for which the atomic resource can be applied, with targetId as defined in ISO/IEC 24752-5, section 6.7.3.6 for <forTargetInstance>.

    NOTE: In the UIList (see 7), the available targetIds are specified as element content of <uiID> elements.

  • 'creator' attribute, indicating the creator of the requested resource, with creator as defined in ISO/IEC 24752-5, section 6.8 for <dc:creator>.
  • 'publisher' attribute, indicating the publisher of the requested resource, with publisher as defined in ISO/IEC 24752-5, section 6.9 for <dc:publisher>.
  • 'date' attribute, indicating the date of the requested resource, with date as defined in ISO/IEC 24752-5, section 6.11 for <dc:date>.
  • 'audience' attribute, indicating the audience for the requested resource, with audience as defined in ISO/IEC 24752-5, section 6.13 for <dcterms:audience>.
• Any resource property not included as attribute of a <resource> element shall be unspecified in the resource query, i.e. their values do not matter for matching the query.

NOTE: The Get Resources request can be used for atomic resources that would not be delivered as part of  Get Value responses or Update Events.  Examples include: labels for the socket itself, for a local input parameter, and for presentational groups.  Still, some controllers may require a retrieval mechanism that can accommodate for more complex resource queries.  In this case it is recommended that the controller retrieve and parse resource sheets, obtained either from the target (through the target description, see 7) or from a resource server.

Upon a processed Get Resources request, the UCH shall respond by transmitting the requested static atomic resources, if available, as follows:

Whereby:

• The response shall include exactly one <resources> element.
• The <resources> element shall have one or more <resource> subelements, each specifying an atomic resource, if available.
• The list of <resource> subelements shall exactly reflect the list of resource queries (<resource> subelements of <getResources>) in the Get Resource request, in size and order.  If no resource is available for a particular resource query of the Open Session request, the corresponding <resource> subelement shall be empty (coded as "<resource />").  If multiple resources match a resource query, it is up to the UCH to pick one of them (selection criteria are implementation-specific).
• An available atomic resource shall be specified either as element content of the <resource> subelement (resource ) or as the value (resourceUri ) of an 'at' attribute of <resource> which may occur.  resourceUri shall be a resolvable URI to the resource content.

The following HTTP status codes apply to a Get Resources response:

HTTP status code	Use Cases
200 OK	The request was successfully processed.  If the request contained invalid path references, they were ignored by the server.
301 Moved Permanently	The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. May be used to redirect the client to either HTTP or HTTPS.
400 Bad Request	The request body is encoded in a format that the server does not support. The XML body of the request is not well-formed.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The server is currently unable to handle the request.

NOTE: Static resources are not specific to sessions and can therefore be retrieved by any client, even though it may not have a session open with the UCH.  Some static resources may be needed by a client before a session has been opened, for example the label for a socket.  In contrast, dynamic resources are target instance specific, and can only be obtained through URC-HTTP if a session is open with the corresponding target.  Controllers should use the in-session version of Get Resources (see 8.3.6) when requesting resources during a session, in order to have dynamic resources automatically included in the response.

8.2.2. Get Document (HTTP Proxy)

A controller may not be able to retrieve documents from the Internet for security restrictions.  In particular, it may want to retrieve target and socket descriptions which may not reside on the UCH itself.  The Get Document function of the URC-HTTP protocol is designed to solve this problem.

A UCH should provide an HTTP proxy function to a controller, as follows:

The UCH, when receiving a GET or POST request to /UCH/GetDocument?url=destinationURL&otherQueryParameters, forwards this request (including headers and body) to destinationURL that has been specified by the client as the first URL query parameter named "url" (small letters).  The other query parameters (otherQueryParameters ) will be forwarded as part of the request to destinationURL . 

The UCH will pass the response of the forwarded request back to the RUI client, including HTTP headers and error code.

Example: The controller sends the following GET request to the UCH:

Whereby:

• hostname is the domain name for the UCH.  Note that the port number is omitted and defaults to 80 (for HTTP) or 443 (for HTTPS).

NOTE: The UCH would handle a POST request in the same fashion, except that it would also forward the body of the request message.

Then the UCH initiates the following forward request:

After the UCH has received the response from res.myurc.org, it will pass it on to the controller, including HTTP error code, headers, and body.

NOTE: The above example does not encode special characters as part of the destination URL. While this is common practice, it does not strictly comply with the requirements of this specification.

8.2.3. Invoke Locator

A controller may request to invoke a target's locator at any time, even when no open session exists with the UCH on this target. 

A controller may request to invoke a target's locator in a message to the UCH, as follows:

Whereby:

• hostname is the domain name for the UCH.  Note that the port number is omitted and defaults to 80 (for HTTP) or 443 (for HTTPS).
• <invokeLocator> shall occur one or more times, with attributes 'targetId' and 'locatorId' on every occurrence.
• targetId is a global target instance identifier, as provided by the UCH as element content of the <uiID> element in the UIList (see 7).
• locatorId is an identifier of a target's locator, as given in a target description as value of the 'id' attribute on a <locator> element (see ISO/IEC 24752-4).  A controller can find out about a target's locators and their identifiers by parsing the target description (see <targetDescriptionAt> element in 7.1).

Upon receipt of an Invoke Locator request, the UCH shall invoke the target's locator as specified.  The UCH shall respond as follows:

NOTE: This response message should not be construed as a confirmation that the locator was actually invoked on the target, since the UCH does not get a confirmation from the target either.

The following HTTP status codes apply to a Invoke Locator response:

HTTP status code	Use Cases
200 OK	The request was successfully passed to the corresponding target, and invalid targetIds are ignored.
301 Moved Permanently	The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. May be used to redirect the client to either HTTP or HTTPS.
400 Bad Request	The request body is encoded in a format that the server does not support. The XML body of the request is not well-formed.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The server is currently unable to handle the request.

8.2.4. Get User Interface Info

A controller may request to get user interface information on a URC-HTTP based remote control URI, as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of a remote control URI offering the URC-HTTP protocol (shortName="URC-HTTP"), as specified in 7.1.

Upon receipt of an Get UI Info request, the UCH shall respond as follows:

Whereby:

• Format and placeholder restrictions apply as specified in 7.1.
• Further restricting the format, the <protocol> element shall occur exactly once, providing information on the user interface being provided by /RUIAppPath.

The following HTTP status codes apply to a Get UI Info response:

HTTP status code	Use Cases
200 OK	The request was successful.
301 Moved Permanently	The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. May be used to redirect the client to either HTTP or HTTPS.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The server is currently unable to handle the request.

8.3. In-Session Messages

8.3.1. Open Session Request

A controller shall open a control session with a URC-HTTP based remote control URI with an Open Session request as POST or GET message:

Or:

Whereby:

• hostname, hostport and RUIAppPath are parts of a remote control URI, offering the URC-HTTP protocol (shortName="URC-HTTP") as specified in section 7.1.
• <openSessionRequest> shall occur exactly once as root element.  It may have an 'authorizationCode' attribute, with code being an authorization code for the open session request.

  NOTE: Implementations should employ a suitable encryption mechanism for transport (e.g. HTTPS with sufficient key length).  Specific security techniques are out of scope for this standard.

• <includeResources> may occur once in the body of the HTTP/HTTPS request.  If it occurs, it specifies resource queries for atomic resources that the UCH shall send along together with socket element values (see 8.3.3, 8.3.4, and 9.2) in this session. If <includeResources> does not occur, the UCH shall not send resources together with socket element values in this session.
• If present, <includeResources> shall contain one or more <resource> subelements, each specifying a resource query for the delivery of atomic resources.  Note that the order of the <resource> subelements is significant since the UCH will provide resources in corresponding order (see 8.3.3, 8.3.4, and 9.2).

  NOTE: Generic resources apply to a socket element in general.  Value-specific resources apply only to specific values of a socket element.

• Each <resource> element may have any of the following attributes (in any order):
  • 'forVal' attribute, with boolean being "true" or "false" (default).  It indicates whether the requested resource is a generic resource ("false") or a value-specific resource ("true").  If value-specific, the pertaining value is the current value of the pertaining socket element.
  • 'role' attribute, indicating the role of the requested resource, with roleUri as defined in ISO/IEC 24752-5, section 6.7.3.4 for <role>.
  • 'type' attribute, indicating the type of the requested resource, with type as defined in ISO/IEC 24752-5, section 6.5 for <dc:type>.
  • 'format' attribute, indicating the MIME type of the requested resource, with mimetype as defined in ISO/IEC 24752-5, section 6.6 for <dc:format>.
  •  'forLang' attribute, indicating the language of the requested resource, with langcode as defined in ISO/IEC 24752-5, section 6.7.3.5 for <forLang>.
  • 'creator' attribute, indicating the creator of the requested resource, with creator as defined in ISO/IEC 24752-5, section 6.8 for <dc:creator>.
  • 'publisher' attribute, indicating the publisher of the requested resource, with publisher as defined in ISO/IEC 24752-5, section 6.9 for <dc:publisher>.
  • 'date' attribute, indicating the date of the requested resource, with date as defined in ISO/IEC 24752-5, section 6.11 for <dc:date>.
  • 'audience' attribute, indicating the audience for the requested resource, with audience as defined in ISO/IEC 24752-5, section 6.13 for <dcterms:audience>.
• Any resource property not included as attribute of a <resource> element shall be unspecified in the resource query, i.e. their values do not matter for matching the query.  Exception: If an atomic resource has a target instance identifier attached, it shall only match a resource query if the session is connected to the specified target instance.

NOTE: The delivery of atomic resources through the URC-HTTP protocol provides a light-weight way for controllers to obtain labels and other resources.  However, some controllers may require a retrieval mechanism that can accommodate for more complex resource queries.  In this case it is recommended that the controller retrieve and parse resource sheets, obtained either from the target (through the target description, see 7) or from a resource server.

Upon an Open Session request the UCH shall either accept, forward or reject the request. 

If accepted, the server shall send information on the opened session as follows:

Whereby:

• <sessionInfo> shall occur exactly once.  SessionId is a server-generated string identifying the new session.  SessionId shall not contain '>' or '<', nor any whitespace character or reserved character in URIs according to section 2.2 of RFC 3986.  Character encoding restrictions apply (see5).

  NOTE: The following are defined as "reserved characters" in RFC 3986: ':', '/', '?', '#', '[', ']', '@', '!', '$', '&', ''', '(', ')', '*', '+', ',', ';', '='

• A UCH may offer an "Update Channel" service to push updates to the connected controller (see 9).  In this case, the controller may (after the Open Session Request) open a permanent TCP/IP connection (called "Update Channel") with the server to receive update messages regarding the values of the UI Socket that it has a session with.  The <updateChannel> element, which may be present, provides the client with the necessary information to open such a connection with the server. If present, the <updateChannel> element shall have the following subelements:
  • One <ipAddress> element with Address as element content.  Address is the IP address for the session-specific Update Channel.
  • One <portNo> element with Port as element content.  Port is the port number for the session-specific Update Channel.

Example: A UCH which provides an Update Channel service responds to an Open Session Request as follows:

In this example, the controller could open a session-specific Update Channel with the IP address 192.168.0.1 on port 8888.  The controller would send the following string on the Update Channel, upon having established the TCP/IP based Update Channel connection (see 9.1):

The UCH may forward the Open Session request, by sending the following response message:

Whereby:

• The <forward> element shall occur as root element.  It indicates a request from the target to open a new session with a different socket of the same or a different target.  (In this case there has been no session created.)  <forward> shall have a 'targetName', a 'targetId' and a 'socketName' attribute, and may have a 'authorizationCode' attribute, with the following meanings:
  • targetName: Name (URI) of target that the controller is forwarded to.  Corresponds to <targetName> element in UIList (see 7.1).
  • targetId: global instance identifier of target that the controller is forwarded to.  Corresponds to <uiID> element in UIList (see 7.1).
  • socketName: Name (URI) of socket that the controller is forwarded to.  Corresponds to <socketName> element content in UIList (see 7.1).
  • authorizationCode: Any string to be used as authorization code, corresponding to the 'authorizationCode' attribute of the <openSessionRequest> element in an open session request (see 8.3.1).

In case the UCH forwards the Open Session request, the controller should send an Open Session request (8.3.1) to the target/socket specified by targetId and socketName , with the authorization code authorizationCode , if available. 

NOTE: Typically, the new session will be opened through the URC-HTTP protocol.  However, the controller may opt to use a different UI protocol, as available in the UIList for the specified target and socket (see 7).

If the UCH rejects the Open Session request, it shall respond with an error code as specified below. 

The following HTTP status codes apply to an Open Session response):

HTTP status code	Use Cases
200 OK	The request was successfully processed, by either creating a new session or forwarding to a different socket.
400 Bad Request	The request body is encoded in a format that the server does not support. The XML body of the request is not well-formed.
403 Forbidden	The client is not authorized to open a new session.  This may occur for sockets that can only be opened by being forwarded from another session.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The open session request was rejected.

NOTE: After successful opening a session with a UCH, a controller should send a Get Values request (see 8.3.3) to retrieve the initial values of the UI Socket.  It may use the "root path" in this request to retrieve all values in one response.  However, a more selective approach may be chosen if the UI Socket contains a great amount of data.

8.3.2. Close Session Request

Having an open session with a remote control URI, a controller can request to close an existing session with the UCH as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of a remote control URI offering the URC-HTTP protocol (shortName="URC-HTTP") for the UCH as specified in 7.1.
• SessionId is the session identifier as contained in the response on the Open Session request (see 8.3.1).

NOTE: When using cookies for session management, a controller has to include the server-provided cookie in the above HTTP/HTTPS request (see 10.2).  When using URL rewriting, a controller has to append "&session=sessionId" to the path in the first line of the above HTTP/HTTPS request, resulting in a complete path of "/RUIAppPath?closeSessionRequest&session=sessionId"  (see 10.1).

If it accepts the request, the UCH shall respond as follows:

The following HTTP status codes apply to a Close Session response:

HTTP status code	Use Cases
200 OK	The request was successfully processed and the session closed.
403 Forbidden	The client is not authorized to close the specified session.
404 Not Found	Invalid session identifier.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The session could not be closed.

8.3.3. Get Values

Having an open session with a remote control URI, a controller can request the values of UI Socket elements (or components thereof) or available index values as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of a remote control URI offering the URC-HTTP protocol (shortName="URC-HTTP") as specified in section 7.1.
• SessionId is the session identifier as contained in the response on the Open Session request (see 8.3.1).
• The request shall include as body one non-empty <getValues> element.
• The <get> element may occur as subelement of <getValues> any number of times, to request the current paths and values of socket elements and, if indicated by the 'includeSets' attribute, the current paths of socket sets.  There shall be no two <get> elements with identical 'ref' attribute values.
  • <get> shall have a 'ref' attribute, with path referencing a Socket element or set (or a component thereof), in one of the following path forms (see 8.1.4): root path, path without indices, shortcut path, path with given indices, path with empty indices, path with range of indices, path for command state, path for command timeToComplete, path for local command parameter, path for partial XML content.  Character encoding restrictions apply (see 5).
• The <getIndex> element may occur as subelement of <getValues> any number of times, to request the available values for a particular index of a dimensional socket element or set, as specified by the 'ref' and 'index' attributes.  There shall be no two <getIndex> elements with identical values for both 'ref' and 'index' attributes.
  • <getIndex> shall have a 'ref' attribute, with elementId bearing the XML identifier ('id' attribute) of a dimensional Socket element or set.
  • <getIndex> shall have a 'index' attribute, with indexNo specifying the 0-based index number (i.e. "0" denotes the first index, "1" the second, etc.).  Note that this 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.  <getIndex ref="set" index="1" /> would request the available values for the second index (which is of type xsd:string).

Upon a processed Get Values request, the UCH shall respond by transmitting the values of all Socket elements (and components thereof) that were specified in the client's request.  If the request contains a reference to the UI Socket itself (root path), subordinate socket elements and components thereof shall be included in the server's response.  If the request contains a set or set component, the values of all current socket elements and element components underneath the specified set (or set component) shall be included in the response. 

The UCH shall respond as follows:

Whereby:

• The <values> element shall occur exactly once. 
• A <value> element may occur multiple times within <values> for transmitting the values of multiple UI Socket elements.  However, there shall be no two instances referencing the same path.
  • A <value> element shall have a 'ref' attribute, with path being a reference to a Socket element/set (or a component thereof), in any of the following forms (see 8.1.4): path without indices, path with given indices, path for command state, path for command timeToComplete, path for local command parameter, path for partial XML content.  Character encoding restrictions apply (see 5).

  NOTE: If a Get Values Request contains an invalid path, the UCH should ignore the corresponding <get> element (return with code 200).

• value is the value of the UI Socket element (or a component thereof), as string representation.  For variables, this is their value, as string representation.  For commands, this is their state (e.g. "ready", "done") or timeToComplete field (only for commands of type timedCommand).  For notifications, this is their state ("active", "inactive").  Character encoding restrictions apply (see 5).
• If the controller requested resource delivery upon opening the session (see 8.3.1), a <value> element shall have one or more <resource> subelements, each specifying a matching atomic resource (if available), pertaining to the socket element referenced by the containing <value> element.
  • The list of <resource> subelements shall exactly reflect the list of resource queries (<resource> subelements of <includeResources>) submitted by the controller as part of the Open Session request, in size and order.  If no resource is available for a particular resource query of the Open Session request, this shall be specified as an empty <resource> element (coded as "<resource />").
  • An available atomic resource shall be specified either as element content of the <resource> subelement (resource ) or as the value (resourceUri ) of an 'at' attribute of <resource> which may occur.  resourceUri shall be a resolvable URI to the resource content.

    NOTE: The 'at' attribute is especially useful for binary resources.

• An <index> element may occur multiple times within <values>, each one for one <getIndex> request from the client.  Each <index> element shall have a 'ref' attribute, with elementId and indexNo as specified in the client's request.
  • Each <index> element may have any number of <indexValue> subelements, each specifying one available index value as element content indexValue .  Character encoding restrictions apply (see 5).
  • If the controller requested resource delivery upon opening the session (see 8.3.1), each <indexValue> element shall have one or more <resource> subelements, each specifying a matching atomic resource (if available), pertaining to the index value specified by the containing <indexValue> element.  The same restrictions apply as for the <resource> subelements of <value>, see above.

    NOTE: Resources that apply to Socket-defined types have an element reference (property http://myurc.org/ns/res#eltRef) of the following format: socketName#typeId, withsocketName being the name (URI) of the socket, andtypeId being the value of the 'id' attribute on the type definition. For resources that apply to Socket-external types, the format is: namespaceUri#typeName, with namespaceUri being the identifier (not prefix) of the namespace, and typeName being the value of the 'name' attribute on the type definition.

Unavailable socket elements: There is no special message for inquiring about the availability of socket elements (see 'optional' attribute on variables and commands in ISO/IEC 24752-2).  The UCH shall send the "undefined value" (see 5.4) for any variable or command that is not available in the session.

NOTE: If a variable's value or command's state is undefined, either the socket element (variable or command) is not available in the session (see 'optional' attribute on variables on commands, ISO/IEC 24752-2), or the value/state is temporarily undefined.  Controllers should not include socket elements in the user interface whose value/state is undefined (see ISO/IEC 24752-1).

The following HTTP status codes apply to a Get Values response:

HTTP status code	Use Cases
200 OK	The request was successfully processed.  If the request contained invalid path references, they were ignored by the server.
400 Bad Request	The request body is encoded in a format that the server does not support. The XML body of the request is not well-formed.
403 Forbidden	The client is not authorized to get values pertaining to the specified session.
404 Not Found	Invalid session identifier.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The server is currently unable to handle the request.

8.3.4. Get Updates

Having an open session with a remote control URI, a controller can request an update of selected UI Socket values, as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of a remote control URI offering the URC-HTTP protocol (shortName="URC-HTTP") as specified in 7.1.
• SessionId is the session identifier as contained in the response on the Open Session request (see 8.3.1).
• The request shall include as body one <getUpdates> element, containing one or multiple <get> elements, each with a mandatory 'ref' attribute.  However, there shall be no two <get> elements with the same path.
• path shall reference a UI Socket element or set, in any of the following forms (see 8.1.4):  root path, path without indices, shortcut path, path with given indices, path with empty indices, path with range of indices, path for command state, path for command timeToComplete, path for local command parameter, path for partial XML content.  Character encoding restrictions apply (see 5).

If a Get Updates Request contains an invalid path, the UCH should ignore the corresponding <get> element (still return with code 200).

Upon a processed Get Updates request, the UCH shall respond by transmitting the values of the specified subset of UI Socket elements, as follows.  The response shall contain the values of those UI Socket elements that were specified in the client's Get Updates request body, and have changed since the last Get Element Updates request (or since the Open Session request if no Get Element Updates request has occurred yet) for the pertaining session.  If the request contained a reference to the UI Socket itself (root path), all socket elements and element components of the UI Socket shall be deemed as specified.  If the request contained a set or set component, the values of all current socket elements and element components underneath the specified set (or set component) shall be deemed as specified.

The server's Get Updates response shall not include those UI Socket elements whose updated value has already been propagated to the controller by the response to a previous Set Values request (see 8.3.5).

Whereby:

• The <updates> element shall occur exactly once (and may be empty).
• The <add> element may occur any number of times (however, instances shall differ in their attribute values).  Each occurrence indicates that the target has added an actual index combination for a dimensional element or set.  It shall have a 'ref' attribute, and addPath shall reference a socket element's component, and shall be of the following form (see 8.1.4): path with given indices.  An initial value of the socket element's component shall be provided as element content (value ).

  NOTE: It is recommended (but not required) that a response message with an <add> element also contain (subsequently) the actual value(s) of the element component(s) that were created as a result of the new index combination.

• The <remove> element may occur any number of times (however, instances shall differ in their attribute values).  Each occurrence indicates that the target has removed an actual index combination for a dimensional element or set.  It shall have a 'ref' attribute, and removePath shall reference a dimensional set or element be of one of the following forms (see 8.1.4): path with given indices, path with empty indices, path with range of indices.
• The <value> element may occur any number of times (however, instances shall differ in their attribute values).  Each occurrence indicates that an element has been assigned a new value.  It shall have a 'ref' attribute; path is a reference to a Socket element (or component thereof), which may take one of the following forms (see 8.1.4): path without indices, path with given indices, path for command state, path for command timeToComplete, path for local command parameter, path for partial XML content.  Character encoding restrictions apply (see 5).
• value is the value of the UI Socket element (or a component thereof), as string representation.  For variables, this is their value, as string representation.  For commands, this is their state (e.g. "ready", "done") or timeToComplete field (only for commands of type timedCommand).  For notifications, this is their state ("active", "inactive").  Character encoding restrictions apply (see 5).
• If the controller requested resource delivery upon opening the session (see 8.3.1), a <value> element shall have one or more <resource> subelements, each specifying a matching atomic resource (if available), pertaining to the socket element referenced by the containing <value> element.
  • The list of <resource> subelements shall exactly reflect the list of resource queries (<resource> subelements of <includeResources>) submitted by the controller as part of the Open Session request, in size and order.  If no resource is available for a particular resource query of the Open Session request, this shall be specified as an empty <resource> element (coded as "<resource />").
  • An available atomic resource shall be specified either as element content of the <resource> subelement (resource ) or as the value (resourceUri ) of an 'at' attribute of <resource> which may occur.  resourceUri shall be a resolvable URI to the resource content.
• A <forward> element may occur any number of times, with the following additional requirements:  (1) instances shall differ in their attribute values, and (2) no <add>, <remove> or <value> elements shall follow a <forward> element with type="D" within <updates>.  Each occurrence of <forward> indicates a request from the target to open another session with a different socket of the same or a different target.  It shall have a 'type', a 'targetName', a 'targetId' and a 'socketName' attribute, and may have an 'authorizationCode' attribute, with the following meanings:
  • type: Type of forward request.  "D" = destructive forward request, "S" = spawn request. 
  • targetName: Name (URI) of target that the controller is forwarded to.  Corresponds to <targetName> element in UIList (see 7.1).
  • targetId: global instance identifier of target that the controller is forwarded to.  Corresponds to <uiID> element in UIList (see 7.1).
  • socketName: Name (URI) of socket that the controller is forwarded to.  Corresponds to <socketName> element content in UIList (see 7.1).
  • authorizationCode: Any string to be used as authorization code, corresponding to the 'authorizationCode' attribute of the <openSessionRequest> element in an open session request (see 8.3.1).
• An <abortSession> element may occur once as the last element of <updates>.  It indicates that the session has been aborted by the target.  <abortSession> may have an element content message , providing a free-text description of the problem that occurred.

The UCH shall respond with an empty <updates> element if no update item is available, as in the following example:

Commands of type basicCommand or timedCommand: A UCH indicates the continuing execution or return of a command invocation by propagating a state (value) change for a "path for command state" (see 8.1.4).  Possible values for state are:

• "initial": initial command state before any execution. 
•  "rejected": command execution has been rejected
• "inProgress": command is still running
•  "done": command concluded
•  "succeeded": command concluded successfully
•  "failed": command concluded, but there was a failure

In the case of the conclusion of a command, the command's new state, and its local and global output parameters shall be included in one and the same "Get Updates" response; the values of its output parameters shall immediately follow the <value> element with the command's path.

Notifications: A UCH indicates the throwing of a notification by propagating a value change of the corresponding notification element from "inactive" to "active".  It indicates a removal of a notification by propagating a change from "active" to "inactive".

Undefined value: If a variable's value or command's state changes from a defined value to the "undefined value", the UCH shall send a Get Updates response with the "undefined value" of the variable/command.  The UCH shall not include socket elements in a Get Updates response that are unavailable (see 'optional' attribute on socket elements in ISO/IEC 24752-2).

Session forwarding: In case of a spawn forward request, the controller should open a new session (8.3.1) with the target specified by targetId , and the socket specified by socketName , with the authorization code authorizationCode , if available.  In case of a destructive forward request, the controller shall close the current session (see 8.3.2) prior to opening the new session.

NOTE: Typically, the new session will be opened through the URC-HTTP protocol.  However, the controller may opt to use a different UI protocol, as available in the UIList for the specified target and socket (see 7).

Session abortion: In case of a session abort event by the target, the controller shall not send any additional requests to the UCH pertaining to this session.  In particular, it shall not send a Close Session request (see 8.3.2).

NOTE: A target that wants to close the session with a client, and forward it to a different socket, could use <forward type="D" …> and <abortSession> (in this order) in one Get Updates reponse.

Update mechanism: A controller can choose whether it wants to receive updates through repeated Get Update requests (i.e. polling, see 8.3.4) or by opening a TCP/IP Update Channel and subsequently receiving updates through that channel (see 9).  However, once a client has opened a TCP/IP connection for receiving updates, the UCH shall send updates (including all that have accumulated before the Update Channel was opened) through the Update Channel only, and may not provide update information through Get Update requests any more.

Session expiration: A controller shall send a Get Updates request to the server at least every 5 minutes, unless it has opened an Update Channel connection with the server (see 9).  A UCH may dispose a session with a client if it has not received a Get Updates message for more than 10 minutes and has no Update Channel connection with the client.

The following HTTP status codes apply to a Get Updates response:

HTTP status code	Use Cases
200 OK	The request was successfully processed.  If the request contained invalid path references, they were ignored by the server.
400 Bad Request	The request body is encoded in a format that the server does not support. The XML body of the request is not well-formed.
403 Forbidden	The client is not authorized to get updates pertaining to the specified session.
404 Not Found	Invalid session identifier.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The server is currently unable to handle the request.

8.3.5. Set Values

Having an open session with a remote control URI, a controller can request to change the target's state by setting the values of one or multiple variables (or components thereof), invoking commands (or components thereof), acknowledging notifications (or components thereof), and/or adding or removing actual indices of dimensional elements or sets, as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of a remote control URI offering the URC-HTTP protocol (shortName="URC-HTTP"), see 7.1.
• SessionId is the session identifier as contained in the response on the Open Session request (see 8.3.1).
•  The <set> element may occur multiple times within <setValues> for requesting changes of multiple UI Socket elements.  There may be multiple <set>, <invoke>, <ack>, <add> or <remove> subelements under <setValues>.
• A <set> subelement may occur any number of times under <setValues>, indicating a request for setting the value of a UI Socket variable or local command parameter (or a component thereof), with value being the requested new value.  varPath shall reference a UI Socket variable (or a component thereof), parPath a local command parameter (or a component thereof).  varPath may take any of the following forms (see 8.1.4): path without indices, shortcut path, path with given indices, path for partial XML content (only with an xmlPath of "id(nodeId)").  parPath may take any of the following forms (see 8.1.4): path for local command parameter.  Character encoding restrictions apply for varPath, parPath and value (see 5).

  NOTE: The request for setting the value of a Socket element is deemed successful (return code 200) if processed by the server, even if it rejects the new value.  In this case the response message does not include the path of the element (since its value did not change).

  NOTE: A controller shall not request to change the value of a variable whose current value is "undefined" (see ISO/IEC 24752-1).

  NOTE: A controller is not allowed to change the content of atomic resources for a socket element, not even for socket elements with dynamic resources.

• An <invoke> subelement may occur any number of times under <setValues>, indicating a request for invoking a UI Socket command (or a component thereof), with invokeMode being either "syn" (for synchronous call mode, i.e. the request will return when the execution has finished) or "asyn" (for asynchronous call mode, i.e. the request may immediately return).  cmdPath shall reference a UI Socket command (or component thereof), and may take one of the following forms (see 8.1.4): path without indices, shortcut path, path with given indices.  Character encoding restrictions apply for cmdPath and invokeMode (see 5).  See also paragraph on "Command invocation" below.

  NOTE: The request for invoking a Socket command is deemed successful (return code 200) if processed by the server, even if it rejects the actual invocation.  In this case the response message does not include the path of the command's state (since it did not change).

• An <ack> subelement may occur any number of times under <setValues>, indicating an acknowledgment of a UI Socket notification (or a component thereof).  A target interprets an acknowledgment as request for withdrawal of the notification.  notifyPath shall reference a UI Socket notification (or component thereof), and may take one of the following forms (see 8.1.4): path without indices, shortcut path, path with given indices.  Character encoding restrictions apply for notifyPath (see 5).  See also paragraph on "Notification acknowledgment" below.

  NOTE: The request for acknowledging a Socket notification is deemed successful (return code 200) if processed by the server, even if it does not retract the notification.  In this case the response message does not include the path of the notification (since its state did not change).

• An <add> subelement may occur any number of times under <setValues>, indicating a request for adding a new actual index combination for a dimensional UI Socket element or set.  addPath shall reference a UI Socket element or set, in the following form: path with given indices.  If addPath specifies a socket element, initValue shall be provided as the proposed initial value of the resulting new element component.  For a variable (component), this is its requested new value as string representation.  For command and notification components initValue shall be empty.  If path specifies a socket set, initValue shall be empty.  Character encoding restrictions apply (see 5).
• A <remove> subelement may occur any number of times under <setValues>, indicating a request for removal of one or multiple actual indices for a dimensional UI Socket element or set.  removePath shall reference a UI Socket element or set, in one of the following forms: path with given indices, path with empty indices, path with range of indices. Character encoding restrictions apply (see 5).

  NOTE: The "path with empty indices" and "path with range of indices" forms can be used to request pruning of multiple components (i.e. request removal of a "slice" of the overall components).

The UCH shall process the individual requests (i.e. <set> elements) in the order as submitted. 

NOTE: If a Set Value Request contains an invalid path, the UCH should ignore the corresponding <set> element (still return with code 200).

Upon a processed Set Values request, the UCH shall respond by transmitting those values (and indices) that have changed based on the Set Values request.  Note that the UCH may or may not set the value of a UI Socket element (component) as requested, or may even set it to a different value because of side effects.

Whereby:

• The response body shall contain exactly one <updates> element (which may be empty).
• One or multiple <add> elements may occur, with restrictions as specified for the <add> element in a Get Updates response (see 8.3.4).
• One or multiple <remove> elements may occur, with restrictions as specified for the <remove> element in a Get Updates response (see 8.3.4).
• A <value> element may occur multiple times within <updates> for transmitting the values of multiple UI Socket elements (or components thereof) that have changed based on the Set Values request.  Note that, in order to avoid duplicate update messages, the UCH shall not send Update Events (see 8.3.4 and 9.2) for those UI Socket elements (or components thereof).  eltPath shall reference a UI Socket element (or a component thereof), and may take one of the following forms (see 8.1.4): path without indices, path with given indices, path for command state, path for command timeToComplete, path for local command parameter, path for partial XML content (only with an xmlPath of "id(nodeId)").  Character encoding restrictions apply for eltPath and value (see 5). 

Command invocation: If the command has local parameters, these shall be included (in the path form "path for local command parameter") as separate <set> elements inside <setValues> that immediately precede the <set> element for the invoke command request.  Global parameters may be included as preceding <set> elements – if their values is requested to change.  Also, this request may contain new value requests for other variables.  The response message to a synchronous command invocation request shall contain updated values of the local and global output parameters of the command, if any.  For asynchronous command invocation, the Set Values response message shall have an empty <updates> element (since the request returns before the execution of the command has finished).  The UCH shall notify the controller about any updated values of the command's local and global output parameters by a subsequent Update Event (see 9.2) or Get Updates request (see 8.3.4).

Notification acknowledgment: The controller acknowledges a notification by sending a Set Values request to the UCH, containing the element id of the corresponding notification element (component), and a new requested value of "inactive".  This request may contain new value request for other variables, but shall not reference other notification elements (or components thereof).  In other words, no two notifications can be acknowledged within one HTTP/HTTPS request.

The following HTTP status codes apply to a Set Values response:

HTTP status code	Use Cases
200 OK	The request was successfully processed.  If the request contained invalid path references, they were ignored by the server.  Also, the target may have rejected some or all of the requested values.
400 Bad Request	The request body is encoded in a format that the server does not support. The XML body of the request is not well-formed.
403 Forbidden	The client is not authorized to set values pertaining to the specified session.
404 Not Found	Invalid session identifier.
500 Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable	The server is currently unable to handle the request.

8.3.6. Get Resources (In-Session)

Having an open session with a remote control URI, a controller may query a list of static or dynamic atomic resources from a UCH, while in a session, as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of a remote control URI offering the URC-HTTP protocol (shortName="URC-HTTP"), see 7.1.
• SessionId is the session identifier as contained in the response on the Open Session request (see 8.3.1).
• Other parameters as specified for the out-of-session message Get Resources (see 8.2.1).

NOTE: The difference between the out-of-session and in-session versions of Get Resources is that the in-session version includes dynamic resources, if provided by the target.  Dynamic resources are session specific, and can only be obtained through URC-HTTP if a session is open with the corresponding target.  Controllers should use the in-session version when requesting resources during a session, in order to have dynamic resources automatically included in the response,

Upon a processed Get Resources request, the UCH shall respond by transmitting the requested static and dynamic atomic resources, if available, as specified in 8.2.1.

9. Update Channel

A UCH shall implement a "push mechanism" to send Update Events to the controller through a permanent TCP/IP socket connection (called "Update Channel").  A controller may open such a TCP/IP connection after it has received the connection specific parameters in an Open Session Request response (see 8.3.1).

Note that a controller is not obliged to open the Update Channel.  It may opt to get updates through repeated Get Updates requests (polling) instead (see 8.3.4).

9.1. Opening the Update Channel

A controller may open an Update Channel to the UCH, using the given IP address and port number contained in the Open Session Request response from the UCH (see 8.3.1).  Upon successful opening of the Update Channel, the controller shall send the following to the UCH through the Update Channel.

Whereby:

• sessionId is the sessionId contained in the Open Session Request response from the UCH (see 8.3.1). 

If sessionId is empty, the client shall still send the EOF character.

9.2. Update Events

If a controller has opened an Update Channel with a UCH, the UCH shall send Update Events for one or multiple UI Socket elements (or components thereof) that have changed, through the Update Channel in the following format:

Whereby the same rules and restrictions (except for session expiration) apply as for the Get Updates response message (see 8.3.4).

The UCH may send an empty Update Event as follows:

Session expiration: The controller shall acknowledge Update Events at most 30 seconds after an Update Event was sent, with the following message through the Update Channel:

The UCH may send empty Update Events on the Update channel to check if the client is still connected.  At any time during a session, if the client does not acknowledge an Update Event nor any subsequent Update Event 30 seconds from the first Update Event, the UCH may dispose the session with the controller, and close the Update Channel with it.

10. Session Management

A UCH shall support URL rewriting (see 10.1) for session management.  It may support Cookies (see 10.2) as an alternate means for session management.  The controller shall use URL rewriting (as specified in this document) when making session-specific HTTP/HTTPS requests (i.e. all HTTP/HTTPS requests except the Open Session request).

The UCH may dispose existing sessions at any time, based on timeout or resource usage limits.  If a message from the client pertains to an expired session, the Server shall respond with HTTP status code 404 Not Found, as follows:

10.1. URL Rewriting

A controller shall use URL rewriting in all HTTP/HTTPS requests following an Open Session request.  As specified in 8.3.2, 0, 8.3.4, and 8.3.5, the controller shall append "&session=SessionId" to the path of every HTTP/HTTPS request to the UCH, following a successful Open Session request. 

Whereby:

• sessionId is the session identifier given by the UCH as content of <session> in its response to an Open Session request (see 8.3.1).

For example, the controller would make a subsequent Get Element Values request as follows, given a sessionId of "xyz1234":

10.2. Cookies

Cookies may be used in any of the HTTP/HTTPS requests to maintain state information between the UCH and controller.

A UCH may respond to a controller's Open Session request (see 8.3.1) with a response including cookie information, if accepted.  See IETF RFC 2109.

For example, a UCH's response to an Open Session request may be as follows:

NOTE: This is just an example and is not intended to constrain the format of the Set-Cookie header used by the UCH.

A controller that has received a Set-Cookie header, may include its value with the Cookie header for any subsequent HTTP/HTTPS request to the same UCH, as specified in IETF RFC 2109 [REF].

For example, the controller could make a subsequent Get Values request as follows:

NOTE: The controller is still required to use URL rewriting in any request, i.e. include the session identifier in the URL of the request.

11. 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:

• Gottfried Zimmermann (Access Technologies Group, Germany)
• Parikshit Thakur (Plenar Technologies, India)
• Gregg Vanderheiden (Trace R&D Center, University of Wisconsin, USA)
• Bruno Rosa, Nelson Alves (Meticube, Portugal)