xeps/xep-0137.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>Publishing Stream Initiation Requests</title>
  <abstract>This specification defines an XMPP protocol extension that enables an XMPP entity to advertise the fact that it is willing accept a particular Stream Initiation request. The protocol is used mainly to inform other entities that a particular file is available for transfer via the File Transfer protocol defined in XEP-0096.</abstract>
  &LEGALNOTICE;
  <number>0137</number>
  <status>Deprecated</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0030</spec>
    <spec>XEP-0095</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>sipub</shortname>
  <schemaloc>
    <url>http://www.xmpp.org/schemas/sipub.xsd</url>
  </schemaloc>
  &linuxwolf;
  &temas;
  <revision>
    <version>1.1</version>
    <date>2018-02-28</date>
    <initials>XEP Editor (ssw)</initials>
    <remark><p>Deprecated per a vote of the XMPP Council.</p></remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2005-08-26</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2005-07-21</date>
    <initials>psa</initials>
    <remark>Corrected several errors in the text and examples.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2004-11-03</date>
    <initials>psa</initials>
    <remark>Editorial review: clarified text throughout and corrected several errors in the examples.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2004-06-16</date>
    <initials>lw/tjm</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>&xep0095; defines a protocol to initiate a data stream between two Jabber/XMPP entities (e.g., for the purpose of &xep0096;). However, the sender is still responsible for informing potential receivers about the existence of a given stream. This document provides an automated way for a sender to announce the availability of a stream without initiating the data transfer. The purpose is to provide a "pull" protocol that enables a receiver to then request initiation of the stream from the sender.</p>
</section1>
<section1 topic='Requirements' anchor='requirements'>
  <p>This proposal addresses the following requirements:</p>
  <ul>
    <li>Allow a potential receiver (rather than the sender) to initiate a data stream.</li>
    <li>Integrate Stream Initiation (SI) with &xep0060;.</li>
    <li>Integrate Stream Initiation with &xep0004;.</li>
  </ul>
</section1>
<section1 topic='Use Cases' anchor='usecase'>
  <section2 topic='Publishing an SI Request' anchor='usecase.publish'>
    <p>A stream owner uses the &lt;sipub/&gt; element to announce that it can perform a specific SI request. This element can be sent to a publish-subscribe (XEP-0060) node, or sent directly to potential recipients within a &MESSAGE; stanza.</p>
    <p>The format of the &lt;sipub/&gt; element is as follows:</p>
    <example caption='Sample &lt;sipub/&gt;'><![CDATA[
  <sipub xmlns='http://jabber.org/protocol/sipub'
         from='sender-jid'
         id='publish-0123'
         profile='si-profile'
         mime-type='mime/type'>
    <profile xmlns='si-profile'></profile>
  </sipub>
]]></example>
    <p>This format is nearly identical to that for the stream initiation &lt;si/&gt; element (see <cite>XEP-0095</cite>). The major difference is the lack of the feature negotiation for the stream methods, and the addition of a 'from' attribute.</p>
    <p>The 'from' attribute SHOULD be present, and MUST be present if the stanza containing the &lt;sipub/&gt; is not from the stream owner (e.g., if the stream is advertised at a publish-subscribe node). If present, this attribute MUST be the valid JID for the stream owner.</p>
    <p>The 'id' attribute is an opaque identifier. This attribute MUST be present, and MUST be a valid non-empty string. It uniquely identifies the published request at the potential sender.</p>
    <p>As with stream initiation, the 'profile' attribute MUST be present, and MUST be the namespace URI governing the profile information. It identifies the format for the SI profile.</p>
    <p>As with stream initiation, the 'mime-type' attribute SHOULD be present, and MUST be an IANA-registered content type. <note>The IANA registry of content types is located at &lt;<link url='http://www.iana.org/assignments/media-types/'>http://www.iana.org/assignments/media-types/</link>&gt;.</note> It provides the receiver with additional information about what the data stream will be.</p>
    <p>The &lt;sipub/&gt; element MUST contain an element qualified by the namespace specified by the 'profile' attribute (e.g., &lt;file xmlns='http://jabber.org/protocol/si/profile/file-transfer'/&gt; for file transfer). This is the additional information about the data stream.</p>
    <p>The &lt;sipub/&gt; information is typically provided via pubsub:</p>
    <example caption='Sender advertises stream via publish-subscribe'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
    to='pubsub.shakespeare.lit'
    id='ps1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='characters'>
      <sipub xmlns='http://jabber.org/protocol/sipub'
          from='bard@shakespeare.lit'
          id='publish-0123'
          mime-type='application/pdf'
          profile='http://jabber.org/protocol/si/profile/file-transfer'>
        <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
              name='NDA.pdf'
              size='138819'
              date='2004-01-28T10:07Z'>
          <desc>All Shakespearean characters must sign and return this NDA ASAP</desc>
        </file>
      </sipub>
    </publish>
  </pubsub>
