2022-02-26 20:24:51 +00:00
# File Upload Notification
## Introduction
When sending files relevant to a current discussion, it sometimes happens that the conversation
moves on while waiting for the file to be uploaded, for example by using [HTTP-Upload ](https://xmpp.org/extensions/xep-0363.html ).
This causes the file to be sent at a later date.
File Upload Notifications are a way to allow supporting clients to place a pseudo-message
that will be replaced once the file has been uploaded.
## Pre-Upload
```xml
< message from = "some.user@some.server/abc123" to = "someone.else@other.server" id = "aaaaa" >
2022-03-02 16:06:36 +00:00
< file-upload xmlns = "proto:urn:xmpp:fun:0" >
< file xmlns = "urn:xmpp:file:metadata:0" >
< name > vacation.jpg< / name >
< media-type > image/jpeg< / media-type >
< / file >
< thumbnail type = "blurhash" xmlns = "proto:urn:xmpp:file-thumbnails:0" >
< blurhash > LEHV6nWB2yk8pyoJadR*.7kCMdnj< / blurhash >
< / thumbnail >
< thumbnail type = "base64-bob" xmlns = "proto:urn:xmpp:file-thumbnails:0" >
< base64-bob uri = "cid:sha1+...@bob.xmpp.org" media-type = "image/png" width = "128" height = "96" / >
< / thumbnail >
< / file-upload >
< origin-id xmlns = "urn:xmpp:sid:0" id = "ccccc" / >
< no-permanent-store xmlns = "urn:xmpp:hints" / >
2022-02-26 20:24:51 +00:00
< / message >
```
The `<file-upload>` element indicates that a message should be replaced with the actual
file embed once the upload is done. Metadata about the file should be included
as specified by [File metadata element ](https://xmpp.org/extensions/xep-0446.html ).
The metadata should include only the bare minimum, i.e. the mime type and filename.
2022-03-02 16:06:36 +00:00
Additionally, one or more thumbnails can be sent with the notification in order to allow clients
2022-02-27 17:57:30 +00:00
to already show a preview. The `<file-thumbnail />` element is specified by [File Thumbnails ](https://github.com/PapaTutuWawa/custom-xeps/blob/master/xep-xxxx-file-thumbnails.md ).
2022-02-26 20:24:51 +00:00
Note that [Unique and Stable Origin IDs ](https://xmpp.org/extensions/xep-0359.html ) must be used when the message is sent to a
groupchat.
Since this message carries no meaning to anyone retrieving it after the file upload has been
completed, a `<no-permanent-store />` element should be added (See [Message Processing Hints ](https://xmpp.org/extensions/xep-0334.html )).
## Post-Upload
After the file upload has been completed, the sending client includes a `<replaces />` element
in the message to inform clients which messages should be replaced.
```xml
< message from = "some.user@some.server/abc123" to = "someone.else@other.server" id = "bbbbb" >
< body > ...< / body >
< x xmlns = "jabber:x:oob" >
< url > ...< / url >
< / x >
2022-02-27 17:57:30 +00:00
< replaces xmlns = "proto:urn:xmpp:fun:0" id = "ccccc" / >
2022-02-26 20:24:51 +00:00
< origin-id xmlns = "urn:xmpp:sid:0" id = "ddddd" / >
< / message >
```
The `id` attribute of the `<replaces />` element refers to either the stanza ID or the
origin ID of the message that contained the original `<file-upload />` .
If sent to a groupchat, the origin ID must be used.
Note the the actual method of communicating a file is of no relevance here, as long as the
method allows a client to show it inline. Examples for such methods are
[Out of Band Data ](https://xmpp.org/extensions/xep-0066.html )
and [Stateless Inline Media Sharing ](https://xmpp.org/extensions/xep-0385.html ).
2022-02-27 17:57:30 +00:00
In case the sender uses methods like [Stateless Inline Media Sharing ](https://xmpp.org/extensions/xep-0385.html )
or [Stateless File Sharing ](https://xmpp.org/extensions/xep-0447.html ) which allow specifying
a thumbnail, then the client should do here as well to allow clients catching up using
[Message Archive Management ](https://xmpp.org/extensions/xep-0313.html ) to also provide a thumbnail to their users.
2022-02-26 20:24:51 +00:00
## Security Considerations
A client receiveing a message with an `<replaces />` element must verify if the message it
is supposed to replace was actually sent by the sender of the `<replaces />` element to
prevent arbitrary messages to be replaced.
2022-02-27 17:57:30 +00:00
## Info
| Key | Value |
| --- | --- |
| Author | PapaTutuWawa |
2022-03-02 16:06:36 +00:00
| Version | 0.0.3 |
2022-02-27 17:57:30 +00:00
| Short name | fun |
