moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

Merge branch 'master' of athena.jabber.org:xmpp

Browse Source
This commit is contained in:
Peter Saint-Andre 2013-04-17 19:16:45 -06:00
commit 575e8e0f88
13 changed files with 14821 additions and 3382 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

411
inbox/fis.xml
View File

@ -19,7 +19,6 @@
<spec>XEP-0234</spec>
<spec>XEP-0059</spec>
<spec>XEP-0265</spec>
<spec>XEP-0055</spec>
</dependencies>
<supersedes>
<spec>XEP-0135</spec>
@ -32,16 +31,22 @@
<jid>j.lagrange@jabber.org</jid>
<jid>j.lagrange@gajim.org</jid>
</author>
<author>
<firstname>Lance</firstname>
<surname>Stout</surname>
<email>lancestout@gmail.com</email>
</author>
<revision>
<version>0.0.2</version>
<date>2012-10-14</date>
<version>0.0.4</version>
<date>2013-01-26</date>
<initials>jl</initials>
<remark>Second draft</remark>
<remark>Third draft</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>XMPP extensions provide ways of transferring files between peers (such as &xep0234; and &xep0096;). However, file transfer is currently limited to needing that the transfer be initiated by the hosting entity. The &xep0234; extension, provides for a way to request files, but it requires the requesting entity to have information about the file being requested, so that it can be uniquely identified. </p>
<p>This document defines an extension which allows the request of information of files being offered by a hosting entity so they can later be requested in a file transfer; If the requesting entity is interested in the file.</p>
<p>&xep0135; is a previous extention that attempted to solve the same problem as this one, but unfortunetly it didn't generate much interest and it got deprecated. This extention aims be a modern replacement for XEP-0135.</p>
<p>IRC users have been able to bypass the limitations of the protocol by using bots that provide information of files and initiate transfer on command. A major downside of this method is that not every user is capable of sharing its files. The aim of this document is to provide a similar functionality while making it easier for users to offer and request information about files. </p>
<p>Microsoft's MSN proprietary IM client, used to provide similar functionality using "Sharing Folders", but this was replaced by Windows Live SkyDrive </p>
</section1>
@ -49,56 +54,37 @@
<ol>
<li>Enable a requesting entity to traverse the shared directory of an offering entity (REQUIRED)</li>
<li>Enable a requesting entity to get detailed information about files. (REQUIRED)</li>
<li>Enable a requesting entity to search files hosted by an offering entity.(OPTIONAL)</li>
<li>Allow the use of MUCs to share information about files among the users.(OPTIONAL)</li>
<!-- <li>Allow the use of Pub/Sub service to search files (OPTIONAL)</li> -->
</ol>
</section1>
<section1 topic='Assumptions' anchor='assump'>
<!-- Maybe make this into a list -->
<p> This protocol assumes the existence of a shared directory (either virtual or physical). The hosting entity must not advertise empty directories. The hosting entity is responsible of maintaining the structure of that directory (such as not allowing two files with the same name and preventing cycles within directories). The hosting entity is in no way required to present the same shared directory to different requesters.</p>
<p> This protocol assumes the existence of one or more shared directories (either virtual or physical). The hosting entity must not advertise empty directories. The hosting entity is responsible of maintaining the structure of those directories (such as not allowing two files with the same name and preventing cycles within directories). The hosting entity is in no way required to present the same shared directories to different requesters. In fact, the reason multiple share directories are allowed, is to make it easier for implementers to manage permissions of who can see what files.</p>
</section1>
<section1 topic='Getting Information About Files ' anchor='disco'>
<section2 topic='Traversing Files' anchor='traver'>
<p>If a requesting entity wishes to traverse the shared folder of an offering entity. It can do so by querying the root directory as it is shown in the following example:</p>
<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[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<request>
<directory/>
</request>
</match>
<query xmlns="urn:xmpp:fis" />
</iq>
]]>
</example>
<p> If the offering entity has files to share, it MUST respond with the root-level files of its shared folder. Files and directories at the root level MUST not be the child of any "directory" tag. In order to save bandwidth, the offering entity MAY omit all the children of the file tag except the "name" which is required and MUST always be present.
</p>
<p>The file tag has the same attributes as defined in &xep0096;. The "name" attribute is required and must be included in every response. The "size" attribute is only required when responding with detailed information about a file.</p>
<example caption='The offering entity responds with files'>
<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[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<offer>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<name>test.txt</name>
<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='pics'/>
</offer>
</match>
<query xmlns="urn:xmpp:fis">
<directory name='documents'/>
<directory name='pics'/>
<directory name='audio'/>
</query>
</iq>
]]>
</example>
@ -109,14 +95,46 @@
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<offer>
<directory/>
</offer>
</match>
<query xmlns="urn:xmpp:fis" />
</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[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<query xmlns="urn:xmpp:fis" 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 &xep0254; 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[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<query xmlns="urn:xmpp:fis" 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>
<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[
@ -124,321 +142,37 @@
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<request>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test2.txt</name>
</file>
</request>
</match>
<query xmlns="urn:xmpp:fis" node="documents/test2.txt" />
</iq>
]]>
</example>
<p> When replying with detailed information about a file, the offering entity must always include the "name" and "size".</p>
<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'>
<match xmlns='urn:xmpp:mam'>
<offer>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test2.txt</name>
<size>1000</size>
</file>
</offer>
</match>
</iq>
]]>
</example>
<example caption='The requesting entity wants know about what files are in a directory'>
<![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<request>
<directory name='pics'/>
</request>
</match>
</iq>
]]>
</example>
<example caption='The offering entity responds with directory structure'>
<![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<offer>
<directory name='pics'>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test3.png</name>
</file>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test4.png</name>
</file>
<directory name="landscapes" />
</directory>
</offer>
</match>
<query xmlns="urn:xmpp:fis" node="test2.txt">
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test2.txt</name>
<size>1000</size>
</file>
</query>
</iq>
]]>
</example>
</section2>
<section2 topic='Searching Files'>
<p>Sometimes the list of files is too big to be efficiently traversed or there are too many peers offering files. This extensions allows simple file search to ease the discovery of files.</p>
<p>The requesting entity can request the fields on which a search can be performed. </p>
<example caption='Requesting search fields'>
<![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search' />
</match>
</iq>
]]>
</example>
<p>The offering entity replies with its search fields. The fields in the following example are required, and they MUST be supported.</p>
<example caption='Receiving search fields'>
<![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<name/>
<size/>
<date/>
<desc/>
<hash xmlns='urn:xmpp:hashes:1'/>
</query>
</match>
</iq>
]]>
</example>
<p>Different files have different metadata and all of them may not be completly covered by the fields mentioned before. Of course, any field that doesn't fit could be included in "desc", however this can make search difficult as it is not clearly defined what to look for.</p>
<p>Fields can be extended using dataforms, as it is defined in &xep0055;</p>
<example caption='Receiving extended search fields'>
<![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<name/>
<size/>
<date/>
<desc/>
<hash xmlns='urn:xmpp:hashes:1'/>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden'
var='FORM_TYPE'>
<value>jabber:iq:search</value>
<field type='list-single'
label='File type'
var='type'>
<option label='Audio'><value>audio</value></option>
<option label='Video'><value>video</value></option>
<option label='Text'><value>text</value></option>
<option label='Image'><value>image</value></option>
</field>
</x>
</query>
</match>
</iq>
]]>
</example>
<example caption='Requester uses extended search field'>
<![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:search</value>
</field>
<field var='x-gender'>
<value>image</value>
</field>
</x>
</query>
</match>
</iq>
]]>
</example>
<example caption='Offering entity responds with files'>
<![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:search</value>
</field>
<item>
<name>pics/test3.png</name>
</item>
<item>
<name>pics/test4.png</name>
</item>
</x>
</query>
</match>
</iq>
]]>
</example>
<p>If a requesting entity wishes to search for a particular keyword in the files name, it only needs to send the keyword within the 'name' tag and it MUST not be a full path.</p>
<p>The requester may also use the 'desc' to match keywords.</p>
<example caption='The requesting entity tries to search for a file'>
<![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<name>test</name>
</query>
</match>
</iq>
]]>
</example>
<example caption='The offering entity responds with search result'>
<![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<item>
<name>test.txt</name>
</item>
<item>
<name>test2.txt</name>
</item>
<item>
<name>pics/test3.png</name>
</item>
<item>
<name>pics/test4.png</name>
</item>
</query>
</match>
</iq>
]]>
</example>
<p>When simple keyword matching is not enough to efficiently search files, regular expressions (as defined in &xep0004;) can be used</p>
<example caption='Requester uses regular expressions to search files'>
<![CDATA[
<iq type='get'
from='juliet@capulet.com/chamber'
to='romeo@montague.net/home'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:search</value>
</field>
<field var='name'>
<validate xmlns='http://jabber.org/protocol/xdata-validate'
datatype='xs:string'>
<regex>*.png</regex>
</validate>
</field>
</x>
</query>
</match>
</iq>
]]>
</example>
<example caption='The offering entity responds with search result'>
<![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<query xmlns='jabber:iq:search'>
<item>
<name>pics/test3.png</name>
</item>
<item>
<name>pics/test4.png</name>
</item>
</query>
</match>
</iq>
]]>
</example>
</section2>
</section1>
<section1 topic='Discovering Files In a MUC' anchor='muc'>
<p>For the most part, discovering files in a MUC is exactly the same as what has been described in this document. However there are some considerations to have present.</p>
<p>First, 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>
<p>Second, a participant may discover files of all the participants in the room by sending the request to the room itself. It is RECOMMENDED that the search capabilities of this protocol be used for this.</p>
</section1>
<section1 topic='Bandwidth Considerations' anchor='bandwidth'>
<p> If a considerable amount of files are being shared by the offering entity, it may be the case that the offering entity response might be too be for the server to handle; As there might be a limitation on the size of the stanzas in the current stream. In order to solve this, extensions have been devised and their implementation are hereby recommended along with the implementation of this extension.</p>
<section2 topic='Using Result Set Management' anchor='resultset'>
<p>&xep0059; defines a way of limiting the results of a request. There are some considerations to use &xep0059; along with this extension.</p>
<p>First, in &xep0059; it is defined that the requesting entity is the one that sets the limit of the number of items that can be replied. So it is up to the requesting entity to choose a sensible number.</p>
<p>Second, since this protocol defines a way of handling the directory tree structure by allowing files tags to be children of a directory tags, it becomes difficult to define items for &xep0059;. Therefore, when responding to a request using &xep0059;, the offering entity MUST NOT send directory tags with files as their children, file tags must be sent separately with their path (starting at the root shared folder) in their name attribute.</p>
<example caption='Offering entity responds using result set'>
<![CDATA[
<iq type='result'
from='romeo@montague.net/home'
to='juliet@capulet.com/chamber'
id='1234'>
<match xmlns='urn:xmpp:mam'>
<offer>
<item>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test.txt</name>
</file>
</item>
<item>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>test2.txt</name>
</file>
</item>
<item>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>pics/test3.png</name>
</file>
</item>
<item>
<file xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
<name>pics/test4.png</name>
</file>
</item>
<item>
<directory name='pics'>
</item>
</offer>
</match>
</iq>
]]>
</example>
<p>&xep0059; defines a way of limiting the results of a request. There are some considerations to use result sets along with this extension.</p>
<p>First, it is defined that the requesting entity is the one that sets the limit of the number of items that can be replied. So it is up to the requesting entity to choose a sensible number.</p>
<p>Second, since this protocol defines a way of handling the directory tree structure by allowing file tags to be children of a directory tags, it becomes difficult to define items for Result Set Management. Therefore, when responding to a request, the offering entity MUST NOT send directory tags with files as their children. </p>
</section2>
<section2 topic='Out of Band Transfer' anchor='out-of-band'>
<p>One obvious way to overcome the limitations of sending large stanzas in-band, is to transfer that information out of band. &xep0065; could be used for that purpose. It is hereby RECOMMENDED its implementation when the offering entity has a massive amount of files that would not be practical to advertise in-band.</p>
<p>It is further recommended that when using XEP-0065, the entire directory structure, along with all the files in the shared folder and subfolders, be exchanged in one single reply. Also, all the files attributes should be included. This is to avoid wasting bandwidth initiating out of band streams going back and forth. </p>
<p>One obvious way to overcome the limitations of sending large stanzas in-band, is to transfer that information out of band. &xep0265; could be used for that purpose. It is hereby RECOMMENDED its implementation when the offering entity has a massive amount of files that would not be practical to advertise in-band.</p>
<p>It is further recommended that when using XEP-0265, the entire directory structure, along with all the files in the shared folder and subfolders, be exchanged in one single reply. Also, all the files attributes should be included. This is to avoid wasting bandwidth initiating out of band streams going back and forth. </p>
<!--
<p>One obvious way to overcome the limitations of sending large stanzas in-band, is to transfer that information out of band. Several extensions have tackled that problem, for example &xep0265; and &xep0105; could be used for this purpose. Unfortunately, both of those extensions are deprecated and thus it is not advised their implementation.</p>
<p>A workaround which would provide the same functionality as those xeps, is to advertise the existence of a tree.xml file in the root of the shared folder. This file would contain the whole directory structure of the shared folder. Its format is exactly the same as the stanzas defined herein, with the exception that it MUST NOT include the "iq" portion of the stanza.</p>
@ -484,9 +218,9 @@
-->
</section2>
</section1>
<section1 topic='Implementation Notes' achor='implementation'>
<section2>
<p> As it was previously discussed, when requesting detailed information about a file, only the "name" and "size" attributes 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>
<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[
<jingle xmlns='urn:xmpp:jingle:1'
@ -505,6 +239,9 @@
]]>
</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>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>A denial of service is possible by repeatedly requesting files. Implementers are advised to take this into consideration and include queues and limits into their implementations.</p>

