%ents; ]>
URL Address Information This document defines a structure for providing information about an Uniform Resource Locator (URL), and a protocol signaling retrieval states. &LEGALNOTICE; 0103 Deferred Standards Track Standards XMPP Core XEP-0095 RFC 3986 url-data &linuxwolf; 0.4.1 2018-11-03 pep Fix a bunch of typos, batch-style. 0.4 2004-01-20 lw Reorganized for Editorial preferences; revised error conditions; added better localization for <desc/> 0.4 2003-09-30 lw Revised &IQ; usage to be "SI" usage 0.3 2003-09-19 lw More fixes to &IQ; usage; Specified additional error code/condition for refused transfers 0.2 2003-07-06 lw Fixed &IQ; usage; Specified error codes/conditions 0.1 2003-06-30 lw Initial version.

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;).

The requirements this protocol fulfills are:

The simplest use of this protocol is to provide just a URL to another entity.

ANNOUNCEMENT: Next Session ]]>

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;:

ANNOUNCEMENT: Next Session jsessionid=1324123wdwfq341w1243asdf' ]]>

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.

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:

Complete list of Session Announcements jsessionid=1324123wdwfq341w1243asdf' Dept-7 d20M Campaign jsessionid=234asa4123wdwfq341w1243asdf' Forgotten Realms, 2nd Edition jsessionid=234asa4123wdwfq341w1242341f' Greyhawk in 3rd Edition ]]>

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.

The general process flow for using "url-data" with SI is as followsThe error conditions for SI are fully-documented in that document, and are therefore not included here.:

  1. The sender makes a SI request, adding "http://jabber.org/protocols/url-data" as one of the "stream-method" features.
  2. The receiver accepts the SI request, and selects "http://jabber.org/protocols/url-data".
  3. The sender provides an &IQ; with the <url-data/>.
  4. The receiver retrieves the data from the provided URL [E1, E2].
  5. Once retrieval is complete, the Receiver responds to Sender (EUC).
  • E1: The given URL is not supported/understood
  • E2: Failure to connect to the given URL

The sender starts with an SI request, using the semantics from XEP-0095:

]]>

The receiver then accepts the request, specifying "url-data" as the stream method:

http://jabber.org/protocol/url-data ]]>

The sender then sends an &IQ; with type "set" to the receiver, providing the <url-data/> element with the URL in the "target" attribute:

]]>

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":

]]>

Including the <url-data/> element in the result is NOT REQUIRED.

If the receiver does not understand or support the URL, it responds with an "iq-error" with the <malformed-url/> condition:

Malformed URL ]]>

If the receiver fails to retrieve data from the URL, it responds with an "iq-error" with the <transfer-failed/> condition:

transfer failed ]]>

If the receiver refuses to accept the URL, it responds with an "iq-error" with the <transfer-refused/> condition:

transfer failed ]]>

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.

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.

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.

The attribute "target" contains the URL. This attribute MUST be present, and MUST be a valid URL.

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.

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.

To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixesThis mapping is for the purpose of simplifying this discussion, and is not intended to be used in the actual protocol..

Prefix URI
xmpp urn:ietf:params:xml:ns:xmpp-stanzas
url http://jabber.org/protocol/url-data

Below are the errors that can result.

Error Type General Condition Specific Condition Description
modify <xmpp:bad-request/> <url:malformed-url/> The URL is not supported or understood.
cancel <xmpp:not-acceptable/> <url:transfer-refused/> The URL transfer failed for some unspecified reason.
cancel <xmpp:undefined-condition/> <url:transfer-failed/> The URL transfer failed for some unspecified reason.
]]>

This document does not yet have any security considerations.

This document requires no interaction with &IANA;.

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.