mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-21 23:28:51 -05:00
0.18
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1849 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre
parent
1be2d4b636
commit
51b0403c32
62
xep-0136.xml
62
xep-0136.xml
@ -32,6 +32,12 @@
|
||||
</author>
|
||||
&stpeter;
|
||||
&infiniti;
|
||||
<revision>
|
||||
<version>0.18</version>
|
||||
<date>2008-05-19</date>
|
||||
<initials>psa</initials>
|
||||
<remark><p>Corrected and clarified usage of exactmatch attribute; removed out-of-date archive, delete, and keys elements from schema.</p></remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.17</version>
|
||||
<date>2008-04-30</date>
|
||||
@ -523,7 +529,7 @@
|
||||
</section1>
|
||||
|
||||
<section1 topic='Collections: The Chat Element' anchor='collections'>
|
||||
<p>Whether manual archiving or automatic archiving is used, messages are archived in the form of "collections. A collection is a set of messages to/from the same user that are received near each other in time or as part of the same conversation thread. A collection is intended to mimic the natural flow of human conversations, which in instant messaging (IM) systems tend to occur in bursts (e.g., a five-minute conversation one day, followed by a ten-minute conversation the next).</p>
|
||||
<p>Whether manual archiving or automatic archiving is used, messages are archived in the form of "collections". A collection is a set of messages to/from the same user that are received near each other in time or as part of the same conversation thread. A collection is intended to mimic the natural flow of human conversations, which in instant messaging (IM) systems tend to occur in bursts (e.g., a five-minute conversation one day, followed by a ten-minute conversation the next).</p>
|
||||
<p>Each collection of messages and notes is encapsulated in a <chat/> element and is uniquely identified by the combination of the 'start' and 'with' attributes as defined below. The syntax of the <chat/> element is specified in this section.</p>
|
||||
<section2 topic='start Attribute' anchor='collections-start'>
|
||||
<p>The 'start' attribute specifies the start time of the conversation thread, which MUST be UTC and adhere to the DateTime format specified in &xep0082;.</p>
|
||||
@ -543,8 +549,9 @@
|
||||
<p>Inclusion of the 'version' attribute is REQUIRED of servers.</p>
|
||||
</section2>
|
||||
<section2 topic='with Attribute' anchor='collections-with'>
|
||||
<p>The 'with' attribute specifies the JID with which the messages were exchanged. If the JID is of the form &LOCALBARE;, any resource matches; if the JID is of the form &DOMAINBARE;, any node matches. If the client or server wishes to match an exact bare JID, the boolean 'exactmatch' attribute MUST be included and MUST be set yo "true" or "0" &BOOLEANNOTE;.</p>
|
||||
<p>Inclusion of the 'with' attributwe is REQUIRED.</p>
|
||||
<p>The 'with' attribute specifies the JID with which the messages were exchanged.</p>
|
||||
<p>If the JID is of the form &LOCALBARE;, any resource matches; if the JID is of the form &DOMAINBARE;, any node matches.</p>
|
||||
<p>Inclusion of the 'with' attribute is REQUIRED.</p>
|
||||
</section2>
|
||||
<section2 topic='from and to Elements' anchor='collections-fromto'>
|
||||
<p>The content of each individual message MUST be encapsulated in a <to/> or <from/> element. The time in whole seconds of the message relative to the previous message in the collection (or, for the first message, relative to the start of the collection) SHOULD be specified with a 'secs' attribute. Note: When deciding whether to round up or down to a number of whole seconds, entities MUST ensure that the sum of the 'secs' attribute and the 'secs' attributes of the preceeding messages will accurately reflect the absolute time of the message. (e.g., if a sequence of messages occur at exactly 0.51-second intervals then the 'secs' attributes should generally alternate between '0' or '1'.)</p>
|
||||
@ -800,7 +807,8 @@
|
||||
</ol>
|
||||
<p>Requirements and protocol flows for each of these use cases are defined below. The protocols to retrieve a list of collections and an indivdual collection both make extensive use of &xep0059;. Clients and servers SHOULD support all the features defined in that protocol.</p>
|
||||
<section2 topic='Retrieving a List of Collections' anchor='manage-list'>
|
||||
<p>To request a list of collections the client sends a <list/> element. The 'start' and 'end' attributes MAY be specified to indicate a date range (the values of these attributes MUST be UTC and adhere to the DateTime format specified in <cite>XEP-0082</cite>). The 'with' attribute MAY be specified to limit the list to a single participating full JID, bare JID or domain.</p>
|
||||
<p>To request a list of collections, the client sends a <list/> element. The 'start' and 'end' attributes MAY be specified to indicate a date range (the values of these attributes MUST be UTC and adhere to the DateTime format specified in <cite>XEP-0082</cite>). The 'with' attribute MAY be specified to limit the list to a single participating full JID, bare JID or domain.</p>
|
||||
<p>In addition, the client MAY match an exact bare JID &BAREJID; by setting the boolean 'exactmatch' attribute to a value of "true" or "1" &BOOLEANNOTE; -- for details, refer to the <link url='#impl-exactmatch'>Exact JID Matching</link> section of this document.</p>
|
||||
<p>If the 'with' attribute is omitted then collections with any JID are returned. If only 'start' is specified then all collections on or after that date should be returned. If only 'end' is specified then all collections prior to that date should be returned.</p>
|
||||
<p>The client SHOULD use <cite>Result Set Management</cite> to limit the number of collections returned by the server in a single stanza, taking care not to request a page of collections that is so big it might exceed rate limiting restrictions.</p>
|
||||
<example caption='Requesting the first page of a list with same JID'><![CDATA[
|
||||
@ -857,7 +865,8 @@
|
||||
<p>Refer to <cite>Result Set Management</cite> to learn more about the various ways that the pages of the list may be accessed.</p>
|
||||
</section2>
|
||||
<section2 topic='Retrieving a Collection' anchor='manage-retrieve'>
|
||||
<p>To request a page of messages from a collection the client sends a <retrieve/> element. The 'with' and 'start' attributes specify the participating full JID and the start time (see <cite>XEP-0082</cite>). Both attributes MUST be included to uniquely identify a collection:</p>
|
||||
<p>To request a page of messages from a collection the client sends a <retrieve/> element. The 'with' and 'start' attributes specify the participating full JID and the start time (see <cite>XEP-0082</cite>). Both attributes MUST be included to uniquely identify a collection.</p>
|
||||
<p>In addition, the client MAY match an exact bare JID &BAREJID; by setting the boolean 'exactmatch' attribute to a value of "true" or "1" &BOOLEANNOTE; -- for details, refer to the <link url='#impl-exactmatch'>Exact JID Matching</link> section of this document.</p>
|
||||
<p>The client SHOULD use <cite>Result Set Management</cite> to limit the number of messages returned by the server in a single stanza, taking care not to request a page of messages that is so big it might exceed rate limiting restrictions.</p>
|
||||
<example caption='Requesting the first page of a collection'><![CDATA[
|
||||
<iq type='get' id='page1'>
|
||||
@ -941,6 +950,7 @@
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The client may remove several collections at once. The 'start' and 'end' elements MAY be specified to indicate a date range. The 'with' attribute MAY be a full JID, bare JID or domain.</p>
|
||||
<p>In addition, the client MAY match an exact bare JID &BAREJID; by setting the boolean 'exactmatch' attribute to a value of "true" or "1" &BOOLEANNOTE; -- for details, refer to the <link url='#impl-exactmatch'>Exact JID Matching</link> section of this document.</p>
|
||||
<example caption='Removing all collections with a specified bare JID between two times'><![CDATA[
|
||||
<iq type='set' id='remove2'>
|
||||
<remove xmlns='urn:xmpp:tmp:archive'
|
||||
@ -1015,7 +1025,7 @@
|
||||
</modified>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The server MUST return the changed collections in the chronological order that they were changed (most recent last). If a collection has been modified, created, or removed <em>after</em> the time specified by the 'start' attribute, then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each <changed/> or <removed/> collection element (for modified/created, or removed collections respectively) in the returned list MUST include only 'with' and 'start' attribues. The XML character data of the <last/> element is a unique, persistent identifier created by the server, which MUST be treated as opaque by the client.</p>
|
||||
<p>The server MUST return the changed collections in the chronological order that they were changed (most recent last). If a collection has been modified, created, or removed <em>after</em> the time specified by the 'start' attribute, then the server MUST include it in the returned result set page of collections (unless the specified maximum page size would be exceeded). Each <changed/> or <removed/> collection element (for modified/created, or removed collections respectively) in the returned list MUST include the 'with' and 'start' attribues (and MAY include the 'exactmatch' attribute if that was specified in the request). The XML character data of the <last/> element is a unique, persistent identifier created by the server, which MUST be treated as opaque by the client.</p>
|
||||
<example caption='Receiving a page of modifications'><![CDATA[
|
||||
<iq type='result' to='romeo@montague.net/orchard' id='sync1'>
|
||||
<modified xmlns='urn:xmpp:tmp:archive'>
|
||||
@ -1082,6 +1092,9 @@
|
||||
</section1>
|
||||
|
||||
<section1 topic='Implementation Notes' anchor='impl'>
|
||||
<section2 topic='Exact JID Matching' anchor='impl-exactmatch'>
|
||||
<p>When the 'exactmatch' attribute is set to "true" or "1" on an element of <item/>, <list/>, <remove/>, or <retrieve/>, a 'with' value such as "example.com" matches that exact JID only rather than <*@example.com>, <*@example.com>, or <example.com/*>, and a 'with' value such as "localpart@example.com" matches that exact JID only rather than <localpart@example.com/*>.</p>
|
||||
</section2>
|
||||
<section2 topic='Time Synchronization' anchor='impl-sync'>
|
||||
<p>When creating a new collection, it is RECOMMENDED that the client synchronizes the collection start time that it sends to the server with server time. This is important since the user may subsequently retrieve the archived collection using client machines whose UTC clocks are not synchronized with the client machine that uploaded the collection. (i.e. Either or both of the clients' UTC clocks may be wrong.) The client can achieve this synchronization with server time by using &xep0202; to estimate the difference between the server and client UTC clocks.</p>
|
||||
<p>When retrieving collections, it is RECOMMENDED that the client adjusts the start times of the collections it receives from server to be synchronized with the clock of the client machine.</p>
|
||||
@ -1151,12 +1164,9 @@
|
||||
<xs:documentation>
|
||||
The allowable root elements for the namespace defined
|
||||
herein are:
|
||||
- archive
|
||||
- auto
|
||||
- chat
|
||||
- delete
|
||||
- itemremove
|
||||
- keys
|
||||
- list
|
||||
- modified
|
||||
- pref
|
||||
@ -1166,15 +1176,6 @@
|
||||
</xs:documentation>
|
||||
</xs:annotation>
|
||||
|
||||
<xs:element name='archive'>
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element ref='chat' minOccurs='1' maxOccurs='unbounded'/>
|
||||
</xs:sequence>
|
||||
<xs:attribute name='with' type='xs:string' use='optional'/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:element name='auto'>
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
@ -1188,6 +1189,7 @@
|
||||
<xs:complexType>
|
||||
<xs:simpleContent>
|
||||
<xs:extension base='empty'>
|
||||
<xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
|
||||
<xs:attribute name='start' type='xs:dateTime' use='required'/>
|
||||
<xs:attribute name='with' type='xs:string' use='required'/>
|
||||
<xs:attribute name='version' type='xs:nonNegativeInteger' use='required'/>
|
||||
@ -1267,16 +1269,6 @@
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:element name='delete'>
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
|
||||
</xs:sequence>
|
||||
<xs:attribute name='start' type='xs:dateTime' use='required'/>
|
||||
<xs:attribute name='with' type='xs:string' use='required'/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:element name='feature'>
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
@ -1289,6 +1281,7 @@
|
||||
<xs:complexType>
|
||||
<xs:simpleContent>
|
||||
<xs:extension base='empty'>
|
||||
<xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
|
||||
<xs:attribute name='expire' type='xs:nonNegativeInteger' use='optional'/>
|
||||
<xs:attribute name='jid' use='required' type='xs:string'/>
|
||||
<xs:attribute name='otr' use='required'>
|
||||
@ -1318,15 +1311,6 @@
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:element name='keys'>
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element ref='chat' minOccurs='0' maxOccurs='unbounded'/>
|
||||
<xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:element name='list'>
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
@ -1334,6 +1318,7 @@
|
||||
<xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
|
||||
</xs:sequence>
|
||||
<xs:attribute name='end' type='xs:dateTime' use='optional'/>
|
||||
<xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
|
||||
<xs:attribute name='start' type='xs:dateTime' use='optional'/>
|
||||
<xs:attribute name='with' type='xs:string' use='optional'/>
|
||||
</xs:complexType>
|
||||
@ -1403,6 +1388,7 @@
|
||||
<xs:simpleContent>
|
||||
<xs:extension base='empty'>
|
||||
<xs:attribute name='end' type='xs:dateTime' use='optional'/>
|
||||
<xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
|
||||
<xs:attribute name='open' use='optional' type='xs:boolean'/>
|
||||
<xs:attribute name='start' type='xs:dateTime' use='required'/>
|
||||
<xs:attribute name='with' type='xs:string' use='required'/>
|
||||
@ -1415,6 +1401,7 @@
|
||||
<xs:complexType>
|
||||
<xs:simpleContent>
|
||||
<xs:extension base='empty'>
|
||||
<xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
|
||||
<xs:attribute name='start' type='xs:dateTime' use='required'/>
|
||||
<xs:attribute name='with' type='xs:string' use='required'/>
|
||||
<xs:attribute name='version' type='xs:nonNegativeInteger' use='required'/>
|
||||
@ -1428,6 +1415,7 @@
|
||||
<xs:sequence>
|
||||
<xs:any processContents='lax' namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
|
||||
</xs:sequence>
|
||||
<xs:attribute name='exactmatch' type='xs:boolean' use='optional'/>
|
||||
<xs:attribute name='start' type='xs:dateTime' use='required'/>
|
||||
<xs:attribute name='with' type='xs:string' use='required'/>
|
||||
</xs:complexType>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user