xeps/inbox/fsn.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>File Sharing Notifications</title>
  <abstract>This specification provides a notification protocol for information about ongoing file uploads and media creation by the user.</abstract>
  &LEGALNOTICE;
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  <author>
    <firstname>Linus</firstname>
    <surname>Jahn</surname>
    <email>lnj@kaidan.im</email>
    <jid>lnj@kaidan.im</jid>
  </author>
  <revision>
    <version>0.0.4</version>
    <date>2018-08-21</date>
    <initials>lnj</initials>
    <remark><p>Add upload-finished state, minor improvements.</p></remark>
  </revision>
  <revision>
    <version>0.0.3</version>
    <date>2018-07-20</date>
    <initials>lnj</initials>
    <remark><p>Added Requirements and Acknowledgements, simplified some definitions and added rules for CSI.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2018-07-19</date>
    <initials>lnj</initials>
    <remark><p>Seperated parts about the usage of chat states and moved the definitions of types to their examples.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2018-07-17</date>
    <initials>lnj</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>The specification of &xep0085; defines a protocol for exchanging information about the activity of the user, for example that the user is currently typing. However with the new possibilities of media sharing as in &xep0385; and &xep0363; there are also new desirable chat states. For example when a user uploads an image, the upload usually takes a while. To notify the chat partner about the uploading process a new chat state is required.</p>
  <p>When users send large files or have a very slow upstream connection it can make the chat partner confused when they are receiving an uploading state for a long time. In these cases it can be nice to share the upload progress. This way the chat partner can estimate if a file will arrive immediately or if it is better to go and get a coffee first.</p>
  <p>Apart from notifications for sending files, there should also be notifications when a user is creating new media files, for example when the user is recording audio, recording a video or is taking a picture.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <ul>
    <li>Convey state of ongoing file uploads.</li>
    <li>Distingush different media types, such as images, videos or audio messages.</li>
    <li>Share the progress of uploads.</li>
    <li>Notify about the recording of media, i.e. when a user is recording audio or taking a picture.</li>
    <li>Signal when an upload was cancelled.</li>
    <li>Be usable in groupchats.</li>
    <li>Define recommended rules for backwards-compatibility with &xep0085;.</li>
  </ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='User takes a picture via. the client and sends it afterwards'>
    <example caption="User begins to take a picture"><![CDATA[
<message
    from='bernardo@shakespeare.lit/pda'
    to='francisco@shakespeare.lit'
    type='chat'>
  <creating xmlns='urn:xmpp:fsn:0' type='image' />
</message>
]]></example>
    <p>Bernardo is informing Francisco about his activity of taking a picture to send it afterwards. If Francisco's client supports file sharing notifications, it should display this similarly to 'Bernardo is taking a photo…'.</p>
    <p>A list of possible 'type' attributes is defined below.</p>
    <table caption='Media types for &lt;creating/&gt; and &lt;uploading/&gt; states'>
      <tr>
        <th>Type</th>
        <th>Definition</th>
      </tr>
      <tr>
        <td>animation</td>
        <td>An animated image file, for example a GIF file. It SHOULD NOT be used in the &lt;creating/&gt; state.</td>
      </tr>
      <tr>
        <td>audio</td>
        <td>An audio file. This MAY also be displayed as a voice recording when used in the &lt;creating/&gt; state.</td>
      </tr>
      <tr>
        <td>image</td>
        <td>An image file.</td>
      </tr>
      <tr>
        <td>video</td>
        <td>A video file.</td>
      </tr>
    </table>
    <example caption="User is now sending the image"><![CDATA[
<message
    from='bernardo@shakespeare.lit/pda'
    to='francisco@shakespeare.lit'
    type='chat'>
  <uploading xmlns='urn:xmpp:fsn:0' type='image' progress='0.28' />
</message>
]]></example>
    <p>Bernardo has taken a good picture for sending and has started uploading, now. The same notification is also used when the image existed before and there were no process of creating it.</p>
    <p>The client SHOULD include a 'progress' attribute. It MUST be in the range of zero (0) and one (1). This value represents the bytes already sent divided by the total bytes. Generally it is not necessary to include more than two digits after the decimal point since the exact uploading status is not important. Clients MUST NOT send progress updates more often than once per second.</p>
    <p>The 'type' attribute equals the 'type' attribute by the &lt;creating/&gt; element.</p>
    <example caption="User has finished the file upload"><![CDATA[
<message
    from='bernardo@shakespeare.lit/pda'
    to='francisco@shakespeare.lit'
    type='chat'>
  <upload-finished xmlns='urn:xmpp:fsn:0'>
</message>
]]></example>
<p>The file upload has succeeded. Now Bernardo can send the file sharing message as in &xep0385; or another file sharing protocol. Francisco's client MUST clear the previous &lt;uploading&gt; notification. The &lt;upload-finished/&gt; notification itself SHOULD NOT be displayed to the user.</p>
    <example caption="User aborts the file upload"><![CDATA[
<message
    from='bernardo@shakespeare.lit/pda'
    to='francisco@shakespeare.lit'
    type='chat'>
  <upload-aborted xmlns='urn:xmpp:fsn:0' type='image' />
</message>
]]></example>
    <p>Of course the file upload also could have ended otherwise. In this case Bernardo has manually aborted the file upload. If the client encounters problems with the upload service after sending the first file sharing notification, the same format will also be used.</p>
  </section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <section2 topic='Chat State Notifications related rules' anchor='rules-chatstates'>
    <p>When a sending client chooses to map file sharing notifcations to &xep0085;, it MUST follow the following rules:</p>
    <ul>
      <li>As long as no upload or creation is in progress, the normal XEP-0085 states are sent.</li>
      <li>During creation, a client MUST send &lt;composing/&gt; state (overriding the state which would normally be sent with XEP-0085 logic).</li>
      <li>During upload and while the user is active, a client SHOULD continue to send the &lt;composing/&gt; state (overriding the state which would normally be sent with XEP-0085 logic).</li>
      <li>During upload and while the user is inactive, a client SHOULD send &lt;inactive/&gt; instead of &lt;composing/&gt;.</li>
      <li>After the upload finishes or is aborted, the normal XEP-0085 logic takes over. Normally, this will put the conversation into &lt;active/&gt; or &lt;inactive/&gt; state (but if the user still has input pending, it may also be &lt;paused/&gt;).</li>
    </ul>
    <p>A client MAY choose not to apply this mapping if it allows text input while creating or uploading media, to allow transmitting normal XEP-0085 states for the text input.</p>
    <p>If a client allows a user to pick media which are already created (thus skipping the &lt;creating/&gt; state), it MAY treat interaction with the media selection like text input in XEP-0085 (i.e. send &lt;composing/&gt; while the user is actively engaging with it and switch to &lt;paused/&gt; if inactive for a certain time).</p>
  </section2>
  <section2 topic='Concurrent Uploads' anchor='rules-concurrent'>
    <p>Media sharing protocols as &xep0385; don't forbid concurrent file uploads, so it may be the case that a client is uploading multiple files of different types to the same user or groupchat at the same time. This could result in different file types being affected at the same time.
      In this case clients SHOULD follow these rules:</p>
    <ul>
      <li>Multiple &lt;uploading/&gt; or &lt;creating/&gt; elements or a combination of these MUST NOT be sent.</li>
      <li>&lt;creating/&gt; notifications SHOULD be preferred to &lt;uploading/&gt; notifications.</li>
      <li>If there are multiple running file uploads, a notification for the approximately next finishing upload SHOULD be sent.</li>
    </ul>
  </section2>
  <section2 topic='Client State Indication related rules' anchor='rules-csi'>
    <p>Servers supporting &xep0352; SHOULD discard messages containing only a file sharing notification as long as a client is inactive.</p>
  </section2>
  <section2 topic='Usage in groupchats' anchor='rules-muc-mix'>
    <p>File sharing notifications MAY be used in groupchats as defined in &xep0045; or &xep0369; just as in normal chats.</p>
  </section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
  <p>It is possible that the connection to any client is lost at any time or a client crashes. Thus, a client SHOULD work with timeouts that will clear notifications after certain intervals.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>A client MUST have a possibility to disable file sharing notifications. This setting MAY be the same as the one for enabling &xep0085;.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with the Internet Assigned Numbers Authority (IANA).</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:fsn:0</li>
    </ul>
    <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <p>tbd</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Jonas Wielicki for his helpful feedback and input.</p>
</section1>
</xep>