1.2pre1

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1944 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0133.xml

@@ -21,65 +21,71 @@
   <supersededby/>
   <shortname>admin</shortname>
   &stpeter;
+  <revision>
+    <version>1.2pre1</version>
+    <date>in progress, last updated 2008-06-10</date>
+    <initials>psa</initials>
+    <remark><p>Added use cases for deleting logs and emptying cache.</p></remark>
+  </revision>
   <revision>
     <version>1.1</version>
     <date>2005-08-19</date>
     <initials>psa</initials>
-    <remark>Added use cases for getting list of idle users and of active users (where online = active + idle), getting number (rather than list) of registered/disabled/online/active/idle users, getting list of disabled users, getting user statistics.</remark>
+    <remark><p>Added use cases for getting list of idle users and of active users (where online = active + idle), getting number (rather than list) of registered/disabled/online/active/idle users, getting list of disabled users, getting user statistics.</p></remark>
   </revision>
   <revision>
     <version>1.0</version>
     <date>2004-12-09</date>
     <initials>psa</initials>
-    <remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
+    <remark><p>Per a vote of the Jabber Council, advanced status to Active.</p></remark>
   </revision>
   <revision>
     <version>0.8</version>
     <date>2004-12-06</date>
     <initials>psa</initials>
-    <remark>Addressed Council feedback: folded add blacklist use case into edit blacklist use case; folded add whitelist use case into edit whitelist use case; changed jid-single to jid-multi in many of the use cases; added accountjid field to change password use case; removed grant administrative privileges and revoke administrative privileges use cases (need edit admin list use case only); added max_items field to get active users and get registered users use case.</remark>
+    <remark><p>Addressed Council feedback: folded add blacklist use case into edit blacklist use case; folded add whitelist use case into edit whitelist use case; changed jid-single to jid-multi in many of the use cases; added accountjid field to change password use case; removed grant administrative privileges and revoke administrative privileges use cases (need edit admin list use case only); added max_items field to get active users and get registered users use case.</p></remark>
   </revision>
   <revision>
     <version>0.7</version>
     <date>2004-12-02</date>
     <initials>psa</initials>
-    <remark>Added use case for editing message of the day.</remark>
+    <remark><p>Added use case for editing message of the day.</p></remark>
   </revision>
   <revision>
     <version>0.6</version>
     <date>2004-11-19</date>
     <initials>psa</initials>
-    <remark>Further clarified message of the day per list discussion.</remark>
+    <remark><p>Further clarified message of the day per list discussion.</p></remark>
   </revision>
   <revision>
     <version>0.5</version>
     <date>2004-11-17</date>
     <initials>psa</initials>
-    <remark>Changed firstname to given_name.</remark>
+    <remark><p>Changed firstname to given_name.</p></remark>
   </revision>
   <revision>
     <version>0.4</version>
     <date>2004-11-02</date>
     <initials>psa</initials>
-    <remark>Added note clarifying concept of message of the day.</remark>
+    <remark><p>Added note clarifying concept of message of the day.</p></remark>
   </revision>
   <revision>
     <version>0.3</version>
     <date>2004-09-30</date>
     <initials>psa</initials>
-    <remark>Changed command naming requirement from MUST to SHOULD.</remark>
+    <remark><p>Changed command naming requirement from MUST to SHOULD.</p></remark>
   </revision>
   <revision>
     <version>0.2</version>
     <date>2004-07-22</date>
     <initials>psa</initials>
-    <remark>Added several more use cases; defined complete protocol flows; specified XMPP Registrar considerations.</remark>
+    <remark><p>Added several more use cases; defined complete protocol flows; specified XMPP Registrar considerations.</p></remark>
   </revision>
   <revision>
     <version>0.1</version>
     <date>2004-04-25</date>
     <initials>psa</initials>
-    <remark>Initial version.</remark>
+    <remark><p>Initial version.</p></remark>
   </revision>
 </header>
 <section1 topic='Introduction' anchor='intro'>
@@ -2495,6 +2501,160 @@
            node='http://jabber.org/protocol/admin#shutdown'
            sessionid='shutdown:20040408T0337Z'
            status='completed'/>
