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.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 a sending state for a long time. In these cases it can be nice to give the chat partner information about 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, a video or is taking a picture.</p>
</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='photo' />
</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 as something similiar as 'Bernardo is taking a photo...'.</p>
    <p>A list of possible 'types' can be found below.</p>
    <table caption='Types of file creations'>
      <tr>
        <th>Type</th>
        <th>Definition</th>
      </tr>
      <tr>
        <td>photo</td>
        <td>User is taking a picture.</td>
      </tr>
      <tr>
        <td>video</td>
        <td>User is recording a video.</td>
      </tr>
      <tr>
        <td>voice</td>
        <td>User is recording their voice.</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 'progress' attribute has to be in the range of zero (0) and one (1). With other words the bytes sent divided by the total bytes. Generally the progress SHOULD NOT have more than two digits after the decimal point since the exact uploading status isn't important. Also there SHOULD be no more progress updates than once per second.</p>
    <p>A table of possible 'types' is listed below.</p>
    <table caption='Types of file uploads'>
      <tr>
        <th>Type</th>
        <th>Definition</th>
      </tr>
      <tr>
        <td>animation</td>
        <td>An animated image file, for example a GIF file.</td>
      </tr>
      <tr>
        <td>audio</td>
        <td>An audio file.</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 has finished the file upload"><![CDATA[
<message
    from='bernardo@shakespeare.lit/pda'
    to='francisco@shakespeare.lit'
    type='chat'>
  ...
</message>
]]></example>
    <p>The file upload has succeeded and Bernardo sends the link to the file as defined in &xep0385; or another possible way. A notification that the file upload has finished is not sent, instead the recipient's client MUST recoginze the incoming media share and reset the state for this 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'>
    <p>If the client also supports &xep0085;, then it SHOULD also send chat states for backwards-compatibility. In this case clients without support file sharing notifications, still receive a normal &lt;composing/&gt; state.</p>
    <p>When sending a &lt;composing/&gt; or &lt;uploading/&gt; notification, the client SHOULD send a &lt;composing/&gt; state, but only as long as the user is active. When the &lt;upload-aborted/&gt; notification is sent the &lt;paused/&gt; state MUST be used.</p>
    <p>Of course the &lt;composing/&gt; state has to be cleared on completion of a file upload and the &lt;active/&gt; state SHALL be sent.</p>
    <p>It is allowed to send a file sharing notification even if according to &xep0085; the user is &lt;inactive/&gt;, for example when the client is continuing a file upload, while the user is doing something else. But keep in mind that the chat state MUST go back to &lt;composing/&gt; when the user becomes active again and the upload is still running. Also, the user SHOULD NOT be seen as &lt;inactive/&gt; while selecting a file or using another application to take a photo, record voice or record a video.</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. However, a client MUST NOT send multiple &lt;uploading/&gt; or &lt;creating/&gt; elements and it MUST NOT send a combination of those elements. In this case the client SHOULD send the state of the upload with the lowest file size.</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>
</xep>