moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 10:12:19 -05:00
Code Issues Releases Wiki Activity

ProtoXEP: File Sharing Notifications

Browse Source
This commit is contained in:
Jonas Wielicki 2018-07-18 16:44:19 +02:00
parent b1a5beb96b
commit 55eaeab245
1 changed files with 193 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
inbox/fsn.xml Normal file
View File

@ -0,0 +1,193 @@
<?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.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='Requirements' anchor='reqs'>
<ul>
<li>Try to keep compatibility with old clients, they should still receive states from &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'>
<composing xmlns='http://jabber.org/protocol/chatstates' />
<creating xmlns='urn:xmpp:fsn:0' type='photo' />
</message>
]]></example>
<p>Bernando 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 'Bernando is taking a photo...'. Bernando's client is adding the &lt;composing/&gt; state from &xep0085; for clients that don't support file sharing notifications. Those clients will just display this as a normal typing notification. However, adding chat states is RECOMMENDED, but OPTIONAL.</p>
<p>Other valid values for the 'type' attribute will be defined later.</p>
<example caption="User is now sending the image"><![CDATA[
<message
from='bernardo@shakespeare.lit/pda'
to='francisco@shakespeare.lit'
type='chat'>
<composing xmlns='http://jabber.org/protocol/chatstates' />
<uploading xmlns='urn:xmpp:fsn:0' type='image' progress='0.28' />
</message>
]]></example>
<p>Bernando 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>Again, the &lt;composing/&gt; state is OPTIONAL and hasn't to be send every time the progress is updated since both are independant from each other.</p>
<example caption="User is going inactive while the client is continuing the file upload"><![CDATA[
<message
from='bernardo@shakespeare.lit/pda'
to='francisco@shakespeare.lit'
type='chat'>
<inactive xmlns='http://jabber.org/protocol/chatstates' />
<uploading xmlns='urn:xmpp:fsn:0' type='image' progress='0.57' />
</message>
]]></example>
<p>Now Bernando has become inactive while his client still continues the upload. Francisco can see that Bernando isn't actively participating in the conversation anymore, but there's still a file upload running. Unfortunately clients without support for file sharing notifications won't see any activity at all.</p>
<p>Keep in mind that when the user becomes active again and the upload is still running, the chat state SHALL go to &lt;composing/&gt; again.</p>
<example caption="User has finished the file upload"><![CDATA[
<message
from='bernardo@shakespeare.lit/pda'
to='francisco@shakespeare.lit'
type='chat'>
...
<active xmlns='http://jabber.org/protocol/chatstates' />
</message>
]]></example>
<p>The file upload has succeeded and Bernando 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>
<p>The &lt;active&gt; state will only be required, if the user is actually active and there was sent a &lt;composing/&gt; state before.</p>
<example caption="User aborts the file upload"><![CDATA[
<message
from='bernardo@shakespeare.lit/pda'
to='francisco@shakespeare.lit'
type='chat'>
<paused xmlns='http://jabber.org/protocol/chatstates' />
<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 Bernando 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>
<p>Again as OPTIONAL possibility the &lt;paused/&gt; state from &xep0085; can be sent.</p>
</section2>
</section1>
<section1 topic='Definitions' anchor='defs'>
<table caption='File Sharing States'>
<tr>
<th>State</th>
<th>Definition</th>
</tr>
<tr>
<td>&lt;creating/&gt;</td>
<td>User is creating a new media file with the purpose of sharing it when finished, for example the user is recording a video or taking a picture. This state MUST have a 'type' as attribute.</td>
</tr>
<tr>
<td>&lt;uploading/&gt;</td>
<td>User is uploading an existing file. A media type and sending of the upload progress is OPTIONAL.</td>
</tr>
<tr>
<td>&lt;upload-aborted/&gt;</td>
<td>User has aborted the upload or the upload failed.</td>
</tr>
</table>
<table caption='Types of file creations'>
<tr>
<th>Type</th>
<th>Definition</th>
</tr>
<tr>
<td>voice</td>
<td>User is recording their voice.</td>
</tr>
<tr>
<td>video</td>
<td>User is recording a video.</td>
</tr>
<tr>
<td>photo</td>
<td>User is taking a picture.</td>
</tr>
</table>
<table caption='Types of file uploads'>
<tr>
<th>Type</th>
<th>Definition</th>
</tr>
<tr>
<td>image</td>
<td>An image file.</td>
</tr>
<tr>
<td>animation</td>
<td>An animated image file, for example a GIF file.</td>
</tr>
<tr>
<td>video</td>
<td>A video file.</td>
</tr>
<tr>
<td>audio</td>
<td>An audio file.</td>
</tr>
</table>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<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>