You are here: MyURC.org > TR > urc-http-protocol1.0-20060303 > Specification

URC-HTTP Protocol Specification

Working Draft 2006-03-03
Editor: Gottfried Zimmermann

Abstract
This URCC Technical Report specifies the Universal Remote Console (URC) on HTTP protocol (short URC-HTTP protocol).  The URC-HTTP protocol can be implemented by Remote UI servers that are compliant to UPnP RemoteUI or CEA-2014.  This protocol may be optional for an RUI server.  However, if an RUI Server implements this protocol, it shall implement it exactly as described in this specification.
The URC protocol can be used by RUI clients that need a semantic description of the user interface components.  Examples for such RUI clients 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 the following standards:

• ANSI/INCITS 389-2005 – Universal Remote Console framework,
• ANSI/INCITS 390-2005 – User Interface Socket Description,
• ANSI/INCITS 392-2005 – Target Description, and
• ANSI/INCITS 393-2005 – Resource Description.

1. Status of this Document

This is a public Working Draft of the URC-HTTP Protocol Specification, as developed by the URC Consortium (URCC).  It is here made available for review by URCC members and the public. This version of this document was created on 2006-03-03.
Comments on this document should be sent to the editor, Gottfried Zimmermann.
Publication as a Working Draft does not imply endorsement by the URCC membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time.

2. <protocol> element

An RUI server that supports the URC/HTTP protocol will indicate so by a <protocol> element with attribute shortName=”URC” within an XML block with root element <uilist>.  The <uilist> XML block is either contained in a file with its URL as specified by the <uiListURL> element of the server’s device description (for RUIS1 or RUIS2), or is returned by the GetCompatibleUIs() action of the server (for RUIS2).
Format for a URC <protocol> element:

Whereby:

• The shortName attribute of a URC <protocol> element shall have the value “URC”.
• hostname, hostport and RUIAppPath denote the URI for the URC-HTTP protocol.  For each User Interface Socket provided by the RUI server there shall be exactly one <uri> subelement with its URI for the URC protocol as element content.  This URI is used by the RUI client to send URC-HTTP protocol conformant requests to the UI Socket of the RUI Server.
• The <protocolInfo> subelement shall have one <targetDescriptionAt> subelement that contains the URI for the Target Description as element content.  A Target Description contains information about a device that can be controlled by the means of the URC framework and the UI Sockets that this device provides for remote control.  This URI may point to a local file on the network (e.g. served by the Target device itself) or to a file on the Internet (e.g. served by a company’s webserver).

Note on Get Updates request vs. Update Channel: An RUI Client can choose whether it wants to receive updates through repeated Get Update requests (i.e. polling, see 2.3) or by opening a TCP/IP Update Channel and subsequently receiving updates through that channel (see 3).  However, once a client has opened a TCP/IP connection for receiving updates, the RUI Server sends updates (including all that have accumulated before the update channel was opened) through the update channel only, and does not have to provide update information through Get Update requests any more.

3. Request messages from RUI Client to RUI Server

Messages from the RUI Client are sent to the RUI Server over HTTP.

3.1 Get Update Channel Info

When interacting with an RUI Server level 1 or 2, a client may open a permanent TCP/IP connection (called “update channel”) with the server to receive update messages regarding the values of the UI Socket.  This request provides the client with the necessary information to open such a connection with the server.

Update Channel Info request:

Whereby:

• hostname, hostport and RUIAppPath are parts of the URI for the RUI Server as specified in section 1.

Upon an “Update Channel Info” request the RUI Server shall send the information as follows:

Whereby:

• Address is the IP address for the TCP/IP socket connection
• Port is the port number for the TCP/IP socket connection

3.2 Get Values

An RUI Client can request the values of one or more UI Socket elements as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of the URI for the RUI Server as specified in section 1.
• elementIdList  is a space-separated list of ids of UI Socket elements.  elementIdList must not be empty.

The RUI Server shall respond by transmitting the requested values as follows:

Whereby:

• elementid is the id of a UI Socket element.
• value is the value of the UI Socket element, as string representation.
• The <value> tag may occur multiple times within <values> for transmitting the values of multiple UI Socket elements.

3.3 Get Updates

An RUI Client can request an update of the UI Socket, as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of the URI for the RUI Server as specified in section 1.

The RUI Server shall respond by transmitting the updated values as follows.  The response shall contain the values of all UI Socket elements that have been updated since the last Get Element Updates request from the same RUI Client.  Exceptions: The first Get Element Updates request shall yield the full list of UI Socket element values.  Those UI Socket elements whose updated value has already been propagated to the RUI Client by the response to a previous Set Element Values request (see 2.4) must not be included here.

Whereby:

