URC-HTTP Protocol 2.0 (DRAFT)

Draft Technical Report 2012-10-22

This version: http://openurc.org/TR/urc-http-protocol2.0-20121022/
Latest version: http://openurc.org/TR/urc-http-protocol2.0/
Previous draft version: http://myurc.org/TR/urc-http-protocol2.0-20091103/ (changes marked)
Latest approved version: http://myurc.org/TR/urc-http-protocol1.0-20060303/
Editors:
Parikshit Thakur
Bruno Rosa

Copyright 2012, OpenURC Alliance


Abstract

This OpenURC Alliance 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. Some features of this spec reflect the new draft versions of ISO/IEC 24752 which are expected to be released by 2013.

Status of this Document

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

Comments on this document should be sent to the editors.

Publication as a Draft Technical Report does not imply endorsement by the OpenURC Alliance 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.

2012-10-22 Gottfried Zimmermann: Publication of draft (heart-beat)

2012-09-07 Parikshit Thakur

2012-03-26 Gottfried Zimmermann

2012-02-06 Bruno Rosa

2012-01-23 Bruno Rosa

2012-01-06 Bruno Rosa

2011-12-11 Parikshit Thakur

2011-12-09 Bruno Rosa

2011-12-7 Bruno Rosa

2011-11-25 Bruno Rosa

2011-11-14 Parikshit Thakur

2011-10-10 Bruno Rosa

2011-09-02 Bruno Rosa

2011-08-03 Parikshit Thakur/p>

2011-07-21 Parikshit Thakur

2011-06-24 Parikshit Thakur

2011-02-01 Parikshit Thakur & Gottfried Zimmermann

2010-03-04 Bruno Rosa:

2010-01-27 Bruno Rosa:

Open Issues [to be removed before final release]

  1. 2012-04-04 Bruno: Get Resources in session still has a TODO for adding new parameters to the response. Analyse it and compare with the GetResources request on the UCH spec.
  2. 2012-09-07 Parikshit: Should we include notification timeout value as part of the updates, so that URC can act upon it accordingly?

Issues pending for spec modification [to be removed before final release]

  1. [2011-11-25] Bruno: revise changes in UCH spec and standard and determine necessary changes on URC-HTTP spec.
  2. [2011-08-09 Parikshit] Section 'Path forms' – for commands of type basic command there is [state] mentioned in path and for type timed command there is [ttc] mentioned in the path. The command response ‘value’ in the updates or in set value response, will be unique in either case of [state] or [ttc]. In case of [state] the values will be ‘initial’, ‘inProgress’, ‘done’, etc. and in case of [ttc] the values will be in seconds or milli seconds. Values are unique and there no need to mention [state] or [ttc] in the path itself. By mentioning in the path it looks like a dimension and also makes ‘state’ and ‘ttc’ reserved words for dimension values, which is very specific to URC-HTTP protocol.
  1. [2011-02-17] If a notification triggers (becomes "active"), its local elements shall be shown in a modal dialog. URC-HTTP must convey the notification together with the values of its local elements.
  2. 2012-02-27 Parikshit & Gottfried: For dimensional elements, is there a way to indicate the order of the components along a dimension, when updates are transferred? Also, we would need an add operation that points to a particular index.

