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

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

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 &jep0060; or messages of type "headline", the <desc/> element is used to provide a textual description:

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 JEP, 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 JEP-0095:

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

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:

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

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

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

Below are the errors that can result.