mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-28 04:02:20 -05:00
initial version
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1999 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre
parent
88ffaf229f
commit
aa20307967
865
xep-0244.xml
Normal file
865
xep-0244.xml
Normal file
@ -0,0 +1,865 @@
|
|||||||
|
<?xml version='1.0' encoding='UTF-8'?>
|
||||||
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
||||||
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
||||||
|
%ents;
|
||||||
|
]>
|
||||||
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
||||||
|
<xep>
|
||||||
|
<header>
|
||||||
|
<title>IO Data</title>
|
||||||
|
<abstract>This specification defines an XMPP protocol extension for handling the input to and output from a remote entity.</abstract>
|
||||||
|
<legal>This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy (<http://www.xmpp.org/extensions/ipr-policy.shtml>). This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<<link url='http://creativecommons.org/licenses/by/2.5/'>http://creativecommons.org/licenses/by/2.5/</link>>).</legal>
|
||||||
|
<number>0244</number>
|
||||||
|
<status>Experimental</status>
|
||||||
|
<type>Standards Track</type>
|
||||||
|
<sig>Standards</sig>
|
||||||
|
<approver>Council</approver>
|
||||||
|
<dependencies>
|
||||||
|
<spec>XMPP Core</spec>
|
||||||
|
<spec>XEP-0001</spec>
|
||||||
|
<spec>XEP-0030</spec>
|
||||||
|
<spec>XEP-0050</spec>
|
||||||
|
</dependencies>
|
||||||
|
<supersedes/>
|
||||||
|
<supersededby/>
|
||||||
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||||
|
<author>
|
||||||
|
<firstname>Johannes</firstname>
|
||||||
|
<surname>Wagener</surname>
|
||||||
|
<email>johannes.wagener@med.uni-muenchen.de</email>
|
||||||
|
<jid>edrin@jabber.org</jid>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Egon</firstname>
|
||||||
|
<surname>Willighagen</surname>
|
||||||
|
<email>egonw@users.sf.net</email>
|
||||||
|
<jid>egonw@jabber.org</jid>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Andreas</firstname>
|
||||||
|
<surname>Heusler</surname>
|
||||||
|
<email>aheusler@in.tum.de</email>
|
||||||
|
<jid>krach@jabber.org</jid>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Tobias</firstname>
|
||||||
|
<surname>Markmann</surname>
|
||||||
|
<email>tm@ayena.de</email>
|
||||||
|
<jid>tm@ayena.de</jid>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Ola</firstname>
|
||||||
|
<surname>Spjuth</surname>
|
||||||
|
<email>ola.spjuth@farmbio.uu.se</email>
|
||||||
|
<jid>olas@pele.farmbio.uu.se</jid>
|
||||||
|
</author>
|
||||||
|
<revision>
|
||||||
|
<version>0.1</version>
|
||||||
|
<date>2008-06-18</date>
|
||||||
|
<initials>psa</initials>
|
||||||
|
<remark><p>Initial published version.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.4</version>
|
||||||
|
<date>2008-06-05</date>
|
||||||
|
<initials>jw/ew</initials>
|
||||||
|
<remark><p>The IO Data specific commands (procedure status and output request) were moved in the IO Data namespace. The Schema was adapted to become extensible.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.3</version>
|
||||||
|
<date>2008-04-16</date>
|
||||||
|
<initials>jw</initials>
|
||||||
|
<remark><p>Applied the suggested modifications in result to the discussion on the XMPP standards mailing list.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.2</version>
|
||||||
|
<date>2008-03-20</date>
|
||||||
|
<initials>jw</initials>
|
||||||
|
<remark><p>Added some missing namespaces in two examples.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.1</version>
|
||||||
|
<date>2008-02-25</date>
|
||||||
|
<initials>jw</initials>
|
||||||
|
<remark><p>Initial Version.</p></remark>
|
||||||
|
</revision>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<section1 topic='Introduction' anchor='intro'>
|
||||||
|
<section2 topic='About the intention to write this XEP' anchor='intention'>
|
||||||
|
<p>&xep0050; became a popular and widespread XMPP Protocol Extension to execute functions on a remote systems. It is supported by many XMPP client and service implementations. To date almost all of its implementations rely on &xep0004; to be the data container. However Ad-Hoc Commands is explicitly designed and mentioned to be used in combination with other data containers, too. This applies for the cases where the Data Forms specification does not fit the needs, for example the Data Forms can be too restrictive on strong typing of data (see Section 1.2).</p>
|
||||||
|
<p>The intention of the present XEP is to define a data container for the cases where Data Forms is not applicable or not optimal. The data container defined herein (IO Data) is very generic and discoverable. It is intended to be used for other purposes than Data Forms.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
<section2 topic='Limitations of Data Forms' anchor='limits'>
|
||||||
|
<p>The Data Forms data container has certain restrictive limitations:</p>
|
||||||
|
<ol>
|
||||||
|
<li>The supported Field Types are limited: text input fields, drop down boxes, different selectable optional values, etc. See <link url='http://www.xmpp.org/extensions/xep-0004.html#protocol-fieldtypes'>Data Forms - Field Types</link></li>
|
||||||
|
<li>The only allowed content type of the fields is xs:string. See <link url='http://www.xmpp.org/extensions/xep-0004.html#schema'>Data Forms - XML Schema</link></li>
|
||||||
|
<li>According to current specifications it is not possible to transport complex tree-based data structures. For example nested elements of elements cannot have nested elements at all, therefore lacking an XML key feature.</li>
|
||||||
|
</ol>
|
||||||
|
<p>The limitations of Data Forms are not bad. They are good for the special use case a client has to render a graphical representation of the service. In HTML the correlative is a HTML form. For a chat client developer this makes it plain and simple to develop a generic graphical client implementation with some simple text-input fields.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
<section2 topic='Why an additional data container is required' anchor='sense'>
|
||||||
|
<p>According to current standards it is not supported to encapsulate more complex data in the Data Forms data container. For example it is not possible to encapsulate a complete XML Document - the real "generic" data container - in the Data Forms data container, unless you encode the XML Document as xs:string – which would be considered bad practice.</p>
|
||||||
|
<p>However specialized clients are developed to make use of the service oriented architecture of XMPP. An example is given here: a XMPP client implementation reflects an Application Programming Interface (API) with an XMPP services by making use of Ad-Hoc Commands.</p>
|
||||||
|
<example caption='get_titles.js'><![CDATA[
|
||||||
|
// javascript syntax
|
||||||
|
|
||||||
|
service = client.getService("database.server.com");
|
||||||
|
|
||||||
|
function = service.getFunction("getXmlFile");
|
||||||
|
|
||||||
|
// Check if this Ad-Hoc Command supports the IO Data XEP?
|
||||||
|
if (function instanceof IoDataFunction) {
|
||||||
|
|
||||||
|
// Discover the input and output XML Schemata - required only once!
|
||||||
|
schemata = function.getIoSchemata();
|
||||||
|
|
||||||
|
// Dynamically marshal an API for the input and output - required only once!
|
||||||
|
inputOutputFactory = new IoFactory( schemata );
|
||||||
|
|
||||||
|
// Create and set the input
|
||||||
|
input1 = inputOutputFactory.createInputObject();
|
||||||
|
input1.setFileName("doc-ID-011021");
|
||||||
|
|
||||||
|
// Invoke the function and get the output
|
||||||
|
result1 = function.invoke(input1);
|
||||||
|
output1 = inputOutputFactory.getOutputObject(result1);
|
||||||
|
title1 = output1.getDocumentTitle();
|
||||||
|
|
||||||
|
// Next document
|
||||||
|
input2 = inputOutputFactory.createInputObject();
|
||||||
|
input2.setFileName("doc-ID-833423");
|
||||||
|
result2 = function.invoke(input2);
|
||||||
|
output2 = inputOutputFactory.getOutputObject(result2);
|
||||||
|
title2 = output1.getDocumentTitle();
|
||||||
|
|
||||||
|
...
|
||||||
|
}]]></example>
|
||||||
|
<p>The limitations of Data Forms make it impossible to define and handshake these actions clearly and precisely and without confusing existing and future implementations for the following reasons:</p>
|
||||||
|
<ol>
|
||||||
|
<li>Data Forms does not support a "Schemata Discovery". The form descriptor Data Forms provides (type='form') is not separated from the data transaction according to the Ad-Hoc Command logic descibed in XEP-0050. Therefore each function invocation would result in a form descriptor submission again causing unnecessary traffic. It is sufficient to discover the IO Schemata once.</li>
|
||||||
|
<li>It is not suggested to encapsulate XML Documents in the Data Forms in general.</li>
|
||||||
|
</ol>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Web Services over XMPP' anchor='ws'>
|
||||||
|
<p>Beside Ad-Hoc Commands two other XEPs exist that provide mechanisms to execute a function on a remote system. For this count &xep0009; and &xep0072;.</p>
|
||||||
|
<p>However, Jabber-RPC and SOAP over XMPP lack certain functionality that is important for flexible, simple and robust Web Services. Because of the limited expressiveness of XML-RPCs data types the Jabber-RPC is not suitable for complex functionality, similar to the limitations of Data Forms. While SOAP over XMPP supports complex data types it lacks an obvious mechanism for asynchronous usage. For example it has no default stateful design: there is no sessionid like in Ad-Hoc Commands. Beside this SOAP brings in severe complexity (XML associated abstractions) that was required for the primary transport layer HTTP. This complexity is not required because XMPP does already implement the required XML associated abstractions. In addition to that there are other issues that argument against SOAP. For example to date most HTTP SOAP implemented services are only compatible with a subset of SOAP libraries.</p>
|
||||||
|
<p>In contrast Ad-Hoc Commands comprises simple, clean and optionally stateful Web Service mechanisms by default. In addition to that asynchronous client notification can be achieved with a <message>, as indicated in Ad-Hoc Commands and as realized in some unofficial implementations.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
<section2 topic='The IO Data data container' anchor='conclusion'>
|
||||||
|
<p>In conclusion and as already suggested in Ad-Hoc Commands we describe an alternative data container. This data container is more generic in the way it can be used:</p>
|
||||||
|
<ol>
|
||||||
|
<li>It supports a "Schemata Discovery". Thus a client implementation can marshal an API for the input and output (and optionally for a service specific error) of a certain service.</li>
|
||||||
|
<li>This "Schemata Discovery" is separated from the data transaction. This reduces the amount of unnecessary traffic.</li>
|
||||||
|
<li>The Field Types of the described data container are on the one hand clearly defined (there is only description, input, output, error, and status) and on the other hand straightforward. Thus any kind of XML data (XML Document with namespaces that represent any imaginable data object) can be submitted.</li>
|
||||||
|
</ol>
|
||||||
|
<p>It is important to note that this XEP does not intent to replace or extent Data Forms. Also it does not break any current Ad-Hoc implementations. It just intends to offer another data container that fits much better under some circumstances where no GUI is rendered around an Ad-Hoc Command service.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Protocol' anchor='protocol'>
|
||||||
|
<p>The base syntax for the 'urn:xmpp:tmp:io-data' namespace is as follows &NSNOTE;; a formal description can be found in the XML Schema section below.</p>
|
||||||
|
<code><![CDATA[
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data'
|
||||||
|
type='transaction-type'>
|
||||||
|
<desc/>
|
||||||
|
<in/>
|
||||||
|
<out/>
|
||||||
|
<error/>
|
||||||
|
<status>
|
||||||
|
<elapsed/>
|
||||||
|
<remaining/>
|
||||||
|
<percentage/>
|
||||||
|
<information/>
|
||||||
|
</status>
|
||||||
|
</iodata>
|
||||||
|
]]></code>
|
||||||
|
|
||||||
|
<section2 topic='Transaction Types' anchor='trans'>
|
||||||
|
<table border="1" caption='IO Data Transaction Types allowed for client to service stanzas'>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Transaction Type</th>
|
||||||
|
<th>Purpose</th>
|
||||||
|
<th>Associated Ad-Hoc Command</th>
|
||||||
|
<th>REQUIRED for generic XEP compatibility</th>
|
||||||
|
<th>Contained Elements</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tr>
|
||||||
|
<th>io-schemata-get</th>
|
||||||
|
<th>To request the schemata of input and output.</th>
|
||||||
|
<th>execute</th>
|
||||||
|
<th>yes</th>
|
||||||
|
<th>-</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>input</th>
|
||||||
|
<th>To submit the input.</th>
|
||||||
|
<th>execute</th>
|
||||||
|
<th>yes</th>
|
||||||
|
<th><in></th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>getStatus</th>
|
||||||
|
<th>To request the status of the procedure.</th>
|
||||||
|
<th>next</th>
|
||||||
|
<th>yes</th>
|
||||||
|
<th>-</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>getOutput</th>
|
||||||
|
<th>To request the output.</th>
|
||||||
|
<th>next, complete</th>
|
||||||
|
<th>yes</th>
|
||||||
|
<th>-</th>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<table border="1" caption='IO Data Transaction Types allowed for service to client stanzas'>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Transaction Type</th>
|
||||||
|
<th>Purpose</th>
|
||||||
|
<th>Associated Ad-Hoc Command status value</th>
|
||||||
|
<th>REQUIRED for generic XEP compatibility</th>
|
||||||
|
<th>Contained Elements</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tr>
|
||||||
|
<th>io-schemata-result</th>
|
||||||
|
<th>To return the schemata of input and output.</th>
|
||||||
|
<th>completed</th>
|
||||||
|
<th>yes</th>
|
||||||
|
<th><desc> <in> <out></th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>output</th>
|
||||||
|
<th>To submit the output.</th>
|
||||||
|
<th>executing, completed</th>
|
||||||
|
<th>yes</th>
|
||||||
|
<th><out></th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>error</th>
|
||||||
|
<th>To submit additional error information.</th>
|
||||||
|
<th>executing</th>
|
||||||
|
<th>no</th>
|
||||||
|
<th><error></th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>status</th>
|
||||||
|
<th>To indicate the current status of the procedure.</th>
|
||||||
|
<th>executing</th>
|
||||||
|
<th>no</th>
|
||||||
|
<th><status></th>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
<section2 topic='Container Elements' anchor='trans'>
|
||||||
|
<p><desc> -- a textual description of the IO Data data container (xs:string).</p>
|
||||||
|
<p><in> -- contains the input. Valid for Transaction Type 'input' and 'io-schemata-result' only. May contain any XML data (XML Schema, XML Document ...).</p>
|
||||||
|
<p><out> -- contains the output. Valid for Transaction Type 'output' and 'io-schemata-result' only. May contain any XML data (XML Schema, XML Document ...).</p>
|
||||||
|
<p><error> -- describes the error raised by the procedure invocation. This element is optional and valid for Transaction Type 'error' and 'io-schemata-result' only. May contain any XML data (XML Schema, XML Document ...).</p>
|
||||||
|
<p><status> -- describes the status of the procedure. This element is optional and valid for Transaction Type 'status' only.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
<section2 topic='Status Elements' anchor='trans'>
|
||||||
|
<p><elapsed> -- an integer value of the time in milliseconds that elapsed since the procedure was invoked (xs:integer).</p>
|
||||||
|
<p><remaining> -- an integer value of the (estimated) time in milliseconds till the procedure will finish (xs:integer).</p>
|
||||||
|
<p><percentage> -- the percentage of the procedure that is finished (xs:integer).</p>
|
||||||
|
<p><information> -- describes the current status of the procedure.</p>
|
||||||
|
</section2>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Implementation Notes' anchor='impl'>
|
||||||
|
<p>Commands (= remote procedures) executed with Ad-Hoc Commands and IO Data SHOULD NOT keep the requester in an uncertain state. This means the responder SHOULD respond to the requester always as fast as possible. Thereby the requester acquires the sessionid. (As some remote procedures/calculations are cost-intensive and/or time-consuming the requester MUST "save" this sessionid for the case a network problem occurs.)</p>
|
||||||
|
<p>The Ad-Hoc Command logic applied for the IO Data data container should be associated with the following rules and keywords:</p>
|
||||||
|
<table border="1" caption='Subsequently allowed Ad-Hoc Commands are depending on the state of the service'>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Ad-Hoc Command</th>
|
||||||
|
<th>Keyword</th>
|
||||||
|
<th>Associated Transaction Type</th>
|
||||||
|
<th>Subsequently allowed commands</th>
|
||||||
|
<th>Status description</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tr>
|
||||||
|
<th>execute</th>
|
||||||
|
<th>Get Schemata</th>
|
||||||
|
<th>io-schemata-get</th>
|
||||||
|
<th>-</th>
|
||||||
|
<th>XML Schemata are returned immediately</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>execute</th>
|
||||||
|
<th>Start procedure</th>
|
||||||
|
<th>input</th>
|
||||||
|
<th>-</th>
|
||||||
|
<th>output returns immediately (synchronous)</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th></th>
|
||||||
|
<th>Start procedure</th>
|
||||||
|
<th>input</th>
|
||||||
|
<th>next, cancel</th>
|
||||||
|
<th>asynchronous procedure was invoked</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>next</th>
|
||||||
|
<th>Check status</th>
|
||||||
|
<th>getStatus</th>
|
||||||
|
<th>next, cancel</th>
|
||||||
|
<th>asynchronous procedure not finished</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th></th>
|
||||||
|
<th>Check status</th>
|
||||||
|
<th>getStatus</th>
|
||||||
|
<th>next, complete, cancel</th>
|
||||||
|
<th>asynchronous procedure finished</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th></th>
|
||||||
|
<th>Get result</th>
|
||||||
|
<th>getOutput</th>
|
||||||
|
<th>next, complete, cancel</th>
|
||||||
|
<th>result was delivered</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>cancel</th>
|
||||||
|
<th>Cancel/delete procedure</th>
|
||||||
|
<th>-</th>
|
||||||
|
<th>-</th>
|
||||||
|
<th>procedure terminated</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<th>complete</th>
|
||||||
|
<th>Get result + delete procedure</th>
|
||||||
|
<th>-</th>
|
||||||
|
<th>-</th>
|
||||||
|
<th>result was delivered, procedure terminated</th>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<section2 topic='Synchronous implementation - for immediately completing services' anchor='sync_imp'>
|
||||||
|
<ol>
|
||||||
|
<li>If a service can return the output immediately, it MAY respond with status='completed' and return the output (IO Data type='output'). This behavior is NOT RECOMMENDED for procedures that need more than 5 seconds to complete or that are cost-intensive.</li>
|
||||||
|
</ol>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Asynchronous implementation - for services that cannot return the output immediately' anchor='async_imp'>
|
||||||
|
<ol>
|
||||||
|
<li>If a service cannot return the result immediately (this refers to procedures that need more than 5 seconds to complete) or the invoked procedure is cost-intensive, it SHOULD response with status='executing' and a <actions> element containing the <next> element.</li>
|
||||||
|
<li>If the service returned status='executing' the requester MAY stay up-to-date by proceeding with action='next' combined with the IO Data transaction type='getStatus'. The responder MUST respond with status='executing' and a <actions> element containing the <next> element only as long as the procedure is not finished.</li>
|
||||||
|
<li>If the procedure finished the responder MUST respond to this request (action='next') combined with the IO Data transaction type='getStatus' with status='executing' and a <actions> element containing the <next> and the <complete> elements to indicate that the output is ready for collection. The requester MAY then request the result by proceeding with action='complete' or action='next' combined with the IO Data transaction type='getOutput'.</li>
|
||||||
|
<li>Asynchronous notification: If the procedure finished the service MUST actively notify the requester by sending a message containing an Ad-Hoc Command element with status='executing' and a <actions> element containing the <next> and the <complete> elements to indicate that the result is ready for collection.</li>
|
||||||
|
<li>If the requester requests the output with action='complete' the responder MUST return the result (IO Data transaction type='output') with status='completed'. This means the Ad-Hoc Command session terminated. The responder MUST subsequently delete associated procedure and result.</li>
|
||||||
|
<li>If the requester requests the output with action='next' combined with the IO Data transaction type='getOutput' the responder MUST return the result (IO Data transaction type='output') with status='executing' and a <actions> element containing the <next> and the <complete> elements to indicate that the the Ad-Hoc Command session continues to exist and the output is still available. The requester MUST subsequently delete the associated procedure and result with action='cancel'.</li>
|
||||||
|
</ol>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Error handling' anchor='error_imp'>
|
||||||
|
<p>Beside the errors that are associated with IQ or Ad-Hoc Command abstraction layer an internal procedure error may occur.</p>
|
||||||
|
<ol>
|
||||||
|
<li>If the procedure invocation fails (an error occurs) the responder MUST respond with status='completed'. To indicate that the procedure failed the <note> element MUST have type='error' as described in XEP 50 Ad-Hoc Commands. The service may provide additional error information within the IO Data data container (IO Data transaction type='error').</li>
|
||||||
|
<li>Asynchronous implementation only: If the service returned status='executing' (asynchronous implementation) and the procedure fails (an error occurs) the service MUST actively notify the requester by sending a message containing an Ad-Hoc Command element with status='executing' and a <actions> element containing the <next> element to the invoker. To indicate that the procedure failed the <note> element MUST have type='error' as described in XEP 50 Ad-Hoc Commands. The service may provide additional error information within the IO Data data container (IO Data transaction type='error'). The requester SHOULD subsequently delete the associated procedure with action='cancel'.</li>
|
||||||
|
<li>Asynchronous implementation only: If the procedure failed (an error occurs) the responder MUST respond to a status request (action='next') with status='executing' and a <actions> element containing the <next> element to the requester. To indicate that the procedure failed the <note> element MUST have type='error' as described in XEP 50 Ad-Hoc Commands. The service may provide additional error information within the IO Data data container (IO Data transaction type='error'). The requester SHOULD subsequently delete the associated procedure with action='cancel'.</li>
|
||||||
|
</ol>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Optional status information' anchor='status_imp'>
|
||||||
|
<ol>
|
||||||
|
<li>As long as the procedure did not finish (!) the service MAY provide additional status information within the IO Data data container (IO Data transaction type='status').</li> </ol>
|
||||||
|
</section2>
|
||||||
|
<p>Formalising machine to machine commands using the namespace defined herein, making such commands detectable and usable on-the-fly without the prerequisite for the requester to know the exact interface on the service site and the support for asynchronous as well as synchronous execution contributes to the usability of XMPP for complex grid-computing projects.</p>
|
||||||
|
<p>In example an IDE could support the development of such projects by generating code interfaces (client stubs) to machine to machine capable XMPP services by discovering and requesting all required information on-the-fly.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Use Cases' anchor='usecases'>
|
||||||
|
|
||||||
|
|
||||||
|
<section2 topic='Discovering support' anchor='ret_coli'>
|
||||||
|
<p>The requester can query for disco information on the command (Ad-Hoc Command) node to find out if it supports IO Data based commands.</p>
|
||||||
|
<example caption='Disco request for command information'><![CDATA[
|
||||||
|
<iq type='get'
|
||||||
|
from='user@university.example.org'
|
||||||
|
to='service.university.example.org'
|
||||||
|
id='iq_125'>
|
||||||
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
||||||
|
node='get_threedimensionalcoordinates'/>
|
||||||
|
</iq>]]></example>
|
||||||
|
<example caption='Disco result for command information'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='service.university.example.org'
|
||||||
|
to='user@university.example.org'
|
||||||
|
id='iq_125'>
|
||||||
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
||||||
|
node='get_threedimensionalcoordinates'>
|
||||||
|
<feature var='http://jabber.org/protocol/commands'/>
|
||||||
|
<feature var='urn:xmpp:tmp:io-data'/>
|
||||||
|
</query>
|
||||||
|
</iq>]]></example>
|
||||||
|
<p>To indicate support for IO Data it MUST include <feature var='urn:xmpp:tmp:io-data'/>. Of course the node can still provide <feature var='jabber:x:data'/> if this is supported, too.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
|
||||||
|
<section2 topic='Retrieving the IO Schemata' anchor='ret-schemata'>
|
||||||
|
<p>The 'in' and 'out' elements may each have any valid XML encoded elements as children. From a XML document style type of view <in/> and <out/> may be seen as root elements. Therefore it is required to "discover" the XML Schemata of the "dynamic children" of <in/> and <out/> (IO Schemata). This way a requester can marshal an API for the input and output of a certain service.</p>
|
||||||
|
<p>Beside the 'in' and 'out' elements an 'error' element is optionally allowed and would be discovered in exactly the same. It is not included in the example to keep it simple.</p>
|
||||||
|
<p>The XML Schemata request is done by setting the type of the IO Data element to 'io-schemata-get'.</p>
|
||||||
|
<example caption='IO Schemata request'><![CDATA[
|
||||||
|
<iq type='get'
|
||||||
|
from='user@university.example.org'
|
||||||
|
to='service.university.example.org'
|
||||||
|
id='iq_126'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
node='get_threedimensionalcoordinates'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='io-schemata-get'/>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<example caption='IO Schemata result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='service.university.example.org'
|
||||||
|
to='user@university.example.org'
|
||||||
|
id='iq_126'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
node='get_threedimensionalcoordinates'
|
||||||
|
status='completed'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='io-schemata-result'>
|
||||||
|
<desc>
|
||||||
|
This service returns 3D atomic coordinates for the
|
||||||
|
input structure. The input and output is encoded using the
|
||||||
|
Chemical Markup Language (CML).
|
||||||
|
</desc>
|
||||||
|
<in>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:any namespace='http://www.xml-cml.org/schema'
|
||||||
|
minOccur='1' maxOccur='1'/>
|
||||||
|
</xs:complexType>
|
||||||
|
</in>
|
||||||
|
<out>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:any namespace='http://www.xml-cml.org/schema'
|
||||||
|
minOccur='1' maxOccur='1'/>
|
||||||
|
</xs:complexType>
|
||||||
|
</out>
|
||||||
|
</iodata>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>This service example requires the content of <in/> and <out/> to be <cite>Chemical Markup Language</cite> <note>The Chemical Markup Language: <<link url='http://www.xml-cml.org/'>http://www.xml-cml.org/</link>>.</note> by requiring input with the namespace 'http://www.xml-cml.org/schema'. Additionally, it also defines the returned output to be <cite>Chemical Markup Language</cite>.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
|
||||||
|
<section2 topic='Executing a service' anchor='exec_serv'>
|
||||||
|
<p>To keep the example simple the children of the 'in' and 'out' elements just contain strings (the protein name and protein sequence). However in real use cases it is likely that the children of 'in' and 'out' contain very complex XML documents with many different valid elements, namespaces, or values.</p>
|
||||||
|
<p>The requester transmits the input to the service (responder) by setting the type of the IO Data element to 'input'.</p>
|
||||||
|
<example caption='Execute Command request'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='user@university.example.org'
|
||||||
|
to='service.university.example.org'
|
||||||
|
id='iq_127'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
node='get_proteinsequence'
|
||||||
|
action='execute'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='input'>
|
||||||
|
<in>
|
||||||
|
<proteinname xmlns='http://university.example.org/protocol/proteinservice/proteinname'>
|
||||||
|
CAB08284
|
||||||
|
</proteinname>
|
||||||
|
</in>
|
||||||
|
</iodata>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The service transmits the output to the requester by setting the type of the IO Data element to 'output'.</p>
|
||||||
|
<example caption='Execute command result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='service.university.example.org'
|
||||||
|
to='user@university.example.org'
|
||||||
|
id='iq_127'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000001'
|
||||||
|
node='get_proteinsequence'
|
||||||
|
status='completed'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='output'>
|
||||||
|
<out>
|
||||||
|
<proteinsequence xmlns='http://university.example.org/protocol/proteinservice/proteinsequence'>
|
||||||
|
mrkhpqsatk hlfvsggvas slgkgltass lgqlltargl hvtmqkldpy lnvdpgtmnp
|
||||||
|
fqhgevfvte dgaetdldvg hyerfldrdl sgsanvttgq vystviaker rgeylgdtvq
|
||||||
|
viphitdeik qrimamaqpd ggdnrpdvvi teiggtvgdi esqpfleaar qvrhdlgren
|
||||||
|
vfflhvslvp hlapsgelkt kptqhsvaal rsigitpdal ilrcdrdvpe slknkialmc
|
||||||
|
dvdidgvist pdapsiydip kvlhreelda fvvrrlnlpf rdvdwtewdd llrrvhephg
|
||||||
|
tvrialvgky vdfsdaylsv sealhaggfk hyakvevvwv asddcetatg aaavladvhg
|
||||||
|
vlipggfgir giegkigair yararglpvl glclglqciv ieatrsvglv qansaefepa
|
||||||
|
tpdpvistma dqkeivagea dfggtmrlga ypavlqpasi vaqaygttqv serhrhryev
|
||||||
|
nnayrdwiae sglrisgtsp dgylvefvey panmhpfvvg tqahpelksr ptrphplfva
|
||||||
|
fvgaaidyks aellpveipa vpeisehlpn ssnqhrdgve rsfpapaarg
|
||||||
|
</proteinsequence>
|
||||||
|
</out>
|
||||||
|
</iodata>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
|
||||||
|
<section2 topic='Executing a time-consuming service' anchor='exec_serv_time'>
|
||||||
|
<p>In this example the Ad-Hoc Command is a time-consuming and cost-intensive computation service. To keep the example simple the computation is a WAV to MP3 encoder - the input and output elements of this example make use of &xep0231;.</p>
|
||||||
|
<example caption='Execute Command request'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='user@server.org'
|
||||||
|
to='encoder.server.org'
|
||||||
|
id='iq_128'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
node='wav2mp3'
|
||||||
|
action='execute'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='input'>
|
||||||
|
<in>
|
||||||
|
<data xmlns='urn:xmpp:tmp:data-element'
|
||||||
|
alt='my-song.wav'
|
||||||
|
type='audio/x-wav'>
|
||||||
|
[ ... base64-encoded-audio ... ]
|
||||||
|
</data>
|
||||||
|
</in>
|
||||||
|
</iodata>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The service notifies the requester that the job is accepted: status='executing' and a <actions> element contains the <next> element.</p>
|
||||||
|
<example caption='Execute command result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='encoder.user.org'
|
||||||
|
to='user@user.org'
|
||||||
|
id='iq_128'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='executing'>
|
||||||
|
<note type='info'>WAV to MP3 encoding has been started. You may stay up to
|
||||||
|
date using the next-action.
|
||||||
|
</note>
|
||||||
|
<actions>
|
||||||
|
<next/>
|
||||||
|
</actions>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The requester MAY stay up-to-date by proceeding with action='next' combined with the IO Data transaction type='getStatus'.</p>
|
||||||
|
<example caption='Execute Command request'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='user@server.org'
|
||||||
|
to='encoder.server.org'
|
||||||
|
id='iq_129a'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
action='next'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='getStatus'>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The service returns the status of the procedure. The "still calculating"-status is indicated with the <actions> element that contains the <next> element only. The "calculation finished"-status is indicated with the <actions> element that contains the <next> and <complete> elements.</p>
|
||||||
|
<p>Optionally the result MAY contain additional status information within the IO Data element with IO Data transaction type='status' although is not shown here to keep the example simple.</p>
|
||||||
|
<example caption='Execute command result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='encoder.user.org'
|
||||||
|
to='user@user.org'
|
||||||
|
id='iq_129a'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='executing'>
|
||||||
|
<actions>
|
||||||
|
<next/>
|
||||||
|
</actions>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
<p>If the procedure is complete the service notifies the invoker with a message stanza containing an Ad-Hoc Command namespace with status='executing' and a <actions> element that contains the <next> and <complete> elements. The <complete> element indicates the calculation finished.</p>
|
||||||
|
<example caption='Notification message'><![CDATA[
|
||||||
|
<message from='encoder.user.org'
|
||||||
|
to='user@user.org'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='executing'>
|
||||||
|
<note type='info'>WAV to MP3 encoding finished. You may request the
|
||||||
|
output now.</note>
|
||||||
|
<actions>
|
||||||
|
<complete/>
|
||||||
|
<next/>
|
||||||
|
</actions>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>After that the requester can request the output with the Ad-Hoc Command action='complete'.</p>
|
||||||
|
<example caption='Execute Command request'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='user@server.org'
|
||||||
|
to='encoder.server.org'
|
||||||
|
id='iq_130a'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
action='complete'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The service returns the MP3 within the IO Data element. The status of the Ad-Hoc Command completed (status='completed').</p>
|
||||||
|
<example caption='Execute command result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='encoder.user.org'
|
||||||
|
to='user@user.org'
|
||||||
|
id='iq_130a'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='completed'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='output'>
|
||||||
|
<out>
|
||||||
|
<data xmlns='urn:xmpp:tmp:data-element'
|
||||||
|
alt='my-song.mp3'
|
||||||
|
type='audio/mpeg'>
|
||||||
|
[ ... base64-encoded-audio ... ]
|
||||||
|
</data>
|
||||||
|
</out>
|
||||||
|
</iodata>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
<p>Alternatively the requester can request the output with the Ad-Hoc Command action='next' combined with the IO Data transaction type='getOutput'. This will keep the Ad-Hoc Command session alive and it must be deleted subsequently. This design allows to recover from network breakage during the result transmission state of the client-server communication, but allowing to request receiving the computation results or second time, because the session was left open after the first request.</p>
|
||||||
|
<example caption='Execute Command request'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='user@server.org'
|
||||||
|
to='encoder.server.org'
|
||||||
|
id='iq_130b'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
action='next'>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='getOutput'>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The service returns the MP3 within the IO Data element. The status of the Ad-Hoc Command remains active (status='executing').</p>
|
||||||
|
<example caption='Execute command result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='encoder.user.org'
|
||||||
|
to='user@user.org'
|
||||||
|
id='iq_130b'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='executing'>
|
||||||
|
<actions>
|
||||||
|
<complete/>
|
||||||
|
<next/>
|
||||||
|
</actions>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='output'>
|
||||||
|
<out>
|
||||||
|
<data xmlns='urn:xmpp:tmp:data-element'
|
||||||
|
alt='my-song.mp3'
|
||||||
|
type='audio/mpeg'>
|
||||||
|
[ ... base64-encoded-audio ... ]
|
||||||
|
</data>
|
||||||
|
</out>
|
||||||
|
</iodata>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The requester MUST subsequently delete the remote procedure with the Ad-Hoc Command action='cancel'.</p>
|
||||||
|
<example caption='Execute Command request'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='user@server.org'
|
||||||
|
to='encoder.server.org'
|
||||||
|
id='iq_131'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
action='cancel'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The remote procedure is deleted.</p>
|
||||||
|
<example caption='Execute command result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='encoder.user.org'
|
||||||
|
to='user@user.org'
|
||||||
|
id='iq_130'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='canceled'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
<section2 topic='Asynchronous error notification' anchor='async_error_serv_time'>
|
||||||
|
<p>In case of an error the service the service notifies the invoker with a message stanza containing an Ad-Hoc Command namespace with status='executing' and a <actions> element that contains the <next> element. In addition to that it MUST contain a <note> element with type='error' to indicate the error.</p>
|
||||||
|
<p>The error notification MAY contain additional error information within the IO Data element with IO Data transaction type='error'.</p>
|
||||||
|
<example caption='Error notification message'><![CDATA[
|
||||||
|
<message from='encoder.user.org'
|
||||||
|
to='user@user.org'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='executing'>
|
||||||
|
<note type='error'>#593 - The encoder could not parse the file.</note>
|
||||||
|
<actions>
|
||||||
|
<next/>
|
||||||
|
</actions>
|
||||||
|
<iodata xmlns='urn:xmpp:tmp:io-data' type='error'>
|
||||||
|
<error>
|
||||||
|
<errorcode/>593</errorcode>
|
||||||
|
<description>The encoder could not parse the file.</description>
|
||||||
|
</error>
|
||||||
|
</iodata>
|
||||||
|
</command>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>In case of an error the service would respond to a status request (Ad-Hoc Command action='next' combined with the IO Data transaction type='getStatus') in a very similar way except that a <iq> and not a <message> would be used.</p>
|
||||||
|
</section2>
|
||||||
|
|
||||||
|
<section2 topic='Canceling a time-consuming service' anchor='cancel_serv_time'>
|
||||||
|
<p>An asynchronous remote procedure may be canceled (deleted) by the invoker at any time.</p>
|
||||||
|
<example caption='Cancel Command request'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='user@server.org'
|
||||||
|
to='encoder.server.org'
|
||||||
|
id='iq_129b'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
node='wav2mp3'
|
||||||
|
action='cancel'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The remote procedure is deleted.</p>
|
||||||
|
<example caption='Cancel command result'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='encoder.user.org'
|
||||||
|
to='user@user.org'
|
||||||
|
id='iq_129b'>
|
||||||
|
<command xmlns='http://jabber.org/protocol/commands'
|
||||||
|
sessionid='RPC-SESSION-0000002'
|
||||||
|
node='wav2mp3'
|
||||||
|
status='canceled'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
</section2>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Error Codes' anchor='error'>
|
||||||
|
<p>Error codes on the Ad-Hoc Command abstraction layer are inherited from Ad-Hoc Commands.</p>
|
||||||
|
<p>Application specific errors associated with a remote procedure call realized with IO Data in combination with Ad-Hoc Commands were described in section 3 - Implementation notes.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Internationalization Considerations' anchor='i18n'>
|
||||||
|
<p>Internationalization of messages sent by the server is covered by setting the @xml:lang attribute of the <iq> element. Services should reply in the same language in which the client asked the question. That is, if the client specifies a locale using the @xml:lang attribute on the <iq> element, then the server should reply in the same locale, and localize messages given in <desc>, <node>@info and <query><item>@name.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Security Considerations' anchor='security'>
|
||||||
|
<p>To follow.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='IANA Considerations' anchor='iana'>
|
||||||
|
<p>This document requires no interaction with &IANA;.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||||||
|
<section2 topic='Protocol Namespaces' anchor='ns'>
|
||||||
|
<p>Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:io-data"; upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
|
||||||
|
</section2>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='XML Schema' anchor='schema'>
|
||||||
|
<code><![CDATA[
|
||||||
|
<?xml version='1.0' encoding='UTF-8'?>
|
||||||
|
|
||||||
|
<xs:schema
|
||||||
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
||||||
|
targetNamespace='urn:xmpp:tmp:io-data'
|
||||||
|
xmlns='urn:xmpp:tmp:io-data'
|
||||||
|
elementFormDefault='qualified'>
|
||||||
|
|
||||||
|
<xs:element name='iodata'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:element name='desc' minOccurs='0' maxOccurs='1'
|
||||||
|
type='xs:string'/>
|
||||||
|
<xs:element name='in' minOccurs='0' maxOccurs='1'/>
|
||||||
|
<xs:element name='out' minOccurs='0' maxOccurs='1'/>
|
||||||
|
<xs:element name='error' minOccurs='0' maxOccurs='1'/>
|
||||||
|
<xs:element name='status' minOccurs='0' maxOccurs='1'/>
|
||||||
|
<xs:attribute name='type' use='required'>
|
||||||
|
<xs:simpleType>
|
||||||
|
<xs:restriction base='xs:NCName'>
|
||||||
|
<xs:enumeration value='io-schemata-get'/>
|
||||||
|
<xs:enumeration value='io-schemata-result'/>
|
||||||
|
<xs:enumeration value='input'/>
|
||||||
|
<xs:enumeration value='output'/>
|
||||||
|
<xs:enumeration value='getStatus'/>
|
||||||
|
<xs:enumeration value='getOutput'/>
|
||||||
|
<xs:enumeration value='error'/>
|
||||||
|
<xs:enumeration value='status'/>
|
||||||
|
</xs:restriction>
|
||||||
|
</xs:simpleType>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:anyAttribute/>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
<xs:element name='in'>
|
||||||
|
<xs:choice>
|
||||||
|
<!-- for x@type='io-schemata-result' : -->
|
||||||
|
<xs:any namespace='http://www.w3.org/2001/XMLSchema'
|
||||||
|
minOccurrence='1' maxOccurence='1'/>
|
||||||
|
<!-- for x@type='input' : -->
|
||||||
|
<xs:any namespace='##other' processContents='strict'/>
|
||||||
|
</xs:choice>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
<xs:element name='out'>
|
||||||
|
<xs:choice>
|
||||||
|
<!-- for x@type='io-schemata-result' : -->
|
||||||
|
<xs:any namespace='http://www.w3.org/2001/XMLSchema'
|
||||||
|
minOccurrence='1' maxOccurence='1'/>
|
||||||
|
<!-- for x@type='output' : -->
|
||||||
|
<xs:any namespace='##other' processContents='strict'/>
|
||||||
|
</xs:choice>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
<xs:element name='error'>
|
||||||
|
<xs:choice>
|
||||||
|
<!-- for x@type='io-schemata-result' : -->
|
||||||
|
<xs:any namespace='http://www.w3.org/2001/XMLSchema'
|
||||||
|
minOccurrence='1' maxOccurence='1'/>
|
||||||
|
<!-- for x@type='error' : -->
|
||||||
|
<xs:any namespace='##other' processContents='strict'/>
|
||||||
|
</xs:choice>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
<xs:element name='status'>
|
||||||
|
<!-- for x@type='status' -->
|
||||||
|
<xs:element name='elapsed' minOccurs='0' maxOccurs='1'
|
||||||
|
type='xs:integer'/>
|
||||||
|
<xs:element name='remaining' minOccurs='0' maxOccurs='1'
|
||||||
|
type='xs:integer'/>
|
||||||
|
<xs:element name='percentage' minOccurs='0' maxOccurs='1'
|
||||||
|
type='xs:integer'/>
|
||||||
|
<xs:element name='information' minOccurs='0' maxOccurs='1'
|
||||||
|
type='xs:string'/>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
</xs:schema>
|
||||||
|
]]></code>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Acknowledgements' anchor='ackn'>
|
||||||
|
<p><link url='http://bioclipse.net/'>The Bioclipse Project</link></p>
|
||||||
|
</section1>
|
||||||
|
</xep>
|
||||||
84
xep-0245.xml
Normal file
84
xep-0245.xml
Normal file
@ -0,0 +1,84 @@
|
|||||||
|
<?xml version='1.0' encoding='UTF-8'?>
|
||||||
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
||||||
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
||||||
|
%ents;
|
||||||
|
]>
|
||||||
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
||||||
|
<xep>
|
||||||
|
<header>
|
||||||
|
<title>The /me Command</title>
|
||||||
|
<abstract>This specification defines recommended handling of the /me command in XMPP instant messaging clients.</abstract>
|
||||||
|
&LEGALNOTICE;
|
||||||
|
<number>0245</number>
|
||||||
|
<status>Experimental</status>
|
||||||
|
<type>Historical</type>
|
||||||
|
<sig>Standards</sig>
|
||||||
|
<approver>Council</approver>
|
||||||
|
<dependencies>
|
||||||
|
<spec>XMPP Core</spec>
|
||||||
|
<spec>XMPP IM</spec>
|
||||||
|
</dependencies>
|
||||||
|
<supersedes/>
|
||||||
|
<supersededby/>
|
||||||
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||||
|
&stpeter;
|
||||||
|
<revision>
|
||||||
|
<version>0.1</version>
|
||||||
|
<date>2008-06-18</date>
|
||||||
|
<initials>psa</initials>
|
||||||
|
<remark><p>Initial published version.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.1</version>
|
||||||
|
<date>2008-06-09</date>
|
||||||
|
<initials>psa</initials>
|
||||||
|
<remark><p>First draft.</p></remark>
|
||||||
|
</revision>
|
||||||
|
</header>
|
||||||
|
<section1 topic='Introduction' anchor='intro'>
|
||||||
|
<p>Many Jabber/XMPP instant messaging clients provide special processing and presentation of the string "/me " at the beginning of a message body. This specification describes the recommended handling of this "command".</p>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Recommended Handling' anchor='handling'>
|
||||||
|
<p>The /me command <note>The string "/me " is usually pronounced "slash-me".</note> is a text string that enables a human user to type an action phrase and have it be presented in a special way within an instant messaging client. The text string is followed by a verb or verb phrase, such as "/me laughs" or "/me is logging off now". This command does not result in the generation of any XMPP protocol. Instead, the command is sent as-is (e.g., <body>/me laughs</body>) and the receiving client performs string-matching on the first four characters of the data included in the &BODY; element to determine if the message begins with the string "/me ". If the client finds a match, the receiving client will show the message in a special format. It is RECOMMENDED for the client to show the user name, nickname, or handle <note>On the difference between user names, nicknames, and handles, see &xep0165; and &xep0172;.</note> of the sender followed by the verb phrase in italicized text, prepended by the "*" character.</p>
|
||||||
|
<p>For example, imagine that the Greek god Atlas is in a chatroom with the other gods and types the following text in his IM client:</p>
|
||||||
|
<example caption="A Command"><![CDATA[
|
||||||
|
/me shrugs in disgust
|
||||||
|
]]></example>
|
||||||
|
<p>That text will be sent to all the occupants in the chatroom as follows:</p>
|
||||||
|
<example caption="XMPP Stanza"><![CDATA[
|
||||||
|
<message from='olympians@chat.gods.lit/Atlas'
|
||||||
|
to='olympians@chat.gods.lit'
|
||||||
|
type='groupchat'>
|
||||||
|
<body>/me shrugs in disgust</body>
|
||||||
|
</message>
|
||||||
|
]]></example>
|
||||||
|
<p>Each recipient's client would then show the message with some special formatting, such as:</p>
|
||||||
|
<example caption="Presented Message">
|
||||||
|
<span style='margin-left: 5%; font-style: italic;'>* Atlas shrugs in disgust</span>
|
||||||
|
</example>
|
||||||
|
<p>If the receiving client does not find a match on the string "/me " in the first four characters of the message body, it SHOULD NOT present the text in a special way. For example, the following message bodies do not match:</p>
|
||||||
|
<example caption="Some Non-Commands"><![CDATA[
|
||||||
|
<body>/meshrugs in disgust</body>
|
||||||
|
|
||||||
|
<body>/me's disgusted</body>
|
||||||
|
|
||||||
|
<body> /me shrugs in disgust</body>
|
||||||
|
|
||||||
|
<body>"/me shrugs in disgust"</body>
|
||||||
|
|
||||||
|
<body>Why did Atlas say "/me shrugs in disgust"?</body>
|
||||||
|
]]></example>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Accessibility Considerations' anchor='access'>
|
||||||
|
<p>This specification describes the /me command in terms of visual presentation. A client that presents messages aurally MAY modify its presentation of /me commands and SHOULD at a minimum transform the string "/me " into the user name, nickname, or handle of the sender.</p>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='Security Considerations' anchor='security'>
|
||||||
|
<p>There are no security concerns related to use of the /me command.</p>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='IANA Considerations' anchor='iana'>
|
||||||
|
<p>This document requires no interaction with &IANA;.</p>
|
||||||
|
</section1>
|
||||||
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||||||
|
<p>This document requires no interaction with the ®ISTRAR;.</p>
|
||||||
|
</section1>
|
||||||
|
</xep>
|
||||||
121
xep-0246.xml
Normal file
121
xep-0246.xml
Normal file
@ -0,0 +1,121 @@
|
|||||||
|
<?xml version='1.0' encoding='UTF-8'?>
|
||||||
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
||||||
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
||||||
|
%ents;
|
||||||
|
]>
|
||||||
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
||||||
|
<xep>
|
||||||
|
<header>
|
||||||
|
<title>End-to-End XML Streams</title>
|
||||||
|
<abstract>This specification defines methods for communicating via end-to-end XML streams over a logical or physical connection that provides a reliable transport between two endpoints.</abstract>
|
||||||
|
&LEGALNOTICE;
|
||||||
|
<number>0246</number>
|
||||||
|
<status>Experimental</status>
|
||||||
|
<type>Standards Track</type>
|
||||||
|
<sig>Standards</sig>
|
||||||
|
<approver>Council</approver>
|
||||||
|
<dependencies>
|
||||||
|
<spec>XMPP Core</spec>
|
||||||
|
</dependencies>
|
||||||
|
<supersedes/>
|
||||||
|
<supersededby/>
|
||||||
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||||
|
<registry/>
|
||||||
|
&stpeter;
|
||||||
|
<revision>
|
||||||
|
<version>0.1</version>
|
||||||
|
<date>2008-06-18</date>
|
||||||
|
<initials>psa</initials>
|
||||||
|
<remark><p>Initial published version.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.1</version>
|
||||||
|
<date>2008-06-13</date>
|
||||||
|
<initials>psa</initials>
|
||||||
|
<remark><p>First draft, split off from XEP-0174.</p></remark>
|
||||||
|
</revision>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<section1 topic='Introduction' anchor='intro'>
|
||||||
|
<p>XMPP as defined in &rfc3920; does not support direct interaction between endpoints, since it requires a client to authenticate an XML stream with a server and send of all of its outbound XML stanzas through that server (which potentially may route those stanzas through another server for delivery to the intended recipient). However, in some scenarios it is desirable to establish end-to-end XML streams between two endpoints instead of relying on the standard client-server architecture. These scenarios include:</p>
|
||||||
|
<ul>
|
||||||
|
<li>Two endpoints cannot access an XMPP server</li>
|
||||||
|
<li>Two endpoints want to enforce end-to-end encryption</li>
|
||||||
|
<li>Two endpoints want to send a high volume of XMPP traffic but the intermediate servers enforce rate limits</li>
|
||||||
|
</ul>
|
||||||
|
<p>The first scenario is addressed by &xep0174;. The second and third scenarios are addressed by [ProtoXEP-Jingle-XML-Streams]. Both of those technologies result in the establishment of a direct or mediated connection between two endpoints, such as a direct TCP connection, a bytestream through SOCKS5 (&xep0065;) or XMPP itself (&xep0047;), or other future transport methods such as ice-tcp.</p>
|
||||||
|
<p>Once two endpoints have such a connection, they can establish an XML stream over that connection for end-to-end "("e2e") communication. We call this an "e2e" stream.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Initiating an e2e Stream' anchor='initiate'>
|
||||||
|
<p>The initiator and recipient essentially follow the process defined in <cite>RFC 3920</cite> to establish XML streams between themselves.</p>
|
||||||
|
<p>First, the initiator opens an XML stream to the recipient over the negotiated transport.</p>
|
||||||
|
<example caption="Opening a Stream"><![CDATA[
|
||||||
|
<stream:stream
|
||||||
|
xmlns='jabber:client'
|
||||||
|
xmlns:stream='http://etherx.jabber.org/streams'
|
||||||
|
from='romeo@forza'
|
||||||
|
to='juliet@pronto'
|
||||||
|
version='1.0'>
|
||||||
|
]]></example>
|
||||||
|
<p>In accordance with &rfc3921bis;, the initial stream header SHOULD include the 'to' and 'from' attributes. In the case of <cite>XEP-0174</cite>, these SHOULD be the username@machine-name advertised in the PTR record. In the case of <cite>Jingle XML Streams</cite>, these SHOULD be the bare JIDs &BAREJID; of the entities as communicated via XMPP.</p>
|
||||||
|
<p>If the initiator supports stream features and the other stream-related aspects of XMPP 1.0 as specified in <cite>RFC 3920</cite>, then it SHOULD include the version='1.0' flag as shown in the previous example.</p>
|
||||||
|
<p>The recipient then responds with a stream header as well:</p>
|
||||||
|
<example caption="Stream Header Response"><![CDATA[
|
||||||
|
<stream:stream
|
||||||
|
xmlns='jabber:client'
|
||||||
|
xmlns:stream='http://etherx.jabber.org/streams'
|
||||||
|
from='juliet@pronto'
|
||||||
|
to='romeo@forza'
|
||||||
|
version='1.0'>
|
||||||
|
]]></example>
|
||||||
|
<p>If both the initiator and recipient included the version='1.0' flag, the recipient SHOULD also send stream features as specified in <cite>RFC 3920</cite>:</p>
|
||||||
|
<example caption="Recipient Sends Stream Features"><![CDATA[
|
||||||
|
<stream:features>
|
||||||
|
<starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
|
||||||
|
</stream:features>
|
||||||
|
]]></example>
|
||||||
|
<p>The exchange of stream headers results in an unencrypted and unauthenticated channel between the two entities. See the <link url='#security'>Security Considerations</link> section of this document regarding methods for authenticating and encrypting the stream.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Exchanging Stanzas' anchor='exchange'>
|
||||||
|
<p>Once the streams are established, either entity then can send XMPP message, presence, and IQ stanzas, with or without 'to' and 'from' addresses.</p>
|
||||||
|
<example caption="Sending a Message"><![CDATA[
|
||||||
|
<message from='romeo@forza' to='juliet@pronto'>
|
||||||
|
<body>M'lady, I would be pleased to make your acquaintance.</body>
|
||||||
|
</message>
|
||||||
|
]]></example>
|
||||||
|
<example caption="A Reply"><![CDATA[
|
||||||
|
<message from='juliet@pronto' to='romeo@forza'>
|
||||||
|
<body>Art thou not Romeo, and a Montague?</body>
|
||||||
|
</message>
|
||||||
|
]]></example>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Ending an e2e Stream' anchor='end'>
|
||||||
|
<p>To end the stream, either party closes the XML stream:</p>
|
||||||
|
<example caption="Closing the Stream"><![CDATA[
|
||||||
|
</stream:stream>
|
||||||
|
]]></example>
|
||||||
|
<p>The other party then closes the stream in the other direction as well:</p>
|
||||||
|
<example caption="Closing the Stream"><![CDATA[
|
||||||
|
</stream:stream>
|
||||||
|
]]></example>
|
||||||
|
<p>Both parties then SHOULD close the logical or physical connection between them.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Security Considerations' anchor='security'>
|
||||||
|
<p>XMPP networks use TLS (&rfc2246;) for channel encryption and SASL (&rfc4422;) for authentication. In the context of e2e XML streams, the parties SHOULD use TLS and SASL EXTERNAL with client certificates, including clientCert requests during the TLS negotiation for the purpose of mutual authentication.</p>
|
||||||
|
<p>End-to-end XML streams can be negotiated between two XMPP clients, between an XMPP client and a remote XMPP service (i.e., a service with which a client does not have a direct XML stream), or between two remote XMPP services. Therefore, a party to an e2e XML stream will present either a client certificate or a server certificate as appropriate. Such certificates MUST be generated and validated in accordance with the certificate guidelines guidelines provided in &rfc3920bis;.</p>
|
||||||
|
<p>A future version of this specification may provide additional guidelines regarding certificate validation in the context of end-to-end encryption.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='IANA Considerations' anchor='iana'>
|
||||||
|
<p>This document requires no interaction with &IANA;.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||||||
|
<p>This document requires no interaction with the ®ISTRAR;.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
</xep>
|
||||||
282
xep-0247.xml
Normal file
282
xep-0247.xml
Normal file
@ -0,0 +1,282 @@
|
|||||||
|
<?xml version='1.0' encoding='UTF-8'?>
|
||||||
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
||||||
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
||||||
|
%ents;
|
||||||
|
]>
|
||||||
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
||||||
|
<xep>
|
||||||
|
<header>
|
||||||
|
<title>Jingle XML Streams</title>
|
||||||
|
<abstract>This specification defines a Jingle application type for establishing direct or mediated XML streams between two entities over any reliable transport. This technology thus enables two entities to establish a trusted connection for end-to-end encryption or for bypassing server limits on large volumes of XMPP traffic.</abstract>
|
||||||
|
&LEGALNOTICE;
|
||||||
|
<number>0247</number>
|
||||||
|
<status>Experimental</status>
|
||||||
|
<type>Standards Track</type>
|
||||||
|
<sig>Standards</sig>
|
||||||
|
<dependencies>
|
||||||
|
<spec>XMPP Core</spec>
|
||||||
|
<spec>XEP-0047</spec>
|
||||||
|
<spec>XEP-0065</spec>
|
||||||
|
<spec>XEP-0166</spec>
|
||||||
|
<spec>XEP-0174</spec>
|
||||||
|
</dependencies>
|
||||||
|
<supersedes/>
|
||||||
|
<supersededby/>
|
||||||
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||||||
|
&stpeter;
|
||||||
|
&infiniti;
|
||||||
|
<author>
|
||||||
|
<firstname>Dirk</firstname>
|
||||||
|
<surname>Meyer</surname>
|
||||||
|
<email>dmeyer@tzi.de</email>
|
||||||
|
<jid>dmeyer@jabber.org</jid>
|
||||||
|
</author>
|
||||||
|
<revision>
|
||||||
|
<version>0.1</version>
|
||||||
|
<date>2008-06-18</date>
|
||||||
|
<initials>psa</initials>
|
||||||
|
<remark><p>Initial published version.</p></remark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<version>0.0.1</version>
|
||||||
|
<date>2008-06-13</date>
|
||||||
|
<initials>psa/jk/dm</initials>
|
||||||
|
<remark>First draft.</remark>
|
||||||
|
</revision>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<section1 topic='Introduction' anchor='intro'>
|
||||||
|
<p>The standard client-server architecture for XMPP communication provides a stable infrastructure for real-time communication. However, there are certain situations in which it is desirable to bypass the standard client-server architecture, including:</p>
|
||||||
|
<ul>
|
||||||
|
<li>Two endpoints cannot access an XMPP server</li>
|
||||||
|
<li>Two endpoints want to enforce end-to-end encryption</li>
|
||||||
|
<li>Two endpoints want to send a high volume of XMPP traffic but the intermediate servers enforce rate limits</li>
|
||||||
|
</ul>
|
||||||
|
<p>The first situation is addressed by &xep0174;. However, if the endpoints already have client-to-server connections but wish to bypass those connections or leverage those streams for a higher-level application such as end-to-end encryption, it is desirable for the two endpoints to negotiate an end-to-end XML stream. This specification defines methods for doing so, where the application format is an XML stream and the transport method is any direct or mediated reliable transport, such as &xep0047; (mediated), &xep0065; (direct or mediated), or a future ice-tcp Jingle transport (direct or mediated) based on &ice-tcp;.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='How It Works' anchor='protocol'>
|
||||||
|
<p>This section provides a friendly introduction to Jingle XML streams.</p>
|
||||||
|
<p>First, the party that wishes to initiate the stream determines the responder's capabilities (via &xep0030; or &xep0115;). Here we assume that the responder supports a service discovery feature of 'urn:xmpp:tmp:jingle:apps:xmlstream' &NSNOTE; corresponding to the Jingle XML stream functionalited defined herein, as well as the 'urn:xmpp:tmp:jingle:transports:bytestreams' and 'urn:xmpp:tmp:jingle:transports:ibb' features currently defined in &xep0234;.</p>
|
||||||
|
<p>The initiator then sends a Jingle session-initiation request to the responder. The content-type of the request specifies two things:</p>
|
||||||
|
<ol start='1'>
|
||||||
|
<li><p>An application type of "urn:xmpp:tmp:jingle:apps:xmlstream" &NSNOTE;, where the <description/> element specifies parameters for the XML stream, where the parameters map to those provided in &xep0155; in a way that is consistent with &xep0116;.</p></li>
|
||||||
|
<li><p>Options for the reliable transport method, such as In-Band Bytestreams ("IBB") as defined in <cite>XEP-0047</cite> or SOCKS5 Bytestreams ("S5B") as defined in <cite>XEP-0065</cite>.</p></li>
|
||||||
|
</ol>
|
||||||
|
<p>In this example, the initiator is <alice@example.org>, the responder is <bob@example.com>, and the initiation request specifies Alice's desired stream parameters along with a transport method of "bytestreams" (i.e., <cite>XEP-0065</cite>).</p>
|
||||||
|
<p>The flow is as follows.</p>
|
||||||
|
<code><![CDATA[
|
||||||
|
Alice Bob
|
||||||
|
| |
|
||||||
|
| session-initiate |
|
||||||
|
|---------------------------->|
|
||||||
|
| ack |
|
||||||
|
|<----------------------------|
|
||||||
|
| [ SOCKS5 negotiation ] |
|
||||||
|
|<--------------------------->|
|
||||||
|
| session-accept |
|
||||||
|
|<----------------------------|
|
||||||
|
| ack |
|
||||||
|
|---------------------------->|
|
||||||
|
| [ XML stream ] |
|
||||||
|
|---------------------------->|
|
||||||
|
| terminate |
|
||||||
|
|<----------------------------|
|
||||||
|
| ack |
|
||||||
|
|---------------------------->|
|
||||||
|
| |
|
||||||
|
]]></code>
|
||||||
|
<p>First the initiator sends a Jingle session-initiate.</p>
|
||||||
|
<example caption="Initiator sends session-initiate"><![CDATA[
|
||||||
|
<iq from='alice@example.org/foo'
|
||||||
|
id='jingle1'
|
||||||
|
to='bob@example.com/bar'
|
||||||
|
type='set'>
|
||||||
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
||||||
|
action='session-initiate'
|
||||||
|
initiator='alice@example.org/foo'
|
||||||
|
sid='851ba2'>
|
||||||
|
<content creator='initiator' name='xmlstream'>
|
||||||
|
<description
|
||||||
|
xmlns='urn:xmpp:tmp:jingle:apps:xmlstream'
|
||||||
|
authentication='optional'
|
||||||
|
disclosure='never'
|
||||||
|
logging='mustnot'
|
||||||
|
tls='required'/>
|
||||||
|
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
|
||||||
|
</content>
|
||||||
|
</jingle>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The responder immediately acknowledges receipt of the Jingle session-initiate.</p>
|
||||||
|
<example caption="Responder acknowledges session-initiate"><![CDATA[
|
||||||
|
<iq from='bob@example.com/bar'
|
||||||
|
id='jingle1'
|
||||||
|
to='alice@example.org/foo'
|
||||||
|
type='result'/>
|
||||||
|
]]></example>
|
||||||
|
<p>The initiator then attempts to initiate a SOCKS5 Bytestream with the responder.</p>
|
||||||
|
<example caption='Initiation of Interaction'><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='alice@example.org/foo'
|
||||||
|
to='bob@example.com/bar'
|
||||||
|
id='initiate'>
|
||||||
|
<query xmlns='http://jabber.org/protocol/bytestreams'
|
||||||
|
sid='mySID'
|
||||||
|
mode='tcp'>
|
||||||
|
<streamhost
|
||||||
|
jid='alice@example.org/foo'
|
||||||
|
host='192.168.4.1'
|
||||||
|
port='5086'/>
|
||||||
|
<streamhost
|
||||||
|
jid='streamhostproxy.example.net'
|
||||||
|
host='24.24.24.1'
|
||||||
|
zeroconf='_jabber.bytestreams'/>
|
||||||
|
</query>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>If the responder is willing to accept the bytestream, it MUST attempt to open a standard TCP socket on the network address of the StreamHost communicated by the initiator. If the initiator provides more than one StreamHost, the responder SHOULD try to connect to them in the order they occur.</p>
|
||||||
|
<p>If the responder is able to open a TCP socket on a StreamHost, it MUST utilize the SOCKS5 protocol specified in &rfc1928; to establish the connection with the StreamHost.</p>
|
||||||
|
<example caption='Responder Connects to StreamHost'><![CDATA[
|
||||||
|
CMD = X'01'
|
||||||
|
ATYP = X'03'
|
||||||
|
DST.ADDR = SHA1 Hash of: (SID + Initiator JID + Responder JID)
|
||||||
|
DST.PORT = 0
|
||||||
|
]]></example>
|
||||||
|
<example caption='StreamHost Acknowledges Connection'><![CDATA[
|
||||||
|
STATUS = X'00'
|
||||||
|
]]></example>
|
||||||
|
<p>After the responder has authenticated with the StreamHost, it MUST send an IQ-result to the initiator indicating which StreamHost was used.</p>
|
||||||
|
<example caption='Responder Notifies Initiator of Connection'><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='bob@example.com/bar'
|
||||||
|
to='alice@example.org/foo'
|
||||||
|
id='initiate'>
|
||||||
|
<query xmlns='http://jabber.org/protocol/bytestreams'>
|
||||||
|
<streamhost-used jid='streamhostproxy.example.net'/>
|
||||||
|
</query>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The responder then sends a Jingle session-accept.</p>
|
||||||
|
<example caption="Responder sends session-accept"><![CDATA[
|
||||||
|
<iq from='bob@example.com/bar'
|
||||||
|
id='accept1'
|
||||||
|
to='alice@example.org/foo'
|
||||||
|
type='set'>
|
||||||
|
<jingle xmlns='urn:xmpp:tmp:jingle'
|
||||||
|
action='session-accept'
|
||||||
|
initiator='alice@example.org/foo'
|
||||||
|
sid='851ba2'>
|
||||||
|
<content creator='initiator' name='xmlstream'>
|
||||||
|
<description
|
||||||
|
xmlns='urn:xmpp:tmp:jingle:apps:xmlstream'
|
||||||
|
authentication='optional'
|
||||||
|
disclosure='never'
|
||||||
|
logging='mustnot'
|
||||||
|
tls='required'/>
|
||||||
|
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
|
||||||
|
</content>
|
||||||
|
</jingle>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The initiator acknowledges the Jingle session-accept.</p>
|
||||||
|
<example caption="Initiator acknowledges session-accept"><![CDATA[
|
||||||
|
<iq from='bob@example.com/bar'
|
||||||
|
id='accept1'
|
||||||
|
to='alice@example.org/foo'
|
||||||
|
type='result'/>
|
||||||
|
]]></example>
|
||||||
|
<p>Now the parties start an XML stream over the negotiated bytestream, following the recommendations in <cite>XEP-0174</cite>.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Implementation Notes' anchor='impl'>
|
||||||
|
<section2 topic='Mandatory to Implement Technologies' anchor='impl-mti'>
|
||||||
|
<p>All implementations MUST support the In-Band Bytestreams transport method as a reliable method of last resort. An implementation SHOULD support other transport methods as well.</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Preference Order of Transport Methods' anchor='impl-pref'>
|
||||||
|
<p>An application MAY present transport methods in any order, except that the In-Band Bytestreams method MUST be the lowest preference.</p>
|
||||||
|
</section2>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='Security Considerations' anchor='security'>
|
||||||
|
<p>In order to secure the e2e XML stream, implementations SHOULD use the standard STARTTLS method defined in <cite>XMPP Core</cite> but MAY instead use a TLS encrypted port that provides immediate encryption rather than upgrading of the stream via STARTTLS.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='IANA Considerations' anchor='iana'>
|
||||||
|
<p>No interaction with &IANA; is required as a result of this document.</p>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||||||
|
<section2 topic='Protocol Namespaces' anchor='ns'>
|
||||||
|
<p>Until this specification advances to a status of Draft, its associated namespaces shall be 'urn:xmpp:tmp:jingle:apps:xmlstream'. Upon advancement of this specification, the ®ISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;. The namespace 'urn:xmpp:jingle:apps:xmlstream' is requested and is thought to be unique per the XMPP Registrar's requirements.</p>
|
||||||
|
</section2>
|
||||||
|
<section2 topic='Jingle Application Formats' anchor='registrar-content'>
|
||||||
|
<p>The XMPP Registrar shall include "xmlstream" in its registry of Jingle application formats. The registry submission is as follows:</p>
|
||||||
|
<code><![CDATA[
|
||||||
|
<application>
|
||||||
|
<name>xmlstream</name>
|
||||||
|
<desc>Jingle sessions for an end-to-end XML stream</desc>
|
||||||
|
<transport>reliable</transport>
|
||||||
|
<doc>XEP-xxxx</doc>
|
||||||
|
</application>
|
||||||
|
]]></code>
|
||||||
|
</section2>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
<section1 topic='XML Schema' anchor='schema'>
|
||||||
|
<code><![CDATA[
|
||||||
|
<?xml version='1.0' encoding='UTF-8'?>
|
||||||
|
|
||||||
|
<xs:schema
|
||||||
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
||||||
|
targetNamespace='urn:xmpp:tmp:jingle:apps:xmlstream'
|
||||||
|
xmlns='urn:xmpp:tmp:jingle:apps:xmlstream'
|
||||||
|
elementFormDefault='qualified'>
|
||||||
|
|
||||||
|
<xs:element name='description'>
|
||||||
|
<xs:complexType>
|
||||||
|
<xs:simpleContent>
|
||||||
|
<xs:extension base='empty'>
|
||||||
|
<xs:attribute name='authentication' use='required'>
|
||||||
|
<xs:simpleType>
|
||||||
|
<xs:restriction base='xs:NCName'>
|
||||||
|
<xs:enumeration value='optional'/>
|
||||||
|
<xs:enumeration value='required'/>
|
||||||
|
</xs:restriction>
|
||||||
|
</xs:simpleType>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='disclosure' use='required'>
|
||||||
|
<xs:simpleType>
|
||||||
|
<xs:restriction base='xs:NCName'>
|
||||||
|
<xs:enumeration value='disabled'/>
|
||||||
|
<xs:enumeration value='enabled'/>
|
||||||
|
<xs:enumeration value='never'/>
|
||||||
|
</xs:restriction>
|
||||||
|
</xs:simpleType>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='logging' use='required'>
|
||||||
|
<xs:simpleType>
|
||||||
|
<xs:restriction base='xs:NCName'>
|
||||||
|
<xs:enumeration value='may'/>
|
||||||
|
<xs:enumeration value='mustnot'/>
|
||||||
|
</xs:restriction>
|
||||||
|
</xs:simpleType>
|
||||||
|
</xs:attribute>
|
||||||
|
<xs:attribute name='tls' use='required'>
|
||||||
|
<xs:simpleType>
|
||||||
|
<xs:restriction base='xs:NCName'>
|
||||||
|
<xs:enumeration value='optional'/>
|
||||||
|
<xs:enumeration value='required'/>
|
||||||
|
</xs:restriction>
|
||||||
|
</xs:simpleType>
|
||||||
|
</xs:attribute>
|
||||||
|
</xs:extension>
|
||||||
|
</xs:simpleContent>
|
||||||
|
</xs:complexType>
|
||||||
|
</xs:element>
|
||||||
|
|
||||||
|
</xs:schema>
|
||||||
|
]]></code>
|
||||||
|
</section1>
|
||||||
|
|
||||||
|
</xep>
|
||||||
Loading…
Reference in New Issue
Block a user