<abstract>This document defines a structure for providing information about an Uniform Resource Locator (URL), and a protocol signaling retrieval states.</abstract>
<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>
<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>
<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>
<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>
<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>
<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>
<section1topic='Formal Description'>
<section2topic='<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>
<section2topic='<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>
<section2topic='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>
<tablecaption='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>
<tablecaption='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>
<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>
