mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 16:55:07 -05:00
inbox/fsn.xml: Restructure & add new revision (0.0.2)
Remark: Seperated parts about the usage of chat states and moved the definitions of types to their examples.
This commit is contained in:
LNJ
parent
f795518658
commit
8543e50a96
142
inbox/fsn.xml
142
inbox/fsn.xml
@ -27,6 +27,12 @@
|
||||
<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>
|
||||
@ -39,11 +45,6 @@
|
||||
<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[
|
||||
@ -51,120 +52,89 @@
|
||||
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 <composing/> 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 <composing/> 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 <composing/> 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 <active> state will only be required, if the user is actually active and there was sent a <composing/> 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 <paused/> 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><creating/></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><uploading/></td>
|
||||
<td>User is uploading an existing file. A media type and sending of the upload progress is OPTIONAL.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><upload-aborted/></td>
|
||||
<td>User has aborted the upload or the upload failed.</td>
|
||||
</tr>
|
||||
</table>
|
||||
<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>voice</td>
|
||||
<td>User is recording their voice.</td>
|
||||
<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>photo</td>
|
||||
<td>User is taking a picture.</td>
|
||||
<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>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>
|
||||
<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 <composing/> state.</p>
|
||||
<p>When sending a <composing/> or <uploading/> notification, the client SHOULD send a <composing/> state, but only as long as the user is active. When the <upload-aborted/> notification is sent the <paused/> state MUST be used.</p>
|
||||
<p>Of course the <composing/> state has to be cleared on completion of a file upload and the <active/> state SHALL be sent.</p>
|
||||
<p>It is allowed to send a file sharing notification even if according to &xep0085; the user is <inactive/>, 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 <composing/> when the user becomes active again and the upload is still running. Also, the user SHOULD NOT be seen as <inactive/> 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 <uploading/> or <creating/> 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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user