moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-22 01:02:17 -05:00
Code Issues Releases Wiki Activity

Merge branch 'xep-0447' into premerge

Browse Source
This commit is contained in:
Jonas Schäfer 2022-08-23 21:32:52 +02:00
commit e5e90286a3
1 changed files with 25 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
xep-0447.xml
View File

@ -17,12 +17,18 @@
<dependencies> <dependencies>
<spec>XMPP Core</spec> <spec>XMPP Core</spec>
<spec>XEP-0001</spec> <spec>XEP-0001</spec>
<spec>XEP-xxxx</spec> <spec>XEP-0446</spec>
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
<shortname>sfs</shortname> <shortname>sfs</shortname>
&larma; &larma;
<revision>
<version>0.2.0</version>
<date>2022-08-03</date>
<initials>lmw</initials>
<remark>Add disposition attribute to signal when inlining is desired.</remark>
</revision>
<revision> <revision>
<version>0.1.2</version> <version>0.1.2</version>
<date>2022-02-10</date> <date>2022-02-10</date>
@ -77,12 +83,13 @@
<section2 topic='Sharing a file' anchor='file-sharing'> <section2 topic='Sharing a file' anchor='file-sharing'>
<p> <p>
To share a file, a user sends a message stanza including <tt>&lt;file-sharing/&gt;</tt> to the inteded recipient contact or group. To share a file, a user sends a message stanza including <tt>&lt;file-sharing/&gt;</tt> to the inteded recipient contact or group.
The <tt>&lt;file-sharing/&gt;</tt> element MAY have a <tt>disposition</tt> attribute with a value of either <tt>attachment</tt> or <tt>inline</tt>.
The <tt>&lt;file-sharing/&gt;</tt> element includes a <tt>&lt;file/&gt;</tt> metadata element as described in &xep0446; as well as a <tt>&lt;sources/&gt;</tt> element. The <tt>&lt;file-sharing/&gt;</tt> element includes a <tt>&lt;file/&gt;</tt> metadata element as described in &xep0446; as well as a <tt>&lt;sources/&gt;</tt> element.
The <tt>&lt;sources/&gt;</tt> element provides one or multiple sources that the receiving client may use to obtain the file. The <tt>&lt;sources/&gt;</tt> element provides one or multiple sources that the receiving client may use to obtain the file.
</p> </p>
<example caption='Sharing summit.jpg with juliet@shakespeare.lit'><![CDATA[ <example caption='Sharing summit.jpg with juliet@shakespeare.lit'><![CDATA[
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'> <message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0'> <file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<file xmlns='urn:xmpp:file:metadata:0'> <file xmlns='urn:xmpp:file:metadata:0'>
<media-type>image/jpeg</media-type> <media-type>image/jpeg</media-type>
<name>summit.jpg</name> <name>summit.jpg</name>
@ -113,7 +120,7 @@
</p> </p>
<example caption='Sharing summit.jpg with juliet@shakespeare.lit with fallback'><![CDATA[ <example caption='Sharing summit.jpg with juliet@shakespeare.lit with fallback'><![CDATA[
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'> <message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0'> <file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<!-- ... --> <!-- ... -->
</file-sharing> </file-sharing>
<body>Photo from the summit: https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</body> <body>Photo from the summit: https://download.montague.lit/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/summit.jpg</body>
@ -123,7 +130,7 @@
<p>If the message has an empty body, it is RECOMMENDED to add a message processing hint, see &xep0334;, to indicate the message to be stored in message stores like &xep0313;.</p> <p>If the message has an empty body, it is RECOMMENDED to add a message processing hint, see &xep0334;, to indicate the message to be stored in message stores like &xep0313;.</p>
<example caption='Sharing summit.jpg with juliet@shakespeare.lit without fallback'><![CDATA[ <example caption='Sharing summit.jpg with juliet@shakespeare.lit without fallback'><![CDATA[
<message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'> <message to='juliet@shakespeare.lit' from='romeo@montague.lit/resource' id='sharing-a-file'>
<file-sharing xmlns='urn:xmpp:sfs:0'> <file-sharing xmlns='urn:xmpp:sfs:0' disposition='inline'>
<!-- ... --> <!-- ... -->
</file-sharing> </file-sharing>
<store xmlns='urn:xmpp:hints' /> <store xmlns='urn:xmpp:hints' />
@ -139,6 +146,10 @@
If the file is not available locally, the file can be obtained by one of the sources listed in the <tt>&lt;sources/&gt;</tt> element. If the file is not available locally, the file can be obtained by one of the sources listed in the <tt>&lt;sources/&gt;</tt> element.
If further sources have been attached (as described in <link url="#attach-source">Attaching a source</link>), the receiving entity may also try to obtain the file from any of those. If further sources have been attached (as described in <link url="#attach-source">Attaching a source</link>), the receiving entity may also try to obtain the file from any of those.
</p> </p>
<p>
The receiving entity SHOULD NOT fetch the file without prior user interaction if the <tt>disposition</tt> attribute is set to <tt>attachment</tt>.
The receiving entity MAY fetch the file without prior user interaction otherwise, but when doing so, user's privacy, security (see <link url="#security">Security Considerations</link>) and network constraints should be considered.
</p>
<p> <p>
When the source is an <tt>&lt;url-data/&gt;</tt> element as described in &xep0103;, the receiving entity MAY obtain the file by downloading it from the specified URL. When the source is an <tt>&lt;url-data/&gt;</tt> element as described in &xep0103;, the receiving entity MAY obtain the file by downloading it from the specified URL.
If the URL uses HTTP or HTTPS and additional HTTP request information as specified in &xep0104; is provided, the receiving entity SHOULD use such information when obtaining the file. If the URL uses HTTP or HTTPS and additional HTTP request information as specified in &xep0104; is provided, the receiving entity SHOULD use such information when obtaining the file.
@ -154,9 +165,13 @@
The details of obtaining such file are out of scope of this document. The details of obtaining such file are out of scope of this document.
</p> </p>
<p> <p>
If the <tt>&lt;media-type/&gt;</tt> of the shared file is such that it can be displayed inline, the receiving entity MAY display the file inline. The intended method to provide or display a file to the user depends on the <tt>disposition</tt> attribute, <tt>&lt;media-type/&gt;</tt> and file type support of the receiving entity:
If no <tt>&lt;media-type/&gt;</tt> is provided or the <tt>&lt;media-type/&gt;</tt> indicates that the file can not be displayed inline, i.e. when the media type is <tt>application/octet-stream</tt>, the receiving entity SHOULD NOT display the file inline and instead offer to download it or save it on the users file system.
</p> </p>
<ul>
<li>If the <tt>disposition</tt> attribute is set to <tt>attachment</tt>, no <tt>&lt;media-type/&gt;</tt> is provided or the <tt>&lt;media-type/&gt;</tt> indicates that the file can not be displayed inline, i.e. when the media type is <tt>application/octet-stream</tt>, the receiving entity SHOULD NOT display the file inline and instead offer to download it or save it on the user's file system.</li>
<li>If the <tt>disposition</tt> attribute is set to <tt>inline</tt>, the receiving entity SHOULD attempt to display the file inline. When displaying the file inline fails, the receiving entity SHOULD indicate to the user that the file was meant to be displayed inline but that the file type was not supported for inline display and offer to open the file using an external viewer or to download the file or save it to the user's file system instead.</li>
<li>If no <tt>disposition</tt> attribute is set and the <tt>&lt;media-type/&gt;</tt> of the shared file indicates that it can be displayed inline, the receiving entity MAY display the file inline. When displaying the file inline fails, the receiving entity SHOULD NOT display any error and instead offer to open the file using an external viewer or to download the file or safe it to the user's file system.</li>
</ul>
</section2> </section2>
<section2 topic='Attaching a source' anchor='attach-source'> <section2 topic='Attaching a source' anchor='attach-source'>
<p class='box'>TODO: The following section relies on &xep0367;, however other methods to attach information to another message like the recently proposed &xep0422; might be suitable here as well. This is to be clarified before advancing to Draft.</p> <p class='box'>TODO: The following section relies on &xep0367;, however other methods to attach information to another message like the recently proposed &xep0422; might be suitable here as well. This is to be clarified before advancing to Draft.</p>
@ -183,6 +198,10 @@
]]></example> ]]></example>
</section2> </section2>
</section1> </section1>
<section1 topic='Accessibility Considerations' anchor='access'>
<p>Entities that support displaying moving images inline SHOULD have an option to turn this functionality off and display a still image instead.</p>
<p>Entities that support displaying files inline SHOULD have an option to turn this functionality off entirely.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<p> <p>
If a <tt>&lt;hash/&gt;</tt> using any supported algorithm is provided, the receiving client SHOULD verify that the <tt>&lt;hash/&gt;</tt> of the announced file matches the obained file before presenting it to the user. If a <tt>&lt;hash/&gt;</tt> using any supported algorithm is provided, the receiving client SHOULD verify that the <tt>&lt;hash/&gt;</tt> of the announced file matches the obained file before presenting it to the user.