</iq>
]]></example>
    <example caption='Pubsub service pushes announcement to all subscribers'><![CDATA[
<message from='pubsub.shakespeare.lit' to='juliet@capulet.com/balcony'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='characters'>
      <item id='current'>
        <sipub xmlns='http://jabber.org/protocol/sipub'
            from='bard@shakespeare.lit'
            id='publish-0123'
            mime-type='application/pdf'
            profile='http://jabber.org/protocol/si/profile/file-transfer'>
          <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
                name='NDA.pdf'
                size='138819'
                date='2004-01-28T10:07Z'>
            <desc>All Shakespearean characters must sign and return this NDA ASAP</desc>
          </file>
        </sipub>
      </item>
    </items>
  </event>
</message>
]]></example>
    <p>The &lt;sipub/&gt; element MAY also be included directly within a &MESSAGE; stanza sent to another entity (or multiple entities, e.g., in &xep0045; or via &xep0033;). This can be especially useful for informing an offline entity about an available stream.</p>
    <example caption='Advertising a stream in a message stanza'><![CDATA[
<message from='romeo@montague.net/pda' to='juliet@capulet.com'>
  <sipub xmlns='http://jabber.org/protocol/sipub'
      id='publish-0123'
      mime-type='application/pdf'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='NDA.pdf'
          size='138819'
          date='2004-01-28T10:07Z'>
      <desc>All Shakespearean characters must sign and return this NDA ASAP</desc>
    </file>
  </sipub>
</message>
]]></example>
  </section2>
  <section2 topic='Integration with Data Forms' anchor='usecase.xdata'>
    <p>One of the goals of sipub is to integrate <cite>Stream Initiation</cite> with <cite>Data Forms</cite> to provide a "file upload" capability. This is accomplished via the datatypes specified in &xep0122;. Each datatype is specific to the profile desired.</p>
    <p>For example the datatype "sipub:file-transfer" is used to identify the file upload field(s) corresponding to <cite>XEP-0096</cite>:</p>
    <example caption='"Upload File" Data Forms Field'><![CDATA[
  <field var='file' type='text-single' label='File to Upload'>
    <validate xmlns='http://jabber.org/protocol/xdata-validate'
              datatype='sipub:file-transfer'/>
  </field>
]]></example>
    <p>When submitting such a form, a field's value(s) MUST be the &lt;sipub/&gt; identifier(s). Also, the submitter MUST provide an &lt;sipub/&gt; element within the data form for each file to be uploaded:</p>
    <example caption='Submitting an "Upload File" form'><![CDATA[
  <x xmlns='jabber:x:data' type='submit'>
    <field var='file'>
      <value>publish-0123</value>
    </field>
    <sipub xmlns='http://jabber.org/protocol/sipub'
           id='publish-0123'
           mime-type='text/html'
           profile='http://jabber.org/protocol/si/profile/file-transfer'>
      <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
            name='missive.html'
            size='1024'
            date='2005-07-21T11:21Z'/>
    </sipub>
  </x>
]]></example>
    <p>The form processor will use this to retrieve the file(s) to be uploaded.</p>
  </section2>
  <section2 topic='Triggering the Stream Initiation Request' anchor='usecase.trigger'>
    <p>A potential receiver starts the stream initiation session by sending an IQ-get to the sender, using the &lt;start xmlns='http://jabber.org/protocol/sipub'/&gt; element. This element contains the 'id' attribute to specify which published stream to retrieve:</p>
    <example caption='Receiver requests start of stream'><![CDATA[
  <iq type='get'
      id='sipub-request-0'
      from='juliet@capulet.com/balcony'
      to='romeo@montague.net/pda'>
    <start xmlns='http://jabber.org/protocol/sipub'
           id='publish-0123'/>
  </iq>
]]></example>
    <p>If the sender accepts the request, it responds with an IQ-result containing a &lt;starting/&gt; element. This element indicates the stream initiation identifier to be used:</p>
    <example caption='Sender accepts request to start stream'><![CDATA[
  <iq type='result'
      id='sipub-request-0'
      from='romeo@montague.net/pda'
      to='juliet@capulet.com/balcony'>
    <starting xmlns='http://jabber.org/protocol/sipub'
              sid='session-87651234'/>
  </iq>
]]></example>
    <p>Then the sender begins the stream initiation negotiation:</p>
    <example caption='Sender starts negotiation'><![CDATA[
  <iq type='set'
      id='sipub-set-1'
      from='romeo@montague.net/pda'
      to='juliet@capulet.com/balcony'>
    <si xmlns='http://jabber.org/protocol/si'
        id='session-87651234'
        mime-type='text/html'
        profile='http://jabber.org/protocol/si/profile/file-transfer'>
      <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='missive.html'
          size='1024'
          date='2005-07-21T11:21Z'>
        <desc>A love letter</desc>
      </file>
    </si>
  </iq>
]]></example>
    <p>If the requested identifier is not valid, the sender SHOULD respond with a &notacceptable; error:</p>
    <example caption='Sender denies because of invalid id'><![CDATA[
  <iq type='error'
      id='sipub-set-1'
      from='romeo@montague.net/pda'
      to='juliet@capulet.com/balcony'>
    <start xmlns='http://jabber.org/protocol/sipub'>publish-0123</start>
    <error code='405' type='modify'>
      <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    </error>
  </iq>
]]></example>
    <p>If the receiver does not have permission to request the data stream, the sender SHOULD respond with a &forbidden; error:</p>
    <example caption='Sender denies because receiver is forbidden'><![CDATA[
  <iq type='error'
      id='sipub-set-1'
      from='romeo@montague.net/pda'
      to='juliet@capulet.com/balcony'>
    <start xmlns='http://jabber.org/protocol/sipub'>publish-0123</start>
    <error code='403' type='auth'>
      <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    </error>
  </iq>
]]></example>
  </section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl-notes'>
  <section2 topic='Publish ID versus SI ID'>
    <p>When publishing a stream via the &lt;sipub/&gt; element, the identifier SHOULD NOT be used as-is for the &lt;si/&gt; element, since a single publication will likely result in multiple &lt;si/&gt; requests, possibly from the same receiver.</p>
  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>This document introduces no security concerns beyond those specified in <cite>XEP-0060</cite> and the relevant Stream Initiation profile in use.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar.namespaces'>
    <p>The &REGISTRAR; includes 'http://jabber.org/protocol/sipub' in its registry of protocol namespaces.</p>
  </section2>
  <section2 topic='Data Form Validation Datatypes' anchor='registrar.xdata-validate'>
    <p>The XMPP Registrar includes 'sipub:' in its registry of Data Forms Validation Datatype Prefixes.</p>
    <p>Normally, each SI profile that wishes to be considered for use with Data Forms MUST register its own datatype qualified by the "sipub:" prefix. However, this document provides an initial seed, based on the currently accepted SI profiles. The following datatypes shall be registered for use with Data Forms Validation:</p>
    <code caption='Data Forms Validation Datatypes Registry Submission'><![CDATA[
<datatype>
  <name>sipub:file-transfer</name>
  <desc>Datatype for publishing an SI using the File Transfer Profile</desc>
  <doc>XEP-0096</doc>
</datatype>
]]></code>
  </section2>
</section1>
<section1 topic='XML Schema' anchor='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/sipub'
    xmlns='http://jabber.org/protocol/sipub'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0137: http://www.xmpp.org/extensions/xep-0137.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='sipub'>
    <xs:annotation>
      <xs:documentation>This is the root content element for advertising a stream.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:any namespace='##other' minOccurs='1' maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='id' type='xs:string' use='required'/>
      <xs:attribute name='from' type='xs:string' use='optional'/>
      <xs:attribute name='mime-type' type='xs:string' use='optional'/>
      <xs:attribute name='profile' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='start'>
    <xs:annotation>
      <xs:documentation>This is the element for requesting retrieval of a stream.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:attribute name='id' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='starting'>
    <xs:annotation>
      <xs:documentation>This is the element for specifying the stream to be retrieved.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:attribute name='sid' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

</xs:schema>
]]></code>
</section1>
</xep>