moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-08-13 16:53:48 -04:00
Code Issues Releases Wiki Activity

Merge pull request #223 from linkmauve/master

Browse Source 
XEP-0329: update to JingleFT:4 and various cosmetic fixes
This commit is contained in:
Florian Schmaus 2016-10-26 22:17:48 +02:00 committed by GitHub
commit b5f978cf1e
1 changed files with 67 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
xep-0329.xml
View File

@ -32,6 +32,12 @@
<jid>j.lagrange@gajim.org</jid>
</author>
&lance;
<revision>
<version>0.3</version>
<date>2016-08-07</date>
<initials>egp</initials>
<remark><p>Updated the &xep0234; referenced version to 0.16 or higher.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2013-11-19</date>
@ -71,104 +77,83 @@
<section1 topic='Getting Information About Files ' anchor='disco'>
<section2 topic='Traversing Files' anchor='traver'>
<p>If a requesting entity wishes to know what files are being shared by an offering entity, it can do so by sending the following query:</p>
<example caption='Requester queries the root of the shared folder'>
<![CDATA[
<example caption='Requester queries the root of the shared folder'><![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<query xmlns="urn:xmpp:fis:0" />
</iq>
]]>
</example>
<query xmlns="urn:xmpp:fis:0" />
</iq>]]></example>
<p> If the offering entity wishes to share files with the requesting entity, it may respond with a list of shared folders. It MUST not include any files in this response.</p>
<example caption='The offering entity responds with shared directories'>
<![CDATA[
<example caption='The offering entity responds with shared directories'><![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<query xmlns="urn:xmpp:fis:0">
<directory name='documents'/>
<directory name='pics'/>
<directory name='audio'/>
</query>
</iq>
]]>
</example>
<query xmlns="urn:xmpp:fis:0">
<directory name='documents'/>
<directory name='pics'/>
<directory name='audio'/>
</query>
</iq>]]></example>
<p>if the offering entity has no files to offer</p>
<example caption='The offering entity responds with no files'>
<![CDATA[
<example caption='The offering entity responds with no files'><![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<query xmlns="urn:xmpp:fis:0" />
</iq>
]]>
</example>
<query xmlns="urn:xmpp:fis:0" />
</iq>]]></example>
<p>Requesting the list of files and directories within a directory.</p>
<example caption='The requesting entity wants to know about a particular directory'>
<![CDATA[
<example caption='The requesting entity wants to know about a particular directory'><![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<query xmlns="urn:xmpp:fis:0" node="documents" />
</iq>
]]>
</example>
id='1235'>
<query xmlns="urn:xmpp:fis:0" node="documents" />
</iq>]]></example>
<p>When replying with a list of files, the offering entity can choose to either reply with verbose information on the file using the file attributes defined by &xep0234; or it may reply only with the 'name' attribute, which is required and MUST be included in every response.</p>
<p>It is RECOMENDED, when the list files to be sent is small, that a verbose response be made (in order to avoid going back and forth requesting information), and that a non-verbose reponse be made otherwise. This recomendation is made to save bandwidth.</p>
<example caption='The offering entity replies with information about a particular directory'>
<![CDATA[
<example caption='The offering entity replies with information about a particular directory'><![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<query xmlns="urn:xmpp:fis:0" node="documents">
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test.txt</name>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<range/>
<size>1022</size>
<hash xmlns='urn:xmpp:hashes:1' algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
</file>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test2.txt</name>
</file>
<directory name="secret docs" />
</query>
</iq>
]]>
</example>
id='1235'>
<query xmlns="urn:xmpp:fis:0" node="documents">
<file xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<name>test.txt</name>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<range/>
<size>1022</size>
<hash xmlns='urn:xmpp:hashes:1' algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
</file>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<name>test2.txt</name>
</file>
<directory name="secret docs" />
</query>
</iq>]]></example>
<p>If the requesting entity wants to get detailed information about a file. It can do so by providing its full path.</p>
<example caption='The requesting entity wants to know about a particular file'>
<![CDATA[
<example caption='The requesting entity wants to know about a particular file'><![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<query xmlns="urn:xmpp:fis:0" node="documents/test2.txt" />
</iq>
]]>
</example>
<example caption='The offering entity responds with more information'>
<![CDATA[
id='1236'>
<query xmlns="urn:xmpp:fis:0" node="documents/test2.txt" />
</iq>]]></example>
<example caption='The offering entity responds with more information'><![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<query xmlns="urn:xmpp:fis:0" node="test2.txt">
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test2.txt</name>
<size>1000</size>
</file>
</query>
</iq>
]]>
</example>
id='1236'>
<query xmlns="urn:xmpp:fis:0" node="test2.txt">
<file xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<name>test2.txt</name>
<size>1000</size>
</file>
</query>
</iq>]]></example>
</section2>
</section1>
<section1 topic='Bandwidth Considerations' anchor='bandwidth'>
@ -186,23 +171,25 @@
<section1 topic='Implementation Notes' anchor='implementation'>
<section2 topic='File identification' anchor='file_id'>
<p> As it was previously discussed, when requesting detailed information about a file, only the "name" attribute is required, but it is strongly RECOMMENDED that the hash attribute be included, in order to reduce the chances of sending the wrong file. When requesting the file to be transferred using &xep0234;, the information that must be provided has to identify the file uniquely. It is then RECOMMENDED that when requesting a file, the full path of the file in the shared folder be included in the "name" attribute.</p>
<example>
<![CDATA[
<example><![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1237'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='juliet@capulet.com/chamber'
sid='uj3b2'>
<content creator='initiator' name='a-file-request'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<request>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>pics/test4.png</name>
<size>10740</size>
</file>
</request>
<content creator='initiator' name='a-file-request' senders='responder'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:4'>
<file>
<name>pics/test4.png</name>
<size>10740</size>
</file>
</description>
]]>
</example>
</content>
</jingle>
</iq>]]></example>
</section2>
<section2 topic='File Sharing in MUCs' anchor='fis_muc'>
<p>For the most part, discovering files in a MUC is exactly the same as what has been described in this document. However, it is RECOMMENDED that a participant in a MUC should have a single shared folder associated with the entire room, as opposed to advertise different files to different participants of the room. This is to reduce the complexity of the client software. Also, due to volatile nature of the participants in a room, keeping track of permissions is more trouble than what it is worth.</p>