forked from xsf/xeps
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathxep-0103.xml
342 lines (336 loc) · 15.8 KB
/
xep-0103.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
<?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>
<approver>Council</approver>
<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='[email protected]'
to='[email protected]'>
<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='[email protected]'
to='[email protected]'>
<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='[email protected]'
to='[email protected]'
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='[email protected]/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='[email protected]/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='[email protected]/resource' to='[email protected]/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='[email protected]/resource' to='[email protected]/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='[email protected]/resource' to='[email protected]/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='[email protected]/resource' to='[email protected]/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='[email protected]/resource' to='[email protected]/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>