diff options
| -rw-r--r-- | ytstenut-protocol-messages.xsd | 6 | ||||
| -rw-r--r-- | ytstenut-protocol-status.xsd | 3 | ||||
| -rw-r--r-- | ytstenut-protocol.xml | 310 |
3 files changed, 192 insertions, 127 deletions
diff --git a/ytstenut-protocol-messages.xsd b/ytstenut-protocol-messages.xsd index d5543ee..e0f7fd4 100644 --- a/ytstenut-protocol-messages.xsd +++ b/ytstenut-protocol-messages.xsd @@ -14,6 +14,12 @@ <xs:attribute name='version' type='xs:string' use='required'/> + <xs:attribute name='from-service' + type='xs:NMTOKEN' + use='required'/> + <xs:attribute name='to-service' + type='xs:NMTOKEN' + use='required'/> <xs:attribute name='time' type='xs:dateTime' use='required'/> diff --git a/ytstenut-protocol-status.xsd b/ytstenut-protocol-status.xsd index 60e5e91..89712ac 100644 --- a/ytstenut-protocol-status.xsd +++ b/ytstenut-protocol-status.xsd @@ -17,6 +17,9 @@ <xs:attribute name='version' type='xs:string' use='required'/> + <xs:attribute name='from-service' + type='xs:NMTOKEN' + use='required'/> <xs:attribute name='capability' type='xs:NMTOKEN' use='required'/> diff --git a/ytstenut-protocol.xml b/ytstenut-protocol.xml index 784197f..82fa363 100644 --- a/ytstenut-protocol.xml +++ b/ytstenut-protocol.xml @@ -105,7 +105,7 @@ </revhistory> <copyright> - <year>2010</year> + <year>2011</year> <holder>Intel Corporation</holder> </copyright> </info> @@ -559,18 +559,6 @@ <section xml:id="local-ytstenut"> <title>Link-local Ytstenut protocol</title> - <annotation role="comment"> - <info> - <authorinitials>tf</authorinitials> - <orgname>Intel</orgname> - </info> - - <para> - We might be able to piggyback directly on local-xmpp, so this might - go. - </para> - </annotation> - <para> The link-local Ytstenut protocol allows for automatic connection between Ytstenut clients running on the same LAN. It is derived from the @@ -631,22 +619,22 @@ </section> + <section xml:id="messaging-app-id"> + <title>Application/Service Identifier</title> + + <para> + Each application/service is identified by a unique identifier. The + identifier is constructed following the D-Bus naming + convention<citation><xref linkend="dbus-spec"/></citation>, e.g., + <code>com.meego.BestestFriendApplication</code>. This identifier is used + to identify message and status senders and recipients as described later + in this document. + </para> + </section> + <section xml:id="messaging-app-info"> <title>Descriptive Application Information</title> - <annotation role="comment"> - <info> - <authorinitials>tf</authorinitials> - <orgname>Intel</orgname> - </info> - <para> - This is in keeping with XPMN device management, but AFAIK XPMN is - missing the definition of user-friendly device and service - description. Something along these lines should be added to the XPMN - spec for service description. - </para> - </annotation> - <para> Ytstenut applications need to provide descriptive information about themselves that can be presented to the user. At the bare minimum, this @@ -654,115 +642,156 @@ </para> <para> - The mechanism for obtaining descriptive application information is XMPP - Entity Capabilities extension<citation><xref - linkend="xep0115"/></citation>; the descriptive information is contained - in a <code><identity/></code> element of <code>category</code> - 'client'. Two new types are defined for use with this category: - <code>'ytstenut-application'</code> and - <code>'ytstenut-controller'</code>, corresponding to task-oriented and - control applications respectively (see <xref - linkend="intro-application-classes"/>). + The descriptive information is advertised together with the application + capabilities, as described in <xref linkend="messaging-apps-caps"/> </para> + </section> - <para> - The <code>name</code> attribute of the <code><identity/></code> - element holds application name, while the <code>xml:lang</code> - attribute identifies the locale used by the <code>name</code> - attribute. As per XMPP Service Discovery extension<citation><xref - linkend="xep0030"/></citation>, the query reply may include multiple - <code><identity/></code> elements of the same category and type, - but with different <code>xml:lang</code> attribute. - </para> + <section xml:id="messaging-app-caps"> + <title>Application/Service Capabilities</title> <para> - If the <code><query/></code> of the original request has an - explicit <code>xml:lang</code> attribute, the reply contents should be - filtered by that attribute. If the <code>xml:lang</code> attribute of - the <code><query/></code> cannot be matched the respondent may - return either a suitable fall-back, or all available translations. + Ytstenut applications/services advertise their Ytstenut capabilities via + XMPP Entity Capabilities protocol<citation><xref + linkend="xep0115"/></citation>, using + <code>urn:ytstenut:capabilities</code> as the value of the + <code>node</code> attribute of the <code><c/></code> element. </para> <para> - (For full description of the XML elements, see <xref - linkend="appendix-schemas"/>). + When the device capabilities are queried, capabilities of each + application/service are represented in the <code><iq/></code> + reply using XMPP data form<citation><xref + linkend="xep0004"/></citation>; the form format is best described by an + example: </para> - <example xml:id="messaging-app-info-example"> - <title>Application Information XML example</title> - - <programlisting language="xml"><![CDATA[ -<iq to="icecream-maker@custom-foods.com/resource" - type="get" - id="appinfo1"> - - <query xmlns='http://jabber.org/protocol/disco#info'/ - xml:lang="en-GB"/> - -</iq> - - ... - -<iq to="a.customer@custom-foods.com/resource" - type="result" - id="appinfo1"> + <annotation role="todo"> + <info> + <authorinitials>tf</authorinitials> + <orgname>Intel</orgname> + </info> + <para> + Need to formaly specify a localisation mechanism for the form fields. + </para> + </annotation> - <identity category='client' - type='ytstenut-application' - name='Magic Icecream Maker' - xml:lang='en-GB'/> + <programlisting><![CDATA[ +<!-- a data form representing Banshee video player: --> +<x xmlns='jabber:x:data' type='result'> + + <field var='FORM_TYPE' type='hidden'> + <value>urn:ytstenut:capabilities#org.gnome.Banshee</value> + </field> + + <field var='type'> + <value>application</value> + </field> + + <field var='name'> + <value>en_GB/Banshee Media Player</value> + <value>fr/Banshee Lecteur de Musique</value> + </field> + + <field var='capabilities'> + <value>urn:ytstenut:capabilities:yts-caps-audio</value> + <value>urn:ytstenut:data:jingle:rtp</value> + </field> +</x> +]]></programlisting> -</iq>]]> - </programlisting> - </example> + <variablelist> + <title>Data form fields:</title> - </section> + <varlistentry> + <term><code>FORM_TYPE</code></term> + <listitem> + <para> + Links the form to the application; the value is constructed by + concatenating an <code>'urn:ytstenut:capabilies#'</code> prefix + with the application unique identifier (see <xref + linkend="messaging-app-id"/>), + </para> + <para> + Required. + </para> + </listitem> + </varlistentry> - <section xml:id="messaging-app-caps"> - <title>Application Capabilities</title> + <varlistentry> + <term><code>type</code></term> + <listitem> - <annotation role="comment"> + <annotation role="todo"> <info> <authorinitials>tf</authorinitials> <orgname>Intel</orgname> </info> <para> - This is in keeping with XPMN device and service management. + Review whether this distinction is really meaningfull, or whether + 'control' should not be another kind of capability. </para> </annotation> - <para> - Ytstenut applications must advertise their Ytstenut capabilities via - XMPP Entity Capabilities protocol<citation><xref - linkend="xep0115"/></citation>, using - <code>urn:ytstenut:capabilities</code> as the value of the - <code>node</code> attribute of the <code><c/></code> element. - </para> + <para> + The application/service type; either <code>application</code> or + <code>controller</code>. + </para> - <para> - Each individual Ytstenut capability is represented by the - <code><feature/></code> element; the <code>var</code> attribute is - constructed by concatenating an <code>'urn:ytstenut:capabilies:'</code> - prefix and the canonical name of the capability (for standard - capabilities defined in <xref linkend="messaging-metadata-caps"/>). - </para> + <para> + Required. + </para> + </listitem> + </varlistentry> - <para> - In addition, Ytstenut applications should also advertise any data - transfer protocols they support as above, using the <code>urn</code>s - defined in <xref linkend="messaging-data-transfer-urns"/> as the value - of the <code>var</code> attribute. For example, an application - supporting video playback capability and able to stream files via Jingle - RTP would be represented as: - </para> + <varlistentry> + <term><code>name</code></term> + <listitem> + <para> + A localised application/service name. + </para> - <programlisting><![CDATA[ -<query xmlns='http://jabber.org/protocol/disco#info' - node='urn:ytstenut:capabilities#....'> - <feature var='urn:ytstenut:capabilities:yts-caps-video' /> - <feature var='urn:ytstenut:data:jingle:rtp' /> -<c/> -]]></programlisting> + <para> + Required. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><code>capabilities</code></term> + + <listitem> + <para> + List of application/service capabilites; the values are + constructed by concatenating an + <code>'urn:ytstenut:capabilies:'</code> prefix and the canonical + name of the capability (for standard capabilities defined in <xref + linkend="messaging-metadata-caps"/>). + </para> + <para> + The capability list should further include any data transfer + protocols supported, using the <code>urn</code>s defined in <xref + linkend="messaging-data-transfer-urns"/> as additional values. + </para> + + <para> + Required. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><code>vendor</code></term> + <listitem> + <para> + A localised vendor name. + </para> + <para> + Optional. + </para> + </listitem> + </varlistentry> + </variablelist> </section> <section xml:id="messaging-status"> @@ -795,6 +824,17 @@ </varlistentry> <varlistentry> + <term><code>from-service</code></term> + + <listitem> + <para> + The ID of the application this status message describes; + required (see <xref linkend="messaging-app-id"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><code>capability</code></term> <listitem> @@ -856,6 +896,7 @@ <programlisting><![CDATA[ <ytstenut:status version='1.0' + from-service='com.meego.BestestFriendApplication' capability='yts-caps-video' activity='yts-activity-play' uri='some random youtube url' @@ -901,6 +942,28 @@ </varlistentry> <varlistentry> + <term><code>from-service</code></term> + + <listitem> + <para> + The ID of the application that sent this message; + required (see <xref linkend="messaging-app-id"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><code>to-service</code></term> + + <listitem> + <para> + The ID of the application that this message is for; + required (see <xref linkend="messaging-app-id"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry> <term> <code>type</code> </term> @@ -922,22 +985,6 @@ defined by this specification, but custom child elements are allowed. </para> - <annotation role="implementation"> - <info> - <authorinitials>tf</authorinitials> - <orgname>Intel</orgname> - </info> - <para> - In terms of TP API, I am thinking that the simplest way would be to - provide access to the message XML payload, either in some parsed - form that might be available in Wocky, or, perhaps even the raw XML - (the assumption is that there will be a higher level library sitting - on the top of telepathy-glib/qt that will provide conveniece API for - developers, so this could take care of how to represent this to the - developer. - </para> - </annotation> - </section> <section xml:id="messaging-commands-types"> @@ -1016,6 +1063,8 @@ <ytstenut:message version='1.0' type='ytstenut/command' time='1970-01-01T00:00:00.000Z' + from-service='com.meego.BestestFriendApplication' + to-service='com.meego.BestestFriendApplication' capability='yts-caps-video' activity='yts-activity-play' uri='some random youtube url' @@ -1725,7 +1774,7 @@ </biblioentry> <biblioentry xml:id="xep0004"> - <title>XEP-0030</title> + <title>XEP-0004</title> <subtitle>Data Forms</subtitle> <publishername>XMPP Standards Foundation</publishername> <bibliosource class="uri"> @@ -1857,6 +1906,13 @@ </bibliosource> </biblioentry> + <biblioentry xml:id="dbus-spec"> + <title>D-Bus Specification</title> + <bibliosource class="uri"> + <link xlink:href="http://dbus.freedesktop.org/doc/dbus-specification.html"/> + </bibliosource> + </biblioentry> + </bibliodiv> </bibliography> </article> |