Closed Issues [to be removed before final release]

  1. [2009-11-03] 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).
  2. [2009-11-03] How to include descriptors in a Get Resources request?
  3. [2010-03-04] The response Map to a setValuesRequest (see http://openurc.org/TR/uch1.0-20121022/#IUIPMListener.setValuesRequest) should also include the realized operation (add, remove or set) and not only the path and value of the modified elements.
  4. [2009-11-03] Not specified: handling streaming (stream-typed variables)
  5. [2009-11-03] Add 'includeSet' attribute to Get Values and Get Updates messages, allowing for inclusion of set paths in the return?
  6. [2009-11-03] Suspend and resume session.
  7. [2009-11-03] Should a request to getValues empty the update queue for the requested elements?
  8. [2009-11-03] Add 'depth' attribute to Get Values and Get Updates messages, specifying the depth for the path?
  9. [2010-03-04] Bruno: Add a method to the UCH API, to the IUIPMListener in order to allow the open/close of contexts in the native protocol of the UI? In this case using URC-HTTP we also need to add specific URC-HTTP requests for this purpose.
  10. [2009-11-03] Automatic updates on dependencies.
  11. [2010-03-04] Bruno: Since the UCH can return multiple resources for each query (see http://openurc.org/TR/uch1.0-20121022/#IUIPMListener.getResources), the URC-HTTP protocol should also allow to return to the UI these multiple resources per query?
  12. [2012-12-09] Bruno: current out of session messages are not really URC-HTTP messages as they are directed to the UCH itself. Necessary to add new URC-HTTP out of session messages: openUserContext, closeUserContext and getCompatibleUIs.
  13. [2010-03-04] Bruno: Should it be added the possibility of passing the contextId (when the user has an open context in the UCH) in the URC-HTTP protocol itself and not always as a cookie? If we use just cookies, for example, different users can't use the same browser at the same time.
  14. [2010-09-23] Use iconList (see UPnP RUI spec) for conveying icons for each item in the ui list.
  15. [2011-09-02] Bruno: In chapter 9 - updates, how does the client knows that the Update channel was successfully established after sending the sessionId? Trace UCH respondes with a<updates>connected<updates \>
  16. [2011-09-02] Bruno: When using cookies with sessionId why is it still required to include the sessionId in the url?
  17. [2011-11-14] PT: EOF ASCII code is used in update channel. According to the ASCII definition this character is named <US> not <EOF>. Indeed, there seems to be no EOF code in ASCII. EOF means end of file and can be tested when reading a file. We are not sure if it is correct to use this term with sockets or streams which have no "end" unless the socket is terminated. We think EOT (end of transmission, ASCII 0x04) suits better in this case.
  18. [2011-02-17] Make notifications global, i.e. they are shown to the user independent of the set/group they are in.
  19. 2012-03-26 Gottfried: Default values for optional attributes in Get Value request? (See below for my proposals.)


Table of Contents


1. Scope

This OpenURC Alliance 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:

A controller is conforming to this standard if it implements:

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://openurc.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.openurc.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).

EOT is the (end-of-transmission) character (ASCII 0x04).

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:

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

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.

NOTE: A UCH that loads and installs a UIPM with the following properties is defined as "supporting the URC-HTTP protocol" [RES-PROP-VOCAB]:

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:

<uilist xmlns="urn:schemas-upnp-org:remoteui:uilist-1-0">
  <ui>
    <uiID>targetName socketName targetId</uiID>
    <name>friendlyName</name>
    <fork>true</fork> 
    <protocol shortName="URC-HTTP">
      <uri>remoteControlUri</uri>
      <protocolInfo> 
        <resName> resNameUri</resName>
        <name> label_for_protocol </name>
        <description> description_for_protocol</description>
        <socketDescriptionAt>SocketDescriptionURI</socketDescriptionAt>
        <targetDescriptionAt>TargetDescriptionURI</targetDescriptionAt>
       <conformsTo> http://openurc.org/TR/urc-http-protocol-2.0</conformsTo>
      </protocolInfo>
    </protocol>
  </ui>
</uilist>

Whereby:

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]:

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

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:

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:

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 User Interface Info

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

GET /RUIAppPath?getInfo HTTP/1.1
HOST: hostname :hostport
User-Agent: OS/version Browser/version
[blank line]

Whereby:

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

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8 
[blank line]
<ui>
  <uiID>targetName socketName targetId</uiID>
  <name>friendlyName </name>
  <protocol shortName="protocolShortName">
    <uri>remoteControlUri </uri>
    <protocolInfo>
      <socketDescriptionAt>SocketDescriptionURI</socketDescriptionAt>
      <targetDescriptionAt>TargetDescriptionURI</targetDescriptionAt>
      <conformsTo> http://myurc.org/TR/urc-http-protocol-20080814</conformsTo>
    </protocolInfo>
  </protocol>
</ui>

Whereby:

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:

POST /RUIAppPath?openSessionRequest
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]
<openSessionRequest authorizationCode="code ">
  <includeDependencies types="dependencyTypes" />
  <includeResources>
    <resource forVal="boolean "
              role="roleUri "
              type="type "
              format="mimetype "
              forLang="langcode "
              creator="creator "
              publisher="publisher "
              date="date "
              audience="audience " />
  </includeResources>
</openSessionRequest>

Or:

GET /RUIAppPath?openSessionRequest
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]

Whereby:

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:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<sessionInfo>
  <session>SessionId</session>
  <updateChannel>
    <ipAddress>Address </ipAddress>
    <portNo>Port </portNo>
  </updateChannel> 
  <includeDependencies types="dependencyTypes" />
</sessionInfo>

Whereby:

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

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<sessionInfo>
  <session> xyz1234 </session>
  <updateChannel>
    <ipAddress>192.168.0.1</ipAddress>
    <portNo>8888</portNo>
  </updateChannel>
  <includeDependencies types="dependencyTypes" />