4306
inbox/rayo.xml Normal file
View File

File diff suppressed because it is too large Load Diff

1257
inbox/sensor-data.xml
View File

File diff suppressed because it is too large Load Diff

5006
inbox/sensor-network-concentrators.xml Normal file
View File

File diff suppressed because one or more lines are too long

1721
inbox/sensor-network-control.xml Normal file
View File

File diff suppressed because it is too large Load Diff

1383
inbox/sensor-network-provisioning.xml
View File

File diff suppressed because it is too large Load Diff

3
xep-0220.xml
View File

@ -10,7 +10,8 @@
<abstract>This specification defines the Server Dialback protocol, which is used between XMPP servers to provide identity verification. Server Dialback uses the Domain Name System (DNS) as the basis for verifying identity; the basic approach is that when a receiving server accepts a server-to-server connection from an initiating server, it does not process traffic over the connection until it has verified the initiating server's key with an authoritative server for the domain asserted by the initiating server. Additionally, the protocol is used to negotitate whether the receiving server is accepting stanzas for the target domain. Although Server Dialback does not provide strong authentication and it is subject to DNS poisoning attacks, it has effectively prevented address spoofing on the XMPP network since its development in the year 2000.</abstract>
&LEGALNOTICE;
<number>0220</number>
<status>Experimental</status>
<status>Proposed</status>
<lastcall>2013-05-10</lastcall>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>

10
inbox/dtls-fingerprint.xml → xep-0320.xml
View File

@ -9,8 +9,8 @@
<title>Use of DTLS-SRTP in Jingle Sessions</title>
<abstract>This specification defines how to use DTLS-SRTP (RFC 5763) in the Jingle application type for the Real-time Transport Protocol (RTP) as a way to negotiate media path key agreement for secure RTP in one-to-one media sessions.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<number>0320</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
@ -31,6 +31,12 @@
-->
<discuss>jingle</discuss>
&fippo;
<revision>
<version>0.1</version>
<date>2013-04-16</date>
<initials>psa</initials>
<remark><p>Initial published version approved by the XMPP Council.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2013-02-18</date>

590
inbox/roster-management.xml → xep-0321.xml
View File

