<?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>Draft</status> <type>Standards Track</type> <sig>Standards</sig> <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.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 <sipub/> 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 <sipub/> element is as follows:</p> <example caption='Sample <sipub/>'><![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 <si/> 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 <sipub/> 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 <<link url='http://www.iana.org/assignments/media-types/'>http://www.iana.org/assignments/media-types/</link>>.</note> It provides the receiver with additional information about what the data stream will be.</p> <p>The <sipub/> element MUST contain an element qualified by the namespace specified by the 'profile' attribute (e.g., <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'/> for file transfer). This is the additional information about the data stream.</p> <p>The <sipub/> 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 <sipub/> 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 <sipub/> identifier(s). Also, the submitter MUST provide an <sipub/> 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 <start xmlns='http://jabber.org/protocol/sipub'/> 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 <starting/> 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 ¬acceptable; 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' achor='impl-notes'> <section2 topic='Publish ID versus SI ID'> <p>When publishing a stream via the <sipub/> element, the identifier SHOULD NOT be used as-is for the <si/> element, since a single publication will likely result in multiple <si/> 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 ®ISTRAR; 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>