Approved Technical Report 2013-12-17"/> name="dc:description" content=" 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 Remote UI [UPnP RUI] or CEA-2014-A [CEA-2014-A]. The URC-HTTP 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."/> URC-HTTP Protocol 2.0 (ATR)

URC-HTTP Protocol 2.0 (ATR)

Approved Technical Report 2013-12-17

This version: http://openurc.org/TR/urc-http-protocol2.0-20131217/
Latest version: http://openurc.org/TR/urc-http-protocol2.0/
Previous draft version: http://openurc.org/TR/urc-http-protocol2.0-20131008/ (changes marked)
Latest approved version: http://openurc.org/TR/urc-http-protocol1.0-20060303/
Editors: Parikshit Thakur, Bruno Rosa, Gottfried Zimmermann
List of current openURC Technical Reports: http://openurc.org/TR/
Copyright 2013, 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 Remote UI [UPnP RUI] or CEA-2014-A [CEA-2014-A].

The URC-HTTP 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-HTTP protocol are specified in ISO/IEC 24752, Universal Remote Console (in particular [ISO/IEC 24752-1]). The features of this specification reflect the new draft versions of ISO/IEC 24752 which are expected to be released by end of 2013.

NOTE: The reader of this document will benefit greatly if they are familiar with the URC standards (ISO/IEC 24752, parts 1, 2, 4, and 5). For a quick introduction, see Overview of the Universal Remote Console framework and URC Technical Primer.

Status of this Document

This is an Approved Technical Report, provided to the public by the openURC Alliance. It was developed by the Technical Committee, in compliance with the TC procedures.

This document has been reviewed by the openURC Alliance members and by the public, and is endorsed by the openURC Board of Directors as an Approved Technical Report. It is a stable document and may be used as reference material or cited from other documents.

Comments on this document can be sent to the public comments list urc-http-protocol-comments@openurc.org. The archives for the comments list are publicly available. Comments received on this document cannot result in changes to this version (except for editorial fixes), but may be addressed in future versions of this document. The Technical Committee does not plan to make formal responses to comments.


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 User Interface servers that are compliant to UPnP Remote UI [UPnP RUI] or CEA-2014-A [CEA-2014-A].

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. Conventions in this Document

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

Messages and their formats are specified in this technical report 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).

3. Conformance

A UCH is conforming to this technical report if it implements:

A controller is conforming to this technical report if it implements:

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

4. Normative References

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

[CEA-2014-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.
[ISO/IEC 24752-1]
ISO/IEC 24752-1 (approved DIS version - final version expected in 2014). Information Technology User Interfaces Universal Remote Console. Part 1: Framework. ISO, 2013.
[ISO/IEC 24752-2]
ISO/IEC 24752-2 (currently FDIS version - final version expected in 2014). Information Technology User Interfaces Universal Remote Console. Part 2: User Interface Socket Description. ISO, 2013.
[ISO/IEC 24752-4]
ISO/IEC 24752-4 (currently FDIS version - final version expected in 2014). Information Technology User Interfaces Universal Remote Console. Part 4: Target Description. ISO, 2013.
[ISO/IEC 24752-5]
ISO/IEC 24752-5 (currently FDIS version - final version expected in 2014). Information Technology User Interfaces Universal Remote Console. Part 5: Resource Description. ISO, 2013.
[RES-PROP-VOCAB]
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 2119]
RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner, March 1997. Available at: http://www.ietf.org/rfc/rfc2119.txt.
[RFC 2616]
RFC 2616: Hypertext Transfer Protocol – HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, 1999. Available at: http://www.ietf.org/rfc/rfc2616.txt.
[RFC 6455]
RFC 6455: The Web Socket Protocol - I. Fette, A. Melnikov, December 2011. Available at: http://tools.ietf.org/html/rfc6455
[RFC application/xml]
RFC application/xml: XML Media Types. M. Murata, S. St.Laurent, D. Kohn, 2001. Available at: http://www.rfc-editor.org/rfc/rfcapplication/xml.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/.
[UPnP RUI]
UPnP Forum. Remote UI Client and Server V 1.0. Aug. 25, 2004. http://upnp.org/specs/rui/remoteui/
[XML Schema Definition Part 2]
W3C Recommendation: XML Schema Part 2: Datatypes Second Edition, 28 October 2004, http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.

5. Coding

5.1. Character Encoding