@ -1,295 +1,295 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Remote Roster Management</title>
<abstract>This document defines a way remote entities may manage user's roster to provide a simple way to keep rosters in sync.</abstract>
<legal>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2012 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &apos;Specification&apos;), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an &apos;AS IS&apos; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
</legal>
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0004</spec>
<spec>XEP-0100</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Sergey</firstname>
<surname>Dobrov</surname>
<email>binary@jrudevels.org</email>
<jid>binary@jrudevels.org</jid>
</author>
<author>
<firstname>Jan</firstname>
<surname>Kalu&#382;a</surname>
<email>hanzz.k@gmail.com</email>
<jid>hanzz@njs.netlab.cz</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2012-12-07</date>
<initials>snd</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>It's often desirable for some XMPP based services to make it possible to manage user's roster to provide some contacts there. The most obvious example of such kind of service is a gateway to some legacy IM system (see &xep0100;). The current way that's recommended by the &xep0100; is to use the &xep0144; to synchronize items that's not sutiable in certain situations.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This document addresses the following requirements:</p>
<ol>
<li>Make it possible for remote services or entities to manage user's roster by the same mechanisms that descibed in the &rfc6121;.</li>
<li>Provide a way for user to control which services have permission to manage his roster.</li>
</ol>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<ul>
<li><strong>Remote entity</strong> — the entity that wants to modify user's roster.</li>
<li><strong>User</strong> — the entity which roster the remote entity wants to have access to.</li>
<li><strong>User's server</strong> — the XMPP server User connected to.</li>
<li><strong>Roster</strong> — the list of User's contacts as defined in the &rfc6121;.</li>
</ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Remote entity asks for permission to manage user&apos;s roster' anchor='ask_permission'>
<p>In order to be able to make any changes to the user&apos;s roster the remote entity MUST ask permission to do so first.</p>
<p>NOTE: in order to be able to perform the query, the remote entity MUST have a presence subscription to the User</p>
<example caption='Remote entity asks for permission'><![CDATA[
<iq from='icq.example.com' to='juliet@example.com' type='set' id='roster_1'>
<query xmlns='urn:xmpp:tmp:roster-management:0' reason='Manage contacts in the ICQ contact list' type='request'/>
</iq>]]></example>
<p>If the presence subscription is absent, the server MUST NOT proceed with the request but MUST respond with the "forbidden" error:</p>
<example caption="The remote entity has no presence subscription"><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='error' id='roster_1'>
<error type='modify'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>You must have a presence subscription to be able to request remote roster management service.</text>
</error>
</iq>]]></example>
<p>The user's server SHOULD then generate a form request using &xep0004; to client in order to ask user if he's OK with granting the permission to the remote entity. The "challenge" form field is generated by the server and is used to identify the client's response. The server also MUST immediatly answer to the request IQ.</p>
<p>NOTE: if the entity is already granted with the permission, the server SHOULD immediatly answer with a success response and skip querying the user.</p>
<example caption='Server asks user for the permission'><![CDATA[
<message from='example.com'
to='juliet@example.com'>
<body>icq.example.com wants to be able to manage your roster with following reason:
Manage contacts in the ICQ contact list
Do you want to allow it? Send "yes 5439123" or "no 5439123" back, pleas.</body>
<x xmlns='jabber:x:data' type='form'>
<title>Roster management permission request</title>
<instructions>icq.example.com wants to be able to manage your roster with following reason:
Manage contacts in the ICQ contact list.
Do you allow it?</instructions>
<field type='hidden' var='challenge'><value>5439123</value></field>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:tmp:roster-management:0</value>
</field>
<field type='boolean'
label='Allow icq.example.com to edit roster?'
var='answer'>
<value>1</value>
</field>
</x>
</message>]]></example>
<p>The client can answer by submit the form or with a text message response:</p>
<example caption='Client responds with to the data form'><![CDATA[
<message from='juliet@example.com/home'
to='example.com'
xml:lang='en'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE'>
<value>urn:xmpp:tmp:roster-management:0</value>
</field>
<field var='challenge'><value>5439123</value></field>
<field var='answer'><value>1</value></field>
</x>
</message>]]></example>
<example caption='Client responds with a text message response'><![CDATA[
<message from='juliet@example.com/home'
to='example.com'
xml:lang='en'>
<body>yes 5439123</body>
</message>]]></example>
<section3 topic='The remote entity is allowed to manage roster' anchor='pemission_granted'>
<p>If the user allowed the roster management then the server MUST inform the remote entity that it has been granted the permission:</p>
<example caption='The server informs the remote entity that it&apos;s allowed to manage the User&apos;s roster'><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_2'>
<query xmlns='urn:xmpp:tmp:roster-management:0' type="allowed"/>
</iq>]]></example>
</section3>
<section3 topic='The remote entity is allowed to manage roster' anchor='pemission_granted'>
<p>If the user disallowed the roster management then the server MUST inform the remote entity that it hasn&apos;t been granted the permission:</p>
<example caption='The server informs the remote entity that it&apos;s allowed to manage the User&apos;s roster'><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_2'>
<query xmlns='urn:xmpp:tmp:roster-management:0' type="rejected"/>
</iq>]]></example>
</section3>
<section3 topic="Reject the permission to manage roster">
<p>In order to reject the permission to manage roster it's enough to reject entity's presence subscription:</p>
<example caption='The user rejects entity&apos;s presence subscription'><![CDATA[
<presence to='icq.ecample.com' type='unsubscribed'/>]]></example>
<p>If the presence subscription is restored then the permission is needed to be rerequested as defined above.</p>
</section3>
</section2>
<section2 topic='The remote entity requests current user&apos;s roster' anchor='request_roster'>
<p>The remote entity being granted the permission to manage roster can request it from the User's server using usual jabber:iq:roster protocol to be able to edit it:</p>
<example caption='The remote entity requests current roster'><![CDATA[
<iq from='icq.example.com' to='juliet@example.com' type='get' id='roster_5'>
<query xmlns='jabber:iq:roster'/>
</iq>]]></example>
<p>The server MUST then answer with User's roster including there only the items that belongs to the entity&apos;s hostname:</p>
<example caption='The server responds with the roster'><![CDATA[
<iq to='icq.exampel.com' from='juliet@example.com' type='result' id='roster_5'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.com'
name='Romeo'
subscription='both'>
<group>Friends</group>
</item>
<item jid='554323654@icq.example.com'
name='Mercutio'
subscription='from'>
<group>Friends</group>
</item>
<item jid='997665667@icq.example.com'
name='Benvolio'
subscription='both'>
<group>Friends</group>
</item>
</query>
</iq>]]></example>
</section2>
<section2 topic='The user updates roster' anchor='user_update'>
<p>If client updates roster and this update affects the remote entity&apos;s contacts (i.e. belongs to it's hostname) then the server MUST forward these items to the remote entity:</p>
<example caption='The user updates roster'><![CDATA[
<iq from='juliet@example.com/chamber' type='set' id='roster_3'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
<group>Lovers</group>
</item>
</query>
</iq>]]></example>
<example caption='The server sends push roster request to the remote entity'><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_3'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
<group>Lovers</group>
</item>
</query>
</iq>]]></example>
</section2>
<section2 topic='The remote entity updates the user&apos;s roster' anchor='entity_update'>
<p>The remote entity can also send the push query to the roster with the same semantics as specified for the jabber:iq:roster protocol described in the &rfc6121;:</p>
<example caption='The remote entity sends push roster request'><![CDATA[
<iq to='juliet@example.com' type='set' id='roster_3'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
<group>Lovers</group>
</item>
</query>
</iq>]]></example>
<p>The server MUST then inform the remote entity of success or an error and in the case of success also forward the push request to all connected User's resources.</p>
<p>If the entity tries to make changes into the items it's not allowed to, the server MUST NOT do any changes in the User's roster but respond to the entity with an error:</p>
<example caption='The server responds with an error'><![CDATA[
<iq from='juliet@example.com' type='set' id='roster_3'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>You have tried to modify the item you don't allowed to.</text>
</iq>]]></example>
</section2>
<section2 topic='Client requests list of components with permissions to edit his roster'>
<p>User can ask the server to provide a list of components or servers which have permissions to edit their roster.</p>
<example caption='User asks the server to get list of components which can edit their roster'><![CDATA[
<iq from='juliet@example.com/home' to='icq.example.com' type='get' id='roster_5'>
<query xmlns='urn:xmpp:tmp:roster-management:0'/>
</iq>
]]></example>
<p>In this case, server responds with list of components or servers which can edit user's roster.</p>
<example caption='Server responds with list of componentss which can edit user&apos;s roster'><![CDATA[
<iq from='juliet@example.com/home' to='icq.example.com' type='result' id='roster_5'>
<query xmlns='urn:xmpp:tmp:roster-management:0'>
<item jid='icq.example.com' reason='Manage ICQ contacts.'/>
<item jid='j2j.example.com' reason='Manage Jabber gateway contacts.'/>
</query>
</iq>
]]></example>
<p>Eventually, user can reject permission granted to component to edit their roster.</p>
<example caption='User rejects permissions to edit his roster'><![CDATA[
<iq from='juliet@example.com/home' to='icq.example.com' type='set' id='roster_6'>
<query xmlns='urn:xmpp:tmp:roster-management:0' type="reject"/>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:tmp:roster-management:0'
xmlns='urn:xmpp:tmp:roster-management:0'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-XXXX: http://www.xmpp.org/extensions/xep-xxxx.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:attribute name='type' use='required'>
<xs:simpleType base='xs:NMTOKEN'>
<xs:enumeration value='request'/>
<xs:enumeration value='allowed'/>
<xs:enumeration value='rejected'/>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='reason' use='optional' type='xs:string'/>
<xs:sequence minOccurs='0'>
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='jid' type='fullJIDType' use='required'/>
<xs:attribute name='reason' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Remote Roster Management</title>
<abstract>This document defines a way remote entities may manage user's roster to provide a simple way to keep rosters in sync.</abstract>
&LEGALNOTICE;
<number>0321</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0001</spec>
<spec>XEP-0004</spec>
<spec>XEP-0100</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Sergey</firstname>
<surname>Dobrov</surname>
<email>binary@jrudevels.org</email>
<jid>binary@jrudevels.org</jid>
</author>
<author>
<firstname>Jan</firstname>
<surname>Kalu&#382;a</surname>
<email>hanzz.k@gmail.com</email>
<jid>hanzz@njs.netlab.cz</jid>
</author>
<revision>
<version>0.1</version>
<date>2013-04-16</date>
<initials>psa</initials>
<remark><p>Initial published version approved by the XMPP Council.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2012-12-07</date>
<initials>snd</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>It's often desirable for some XMPP based services to make it possible to manage user's roster to provide some contacts there. The most obvious example of such kind of service is a gateway to some legacy IM system (see &xep0100;). The current way that's recommended by the &xep0100; is to use the &xep0144; to synchronize items that's not sutiable in certain situations.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This document addresses the following requirements:</p>
<ol>
<li>Make it possible for remote services or entities to manage user's roster by the same mechanisms that descibed in the &rfc6121;.</li>
<li>Provide a way for user to control which services have permission to manage his roster.</li>
</ol>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<ul>
<li><strong>Remote entity</strong> — the entity that wants to modify user's roster.</li>
<li><strong>User</strong> — the entity which roster the remote entity wants to have access to.</li>
<li><strong>User's server</strong> — the XMPP server User connected to.</li>
<li><strong>Roster</strong> — the list of User's contacts as defined in the &rfc6121;.</li>
</ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Remote entity asks for permission to manage user&apos;s roster' anchor='ask_permission'>
<p>In order to be able to make any changes to the user&apos;s roster the remote entity MUST ask permission to do so first.</p>
<p>NOTE: in order to be able to perform the query, the remote entity MUST have a presence subscription to the User</p>
<example caption='Remote entity asks for permission'><![CDATA[
<iq from='icq.example.com' to='juliet@example.com' type='set' id='roster_1'>
<query xmlns='urn:xmpp:tmp:roster-management:0' reason='Manage contacts in the ICQ contact list' type='request'/>
</iq>]]></example>
<p>If the presence subscription is absent, the server MUST NOT proceed with the request but MUST respond with the "forbidden" error:</p>
<example caption="The remote entity has no presence subscription"><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='error' id='roster_1'>
<error type='modify'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>You must have a presence subscription to be able to request remote roster management service.</text>
</error>
</iq>]]></example>
<p>The user's server SHOULD then generate a form request using &xep0004; to client in order to ask user if he's OK with granting the permission to the remote entity. The "challenge" form field is generated by the server and is used to identify the client's response. The server also MUST immediatly answer to the request IQ.</p>
<p>NOTE: if the entity is already granted with the permission, the server SHOULD immediatly answer with a success response and skip querying the user.</p>
<example caption='Server asks user for the permission'><![CDATA[
<message from='example.com'
to='juliet@example.com'>
<body>icq.example.com wants to be able to manage your roster with following reason:
Manage contacts in the ICQ contact list
Do you want to allow it? Send "yes 5439123" or "no 5439123" back, pleas.</body>
<x xmlns='jabber:x:data' type='form'>
<title>Roster management permission request</title>
<instructions>icq.example.com wants to be able to manage your roster with following reason:
Manage contacts in the ICQ contact list.
Do you allow it?</instructions>
<field type='hidden' var='challenge'><value>5439123</value></field>
<field type='hidden' var='FORM_TYPE'>
<value>urn:xmpp:tmp:roster-management:0</value>
</field>
<field type='boolean'
label='Allow icq.example.com to edit roster?'
var='answer'>
<value>1</value>
</field>
</x>
</message>]]></example>
<p>The client can answer by submit the form or with a text message response:</p>
<example caption='Client responds with to the data form'><![CDATA[
<message from='juliet@example.com/home'
to='example.com'
xml:lang='en'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE'>
<value>urn:xmpp:tmp:roster-management:0</value>
</field>
<field var='challenge'><value>5439123</value></field>
<field var='answer'><value>1</value></field>
</x>
</message>]]></example>
<example caption='Client responds with a text message response'><![CDATA[
<message from='juliet@example.com/home'
to='example.com'
xml:lang='en'>
<body>yes 5439123</body>
</message>]]></example>
<section3 topic='The remote entity is allowed to manage roster' anchor='pemission_granted'>
<p>If the user allowed the roster management then the server MUST inform the remote entity that it has been granted the permission:</p>
<example caption='The server informs the remote entity that it&apos;s allowed to manage the User&apos;s roster'><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_2'>
<query xmlns='urn:xmpp:tmp:roster-management:0' type="allowed"/>
</iq>]]></example>
</section3>
<section3 topic='The remote entity is allowed to manage roster' anchor='pemission_granted'>
<p>If the user disallowed the roster management then the server MUST inform the remote entity that it hasn&apos;t been granted the permission:</p>
<example caption='The server informs the remote entity that it&apos;s allowed to manage the User&apos;s roster'><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_2'>
<query xmlns='urn:xmpp:tmp:roster-management:0' type="rejected"/>
</iq>]]></example>
</section3>
<section3 topic="Reject the permission to manage roster">
<p>In order to reject the permission to manage roster it's enough to reject entity's presence subscription:</p>
<example caption='The user rejects entity&apos;s presence subscription'><![CDATA[
<presence to='icq.ecample.com' type='unsubscribed'/>]]></example>
<p>If the presence subscription is restored then the permission is needed to be rerequested as defined above.</p>
</section3>
</section2>
<section2 topic='The remote entity requests current user&apos;s roster' anchor='request_roster'>
<p>The remote entity being granted the permission to manage roster can request it from the User's server using usual jabber:iq:roster protocol to be able to edit it:</p>
<example caption='The remote entity requests current roster'><![CDATA[
<iq from='icq.example.com' to='juliet@example.com' type='get' id='roster_5'>
<query xmlns='jabber:iq:roster'/>
</iq>]]></example>
<p>The server MUST then answer with User's roster including there only the items that belongs to the entity&apos;s hostname:</p>
<example caption='The server responds with the roster'><![CDATA[
<iq to='icq.exampel.com' from='juliet@example.com' type='result' id='roster_5'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.com'
name='Romeo'
subscription='both'>
<group>Friends</group>
</item>
<item jid='554323654@icq.example.com'
name='Mercutio'
subscription='from'>
<group>Friends</group>
</item>
<item jid='997665667@icq.example.com'
name='Benvolio'
subscription='both'>
<group>Friends</group>
</item>
</query>
</iq>]]></example>
</section2>
<section2 topic='The user updates roster' anchor='user_update'>
<p>If client updates roster and this update affects the remote entity&apos;s contacts (i.e. belongs to it's hostname) then the server MUST forward these items to the remote entity:</p>
<example caption='The user updates roster'><![CDATA[
<iq from='juliet@example.com/chamber' type='set' id='roster_3'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
<group>Lovers</group>
</item>
</query>
</iq>]]></example>
<example caption='The server sends push roster request to the remote entity'><![CDATA[
<iq from='juliet@example.com' to='icq.example.com' type='set' id='roster_3'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
<group>Lovers</group>
</item>
</query>
</iq>]]></example>
</section2>
<section2 topic='The remote entity updates the user&apos;s roster' anchor='entity_update'>
<p>The remote entity can also send the push query to the roster with the same semantics as specified for the jabber:iq:roster protocol described in the &rfc6121;:</p>
<example caption='The remote entity sends push roster request'><![CDATA[
<iq to='juliet@example.com' type='set' id='roster_3'>
<query xmlns='jabber:iq:roster'>
<item jid='123456789@icq.example.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
<group>Lovers</group>
</item>
</query>
</iq>]]></example>
<p>The server MUST then inform the remote entity of success or an error and in the case of success also forward the push request to all connected User's resources.</p>
<p>If the entity tries to make changes into the items it's not allowed to, the server MUST NOT do any changes in the User's roster but respond to the entity with an error:</p>
<example caption='The server responds with an error'><![CDATA[
<iq from='juliet@example.com' type='set' id='roster_3'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>You have tried to modify the item you don't allowed to.</text>
</iq>]]></example>
</section2>
<section2 topic='Client requests list of components with permissions to edit his roster'>
<p>User can ask the server to provide a list of components or servers which have permissions to edit their roster.</p>
<example caption='User asks the server to get list of components which can edit their roster'><![CDATA[
<iq from='juliet@example.com/home' to='icq.example.com' type='get' id='roster_5'>
<query xmlns='urn:xmpp:tmp:roster-management:0'/>
</iq>
]]></example>
<p>In this case, server responds with list of components or servers which can edit user's roster.</p>
<example caption='Server responds with list of componentss which can edit user&apos;s roster'><![CDATA[
<iq from='juliet@example.com/home' to='icq.example.com' type='result' id='roster_5'>
<query xmlns='urn:xmpp:tmp:roster-management:0'>
<item jid='icq.example.com' reason='Manage ICQ contacts.'/>
<item jid='j2j.example.com' reason='Manage Jabber gateway contacts.'/>
</query>
</iq>
]]></example>
<p>Eventually, user can reject permission granted to component to edit their roster.</p>
<example caption='User rejects permissions to edit his roster'><![CDATA[
<iq from='juliet@example.com/home' to='icq.example.com' type='set' id='roster_6'>
<query xmlns='urn:xmpp:tmp:roster-management:0' type="reject"/>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:tmp:roster-management:0'
xmlns='urn:xmpp:tmp:roster-management:0'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-XXXX: http://www.xmpp.org/extensions/xep-xxxx.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:attribute name='type' use='required'>
<xs:simpleType base='xs:NMTOKEN'>
<xs:enumeration value='request'/>
<xs:enumeration value='allowed'/>
<xs:enumeration value='rejected'/>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='reason' use='optional' type='xs:string'/>
<xs:sequence minOccurs='0'>
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='jid' type='fullJIDType' use='required'/>
<xs:attribute name='reason' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>

412
inbox/exi.xml → xep-0322.xml
View File

@ -1,4 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
<!-- TODO: Add sequence diagrams. -->
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
@ -6,19 +7,11 @@
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Using Efficient XML Interchange (EXI) Format in XMPP</title>
<title>Efficient XML Interchange (EXI) Format</title>
<abstract>This specification describes how EXI compression can be used in XMPP networks.</abstract>
<legal>
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF).</copyright>
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;Specification&quot;), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
<warranty>## NOTE WELL: This Specification is provided on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
<conformance>
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).
</conformance>
</legal>
<number>xxxx</number>
<status>ProtoXEP</status>
&LEGALNOTICE;
<number>0322</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
@ -37,6 +30,38 @@
<jid>peter.waher@jabber.org</jid>
<uri>http://se.linkedin.com/pub/peter-waher/1a/71b/a29/</uri>
</author>
<revision>
<version>0.1</version>
<date>2013-04-16</date>
<initials>psa</initials>
<remark><p>Initial published version approved by the XMPP Council.</p></remark>
</revision>
<revision>
<version>0.0.4</version>
<date>2013-03-19</date>
<initials>pwa</initials>
<remark>
<p>Added support for uploading EXI-compressed schema files.</p>
</remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2013-03-15</date>
<initials>pwa</initials>
<remark>
<p>Added definition: EXI body.</p>
<p>Added note regarding preserverance of namespace prefixes.</p>
<p>Corrected the language.</p>
</remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2013-03-13</date>
<initials>pwa</initials>
<remark>
<p>Added support for session-wide buffers and string tables.</p>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2013-03-12</date>
@ -54,7 +79,7 @@
communicate efficiently. The strong support in EXI for generating efficient stubcodes is also vital to build efficient code in constrained devices.
</p>
<p>
Activating EXI compression requires a handshake to take place prior, where the server and client agrees on a set of parameters. Some of these parameters may increase compression ratio,
Activating EXI compression requires a handshake to take place prior, where the server and client agree on a set of parameters. Some of these parameters may increase the compression ratio,
at the cost of processing power and readability. These parameters include:
</p>
<ul>
@ -71,10 +96,10 @@
<li>Value partition capacity.</li>
</ul>
<p>
These parameters will be discussed deeper in the following sections. There are also default values users can use to commence evaluating EXI compression.
These parameters will be discussed in greater depth in the following sections. There are also default values that can be used to commence evaluating EXI compression.
</p>
<p>
The single most important property to agree on however, is the set of schemas to use during EXI compression. EXI compresses XML much more efficiently if there exist schemas
The single most important property to agree on however, is the set of schemas to use during EXI compression. EXI compresses XML much more efficiently if schemas exist
describing the format of the expected XML. Since the server is not supposed to know all possible XML schemas, a mechanism is provided in this document whereby schemas can be
interchanged, so that the server can adapt its compression to the needs of the client.
</p>
@ -96,12 +121,12 @@
</stream:features>]]>
</example>
<p>
Support for EXI compression is detected by the existance of the <strong>exi</strong> compression method in the <strong>features</strong> stanza.
Support for EXI compression is detected by the existence of the <strong>exi</strong> compression method in the <strong>features</strong> stanza.
</p>
</section2>
<section2 topic='Invalid setup'>
<p>
If the client attempts to activate EXI stream at this point, before negotiation of EXI properties have been performed, the server must respond with a
If the client attempts to activate an EXI stream at this point, before the negotiation of EXI properties has been performed, the server must respond with a
<strong>setup-failed</strong> response.
</p>
<example caption='Invalid setup'>
@ -143,27 +168,27 @@
<strong>MD5 hash</strong>. The <strong>MD5 hash</strong> provides a way to detect small changes in the file, even if the byte size and namespace are the same.
</p>
<p>
Schema files that the server does not have, based on namespace, byte size and MD5 hash, are marked with the <strong>missingSchema</strong> element instead of the
Schema files that the server does not have (based on namespace, byte size and MD5 hash) are marked with the <strong>missingSchema</strong> element instead of the
normal <strong>schema</strong> element.
</p>
<p>
The client can, at this point, choose to abort the EXI enablement sequence, if it cannot accommodate itself with the proposed parameter settings provided by the server.
The XMPP session will continue to work in its current state.
</p>
At this point the client can choose to abort the EXI enablement sequence, if it cannot accommodate itself with the proposed parameter settings provided by the server.
The XMPP session will continue to work in its current state. Aborting does not require taking further action from the client.
</p>
</section2>
<section2 topic='Uploading new schema files'>
<p>
If the server lacks information about a schema file, this is specified in the response through the <strong>missingSchema</strong> elements. The client can at this point
either choose to accept that these schema files are not available, making compression less efficient, or choose to upload the missing schema files to the server. Of course,
uploading schema files would require the device to have sufficient buffers and memory to store and upload the schema files in the first place. (If not possible to upload the
schema files, consideration should be taken to install the schema files manually at the server.)
</p>
If the server lacks information about a schema file, it is specified in the response through the <strong>missingSchema</strong> elements. At this point, the client can
either choose to accept that these schema files are not available, making compression less efficient, or choose to upload the missing schema files to the server. Of course,
uploading schema files would require the device to have sufficient buffers and memory to store and upload the schema files in the first place. (If it is not possible to upload the
schema files, consideration should be given to installing the schema files manually at the server.)
</p>
<p>
To upload a schema file, the client simply sends the schema file using an <strong>uploadSchema</strong> element, as follows:
</p>
<example caption='Uploading schema file'>
<![CDATA[
<uploadSchema xmlns='http://jabber.org/protocol/compress/exi'>
<uploadSchema xmlns='http://jabber.org/protocol/compress/exi' contentType='Text'>
PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4NCjx4czpzY2hlbWENCiAgICB4
bWxuczp4cz0naHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEnDQogICAgdGFyZ2V0TmFt
ZXNwYWNlPSd1cm46eG1wcDpzbjpwcm92aXNpb25pbmcnDQogICAgeG1sbnM9J3Vybjp4bXBwOnNu
@ -175,11 +200,11 @@
</uploadSchema>]]>
</example>
<p>
The schema itself is sent using base64 encoding to the server. This, to make sure a binary exact copy is transferred, maintaining encoding, processing instructions, etc. The
server then computes the <strong>target namespace</strong>, <strong>byte size</strong> and <strong>MD5 Hash</strong> from this schema file sent.
The schema itself is sent using base64 encoding to the server. This is to make sure a binary exact copy is transferred, maintaining encoding, processing instructions, etc. The
server then computes the <strong>target namespace</strong>, <strong>byte size</strong> and <strong>MD5 Hash</strong> from the sent schema file.
</p>
<p>
If the client desires, it can test the EXI setup again. This is however optional, but can be used to test that uploading the schema files, and any new property values
If the client desires, it can test the EXI setup again. This is optional, but can be used to test that uploading the schema files, and any new property values
are accepted by the server.
</p>
<example caption='Testing newly uploaded schema files'>
@ -190,7 +215,7 @@
</setup>]]>
</example>
<p>
And the server should now respond:
And the server should then respond:
</p>
<example caption='Agreement between client and server'>
<![CDATA[
@ -205,6 +230,94 @@
The client in turn can check this attribute as a quick way to check if agreement exists.
</p>
</section2>
<section2 topic='Uploading compressed schema files'>
<p>
The <strong>uploadSchema</strong> command has an optional attribute called <strong>contentType</strong> that can be used to send different types of documents
to the server. This is not a MIME content type, but an enumeration with the following options:
</p>
<table caption='contentType values'>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>Text</td>
<td>The schema is sent as plain text. If no encoding is provided in the XML header of the schema file, UTF-8 encoding is assumed. This is the default value.</td>
</tr>
<tr>
<td>ExiBody</td>
<td>The schema file is sent as an EXI compressed file, but only the body is sent. *</td>
</tr>
<tr>
<td>ExiDocument</td>
<td>The schema file is sent as an EXI compressed file. The entire file, including Exi header is provided. *</td>
</tr>
</table>
<p>
(*) These options assume the following set of default EXI options are used. It is assumed the XMPP server has more capabilities than the client, so the following
set of options must be supported by the XMPP server. The schema files can be precompressed and stored as binary files on the client for easier transmission.
</p>
<table caption='Default EXI options'>
<tr>
<th>Option</th>
<th>Default value</th>
</tr>
<tr>
<td>Version</td>
<td>1</td>
</tr>
<tr>
<td>alignment</td>
<td>bit-packed</td>
</tr>
<tr>
<td>compression</td>
<td>false</td>
</tr>
<tr>
<td>strict</td>
<td>false</td>
</tr>
<tr>
<td>fragment</td>
<td>false</td>
</tr>
<tr>
<td>preserve</td>
<td>all false</td>
</tr>
<tr>
<td>selfContained</td>
<td>false</td>
</tr>
<tr>
<td>schemaId</td>
<td>No schema</td>
</tr>
<tr>
<td>datatypeRepresentationMap</td>
<td>No map</td>
</tr>
<tr>
<td>blockSize</td>
<td>1000000 (one million)</td>
</tr>
<tr>
<td>valueMaxLength</td>
<td>unbounded</td>
</tr>
<tr>
<td>valuePartitionCapacity</td>
<td>unbounded</td>
</tr>
</table>
<p>
Since EXI compression does not perserve the extact binary representation of the schema file (for instance it doesn't preserve white space), the server
cannot correctly compute byte size and an MD5 hash for the file. Therefore, the client needs to provide this information in the <strong>uploadSchema</strong>
command using the <strong>bytes</strong> and <strong>md5Hash</strong> attributes. They are mandatory in case EXI compressed schema files are uploaded to the
server. Also note that the byte length and MD5 Hash should be computed on the original XML Schema file, not the compressed or decompressed version.
</p>
</section2>
<section2 topic='Downloading new schema files on server'>
<p>
As an alternative to uploading a schema file to the server, the client can ask the server to download a schema file by itself. This is done using the <strong>downloadSchema</strong>
@ -219,7 +332,7 @@
from the downloaded schema.
</p>
<p>
When the schema has been downloaded, a successful download response is returned, as follows:
When the schema has been downloaded, the following successful download response is returned:
</p>
<example caption='Schema successfully downloaded'>
<![CDATA[
@ -235,7 +348,7 @@
</downloadSchemaResponse>]]>
</example>
<p>
If the URL could not be resolved, a response as follows is returned:
If the URL could not be resolved, the following response is returned:
</p>
<example caption='Invalid URL'>
<![CDATA[
@ -244,7 +357,7 @@
</downloadSchemaResponse>]]>
</example>
<p>
If a timeout occurred during the download attempt, a response as follows is returned:
If a timeout occurred during the download attempt, the following response is returned:
</p>
<example caption='Timeout'>
<![CDATA[
@ -253,7 +366,7 @@
</downloadSchemaResponse>]]>
</example>
<p>
If the url points to something that is not a schema, a response as follows is returned:
If the url points to something that is not a schema, the following response is returned:
</p>
<example caption='Invalid Content Type'>
<![CDATA[
@ -262,7 +375,7 @@
</downloadSchemaResponse>]]>
</example>
<p>
If some other error occurs, unforseen by this specification, the server can simply respond with a generic error message, as follows:
If an error occurs that is unforeseen by this specification, the server can simply respond with a generic error message, as follows:
</p>
<example caption='Other types of errors'>
<![CDATA[
@ -272,10 +385,10 @@
</example>
<p>
<strong>Note:</strong> Downloading a schema, might download a version which does not correspond to the desired version
of the schema. So, it's more important in this case, the client checks that the server actually has the version of the schema required by the client.
of the schema. It's more important in this case so the client checks that the server actually has the version of the schema required by the client.
</p>
</section2>
<section2 topic='Starting compression'>
<section2 topic='Start compression'>
<p>
When EXI option negotiation has been completed, the client can tell the server that it is ready to start compression. It does this using the normal <strong>compress</strong>
stanza, as follows:
@ -287,15 +400,16 @@
</compress>]]>
</example>
<p>
The server now having necessary knowledge on how the EXI engine should be configured for the current session, responds:
The server now has the necessary knowledge on how the EXI engine should be configured for the current session and it responds as follows:
</p>
<example>
<example caption='Compression accepted'>
<![CDATA[
<compressed xmlns='http://jabber.org/protocol/compress'/>]]>
</example>
<p>
When the client receives acknowledgement that the compression method has been accepted, it restarts the stream, as explained in
<link url='http://xmpp.org/extensions/xep-0138.html#usecase'>XEP 0138</link>.
<link url='http://xmpp.org/extensions/xep-0138.html#usecase'>XEP 0138</link>, except that it <strong>must not</strong> resend the <strong>&lt;stream&gt;</strong>
start element sequence. Similarly, the client must not send a <strong>&lt;/stream&gt;</strong> element when closing the session. Closing the connection is sufficient.
</p>
</section2>
</section1>
@ -340,7 +454,64 @@
<p>
The <strong>valuePartitionCapacity option</strong> specifies the maximum number of value content items in the string table at any given time. The default value "unbounded" is assumed when the "valuePartitionCapacity" element is absent in the EXI Options document. Section <link url='http://www.w3.org/TR/exi/#encodingOptimizedForMisses'>7.3.3 Partitions Optimized for Frequent use of String Literals</link> specifies the behavior of the string table when this capacity is reached.
</p>
<p>
The <strong>sessionWideBuffers</strong> controls buffer and string table life time. If set to true, all buffers, string tables, etc. will be maintained during the entire session.
This may improve performance during time since strings can be omitted in the compressed binary stream, but it might also in some cases degrade performance since more options are
available in the tables, requiring more bits to encode strings. The default value is false, meaning that buffers, string tables, etc., are cleared between each stanza. (This option
is EXI/XMPP specific.)
</p>
</section2>
<section2 topic='Transmission of EXI bodies and Session-wide Buffers'>
<p>
The transmission of EXI-compressed stanzas takes the form of a sequence of EXI bodies. In order for the recipient to be able to correctly interpret these incoming
EXI bodies, the sender is required to flush any pending bits at the end of the last End Document (ED) event for each stanza and then send any pending bytes available
in the output buffer. Since this makes sure each EXI body starts at an even byte boundary, it permits the recipient to decompress the body into an XML stanza.
</p>
<p>
Therefore, each stanza sent on the stream, must be compressed separately, reusing the same options as used by the stream.
(Options are not sent on the stream, only the generated EXI bodies).
</p>
<p>
Compression of the stanza must be done in document mode, not fragment mode, including the Start Document (SD) and End Document (ED) events.
If there are unwritten bits pending after the last End Document (ED) event (after the end of the stanza), Zero-bits are written until a byte boundary is created.
The receptor must ignore bits in the last byte after the last End Document event has been received.
</p>
<p>
During setup of the EXI compression engine, the client can choose if buffers are to be reused between stanzas, or cleared between each stanza. This is done
using the EXI over XMPP specific option <strong>sessionWideBuffers</strong>, which is false by default, meaning buffers and string tables are cleared between
each stanza.
</p>
<p>
There may be cases where maintaining buffers and string tables throughout the session is preferrable. Since strings are already available in the buffers,
they don't need to be output in the stream the first time they appear in a stanza. However, the number of strings in tables increase, and so does the number of bits required to
encode them. Depending on what type of communication is performed, this option might give better results one way or another. If the same type of message is always
sent, maintaining string buffers may be more efficient. But if the client sends many many different types of messages, clearing buffers may be more efficient.
</p>
<p>
Note that the stream of EXI bodies is indefinite. It only stops when the session is closed, i.e. when the socket connection is dropped. Therefore, the buffers can grow
indefinitely unless control is maintained on what types of messages are sent, their contents (specifically string values), and to whom they are sent (JIDs being strings).
All string tables and buffers must be cleared when a connection is lost.
</p>
<p>
Note also that if you want the option to enter a session in the middle of the flow to listen to the communication, you need to clear tables and buffers between each
stanza, or you will not be able to decode the binary stream appropriately.
</p>
</section2>
<section2 topic='Preserving prefixes'>
<p>
Normally, prefixes are not preserved during EXI compression and decompression. If the communicating parties (sending client, XMPP server(s) and receiving clients)
interpret incoming stanzas and content according to namespace, this should be sufficient. However, some implementations do not check namespaces, but prefix names used.
In such cases, all communicating parties are required to enable the preserve prefixes option during negotionating.
</p>
<p>
<strong>Note:</strong> It is not sufficient that one party enable this option. Both sender and received are required to enable this option, or prefix names will be
lost in the transmission.
</p>
<p>
Note also, that preserving prefix names result in less efficient compression. Therefore, all clients implementing EXI compression should strive to parse incoming
XML based on namespace, not prefix name.
</p>
</section2>
<section2 topic='Networks containing clients having limited memory'>
<p>
To successfully implement a network with clients having limited memory, such as sensor networks, care should be taken to make sure necessary schema files are
@ -369,27 +540,27 @@
download one.
</p>
<p>
Uloading a schema has the advantage, that the client knows exactly the version that the server requires. It has the disadvantage, that the client needs to store the schema
Uploading a schema has the advantage, that the client knows exactly the version that the server requires. It has the disadvantage, that the client needs to store the schema
and send a possible large schema to the server. If EXI is used because the device has limited memory, uploading a schema might not be an option.
</p>
<p>
Downloading a schema has the advantage, that size of schema does not matter. The disadvantage is that asynchronous errors might occur, so the client needs to pay respect
Downloading a schema has the advantage, that size of schema does not matter. The disadvantage is that asynchronous errors might occur, so the client needs to pay attention
to the responses returned by the server when downloading schemas. Also, downloading a schema, might download a version which does not correspond to the desired version
of the schema. So, it's more important in this case, the client checks that the server actually has the version of the schema required by the client.
of the schema. So, it's more important in this case that the client checks that the server actually has the version of the schema required by the client.
</p>
</section2>
<section2 topic='Server decompression and recompression vs. binary forwarding'>
<p>
If two XMPP clients communicate with each other through an XMPP server, and both clients use EXI compression, the server must only forward
binary packets if both EXI compressed channels have exactly the same setup. If any parameter is different, the server MUST always recompress
packets sent through it.
</p>
<p>
Since the server always needs to decompress incoming EXI compressed packets to decode headers, omitting the compression part might save the server
some processing power, but not all. Note that, in some networks it might be common using similar compression settings, while in others different compression
settings are most common.
</p>
</section2>
<section2 topic='Server decompression and recompression vs. binary forwarding'>
<p>
If two XMPP clients communicate with each other through an XMPP server, and both clients use EXI compression, the server must only forward
binary packets if both EXI compressed channels have exactly the same setup. If any parameter is different, the server MUST always recompress
packets sent through it.
</p>
<p>
Since the server always needs to decompress incoming EXI compressed packets to decode headers, omitting the compression part might save the server
some processing power, but not all. Note that, in some networks it might be common using similar compression settings, while in others different compression
settings are most common.
</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>
@ -417,7 +588,7 @@
<xs:element name='setup' type='Setup'/>
<xs:element name='setupResponse' type='SetupResponse'/>
<xs:complexType name='Setup'>
<xs:complexType name='Setup'>
<xs:choice minOccurs='0' maxOccurs='unbounded'>
<xs:element name='schema' type='Schema'/>
<xs:element name='datatypeRepresentationMap' type='DatatypeRepresentationMap'/>
@ -452,36 +623,36 @@
<xs:attribute name='alignment' type='Alignment' use='optional' default='bit-packed'>
<xs:annotation>
<xs:documentation>The alignment option is used to control the alignment of event codes and content items.
The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value
assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment
and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options
document, respectively. When the value of compression option is set to true, alignment of the EXI Body is
governed by the rules specified in 9. EXI Compression instead of the alignment option value. The "alignment"
element MUST NOT appear in an EXI options document when the "compression" element is present.</xs:documentation>
The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value
assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment
and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options
document, respectively. When the value of compression option is set to true, alignment of the EXI Body is
governed by the rules specified in 9. EXI Compression instead of the alignment option value. The "alignment"
element MUST NOT appear in an EXI options document when the "compression" element is present.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='compression' type='xs:boolean' use='optional' default='false'>
<xs:annotation>
<xs:documentation>The compression option is a Boolean used to increase compactness using additional
computational resources. The default value "false" is assumed when the "compression" element is absent in
the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes
and associated content are compressed according to 9. EXI Compression regardless of the alignment option
value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the
"alignment" element is present.</xs:documentation>
computational resources. The default value "false" is assumed when the "compression" element is absent in
the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes
and associated content are compressed according to 9. EXI Compression regardless of the alignment option
value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the
"alignment" element is present.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='strict' type='xs:boolean' use='optional' default='false'>
<xs:annotation>
<xs:documentation>The strict option is a Boolean used to increase compactness by using a strict
interpretation of the schemas and omitting preservation of certain items, such as comments, processing
instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is
absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those
productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and
schema-informed element and type grammars are restricted to only permit items declared in the schemas.
A note in section 8.5.4.4.2 Adding Productions when Strict is True describes some additional restrictions
consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document
when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same
options document.</xs:documentation>
interpretation of the schemas and omitting preservation of certain items, such as comments, processing
instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is
absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those
productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and
schema-informed element and type grammars are restricted to only permit items declared in the schemas.
A note in section 8.5.4.4.2 Adding Productions when Strict is True describes some additional restrictions
consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document
when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same
options document.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='preserveComments' type='xs:boolean' use='optional' default='false'>
@ -492,7 +663,7 @@
<xs:attribute name='preservePIs' type='xs:boolean' use='optional' default='false'>
<xs:annotation>
<xs:documentation>Processing instructions are preserved. Must not be used together with the strict
option.</xs:documentation>
option.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='preserveDTD' type='xs:boolean' use='optional' default='false'>
@ -508,41 +679,50 @@
<xs:attribute name='preserveLexical' type='xs:boolean' use='optional' default='false'>
<xs:annotation>
<xs:documentation>Lexical form of element and attribute values can be preserved in value content items.
Can be used together with the strict option.</xs:documentation>
Can be used together with the strict option.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='selfContained' type='xs:boolean' use='optional' default='false'>
<xs:annotation>
<xs:documentation>The selfContained option is a Boolean used to enable the use of self-contained elements
in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body,
allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI
options document when one of "compression", "pre-compression" or "strict" elements are present in the
same options document. The default value "false" is assumed when the "selfContained" element is absent
from the EXI Options document whereas its presence denotes the value "true".</xs:documentation>
in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body,
allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI
options document when one of "compression", "pre-compression" or "strict" elements are present in the
same options document. The default value "false" is assumed when the "selfContained" element is absent
from the EXI Options document whereas its presence denotes the value "true".</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='blockSize' type='xs:positiveInteger' use='optional' default='1000000'>
<xs:annotation>
<xs:documentation>The blockSize option specifies the block size used for EXI compression. When the
"blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used.
The default blockSize is intentionally large but can be reduced for processing large documents on
devices with limited memory.</xs:documentation>
"blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used.
The default blockSize is intentionally large but can be reduced for processing large documents on
devices with limited memory.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='valueMaxLength' type='xs:positiveInteger' use='optional'>
<xs:annotation>
<xs:documentation>The valueMaxLength option specifies the maximum length of value content items to be
considered for addition to the string table. The default value "unbounded" is assumed when the
"valueMaxLength" element is absent in the EXI Options document.</xs:documentation>
considered for addition to the string table. The default value "unbounded" is assumed when the
"valueMaxLength" element is absent in the EXI Options document.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='valuePartitionCapacity' type='xs:positiveInteger' use='optional'>
<xs:annotation>
<xs:documentation>The valuePartitionCapacity option specifies the maximum number of value content
items in the string table at any given time. The default value "unbounded" is assumed when the
"valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions
Optimized for Frequent use of String Literals specifies the behavior of the string table when this
capacity is reached.</xs:documentation>
items in the string table at any given time. The default value "unbounded" is assumed when the
"valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions
Optimized for Frequent use of String Literals specifies the behavior of the string table when this
capacity is reached.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name='sessionWideBuffers' type='xs:boolean' use='optional' default='false'>
<xs:annotation>
<xs:documentation>If set to true, all buffers, string tables, etc. will be maintained during the
entire session. This may improve performance during time since strings can be omitted in the
compressed binary stream, but it might also in some cases degrade performance since more options
are available in the tables, requiring more bits to encode strings. The default value is false,
meaning that buffers, string tables, etc., are cleared between each stanza.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:attributeGroup>
@ -558,32 +738,50 @@
<xs:enumeration value='bit-packed'>
<xs:annotation>
<xs:documentation>The alignment option value bit-packed indicates that the event codes and associated
content are packed in bits without any padding in-between.</xs:documentation>
content are packed in bits without any padding in-between.</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value='byte-alignment'>
<xs:annotation>
<xs:documentation>The alignment option value byte-alignment indicates that the event codes and
associated content are aligned on byte boundaries. While byte-alignment generally results in EXI
streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a
help in some use cases that involve frequent copying of large arrays of scalar data directly out
of the stream. It can also make it possible to work with data in-place and can make it easier to
debug encoded data by allowing items on aligned boundaries to be easily located in the stream.</xs:documentation>
associated content are aligned on byte boundaries. While byte-alignment generally results in EXI
streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a
help in some use cases that involve frequent copying of large arrays of scalar data directly out
of the stream. It can also make it possible to work with data in-place and can make it easier to
debug encoded data by allowing items on aligned boundaries to be easily located in the stream.</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value='pre-compression'>
<xs:annotation>
<xs:documentation>The alignment option value pre-compression indicates that all steps involved
in compression (see section 9. EXI Compression) are to be done with the exception of the final
step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a
duplicate compression step when compression capability is built into the transport protocol. In
this case, pre-compression just prepares the stream for later compression.</xs:documentation>
in compression (see section 9. EXI Compression) are to be done with the exception of the final
step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a
duplicate compression step when compression capability is built into the transport protocol. In
this case, pre-compression just prepares the stream for later compression.</xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
<xs:element name='uploadSchema' type='xs:base64Binary'/>
<xs:element name='uploadSchema'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:base64Binary'>
<xs:attribute name='contentType' type='ContentType' use='optional' default='Text'/>
<xs:attribute name='bytes' type='xs:positiveInteger' use='optional'/>
<xs:attribute name='md5Hash' type='MD5Hash' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:simpleType name='ContentType'>
<xs:restriction base='xs:string'>
<xs:enumeration value='Text'/>
<xs:enumeration value='ExiBody'/>
<xs:enumeration value='ExiDocument'/>
</xs:restriction>
</xs:simpleType>
<xs:element name='downloadSchema' type='DownloadSchema'/>
<xs:element name='downloadSchemaResponse' type='DownloadSchemaResponse'/>
@ -632,7 +830,7 @@
]]>
</code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Joachim Lindborg for all valuable feedback.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Joachim Lindborg, Yusuke Doi, Takuki Kamiya, Tina Beckman, Karin Forsell, Jeff Freund and Rumen Kyusakov for all valuable feedback.</p>
</section1>
</xep>

1429
xep-0323.xml Normal file
View File

File diff suppressed because one or more lines are too long

1670
xep-0324.xml Normal file
View File

File diff suppressed because one or more lines are too long

5
xep.ent
View File

@ -1267,3 +1267,8 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates</link></span> <note>
<!ENTITY xep0317 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0317.html'>Hats</link></span> <note>XEP-0317: Hats &lt;<link url='http://xmpp.org/extensions/xep-0317.html'>http://xmpp.org/extensions/xep-0317.html</link>&gt;.</note>" >
<!ENTITY xep0318 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0318.html'>Last Presence using Delayed Delivery</link></span> <note>XEP-0318: Last Presence using Delayed Delivery &lt;<link url='http://xmpp.org/extensions/xep-0318.html'>http://xmpp.org/extensions/xep-0318.html</link>&gt;.</note>" >
<!ENTITY xep0319 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0319.html'>Last User Interaction in Presence</link></span> <note>XEP-0319: Last User Interaction in Presence &lt;<link url='http://xmpp.org/extensions/xep-0319.html'>http://xmpp.org/extensions/xep-0319.html</link>&gt;.</note>" >
<!ENTITY xep0320 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0320.html'>Use of DTLS-SRTP in Jingle Sessions</link></span> <note>XEP-0320: Use of DTLS-SRTP in Jingle Sessions &lt;<link url='http://xmpp.org/extensions/xep-0320.html'>http://xmpp.org/extensions/xep-0320.html</link>&gt;.</note>" >
<!ENTITY xep0321 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0321.html'>Remote Roster Management</link></span> <note>XEP-0321: Remote Roster Management &lt;<link url='http://xmpp.org/extensions/xep-0321.html'>http://xmpp.org/extensions/xep-0321.html</link>&gt;.</note>" >
<!ENTITY xep0322 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0322.html'>Efficient XML Interchange (EXI) Format</link></span> <note>XEP-0322: Efficient XML Interchange (EXI) Format &lt;<link url='http://xmpp.org/extensions/xep-0322.html'>http://xmpp.org/extensions/xep-0322.html</link>&gt;.</note>" >
<!ENTITY xep0323 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0323.html'>Sensor Networks - Sensor Data</link></span> <note>XEP-0323: Sensor Networks - Sensor Data &lt;<link url='http://xmpp.org/extensions/xep-0323.html'>http://xmpp.org/extensions/xep-0323.html</link>&gt;.</note>" >
<!ENTITY xep0324 "<span class='ref'><link url='http://xmpp.org/extensions/xep-0324.html'>Sensor Networks - Provisioning</link></span> <note>XEP-0324: Sensor Networks - Provisioning &lt;<link url='http://xmpp.org/extensions/xep-0324.html'>http://xmpp.org/extensions/xep-0324.html</link>&gt;.</note>" >