</sessionInfo>

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

<session>xyz1234</session>
EOF

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

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<forward targetName="targetName" targetId="targetId" socketName="socketName" authorizationCode="authorizationCode" />

Whereby:

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:

GET /RUIAppPath?closeSessionRequest&session=SessionId HTTP/1.1
HOST: hostname :hostport
User-Agent: OS/version Browser/version
[blank line]

Whereby:

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:

HTTP/1.1 200 OK
Accept-Ranges: bytes
[blank line]
<sessionClosed />

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:

POST/RUIAppPath?getValues&session=SessionId
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]
<getValues emptyUpdateQueue="boolean">
  <get ref="path"depth="number" pruneIndices="boolean" pruneXMLContent="boolean" includeSets="boolean" />
  <getIndex ref="elementPath" />
</getValues>

Whereby:

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:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<values>
  <elt ref="path" hasDynRes="hasDynResValue" socketEltType="socketEltTypeValue" notifyCat="notifyCatValue">
    <value>value  </value>
    <resource />
    <resource>resource </resource>
    <resource at="resourceUri " />
    <dependencies>
      <relevant> relevantValue </relevant>
      <write> writeValue </write>
      <insert> insertValue </insert>
    </dependencies>
  </elt>
  <index ref="elementPath">
    <indexValue>indexValue 
      <resource />
      <resource>resource </resource>
      <resource at="resourceUri " />
    </indexValue>
  </index>
</values>

Whereby:

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:

GET/RUIAppPath?getUpdates&session=SessionId
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]
<getUpdates>
  <get ref="path" depth="number" pruneIndices="boolean" pruneXMLContent="boolean" includeSets="boolean" />
</getUpdates>

Whereby:

If a Get Updates Request contains an invalid path, or a path that has no matching instance (for dimensional elements), 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).

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<updates>
  <add ref="addPath" hasDynRes="hasDynResValue" socketEltType="socketEltTypeValue" notifyCat="notifyCatValue">
    <value> value</value>
    <dependencies>
      <relevant> relevantValue </relevant>
      <write> writeValue </write>
      <insert> insertValue </insert>
    </dependencies>
    <resource />
    <resource> resource </resource>
    <resource at="resourceUri " />
  </add>
  <remove ref="removePath" hasDynRes="hasDynResValue" socketEltType="socketEltTypeValue" notifyCat="notifyCatValue" />
  <update ref="path" hasDynRes="hasDynResValue"socketEltType="socketEltTypeValue" notifyCat="notifyCatValue">
    <value> value</value>
    <dependencies> 
      <relevant> relevantValue </relevant>
      <write> writeValue </write>
      <insert> insertValue </insert>
    </dependencies>
    <resource />
    <resource> resource </resource>
    <resource at="resourceUri " />
  </update>
  <forward type="forwardType " targetName="targetName" targetId="targetId" socketName="socketName" authorizationCode="authorizationCode" />
  <abortSession> message </abortSession>
</updates>

Whereby:

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

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<updates />

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:

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". In case the response to getUpdates includes a notification's change to state "active", and the notification contains variables or commands, the values of those variables and commands shall be included in the same getUpdates response in any case (even if they haven't changed their values). Notification updates should be sent to the user even if the request is for a different socket element. Notifications are global and so their updates should be always propagated even if not requested.

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

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. Get Dependency Values

A URC-HTTP server may support a get dependency values request.

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

POST/RUIAppPath?getDependencyValues&session=SessionId
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]
<getDependencyValues>
  <get ref="path" dependency="dependencyType" />
</getDependencyValues>

Whereby:

Upon a processed Get Dependency Values request, the UCH shall respond by transmitting the values of all requested dependencies of all requested 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 the requested dependencies 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:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<dependencies>
  <dependency ref="path" dependency="dependencyType">dependencyValue</dependency>
</dependencies>

Whereby:

Unavailable dependency on a socket element: There is no special message for inquiring about the availability of dependencies on socket elements. The UCH shall send the "undefined value" (see 5.4) for any dependency value that is not available in the session.

The following HTTP status codes apply to a Get Dependency 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 dependency 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.58.3.6. 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:

POST/RUIAppPath?setValues&session=SessionId
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]
<setValues>
  <set ref="varPath ">value </set>
  <set ref="parPath ">value </set>
  <invoke ref="cmdPath">invokeMode </invoke>
  <ack ref="notifyPath">value </ack>
  <add ref="addPath ">initValue </add>
  <remove ref="removePath " />
</setValues>