For all messages defined in this technical report, 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 ' '.

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, a command’s state or a notification state is undefined, either the socket element (variable, command or notification) is not available in the session (see ‘optional’ attribute on variables, commands and notifications, 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 technical report does not support multiple namespaces. All elements and attributes belong to the default namespace whose URI shall be "http://openurc.org/ns/urc-http2".

This namespace URI shall be implicitly assumed for all XML fragments defined by this technical report, 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. Discovery of URC-HTTP Protocol Remote User Interface

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 [CEA-2014-A]. The discovery of the URC-HTTP Protocol Remote User Interface shall comply with [UCH] section 12 "Discovery of Remote User Interface".

7.1. Advertising of URC-HTTP protocol

A UCH supporting the URC-HTTP protocol (see following note) shall advertise it 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 <ui> subelement (underneath the <uilist> element), 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://openurc.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.

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 Advertising of URC-HTTP protocol.

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 section Discovery of URC-HTTP Protocol Remote User Interface). 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/xml", if applicable.

NOTE: This MIME type is registered with IANA for XML "document entities" [RFC3023].

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 socket elements 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

cmdid

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

"state" value 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 notification timeToComplete

/set1/set2/notid[ttc]

notid[ttc]

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

"timeToComplete" field of a notification (component) – use first or second form for non-dimensional notifications; and last form for dimensional notifications.

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 [XML Schema Definition Part 2]. Values are case-sensitive.

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

8.1.6. Order of Elements

The order of elements in a transmission from the UCH to the controller does not necessarily reflect their order in the socket description. Controllers should be aware of this.

The internal order of dimensional elements (i.e. the order in which the components of a dimensional elements are transferred from the UCH to the controller) should reflect the defined order of its index values, as defined by the fundamental facet ‘ordered’ of the index type definition [XML Schema Definition Part 2]. For index types defined by restriction (enumeration types), the order should reflect the order in which the values are enumerated in the definition. If enumeration types are merged by the union operator, the order should follow the order in which the base types appear in the union statement.. This will support the controller in presenting the components in the same order, as recommended in [ISO/IEC 24752-1], section 5.7.6, Ordering of elements

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 User Interface Info request, the UCH shall respond as follows:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/xml; charset=utf-8 
[blank line]
<ui>
  <uiID>targetName socketName targetId</uiID>
  <name>friendlyName </name>
  <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-protocol2.0-20121022</conformsTo>
    </protocolInfo>
  </protocol>
</ui>

Whereby:

The following HTTP status codes apply to a Get User Interface Information 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 controller 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 "
              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 section Discovery of URC-HTTP Protocol Remote User Interface) 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/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/xml; charset=utf-8
[blank line]
<sessionInfo>
  <session> xyz1234 </session>
  <updateChannel>
    <ipAddress>192.168.0.1</ipAddress>
    <portNo>8888</portNo>
  </updateChannel>
  <includeDependencies types="relevant write" />
</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 Opening the Update Channel):

<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/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 Discovery of URC-HTTP Protocol Remote User Interface).

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 controller is not authorized to open a new session. This may occur for sockets that can only be opened by being forwarded from another session. Can also happen if the authorization code provided is not valid.

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 Get Values) 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 that 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 Cookies), instead of appending the "&session=SessionId" to the url. 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 URL Rewriting).

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 controller 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 controller'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/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 Undefined Value) 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 controller 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:

POST /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 controller'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 Set Updates).

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/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/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 Path Forms). 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 (Open Session Request) 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 Close Session Request) 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 section Discovery of URC-HTTP Protocol Remote User Interface).

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 Close Session Request).

NOTE: A target that wants to close the session with a controller, 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 Updates requests (i.e. polling, see Get Updates) or by opening a TCP/IP Update Channel and subsequently receiving updates through that channel (see Update Channel). However, once a controller 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 Updates 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 Update Channel). A UCH may dispose a session with a controller if it has not received a Get Updates message for more than 10 minutes and has no Update Channel connection with the controller.

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 controller 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 controller'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/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 Undefined Value) 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 controller 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.

501 Not Implemented This request is not supported by the UCH (since it is optional)

503 Service Unavailable

The server is currently unable to handle the request.

8.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/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>
</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.2Update Events) or Get Updates request (see Get Updates).

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). 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 controller 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.7. Get Resources (In-Session)

Having an open session with a remote control URI, a controller may query a list of atomic resources (static and/or dynamic) from a UCH, while in a session. Note that this request returns exactly one match per query item (or zero if no matching resource is found). Use the Get Resources With Properties request to obtain multiple matches per query item.

The request shall be as follows:

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

Whereby:

NOTE: The difference between this in-session version of Get Resources and the out-of-session version specified in [UCH] 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 one match per requested static atomic resource, if available, as follows:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/xml; charset=utf-8
[blank line]
<resourceResponse> 
  <resource />
  <resource> content </resource>
  <resource at="resourceUri" />
</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 controller 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.

404 Not Found

Invalid session identifier (SessionId).

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. Get Resources With Properties (In-Session)

A URC-HTTP server may implement a Get Resources With Properties request.

Having an open session with a remote control URI, a controller may query a detailed list of atomic resources (static and/or dynamic) from a UCH, while in a session. Each list item will yield a set of matching resources, if available. The list of resource sets may be split into multiple parts, upon request of the controller.

NOTE: The server may split the list into multiple parts ("slicing") in a light-weight way, by repeating the query to the resource server. In an extreme case (when the set of relevant resources changes on the resource server between the "slicing" calls) this may cause duplicate or missing resources. The controller should be aware of this risk, and call the "slicing" calls as quickly upon each other as possible.

The request shall be as follows:

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

Whereby:

NOTE: The Get Resources With Properties 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 section Discovery of URC-HTTP Protocol Remote User Interface) or from a resource server.

NOTE: The difference between this in-session version of Get Resources With Properties and the out-of-session version specified in [UCH] 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.

NOTE: In contrast to Get Resources, Get Resources With Properties can return, in the response to the request, multiple results ("resource set") per query. Each result includes also the attributes about the resource that the UCH knows. It can also slice the resulting resource sets, by using the 'start' and 'count' attributes on <getResource>.

Upon a processed Get Resources With Properties request, the UCH shall respond by transmitting the requested list of resulting resource sets with static atomic resources, if available, as follows:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/xml; charset=utf-8
[blank line]
<resourceResponse> 
  <resourceSet start="start" count="count" total="total">
    <resource 
      eltRef="eltRef"
      valRef="value" 
      opRef="opUri"
      role="roleUri"
      type="type"
      format="mimetype"
      forLang="langcode"
      forTargetInstance="targetId"
      creator="creator"
      publisher="publisher"
      date="date"
      audience="audience">
      content 
    </resource>
    <resource 
      eltRef="eltRef"
      valRef="value" 
      opRef="opUri"
      role="roleUri"
      type="type"
      format="mimetype"
      forLang="langcode "
      forTargetInstance="targetId"
      creator="creator"
      publisher="publisher"
      date="date"
      audience="audience" 
      at="resourceUri" />
  </resourceSet>
</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 controller 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.

404 Not Found

Invalid session identifier (SessionId).

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

501 Not Implemented This request is not supported by the UCH (since it is optional)

503 Service Unavailable

The server is currently unable to handle the request.

8.3.9. 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/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 controller 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.

501 Not Implemented This request is not supported by the UCH (since it is optional)

503 Service Unavailable

The session could not be suspend because this feature is not available for this session.

8.3.10. Resume Session

Having an open session with a remote control URI, and being that session suspended (see Suspend Session), 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/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 controller 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.

501 Not Implemented This request is not supported by the UCH (since it is optional)

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 Web socket connection as defined in [RFC 6455] (called "Update Channel"). A controller may open such a TCP/IP Web socket connection after it has received the connection specific parameters in an Open Session Request response (see Open Session Request).

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

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 Open Session Request). Upon successful opening of the Update Channel, the controller shall send the following to the UCH through the Update Channel.

<session>sessionId</session>

Whereby:

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" 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 same rules and restrictions (except for session expiration) apply as for the Get Updates response message (see Get Updates).

The UCH may send an empty Update Event as follows:

<updates />

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 />

The UCH may send empty Update Events on the Update channel to check if the controller is still connected. At any time during a session, if the controller 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 URL Rewriting) and Cookies (see Cookies) 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 controller 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 sections Close Session Request, Get Values, Get Updates, Get Dependency Values, Set Values, Get Resources (In-Session), Get Resources With Properties (In-Session), Suspend Session, Resume Session, 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 emptyUpdateQueue="boolean">
  <get ref="path" depth="number" pruneIndices="boolean" pruneXMLContent="boolean" includeSets="boolean" />
  <getIndex ref="elementPath" />
</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 Open Session Request) 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/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 emptyUpdateQueue="boolean">
  <get ref="path" depth="number" pruneIndices="boolean" pruneXMLContent="boolean" includeSets="boolean" />
  <getIndex ref="elementPath" />
</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 Grants H133E030012 & H133E080022 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:

12. Appendix (informative): Is URC-HTTP RESTful?