From 55eaeab24502f51c2b25a995385c82ab8d7d1a72 Mon Sep 17 00:00:00 2001 From: Jonas Wielicki Date: Wed, 18 Jul 2018 16:44:19 +0200 Subject: [PATCH] ProtoXEP: File Sharing Notifications --- inbox/fsn.xml | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 inbox/fsn.xml diff --git a/inbox/fsn.xml b/inbox/fsn.xml new file mode 100644 index 00000000..7782fab8 --- /dev/null +++ b/inbox/fsn.xml @@ -0,0 +1,193 @@ + + +%ents; +]> + + +
+ File Sharing Notifications + This specification provides a notification protocol for information about ongoing file uploads and media creation by the user. + &LEGALNOTICE; + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + XMPP IM + + + + NOT_YET_ASSIGNED + + Linus + Jahn + lnj@kaidan.im + lnj@kaidan.im + + + 0.0.1 + 2018-07-17 + lnj +

First draft.

 + +
+ +

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.

+

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.

+

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.

+ + +
    +
  • Try to keep compatibility with old clients, they should still receive states from &xep0085;.
    • +
+ + + + + + + +]]> +

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.

+

Other valid values for the 'type' attribute will be defined later.

+ + + + +]]> +

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.

+

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.

+

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.

+ + + + +]]> +

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.

+

Keep in mind that when the user becomes active again and the upload is still running, the chat state SHALL go to <composing/> again.

+ + ... + + +]]> +

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.

+

The <active> state will only be required, if the user is actually active and there was sent a <composing/> state before.

+ + + + +]]> +

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.

+

Again as OPTIONAL possibility the <paused/> state from &xep0085; can be sent.

+ + + + + + + + + + + + + + + + + + + + +
StateDefinition
<creating/>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.
<uploading/>User is uploading an existing file. A media type and sending of the upload progress is OPTIONAL.
<upload-aborted/>User has aborted the upload or the upload failed.
+ + + + + + + + + + + + + + + + + +
TypeDefinition
voiceUser is recording their voice.
videoUser is recording a video.
photoUser is taking a picture.
+ + + + + + + + + + + + + + + + + + + + + +
TypeDefinition
imageAn image file.
animationAn animated image file, for example a GIF file.
videoA video file.
audioAn audio file.
+ + + +

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.

+ + + +

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.

+ + +

A client MUST have a possibility to disable file sharing notifications. This setting MAY be the same as the one for enabling &xep0085;.

+ + +

This document requires no interaction with the Internet Assigned Numbers Authority (IANA).

+ + + +

This specification defines the following XML namespace:

+
    +
  • urn:xmpp:fsn:0
    • +
+

Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.

+ + + +

tbd

+ +