Whereby:

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.

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<updates>
  <add ref="addPath ">value
    <resource />
    <resource> resource </resource>
    <resource at="resourceUri " />
  </add>
  <remove ref="removePath " />
  <value ref="eltPath ">value
    <resource />
    <resource> resource </resource>
    <resource at="resourceUri " />
  </value>
</updates>

Whereby:

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 as per the type of the notification (possible values described above in setValues request XML). 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.8.3.7. 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:

POST/RUIAppPath?GetResources&session=SessionId
HTTP/1.1
HOST: hostname:hostport 
User-Agent: OS/version Browser/version
[blank line]
<resourceRequest maxItems="number">
  <getResource eltRef="eltRef "
  valRef="value " 
  opRef="opUri "
  role="roleUri "
  type="type "
  format="mimetype "
  forLang="langcode "
  forTargetInstance="targetId "
  creator="creator "
  publisher="publisher "
  date="date "
  audience="audience" /> 

TODO: Add
   
1. "start" indicating the start index of the requested list of resources.
2. "count" indicating the number of requested resources, starting from the start index.
3. "referenceId" indicating a reference identifier for a previous query.

</resourceRequest>

Whereby:

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.

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 atomic resources, if available, as follows:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<resourceResponse> 
  <resourceResults>
    <resource />
    <resource> resource </resource>
    <resource> resource </resource>
    <resource at="resourceUri " />
  </resourceResults>
</resourceResponse>

Whereby:

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.

8.3.8.3.8. Suspend Session

Having an open session with a remote control URI, a controller can request to suspend the current session, as follows:

POST/RUIAppPath?suspendSession&session=SessionId&timeout=Timeout
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]

Whereby:

Upon a processed Suspend Session request, the UCH shall respond if the session was suspended or not.

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<sessionInfo>
  <sessionSuspended>sessionSuspended</sessionSuspended>
  <sessionTimeout>sessionTimeout</sessionTimeout>
</sessionInfo>

Whereby:

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

HTTP status code

Use Cases

200 OK

The request was successfully processed.

403 Forbidden

The client is not authorized to suspend 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 suspend because this feature is not available for this session.

8.3.8.3.9. Resume Session

Having an open session with a remote control URI, and being that session suspended (see ref="#RefOpenSessionRequest">8.3.7), a controller can request to resume the current session, as follows:

POST/RUIAppPath?resumeSession&session=SessionId
HTTP/1.1
HOST: hostname :hostport 
User-Agent: OS/version Browser/version
[blank line]

Whereby:

Upon a processed Resume Session request, the UCH shall respond if the session was resumed or not.

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
[blank line]
<sessionInfo>
  <sessionResumed>sessionResumed</sessionResumed>
</sessionInfo>

Whereby:

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

HTTP status code

Use Cases

200 OK

The request was successfully processed.

403 Forbidden

The client is not authorized to resume 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 resumed because the UCH does not have this feature available.

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.

<session>sessionId </session> EOT

Whereby:

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

The UCH shall respond to an update channel request by either one of the following messages:

Whereby:

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:

<updates>
  <add ref="addPath ">value
    <resource />
    <resource> resource </resource>
    <resource at="resourceUri " />
  </add>
  <remove ref="removePath " />
  <value ref="path ">value
    <resource />
    <resource> resource </resource>
    <resource at="resourceUri " />
  </value>
  <forward type="forwardType" targetId="targetId" socketName="socketName" authorizationCode="authorizationCode " />
  <abortSession> message </abortSession>
</updates>
EOF  

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:

<updates />
EOF 

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:

<ackUpdates />
EOF 

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) and Cookies (see 10.2) for session management. The controller shall use either URL rewriting or Cookies (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:

HTTP/1.1 404 Not Found
Accept-Ranges: bytes

10.1. URL Rewriting

A controller may 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:

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

POST /RUIAppPath?getValues&session=xyz1234 HTTP/1.1
HOST: 192.168.0.1:8888 User-Agent: OS/version
Browser/version
[blank line]
<getValues>
  <get ref="path" includeSets="boolean" />
</getValues>

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:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/urc-http+xml; charset=utf-8
Set-Cookie: session=xyz1234
[blank line]
<sessionInfo>
  <session>xyz1234</session>
  <updateChannel>
    <ipAddress>192.168.0.1</ipAddress>
    <portNo>8888</portNo>
  </updateChannel>
</sessionInfo>

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, should 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:

POST /RUIAppPath?getValues HTTP/1.1
HOST: 192.168.0.1:8888
User-Agent: OS/version Browser/version
Cookie: session=xyz1234
[blank line]
<getValues>
  <get ref="path" includeSets="boolean" />
</getValues>

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: