No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0098.xml 10KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM "xep.ent">
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Enhanced Private XML Storage</title>
  10. <abstract>Standardizes "private" XML data storage.</abstract>
  11. &LEGALNOTICE;
  12. <number>0098</number>
  13. <status>Deferred</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies/>
  17. <supersedes/>
  18. <supersededby/>
  19. <shortname>private-xml</shortname>
  20. <author>
  21. <firstname>Iain</firstname>
  22. <surname>Shigeoka</surname>
  23. <email>iain@jivesoftware.com</email>
  24. <jid>smirk@jabber.com</jid>
  25. </author>
  26. <revision>
  27. <version>0.1</version>
  28. <date>2003-06-25</date>
  29. <initials>iss</initials>
  30. <remark>Initial version.</remark>
  31. </revision>
  32. </header>
  33. <section1 topic='Introduction'>
  34. <p>The 'jabber:iq:private' namespace has been
  35. documented in &xep0049; according to the historical behavior
  36. of current implementations. However there are two backward compatible
  37. improvements to the protocol introduced in this standard
  38. that increase the future useability of the protocol: matching on the fully
  39. qualified name of the XML fragment root, and the introduction of a standard
  40. mechanism of removing stored data. Because the protocol defined herein is not identical to 'jabber:iq:private', a new namespace name is used: 'http://jabber.org/protocol/private-xml'.</p>
  41. <p>This protocol is designed to provide a simple interface to XML data storage
  42. on XMPP servers. The simple interface eases the implementation burden for the most
  43. basic data storage use-cases (e.g. storing simple client preferences on the server).
  44. More sophisticated XML data storage protocols should be built on top of, or compatible
  45. with this standard.</p>
  46. </section1>
  47. <section1 topic='private-xml Namespace'>
  48. <section2 topic='Description'>
  49. <p>A Jabber client can store any arbitrary XML on the server side by sending an
  50. &IQ; chunk of type "set" to the server with a &QUERY; child scoped by the
  51. 'http://jabber.org/protocol/private-xml' namespace. The &QUERY; element MUST contain a single, arbitrary
  52. XML fragment. That fragment MUST be scoped by its
  53. own namespace. Any existing data stored on the server with the same fully qualified
  54. element name (tag name + namespace) is replaced by the new data.</p>
  55. <p>The data can then be retrieved by sending an &IQ;
  56. of type "get" with a &QUERY; child scoped by the 'http://jabber.org/protocol/private-xml' namespace,
  57. which in turn MUST contain a single child element scoped by the namespace used
  58. for storage of that fragment. The fully qualified element name is used to locate
  59. matching XML data on the server. If no matching data is found, the server will
  60. respond with the empty query child element and not an error.</p>
  61. <p>Finally, existing data on the server can be removed by sending an &IQ;
  62. of type "set" with a &QUERY; child scoped by the 'http://jabber.org/protocol/private-xml' namespace and
  63. containing an 'action' attribute with value 'delete',
  64. which in turn MUST contain a single child element scoped by the namespace used
  65. for storage of that fragment. The fully qualified element name is used to locate
  66. matching XML data on the server. The server responds with a successful result
  67. whether a matching data fragment was found or not (it's successful because the
  68. provided data no longer exits on the server). Deleting data using this method is
  69. indistinguishable from setting an empty XML fragment as far as the behavior this
  70. protoco is concerned. However, deleting data MUST remove the data from the server
  71. which may be implemented differently than the case of setting the data to an empty
  72. element. This may have significance in the context of future advanced XML storage protocols.
  73. Using the basic private XML data storage protocol, Jabber entities can create, read, update, and delete
  74. private data on the server. The data stored might be
  75. anything, as long as it is valid XML. One typical usage for this namespace is the
  76. server-side storage of client preferences.</p>
  77. </section2>
  78. <section2 topic='Methods'>
  79. <table caption='Description of Acceptable Methods'>
  80. <tr><td>get</td><td>Sent with a blank query to retrieve the private data from the server.</td></tr>
  81. <tr><td>set</td><td>Sent with the private XML data contained inside of a query.</td></tr>
  82. <tr><td>set action='delete'</td><td>Sent with a blank query to delete private data from the server.</td></tr>
  83. <tr><td>result</td><td>Returns the private data from the server.</td></tr>
  84. <tr><td>error</td><td>There was an error processing the request. The exact error can be found in the child error element.</td></tr>
  85. </table>
  86. </section2>
  87. <section2 topic='Elements'>
  88. <p>The root element of this namespace is query. A single child
  89. element with a proper namespace must be included otherwise the server will
  90. respond with error code 406. Only one element can be queried or set in a
  91. single IQ request. However, multiple elements, each containing data,
  92. can be stored independently on the server using separate set queries.</p>
  93. <example caption='Client Stores Private Data'><![CDATA[
  94. CLIENT:
  95. <iq type="set" id="1001">
  96. <query xmlns="http://jabber.org/protocol/private-xml">
  97. <exodus xmlns="exodus:prefs">
  98. <defaultnick>Hamlet</defaultnick>
  99. </exodus>
  100. </query>
  101. </iq>
  102. SERVER:
  103. <iq
  104. type="result"
  105. from="hamlet@shakespeare.lit/denmark"
  106. to="hamlet@shakespeare.lit/denmark"
  107. id="1001"/>
  108. ]]></example>
  109. <example caption='Client Retrieves Private Data'><![CDATA[
  110. CLIENT:
  111. <iq type="get" id="1002">
  112. <query xmlns="http://jabber.org/protocol/private-xml">
  113. <exodus xmlns="exodus:prefs"/>
  114. </query>
  115. </iq>
  116. SERVER:
  117. <iq
  118. type="result"
  119. from="hamlet@shakespeare.lit/denmark"
  120. to="hamlet@shakespeare.lit/denmark"
  121. id="1002">
  122. <query xmlns="http://jabber.org/protocol/private-xml">
  123. <exodus xmlns="exodus:prefs">
  124. <defaultnick>Hamlet</defaultnick>
  125. </exodus>
  126. </query>
  127. </iq>
  128. ]]></example>
  129. <p>If a user attempts to get or set http://jabber.org/protocol/private-xml data that belongs to another user, the server must return an error to the sender. The error commonly used is 503 (Service Unavailable).</p>
  130. <example caption='User Attempts to Get or Set Data for Another User'><![CDATA[
  131. CLIENT:
  132. <iq type="set" to="hamlet@shakespeare.lit" id="1003">
  133. <query xmlns="http://jabber.org/protocol/private-xml">
  134. <exodus xmlns="exodus:prefs">
  135. <defaultnick>Macbeth</defaultnick>
  136. </exodus>
  137. </query>
  138. </iq>
  139. SERVER:
  140. <iq
  141. type="error"
  142. from="hamlet@shakespeare.lit"
  143. to="macbeth@shakespeare.lit"
  144. iq="1003">
  145. <query xmlns="http://jabber.org/protocol/private-xml">
  146. <exodus xmlns="exodus:prefs">
  147. <defaultnick>Macbeth</defaultnick>
  148. </exodus>
  149. </query>
  150. <error code="503">Service Unavailable</error>
  151. </iq>
  152. ]]></example>
  153. <p>If a user attempts to perform a get without providing a child element, the server should return a 406 (Not Acceptable) error:</p>
  154. <example caption='User Attempts to Get Data Without Specifying Child Element/Namespace'><![CDATA[
  155. CLIENT:
  156. <iq type="set" id="1004">
  157. <query xmlns="http://jabber.org/protocol/private-xml"/>
  158. </iq>
  159. SERVER:
  160. <iq type="error" iq="1004">
  161. <query xmlns="http://jabber.org/protocol/private-xml"/>
  162. <error code="406">Not Acceptable</error>
  163. </iq>
  164. ]]></example>
  165. <p>Certain namespaces are reserved in Jabber (namespaces beginning with 'jabber:' or 'http://jabber.org/', as well as 'vcard-temp'). If a user attempts to get or set http://jabber.org/protocol/private-xml data in a reserved namespace, historically some server implementations have chosen to return an error (commonly 406 [Not Acceptable]) to the sender. Such behavior is not required in order to comply with this document, but may be encountered by clients when interacting with some current server implementations.</p>
  166. <example caption='User Attempts to Get or Set Data in a Reserved Namespace'><![CDATA[
  167. CLIENT:
  168. <iq type="set" id="1005">
  169. <query xmlns="http://jabber.org/protocol/private-xml">
  170. <vCard xmlns="vcard-temp">
  171. <FN>Hamlet</FN>
  172. </vCard>
  173. </query>
  174. </iq>
  175. SERVER (optional error):
  176. <iq type="error" iq="1005">
  177. <query xmlns="http://jabber.org/protocol/private-xml">
  178. <vCard xmlns="vcard-temp">
  179. <FN>Hamlet</FN>
  180. </vCard>
  181. </query>
  182. <error code="406">Not Acceptable</error>
  183. </iq>
  184. ]]></example>
  185. <p>The server always replies to a properly formatted get query with
  186. a result response rather than some form of 'not found' error.
  187. for exmple, the following shows the response from a server that does not have XML
  188. data under the 'data' name and 'imaginary' namespace.</p>
  189. <example caption='User Attempts to Get Data in That Does Not Exist'><![CDATA[
  190. CLIENT:
  191. <iq type="get" id="1006">
  192. <query xmlns="http://jabber.org/protocol/private-xml">
  193. <data xmlns="imaginary"/>
  194. </query>
  195. </iq>
  196. SERVER (does not have data in "imaginary" namespace, returns empty element):
  197. <iq
  198. type="result"
  199. from="hamlet@shakespeare.lit/denmark"
  200. to="hamlet@shakespeare.lit/denmark"
  201. id="1006">
  202. <query xmlns="http://jabber.org/protocol/private-xml">
  203. <data xmlns="imaginary"/>
  204. </query>
  205. </iq>
  206. ]]></example>
  207. <p>Finally, the client can delete data from the server using the delete query action.</p>
  208. <example caption='User Deletes Data'><![CDATA[
  209. CLIENT:
  210. <iq type="get" id="1006">
  211. <query xmlns="http://jabber.org/protocol/private-xml" action="delete">
  212. <exodus xmlns="exodus:prefs"/>
  213. </query>
  214. </iq>
  215. SERVER (server responds with success):
  216. <iq
  217. type="result"
  218. from="hamlet@shakespeare.lit/denmark"
  219. to="hamlet@shakespeare.lit/denmark"
  220. id="1006"/>
  221. ]]></example>
  222. </section2>
  223. <section2 topic='Error Codes'>
  224. <table caption='Error Codes used by http://jabber.org/protocol/private-xml'>
  225. <tr>
  226. <th>Code</th><th>Text</th><th>Description</th>
  227. </tr>
  228. <tr>
  229. <td>406</td><td>Not Acceptable</td><td>The IQ get does not contain a child element or (optionally) the IQ get or set is in a reserved namespace.</td>
  230. </tr>
  231. <tr>
  232. <td>503</td><td>Service Unavailable</td><td>The IQ get or set is sent to a JID other than that of the sender.</td>
  233. </tr>
  234. </table>
  235. </section2>
  236. <section2 topic='DTD'>
  237. <code><![CDATA[
  238. <?xml version="1.0" encoding="UTF-8" ?>
  239. <!ELEMENT query (#PCDATA)>
  240. ]]></code>
  241. </section2>
  242. </section1>
  243. </xep>