• elementid is the id of a UI Socket element (variable, command or notification).
• value is the value of the UI Socket element.  For variables, this is their value, as string representation.  For commands, this is their state (e.g. “ready”, “done”).  For notifications, this is their state (“active”, “inactive”).
• The <value> tag may occur multiple times within <updates> for transmitting the values of multiple UI Socket elements.

Note on command of type basicCommand or timedCommand: A URC Server indicates the continuing execution or return of a command invocation by propagating a state (value) change for the command’s elementid.  A new state of “inprogress” indicates that the command is still running.  A new state of “ready”, “error” or “done” indicate the conclusion of a command.  In the case of the conclusion of a command, the command’s local and global output parameters shall be included in the same “Get Updates” response, following immediately the <value> element with the command’s elementid

Note on notifications: A URC Server 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 a change from “active” to “inactive”.

3.4 Set Values

An RUI Client can request to set the values of one or multiple UI Socket elements, as follows:

Whereby:

• hostname, hostport and RUIAppPath are parts of the URI for the RUI Server as specified in section 1.
• elementid is the id of a UI Socket element (variable, command or notification).
• value is the requested new value of the UI Socket element. For variables, this is their requested new value as string representation.  For commands, it is the string “invoke” to request to invoke the corresponding command on the RUI Server (see note on command invocation below).  For notifications, it is “inactive” to request to withdraw the corresponding notification (see note on notification acknowledgement below).
• The <set> tag may occur multiple times within <setValues> for setting the values of multiple UI Socket elements, but there shall be no two instances referencing the same elementid.

The RUI Server shall process the individual requests (i.e. <set> elements) in the order as submitted.  The RUI Server shall respond by transmitting the updated values of the requested UI Socket elements.  Note that the RUI Server may or may not set the value of a UI Socket element as requested, or may even set it to a different value because of side effects.  In any case, the response must contain the values of the UI Socket elements after the RUI Server has dealt with the request:

Whereby:

• elementid is the id of a UI Socket element.
• value is the value of the UI Socket element.  For variables, this is their new value as string representation.  For commands, it is their state (e.g. “ready”, “done”).  For notifications, it is their new state (“active“ or “inactive”).
• The <value> tag may occur multiple times within <values> for transmitting the values of multiple UI Socket elements.

Note that the RUI Server will NOT send update events (see 2.3 and 3.1) for those UI Socket elements (variables and notifications) that are contained in the Set Element Values request and response.

Note on command invocation: There is no separate “invoke command” request.  RUI Clients invoke commands by sending a “Set Element Values” request and submitting the new value “invoke”.  This is a convention and should not be construed as setting the state of a command (which can only be changed by the server, not by the client).  If the command has local parameters, these shall be included as separate <set> elements inside <setValues> that immediately precede the <set> element for the “invoke command” request.  Global parameters may also be included as preceding <set> elements – if not the most recent value is assumed.  Also, this request may contain new value request for other variables.

Note on notification acknowledgment: The RUI Client acknowledges a notification by sending a Set Element Values request to the RUI Server, containing the element id of the corresponding notification element, and a new requested value of “inactive”.  This request may contain new value request for other variables, but must not reference other notification elements.  In other words, no two notifications can be acknowledged within one HTTP request.

3.5 Cookies

Cookies may be used in any of the above HTTP requests and responses to maintain state information between the RUI Server and RUI Client.

• Cookie HTTP-request header as specified in IETF RFC 2109 [REF]
• Set-Cookie HTTP-response header as specified in IETF RFC 2109 [REF]

For example, an RUI Server may respond to a Get Update Channel Info request by responding with a Set-Cookie header:

Note: This is just an example and is not intended to constrain the format of the Set-Cookie header used by the RUI Server.
Once the RUI Client has received a Set-Cookie header, it shall include its value with the Cookie header for any subsequent HTTP request to the same RUI Server, as specified in IETF RFC 2109 [REF].
For example, the RUI Client should make a subsequent Get Element Values request as follows:

4. Update channel for events from RUI Server to RUI Client

An RUI Server of level 1 and 2 “pushes” update events to the RUI Client through a permanent TCP/IP socket connection (called “update channel”).  The client may open such a TCP/IP connection after it has received the connection specific parameters by making an Get Update Channel Info request (see 2.1).
Note: There is no obligation on the client side to open the update channel.  It may opt to get updates through repeated get updates requests (polling, see 2.3) instead.

4.1 Update Values

If an RUI client has opened an update channel with the RUI Server, the server must send update events for one or multiple UI Socket elements through the update channel in the following XML format:

Whereby:

• elementid is the id of the element in the Socket Description whose value has changed.
• value is the new value of the element
• <value> may occur multiple times within <updates> for bundling multiple update events in one message.
• EOF is the End-Of-File character (ASCII 31)

Open Issues

• Do we need a MIME type for the URC/HTTP URI?
• Should we mandate UTF-8 or UTF-16 for the update channel?
• Can the server set a maximum frequency for polling (Get Updates request)?