Seperated parts about the usage of chat states and moved the definitions of types to their examples.
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.
-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.
+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...'.
+A list of possible 'types' can be found below.
+| Type | +Definition | +
|---|---|
| photo | +User is taking a picture. | +
| video | +User is recording a video. | +
| voice | +User is recording their voice. | +
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.
+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.
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.
+A table of possible 'types' is listed below.
+| Type | +Definition | +
|---|---|
| animation | +An animated image file, for example a GIF file. | +
| audio | +An audio file. | +
| image | +An image file. | +
| video | +A video file. | +
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.
+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.
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.
+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.
| State | -Definition | -
|---|---|
| <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. | -
| Type | -Definition | -
|---|---|
| voice | -User is recording their voice. | -
| video | -User is recording a video. | -
| photo | -User is taking a picture. | -
| Type | -Definition | -
|---|---|
| image | -An image file. | -
| animation | -An animated image file, for example a GIF file. | -
| video | -A video file. | -
| audio | -An audio file. | -
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.
+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.
+Of course the <composing/> state has to be cleared on completion of a file upload and the <active/> state SHALL be sent.
+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.
+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.