mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 08:45:04 -05:00
198 lines
10 KiB
XML
198 lines
10 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
<!ENTITY ns "urn:xmpp:udt:0">
|
|
<!ENTITY nsx "urn:example:">
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>User-defined Data Transfer</title>
|
|
<abstract>This specification proposes a simple mechanism by which applications can transfer data safely, without
|
|
needing additional protocol design work. It is intended to provide a protocol that is trivial to implement and can
|
|
be driven with a simple API.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>XXXX</number>
|
|
<status>ProtoXEP</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>udt</shortname>
|
|
&dcridland;
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2019-12-30</date>
|
|
<initials>dwd</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Initial Revision</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
</header>
|
|
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>Applications written on top of XMPP often need to exchange data that has no existing standard. Such applications are
|
|
often written by developers unfamiliar with best practise in designing new extensions for XMPP, making it hard to achieve
|
|
this simple design goal without causing longer term problems.</p>
|
|
<p>This leads to "solutions" such as stuffing JSON directly in the <body/> element, for example, and recognising
|
|
this at the receiver either by heuristics or by a special <subject/>. While this works, it's difficult to then
|
|
migrate to something else, and enforces that custom clients are always used.</p>
|
|
<p>Therefore this document proposes a very simple (and simplistic) framework for sending such data which - while
|
|
very light on features - nevertheless conforms to best practice. Unusually, this specification SHOULD NOT be used
|
|
as a base upon which to build other standards, and suggests an API for library developers to implement.</p>
|
|
<section2 topic="Terminology">
|
|
<p>Data transferred using this specification is encoded using JSON. The type of the data is given by a URI under
|
|
the same rules as an XML namespace, and this specification refers to this as the datatype.</p>
|
|
<p>Because this document defines mechanisms for sending essentially arbitrary data, no real-world examples are
|
|
given.</p>
|
|
<p>Instead, example namespaces are used within an XML namespace prefixed by <tt>&nsx;</tt></p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Overview' anchor="overview">
|
|
<section2 topic="Discovering Support" anchor="feature">
|
|
<p>Support for this protocol is advertised by the Service Discovery protocol defined in &xep0030; using a feature
|
|
of <tt>&ns;</tt>.</p>
|
|
<p>Support for a particular datatype is given by concatenating the <tt>&ns;</tt> feature with a hash character
|
|
('<tt>#</tt>') and the datatype, for example <tt>&ns;#&nsx;foo</tt>.</p>
|
|
</section2>
|
|
<section2 topic="Data Transfers">
|
|
<p>This specification provides for two types of user-defined data transfers. Each uses a similar payload syntax,
|
|
the UDT data payload.</p>
|
|
<p>Requests are carried within <iq/> stanzas, either of type "get" or "set", and result in a "result" optionally
|
|
containing a second UDT data payload.</p>
|
|
<p>UDT payloads may also be placed within a <message/> stanza. <message/> stanzas MAY contain multiple UDT
|
|
payloads, but typical usage is expected to be that there will be only one. The UDT payload may be ancillary data
|
|
to another message, or a standalone message in its own right.</p>
|
|
<section3 topic="Protocol Syntax">
|
|
<p>A UDT payload consists of a single element, <tt><payload/></tt>, qualified by the XML namespace
|
|
<tt>&ns;</tt>. It has a single, mandatory attribute of <tt>datatype</tt>, which MUST contain a string conformant
|
|
to the requirements for XML namespaces (typically a URI under the control of the application developer).</p>
|
|
<p>As with XML namespaces, this URI is never expected to be resolved, and is used solely as an indentifier.
|
|
Different strings are considered entirely different datatypes, and common prefixes etc MUST be considered
|
|
irrelevant for the purposes of interpreting the data. There are no common or standard datatypes.</p>
|
|
<p>The <tt><payload</tt> element contains exactly one mandatory child element, the <tt><json/></tt> element
|
|
defined in &xep0335;. This in turns contains the JSON data.</p>
|
|
<example><![CDATA[
|
|
<message from="gamer@game-company.example"
|
|
to="match-maker.game-company.example"
|
|
id="12345">
|
|
<payload xmlns="]]>&ns;<![CDATA[" datatype="]]>&nsx;foo<![CDATA[">
|
|
<json xmlns="urn:xmpp:json:0">
|
|
{
|
|
"annoying-teenager-level": 11
|
|
}
|
|
</json>
|
|
</payload>
|
|
</message>
|
|
]]></example>
|
|
<p>Note that the suggested custom &IQ; query payload of &xep0335; is not used as this would generally require
|
|
custom handlers within client libraries:</p>
|
|
<example><![CDATA[
|
|
<iq from="gamer@game-company.example"
|
|
to="match-maker.game-company.example"
|
|
id="12345"
|
|
type="set">
|
|
<payload xmlns="]]>&ns;<![CDATA[" datatype="]]>&nsx;foo<![CDATA[">
|
|
<json xmlns="urn:xmpp:json:0">
|
|
{
|
|
"annoying-teenager-percentage": 101
|
|
}
|
|
</json>
|
|
</payload>
|
|
</iq>
|
|
]]></example>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic="API Requirements">
|
|
<p>In order to satisfy the goals of this protocol, it is necessary to define an API that can be consistently
|
|
implemented across APIs. This allows application developers to use the protocol easily, and encourages this
|
|
over using the ad-hoc techniques described in the introduction.</p>
|
|
<p>Therefore, while not imposing hard and fast API definitions, this specification proposes naming conventions
|
|
for APIs that will hopefully guide application developers toward consistent usage.</p>
|
|
<p>While names are specified in "snake_case", API developers are free to use their own naming. This specification
|
|
also defines APIs as taking session arguments which will often be implied by method calls, and omits types.</p>
|
|
<p>Library developers SHOULD make these calls as simple to use as possible. If these are significantly harder to use
|
|
for inexperienced developers than ad-hoc techniques, then ad-hoc techniques will be used instead.</p>
|
|
<section2 topic="Arguments and Types">
|
|
<ul>
|
|
<li><tt>session</tt> - The session, connection or stream object or handle for the library. In cases where the
|
|
library uses a single global connection this is omitted. An OO library is likely to elide this and have the call
|
|
be a method call on the object instead.</li>
|
|
<li><tt>message</tt> - The message object or handle for the library. An OO library is likely to elide this and have the call
|
|
be a method call on the object instead.</li>
|
|
<li><tt>datatype</tt> - Typically a string containing an XML-style namespace.</li>
|
|
<li><tt>jid</tt> - A string or JID object. Any form of legal jid might be used here.</li>
|
|
<li><tt>data</tt> - Either a JSON-encoded string, or an object or data structure which can be converted by the
|
|
library.</li>
|
|
<li><tt>get_or_set</tt> - A flag for indicating whether this is a "get" or "set" request.</li>
|
|
<li><tt>callback</tt> - Some callable object or similar as meets the idiom of the language.</li>
|
|
</ul>
|
|
</section2>
|
|
<section2 topic="Advertising Support">
|
|
<p>Support is advertised on a session by calling <tt>udt_advertise(session, datatype)</tt>. Calling this MUST
|
|
explicitly advertise both the <tt>&ns;</tt> feature and that of the datatype support.</p>
|
|
<p>APIs are free to (and encouraged to) implicitly advertise support when other calls are made.</p>
|
|
</section2>
|
|
<section2 topic="Requests">
|
|
<p>Requests are sent to a particular jid by calling <tt>udt_request(session, jid, get_or_set, datatype, data)</tt>.
|
|
This might return a UDT payload, or have an additional <tt>callback</tt> argument to call with the response.</p>
|
|
<p>Applications may register to handle such requests by calling <tt>udt_request_callback(session, get_or_set,
|
|
datatype, callback)</tt>. The callback should be called as <tt>callback(session, jid, get_or_set, datatype,
|
|
data)</tt>, and returning a payload should send a <tt>result</tt> containing it. Applications registering this
|
|
way SHOULD implicitly advertise support for the datatype.</p>
|
|
</section2>
|
|
<section2 topic="Messages">
|
|
<p>Messages are sent to a particular jid by calling <tt>udt_message(session, jid, get_or_set, datatype, data)</tt>.</p>
|
|
<p>Applications may register to handle such requests by calling <tt>udt_message_callback(session, get_or_set,
|
|
datatype, callback)</tt>. The callback should be called as <tt>callback(session, jid, get_or_set, datatype,
|
|
data)</tt>. Applications registering this way SHOULD implicitly advertise support for the datatype.</p>
|
|
<p>Applications may check to see if any message stanza contains a UDT payload by calling <tt>udt_payload(message,
|
|
datatype)</tt>, which returns the payload if it exists.</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic="Schema">
|
|
<code>
|
|
<![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="]]>&ns;<![CDATA[" xmlns:xs="http://www.w3.org/2001/XMLSchema">
|
|
<xs:element name="payload" type="udt:payloadType" xmlns:udt="]]>&ns;<![CDATA["/>
|
|
<xs:complexType name="payloadType">
|
|
<xs:sequence>
|
|
<xs:any minOccurs="1" maxOccurs="1"/>
|
|
<!-- Always a XEP-0335 json element, but I can't figure that out. -->
|
|
</xs:sequence>
|
|
<xs:attribute type="xs:string" name="datatype"/>
|
|
</xs:complexType>
|
|
</xs:schema>
|
|
]]>
|
|
</code>
|
|
</section1>
|
|
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>All security implications herein are those of the payload.</p>
|
|
</section1>
|
|
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This XEP requires no interaction with &IANA;. </p>
|
|
</section1>
|
|
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<p>None.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>The authors wish to share any credit with many members of the community, including Florian Schmaus.</p>
|
|
</section1>
|
|
|
|
</xep>
|