mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-05 00:45:05 -05:00
342 lines
16 KiB
XML
342 lines
16 KiB
XML
<?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>URL Address Information</title>
|
|
<abstract>This document defines a structure for providing information about an Uniform Resource Locator (URL), and a protocol signaling retrieval states.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0103</number>
|
|
<status>Deferred</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XEP-0095</spec>
|
|
<spec>RFC 3986</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>url-data</shortname>
|
|
&linuxwolf;
|
|
<revision>
|
|
<version>0.4.1</version>
|
|
<date>2018-11-03</date>
|
|
<initials>pep</initials>
|
|
<remark>Fix a bunch of typos, batch-style.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2004-01-20</date>
|
|
<initials>lw</initials>
|
|
<remark>Reorganized for Editorial preferences; revised error conditions; added better localization for <desc/></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2003-09-30</date>
|
|
<initials>lw</initials>
|
|
<remark>Revised &IQ; usage to be "SI" usage</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2003-09-19</date>
|
|
<initials>lw</initials>
|
|
<remark>More fixes to &IQ; usage; Specified additional error code/condition for refused transfers</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2003-07-06</date>
|
|
<initials>lw</initials>
|
|
<remark>Fixed &IQ; usage; Specified error codes/conditions</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2003-06-30</date>
|
|
<initials>lw</initials>
|
|
<remark>Initial version.</remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction'>
|
|
<p>As Jabber becomes more widely utilized, applications of the protocol are veering away from traditional use as an IM product and are utilizing it for more generic data transportation and negotiation. While many advances are being made to facilitate non-IM data transportation, they do not address the use of already-established mechanisms of transporting data via URLs. This document provides a method that is compatible with these data transportation mechanisms and that is based on standard Internet Uniform Resource Locators (see &rfc3986;).</p>
|
|
</section1>
|
|
<section1 topic='Requirements'>
|
|
<p>The requirements this protocol fulfills are:</p>
|
|
<ul>
|
|
<li>Simple usage that can be easily extended</li>
|
|
<li>Provide any metadata necessary for using the URL</li>
|
|
<li>Compatibility with &xep0095;</li>
|
|
</ul>
|
|
</section1>
|
|
<section1 topic='Use Cases'>
|
|
<section2 topic='"Publishing" URLs'>
|
|
<p>The simplest use of this protocol is to provide just a URL to another entity.</p>
|
|
<example caption='Exchanging a simple HTTP URL'><![CDATA[
|
|
<message from='d20M@festhall.outer-planes.net'
|
|
to='linuxwolf@outer-planes.net'>
|
|
<body>ANNOUNCEMENT: Next Session</body>
|
|
<url-data
|
|
xmlns='http://jabber.org/protocol/url-data'
|
|
target='http://festhall.outer-planes.net/d20M/announce/latest/'/>
|
|
</message>
|
|
]]></example>
|
|
<p>If more information is necessary for successfully using the URL, the sender includes meta-information in a scheme-specific format such as that defined in &xep0104;:</p>
|
|
<example caption='Exchanging a HTTP URL with Headers'><![CDATA[
|
|
<message from='d20M@festhall.outer-planes.net'
|
|
to='linuxwolf@outer-planes.net'>
|
|
<body>ANNOUNCEMENT: Next Session</body>
|
|
<url-data
|
|
xmlns='http://jabber.org/protocol/url-data'
|
|
xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
|
|
target='http://festhall.outer-planes.net/d20M/announce/latest/'>
|
|
<http:header name='Cookie'>jsessionid=1324123wdwfq341w1243asdf'</http:header>
|
|
</url-data>
|
|
</message>
|
|
]]></example>
|
|
<p>The above example illustrates supplying a HTTP URL with a cookie header. Additional information could be provided, such as HTTP authentication requirements or even POST data.</p>
|
|
<p>To support the use of bulk publishing methods such as &xep0060; or messages of type "headline", the <desc/> element is used to provide a textual description:</p>
|
|
<example caption='&MESSAGE; Headines'><![CDATA[
|
|
<message
|
|
from='d20M@festhall.outer-planes.net'
|
|
to='linuxwolf@outer-planes.net'
|
|
type='headline'>
|
|
<body>Complete list of Session Announcements</body>
|
|
<url-data
|
|
xmlns='http://jabber.org/protocol/url-data'
|
|
xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
|
|
target='http://festhall.outer-planes.net/d20M/announce/latest/'>
|
|
<http:header name='Cookie'>jsessionid=1324123wdwfq341w1243asdf'</http:header>
|
|
<desc>Dept-7 d20M Campaign</desc>
|
|
</url-data>
|
|
<url-data
|
|
xmlns='http://jabber.org/protocol/url-data'
|
|
xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
|
|
target='http://festhall.outer-planes.net/add2/announce/latest/'>
|
|
<http:header name='Cookie'>jsessionid=234asa4123wdwfq341w1243asdf'</http:header>
|
|
<desc>Forgotten Realms, 2nd Edition</desc>
|
|
</url-data>
|
|
<url-data
|
|
xmlns='http://jabber.org/protocol/url-data'
|
|
xmlns:http='http://jabber.org/protocol/url-data/scheme/http'
|
|
target='http://festhall.outer-planes.net/dd3/announce/latest/'>
|
|
<http:header name='Cookie'>jsessionid=234asa4123wdwfq341w1242341f'</http:header>
|
|
<desc>Greyhawk in 3rd Edition</desc>
|
|
</url-data>
|
|
</message>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='SI Usage'>
|
|
<p>To use "url-data" in conjunction with SI, the "sid" attribute of <url-data/> is used. This attribute MUST be equal to the SI session id.</p>
|
|
<p>The general process flow for using "url-data" with SI is as follows<note>The error conditions for SI are fully-documented in that document, and are therefore not included here.</note>:</p>
|
|
<ol>
|
|
<li>The sender makes a SI request, adding "http://jabber.org/protocols/url-data" as one of the "stream-method" features.</li>
|
|
<li>The receiver accepts the SI request, and selects "http://jabber.org/protocols/url-data".</li>
|
|
<li>The sender provides an &IQ; with the <url-data/>.</li>
|
|
<li>The receiver retrieves the data from the provided URL [E1, E2].</li>
|
|
<li>Once retrieval is complete, the Receiver responds to Sender (EUC).</li>
|
|
</ol>
|
|
<ul>
|
|
<li><strong>E1:</strong> The given URL is not supported/understood</li>
|
|
<li><strong>E2:</strong> Failure to connect to the given URL</li>
|
|
</ul>
|
|
<p>The sender starts with an SI request, using the semantics from XEP-0095:</p>
|
|
<example caption='Requesting SI transfer'><![CDATA[
|
|
<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
|
|
<si xmlns='http://jabber.org/protocol/si'
|
|
id='a0'
|
|
mime-type='text/plain'
|
|
profile='http://jabber.org/protocol/si/profile/file-transfer'>
|
|
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
|
|
name='test.txt'
|
|
size='1022'/>
|
|
<feature xmlns='http://jabber.org/protocol/feature-neg'>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='stream-method' type='list-single'>
|
|
<option><value>http://jabber.org/protocol/url-data</value></option>
|
|
<option><value>http://jabber.org/protocol/bytestreams</value></option>
|
|
<option><value>http://jabber.org/protocol/ibb</value></option>
|
|
</field>
|
|
</x>
|
|
</feature>
|
|
</si>
|
|
</iq>
|
|
]]></example>
|
|
<p>The receiver then accepts the request, specifying "url-data" as the stream method:</p>
|
|
<example caption=''><![CDATA[
|
|
<iq type='result' to='sender@jabber.org/resource' id='offer1'>
|
|
<si xmlns='http://jabber.org/protocol/si'>
|
|
<feature xmlns='http://jabber.org/protocol/feature-neg'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='stream-method'>
|
|
<value>http://jabber.org/protocol/url-data</value>
|
|
</field>
|
|
</x>
|
|
</feature>
|
|
</si>
|
|
</iq>
|
|
]]></example>
|
|
<p>The sender then sends an &IQ; with type "set" to the receiver, providing the <url-data/> element with the URL in the "target" attribute:</p>
|
|
<example caption='Providing <url-data/>'><![CDATA[
|
|
<iq type='set' from='sender@jabber.org/resource' to='receiver@jabber.org/resource' id='offer2'>
|
|
<url-data xmlns='http://jabber.org/protocol/url-data'
|
|
sid='a0'
|
|
target='http://pass.jabber.org:8519/test.txt'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The receiver attempts to retrieve the data from the given URL. The receiver MUST NOT respond to the &IQ; until the data is completely retrieved, or an error occurs. If the retrieval is successful, the receiver responds with an "iq-result":</p>
|
|
<example caption='Receiver responds successfully'><![CDATA[
|
|
<iq type='result' from='receiver@jabber.org/resource' to='sender@jabber.org/resource' id='offer2'>
|
|
<url-data xmlns='http://jabber.org/protocol/url-data'
|
|
sid='a0'
|
|
target='http://pass.jabber.org:8519/test.txt'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Including the <url-data/> element in the result is NOT REQUIRED.</p>
|
|
<p>If the receiver does not understand or support the URL, it responds with an "iq-error" with the <malformed-url/> condition:</p>
|
|
<example caption='Receiver does not understand/support URL'><![CDATA[
|
|
<iq type='error' from='receiver@jabber.org/resource' to='sender@jabber.org/resource' id='offer2'>
|
|
<url-data xmlns='http://jabber.org/protocol/url-data'
|
|
sid='a0'
|
|
target='http://pass.jabber.org:8519/thefile.txt'/>
|
|
<error type='cancel' code='400'>Malformed URL
|
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<malformed-url xmlns='http://jabber.org/protocol/url-data'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the receiver fails to retrieve data from the URL, it responds with an "iq-error" with the <transfer-failed/> condition:</p>
|
|
<example caption='Receiver does not understand/support URL'><![CDATA[
|
|
<iq type='error' from='receiver@jabber.org/resource' to='sender@jabber.org/resource' id='offer2'>
|
|
<url-data xmlns='http://jabber.org/protocol/url-data'
|
|
sid='a0'
|
|
target='http://pass.jabber.org:8519/thefile.txt'/>
|
|
<error type='cancel' code='500'>transfer failed
|
|
<undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<transfer-failed xmlns='http://jabber.org/protocol/url-data'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the receiver refuses to accept the URL, it responds with an "iq-error" with the <transfer-refused/> condition:</p>
|
|
<example caption='Receiver does not understand/support URL'><![CDATA[
|
|
<iq type='error' from='receiver@jabber.org/resource' to='sender@jabber.org/resource' id='offer2'>
|
|
<url-data xmlns='http://jabber.org/protocol/url-data'
|
|
sid='a0'
|
|
target='http://pass.jabber.org:8519/thefile.txt'/>
|
|
<error type='cancel' code='500'>transfer failed
|
|
<undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
<transfer-refused xmlns='http://jabber.org/protocol/url-data'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Implementation Notes'>
|
|
<section2 topic='Schemes'>
|
|
<p>The additional information provided by a particular scheme is OPTIONAL. The additional data is provided as XML in a dedicated namespace, and this namespace SHOULD be declared (with an appropriate prefix) within the <url-data/> element.</p>
|
|
<p>Entities receiving a <url-data/> element MAY incorporate this information into the use of the URL as necessary. An entity providing a <url-data/> with scheme-specific information SHOULD NOT assume the receiving entity understands it, even if the receiving entity is capable of processing a URL for that scheme.</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Formal Description'>
|
|
<section2 topic='<url-data/> Root Element'>
|
|
<p>The <url-data/> element provides the root structure for providing URL addresses. The element has attribute for the target URL and (optional) stream identifier. It contains content for the optional description, and any and all scheme-specific content.</p>
|
|
<p>The attribute "target" contains the URL. This attribute MUST be present, and MUST be a valid URL.</p>
|
|
<p>The attribute "sid" contains the stream identifier. While this attribute is optional, its usage is REQUIRED when used with Stream Initiation, and MUST contain the Stream Initiation identifier previously agreed to.</p>
|
|
</section2>
|
|
<section2 topic='<desc/> Element'>
|
|
<p>In cases where textual descriptions cannot be provided, this element fullfills this need. It MAY include the "xml:lang" attribute for localization purposes, and its content is the text of the description. Multiple instances of <desc/> MAY be present, but each instance MUST have a different value for "xml:lang" attribute.</p>
|
|
</section2>
|
|
<section2 topic='Error Conditions'>
|
|
<p>To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes<note>This mapping is for the purpose of simplifying this discussion, and is not intended to be used in the actual protocol.</note>.</p>
|
|
<table caption='Namespace Mappings'>
|
|
<tr>
|
|
<th>Prefix</th>
|
|
<th>URI</th>
|
|
</tr>
|
|
<tr>
|
|
<td>xmpp</td>
|
|
<td>urn:ietf:params:xml:ns:xmpp-stanzas</td>
|
|
</tr>
|
|
<tr>
|
|
<td>url</td>
|
|
<td>http://jabber.org/protocol/url-data</td>
|
|
</tr>
|
|
</table>
|
|
<p>Below are the errors that can result.</p>
|
|
<table caption='Error Conditions/Codes'>
|
|
<tr>
|
|
<th>Error Type</th>
|
|
<th>General Condition</th>
|
|
<th>Specific Condition</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>modify</td>
|
|
<td><xmpp:bad-request/></td>
|
|
<td><url:malformed-url/></td>
|
|
<td>The URL is not supported or understood.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>cancel</td>
|
|
<td><xmpp:not-acceptable/></td>
|
|
<td><url:transfer-refused/></td>
|
|
<td>The URL transfer failed for some unspecified reason.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>cancel</td>
|
|
<td><xmpp:undefined-condition/></td>
|
|
<td><url:transfer-failed/></td>
|
|
<td>The URL transfer failed for some unspecified reason.</td>
|
|
</tr>
|
|
</table>
|
|
</section2>
|
|
<section2 topic='XML Schema'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/url-data'
|
|
xmlns='http://jabber.org/protocol/url-data'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:import namespace='http://www.w3.org/XML/1998/namespace'
|
|
schemaLocation='http://www.w3.org/2001/xml.xsd'/>
|
|
|
|
<xs:element name='url-data'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
|
|
<xs:element ref='desc' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='target' type='xs:anyURI' use='required'/>
|
|
<xs:attribute name='sid' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='desc' type='xs:string'>
|
|
<xs:complexType>
|
|
<xs:attribute ref='xml:lang' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='malformed-url'/>
|
|
<xs:element name='transfer-failed'/>
|
|
<xs:element name='transfer-refused'/>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Security Considerations'>
|
|
<p>This document does not yet have any security considerations.</p>
|
|
</section1>
|
|
<section1 topic='IANA Considerations'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations'>
|
|
<p>The ®ISTRAR; shall register the namespace "http://jabber.org/protocol/url-data" as a standard namespace. Also, the XMPP Registrar shall register the &xep0020; option "url-data" for use with Stream Initiation.</p>
|
|
</section1>
|
|
</xep>
|