+</iq>
+    ]]></example>
+  </section2>
+  <section2 topic='Delete Log' anchor='deletelog'>
+    <p>A service may allow an administrator to delete a log related to the service (e.g., a server log, a personal conversation log, or a discussion log from a multi-user chat room). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#deletelog".</p>
+    <p>A sample protocol flow for this use case is shown below.</p>
+    <example caption='Admin Requests Log Deletion'><![CDATA[
+<iq from='bard@shakespeare.lit/globe'
+    id='deletelog-1'
+    to='chat.shakespeare.lit'
+    type='set'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           action='execute'
+           node='http://jabber.org/protocol/admin#deletelog'/>
+</iq>
+    ]]></example>
+    <p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
+    <example caption='Service Returns Log Deletion Form to Admin'><![CDATA[
+<iq from='chat.shakespeare.lit'
+    id='deletelog-1'
+    to='bard@shakespeare.lit/globe'
+    type='result'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           node='http://jabber.org/protocol/admin#deletelog'
+           sessionid='deletelog:20080610T2112Z'
+           status='executing'>
+    <x xmlns='jabber:x:data' type='form'>
+      <title>Deleting a Log</title>
+      <instructions>Fill out this form to delete logs.</instructions>
+      <field type='hidden' var='FORM_TYPE'>
+        <value>http://jabber.org/protocol/admin</value>
+      </field>
+      <field label='Log(s) to remove'
+             type='list-multi'
+             var='logs'>
+        <option label='2008-06-10'><value>2008-06-10</value></option>
+        <option label='2008-06-09'><value>2008-06-09</value></option>
+        <option label='2008-06-08'><value>2008-06-08</value></option>
+        <option label='2008-06-07'><value>2008-06-07</value></option>
+        <option label='2008-06-06'><value>2008-06-06</value></option>
+        <option label='2008-06-05'><value>2008-06-05</value></option>
+        <option label='2008-06-04'><value>2008-06-04</value></option>
+        <option label='2008-06-03'><value>2008-06-03</value></option>
+      </field>
+    </x>
+  </command>
+</iq>
+    ]]></example>
+    <example caption='Admin Submits Log Deletion Form to Service'><![CDATA[
+<iq from='bard@shakespeare.lit/globe'
+    id='deletelog-2'
+    to='chat.shakespeare.lit'
+    type='set'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           node='http://jabber.org/protocol/admin#deletelog'
+           sessionid='deletelog:20080610T2112Z'>
+    <x xmlns='jabber:x:data' type='submit'>
+      <field type='hidden' var='FORM_TYPE'>
+        <value>http://jabber.org/protocol/admin</value>
+      </field>
+      <field var='logs'>
+        <value>20080610</value>
+      </field>
+    </x>
+  </command>
+</iq>
+    ]]></example>
+    <example caption='Service Informs Admin of Completion'><![CDATA[
+<iq from='chat.shakespeare.lit'
+    id='deletelog-2'
+    to='bard@shakespeare.lit/globe'
+    type='result'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           node='http://jabber.org/protocol/admin#deletelog'
+           sessionid='deletelog:20080610T2112Z'
+           status='completed'/>
+</iq>
+    ]]></example>
+  </section2>
+  <section2 topic='Empty Cache' anchor='emptycache'>
+    <p>A service may allow an administrator to empty cached information related to a service (e.g., the history of a chat room). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#emptycache".</p>
+    <p>A sample protocol flow for this use case is shown below.</p>
+    <example caption='Admin Requests Emptying the Cache'><![CDATA[
+<iq from='bard@shakespeare.lit/globe'
+    id='emptycache-1'
+    to='someroom@chat.shakespeare.lit'
+    type='set'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           action='execute'
+           node='http://jabber.org/protocol/admin#deletelog'/>
+</iq>
+    ]]></example>
+    <p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
+    <example caption='Service Returns Empty Cache Form to Admin'><![CDATA[
+<iq from='chat.shakespeare.lit'
+    id='emptycache-1'
+    to='bard@shakespeare.lit/globe'
+    type='result'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           node='http://jabber.org/protocol/admin#emptycache'
+           sessionid='emptycache:20080610T2247Z'
+           status='executing'>
+    <x xmlns='jabber:x:data' type='form'>
+      <title>Emptying the Cache</title>
+      <instructions>Fill out this form to empty the cache.</instructions>
+      <field type='hidden' var='FORM_TYPE'>
+        <value>http://jabber.org/protocol/admin</value>
+      </field>
+      <field label='Cache to empty'
+             type='list-multi'
+             var='cache'>
+        <option label='someroom'><value>someroom</value></option>
+        <option label='anotherroom'><value>anotherroom</value></option>
+      </field>
+    </x>
+  </command>
+</iq>
+    ]]></example>
+    <example caption='Admin Submits Empty Cache Form to Service'><![CDATA[
+<iq from='bard@shakespeare.lit/globe'
+    id='emptycache-2'
+    to='chat.shakespeare.lit'
+    type='set'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           node='http://jabber.org/protocol/admin#emptycache'
+           sessionid='emptycache:20080610T2247Z'>
+    <x xmlns='jabber:x:data' type='submit'>
+      <field type='hidden' var='FORM_TYPE'>
+        <value>http://jabber.org/protocol/admin</value>
+      </field>
+      <field var='cache'>
+        <value>someroom</value>
+      </field>
+    </x>
+  </command>
+</iq>
+    ]]></example>
+    <example caption='Service Informs Admin of Completion'><![CDATA[
+<iq from='chat.shakespeare.lit'
+    id='emptycache-2'
+    to='bard@shakespeare.lit/globe'
+    type='result'
+    xml:lang='en'>
+  <command xmlns='http://jabber.org/protocol/commands' 
+           node='http://jabber.org/protocol/admin#deletelog'
+           sessionid='emptycache:20080610T2247Z'
+           status='completed'/>
 </iq>
     ]]></example>
   </section2>
@@ -2527,7 +2687,7 @@
       <td>The ad-hoc commands protocol is not supported.</td>
     </tr>
   </table>
-  <p>For the syntax of these errors, see &xep0086;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).</p> 
+  <p>For the syntax of these errors, see &xmppcore;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).</p> 
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
   <p>The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.</p>
@@ -2595,6 +2755,9 @@
   <field var='loginsperminute'
          type='text-single'
          label='The number of logins per minute for an account'/>
+  <field var='logs'
+         type='list-multi'
+         label='Particular logs to manage'/>
   <field var='max_items'
          type='list-single'
          label='The maximum number of items associated with a search or list'/>