xeps/xep-0146.xml

<?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 Controlling Clients</title>
    <abstract>This document specifies recommended best practices for remote controlling clients using Ad-Hoc Commands.</abstract>
    &LEGALNOTICE;
    <number>0146</number>
    <status>Active</status>
    <type>Informational</type>
    <sig>Standards</sig>
    <dependencies>
      <spec>XMPP Core</spec>
      <spec>XEP-0050</spec>
    </dependencies>
    <supersedes>None</supersedes>
    <supersededby>None</supersededby>
    <shortname>rc</shortname>
    &remko;
    &stpeter;
    <revision>
      <version>1.0</version>
      <date>2006-03-23</date>
      <initials>psa</initials>
      <remark><p>Per a vote of the Jabber Council, advanced to Active.</p></remark>
    </revision>
	<revision>
		<version>0.3</version>
		<date>2006-01-25</date>
		<initials>rt</initials>
		<remark>Using XEP-0033 (Extended Stanza Addressing) for Forwarding 
		use case.</remark>
	</revision>
	<revision>
		<version>0.2</version>
		<date>2005-03-16</date>
		<initials>rt</initials>
		<remark>Minor modifications; completed Set Options use case; completed Leave Groupchats use case.</remark>
	</revision>
    <revision>
        <version>0.1</version>
        <date>2004-11-12</date>
        <initials>rt</initials>
        <remark>Initial version.</remark>
    </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
    <p>
    When one has multiple clients at different locations logged in 
    simultaneously, it is often desirable to control these clients from 
    the client you are currently using. There are a number of common tasks
    one might want to perform remotely on clients: change the status of the
    client, forward all received unread messages to this client, and so on.
    Therefore, it makes sense to define a protocol for performing these tasks.
    </p>
    
    <p>
    This document describes a protocol to perform a set of common tasks on a
    remote client, by specifying a profile of &xep0050;.
    </p>
</section1>


<section1 topic='Requirements' anchor='reqs'>
    <p>This document addresses the following requirements:</p>
    <ul>
        <li>Enable users to perform a set of common tasks on a remote 
            client.</li>
        <li>Re-use existing XMPP and Jabber protocols wherever possible.</li>
    </ul>
</section1>


<section1 topic='Discovery' anchor='disco'>
    <p>A client MUST advertise any remote controlling commands it supports via 
    &xep0030; (as described in <strong>XEP-0050: Ad-Hoc Commands</strong>).
    &xep0115; can be used to query capability of remote controlling commands
    in a client.
    </p>
</section1>


<section1 topic='Use Cases' anchor='usecases'>
    <p>This document defines a profile of <strong>XEP-0050: Ad-Hoc Commands</strong>
    that enables a user to perform the following tasks on a remote client:</p>
    <ol>
        <li>Change status</li>
        <li>Forward unread messages residing at the remote client to the
        local client</li>
        <li>Change run-time options</li>
        <li>Accept pending file transfer requests</li>
        <li>Leave groupchats</li>
    </ol>
	<p>
	Although this document aims to define common use cases for remote controlling clients,
	an implementation or deployment MAY support any subset and MAY support additional
	commands not defined herein.
	</p>
    <p><em>Note: The text that follows assumes that implementors have read and understood <strong>XEP-0050: Ad-Hoc Commands</strong></em>.</p>


    <section2 topic='Change Status' anchor='set-status'>
        <p>It is common to forget changing the status of a resource when leaving the
		client for a longer period. When realizing this while at another location, it 
		might be desirable to change the status from there, to avoid contacts 
		thinking that resource is attended and sending it messages.</p>
		<example caption='Local Client Requests to Set the Status of a Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-status-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/rc#set-status'/>
</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='Remote Client Replies with a Form to Set its Status'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='set-status-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
             node='http://jabber.org/protocol/rc#set-status'
             sessionid='set-status:20040727T0337Z'
             status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Change Status</title>
      <instructions>Choose the status and status message</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field label='Status' 
             type='list-single' 
             var='status'>
        <required/>
        <value>online</value>
        <option label='Chat'> 
            <value>chat</value>
        </option>
        <option label='Online'> 
            <value>online</value>
        </option>
        <option label='Away'> 
            <value>away</value>
        </option>
        <option label='Extended Away'> 
            <value>xa</value>
        </option>
        <option label='Do Not Disturb'> 
            <value>dnd</value>
        </option>
        <option label='Invisible'> 
            <value>invisible</value>
        </option>
        <option label='Offline'> 
            <value>offline</value>
        </option>
      </field>
      <field label='Priority'
             type='text-single'
             var='status-priority'>
        <value>5</value> 
      </field>
      <field label='Message' 
             type='text-multi' 
             var='status-message'/>
    </x>
  </command>
</iq>
        ]]></example>
        <example caption='Local Client Submits Set Status Form to Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-status-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/rc#set-status'
           sessionid='set-status:20040727T0337Z'>
    <x xmlns='jabber:x:data' type='form'>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field type='list-single' var='status'>
        <value>xa</value>
      </field>
      <field type='text-single' var='status-priority'>
        <value>-1</value>
      </field>
      <field type='text-multi' var='status-message'>
        <value>In my chamber.</value>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <p>If the 'status-priority' variable is omitted, the client SHOULD NOT
        change the priority of the client</p>
        <example caption='Remote Client Informs Local Client of Completion'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='set-status-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/rc#set-status'
           sessionid='set-status:20040727T0337Z'
           status='completed'/>
</iq>
        ]]></example>
        <p>Notification of completion MAY include the processed data in a data 
        form of type 'result'.</p>
    </section2>


    <section2 topic='Forward Unread Messages Residing at a Remote Client' anchor='forward'>
        <p>A user might want to forward all the unread messages residing at
        the remote client to the local client (e.g. when the remote client was
        accidentally left on-line, and has received messages in the meantime).</p>
        
        For example, suppose Romeo sends a message to Juliet, thinking she is
        still on her balcony. The balcony client receives the message:
        <example caption='Remote Client Receives Message'><![CDATA[
<message from='romeo@example.com/orchard' 
         to='juliet@example.com/balcony'>
  <subject>Just saying hi</subject>
  <body>Hello Juliet!</body>
</message>
        ]]></example>

        However, Juliet is in her chamber, so she doesn't know about the message
        (yet). Realizing she left her balcony client unattended, she sends a 
        request to the remote client to forward all unread messages.

        <example caption='Local Client Requests to Forward Unread Messages Currently Residing at the Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='forward-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/rc#forward'
           sessionid='forward:20040727T0337Z'/>
</iq>
        ]]></example>
        
        The client forwards all unread messages to the local client, adding
        information about the origin of the message (using the 'ofrom' 
		&xep0033; address). 
		The chamber client receives both these messages and a
        confirmation that the command was completed.
        <example caption='Remote Client Forwards All Unread Messages to Local Client'><![CDATA[
<message from='juliet@example.com/balcony' 
         to='juliet@example.com/chamber'>
  <subject>Just saying hi</subject>
  <body>Hello Juliet!</body>
  <addresses xmlns='http://jabber.org/protocol/address'>
    <address type='ofrom' jid='romeo@example.com/orchard'/>
  </addresses>  
</message>
        ]]></example>

        <example caption='Remote Client Informs Local Client of Completion'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='forward-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/rc#forward'
           sessionid='forward:20040727T0337Z'
           status='completed'/>
</iq>
        ]]></example>

		A client MAY provide a more fine-grained implementation, e.g. by
		presenting the requester an extra form to select which messages
		have to be forwarded.
    </section2>


    <section2 topic='Change Run-Time Options'>
        <p>It might be desirable to remotely set some run-time options of
        a client. For example, when neighbours complain about the sounds your 
        client makes while you're at another location, you could turn the 
        sounds off at the remote client.
        </p>
		<example caption='Local Client Requests to Change Options of a Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-options-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/rc#set-options'/>
</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='Remote Client Replies with a Form to Set its Options'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='set-options-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
             node='http://jabber.org/protocol/rc#set-options'
             sessionid='set-options:20040727T0337Z'
             status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Set Options</title>
      <instructions>Set the desired options</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field label='Play sounds' 
             type='boolean' 
             var='sounds'>
        <value>1</value>
      </field>
      <field label='Automatically Go Offline when Idle' 
             type='boolean' 
             var='auto-offline'>
        <value>0</value>
      </field>
      <field label='Automatically Open New Messages' 
             type='boolean' 
             var='auto-msg'>
        <value>0</value>
      </field>
      <field label='Automatically Accept File Transfers' 
             type='boolean' 
             var='auto-files'>
        <value>0</value>
      </field>
      <field label='Automatically Authorize Contacts' 
             type='boolean' 
             var='auto-auth'>
        <value>0</value>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <example caption='Local Client Submits Set Options Form to Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='set-options-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/rc#set-options'
           sessionid='set-options:20040727T0337Z'>
    <x xmlns='jabber:x:data' type='form'>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field type='boolean' var='sounds'>
        <value>0</value>
      </field>
      <field type='boolean' var='auto-offline'>
        <value>0</value>
      </field>
      <field type='boolean' var='auto-msg'>
        <value>0</value>
      </field>
      <field type='boolean' var='auto-files'>
        <value>0</value>
      </field>
      <field type='boolean' var='auto-auth'>
        <value>0</value>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <p>The remote client sets the values of the options to their requested
		value. If a variable is omitted, the client SHOULD NOT change the value of the 
		corresponding option.</p>

        <example caption='Remote Client Informs Local Client of Completion'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='set-options-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/rc#set-options'
           sessionid='set-options:20040727T0337Z'
           status='completed'/>
</iq>
        ]]></example>
        <p>Notification of completion MAY include the processed data in a data 
        form of type 'result'.</p>
    </section2>


	<!-- ************************************************************************ -->

    <section2 topic='Accept Pending File Transfer Requests'>
        <example caption='Local Client Requests to Accept Pending File Transfer Requests on the Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='accept-files-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/rc#accept-files'/>
</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='Remote Client Replies with a Form Containing Pending File Transfers'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='accept-files-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
             node='http://jabber.org/protocol/rc#accept-files'
             sessionid='set-status:20040727T0337Z'
             status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Pending File Transfers</title>
      <instructions>Select the pending file transfers to accept</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field label='Files' 
             type='list-multi' 
             var='files'>
        <required/>
        <option label='ballad.ogg (romeo@example.com)'> 
          <value>romeo@example.com/orchard:1</value>
        </option>
        <option label='picture.jpg (romeo@example.com)'> 
          <value>romeo@example.com/orchard:2</value>
        </option>
        <option label='challenge.txt (mercutio@example.com)'> 
          <value>mercutio@example.com/orchard:1</value>
        </option>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <example caption='Local Client Submits Form to Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='accept-files-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/rc#accept-files'
           sessionid='accept-files:20040727T0337Z'>
    <x xmlns='jabber:x:data' type='form'>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field type='list-multi' var='files'>
        <value>romeo@example.com/orchard:2</value>
      </field>
    </x>
  </command>
</iq>
        ]]></example>

        The remote client accepts the selected file transfers, and informs
        the local client of completion.
        <example caption='Remote Client Informs Local Client of Completion'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='accept-files-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/rc#accept-files'
           sessionid='accept-files:20040727T0337Z'
           status='completed'/>
</iq>
        ]]></example>
    </section2>



    <section2 topic='Leave Groupchats'>
		<example caption='Local Client Requests the Remote Client to Leave Groupchats'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='leave-groupchats-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/rc#leave-groupchats'/>
</iq>
        ]]></example>
        <example caption='Remote Client Replies with a Form with a List of Groupchats it is currently in'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='leave-groupchats-1'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
             node='http://jabber.org/protocol/rc#leave-groupchats'
             sessionid='leave-groupchats:20040727T0337Z'
             status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Leave Groupchats</title>
      <instructions>Choose the groupchats you want to leave</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field label='Groupchats' 
             type='list-multi' 
             var='groupchats'>
        <required/>
        <option label='juliet on jdev@conference.jabber.org'> 
            <value>jdev@conference.jabber.org/juliet</value>
        </option>
        <option label='juliette on jdev@conference.jabber.org'> 
            <value>jdev@conference.jabber.org/juliette</value>
        </option>
        <option label='juliet on girlsonly@jabber.com'> 
            <value>girlsonly@jabber.com/juliet</value>
        </option>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
        <example caption='Local Client Submits Form to Remote Client'><![CDATA[
<iq from='juliet@example.com/chamber'
    to='juliet@example.com/balcony'
    type='set'
    id='leave-groupchats-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/rc#leave-groupchats'
           sessionid='leave-groupchats:20040727T0337Z'>
    <x xmlns='jabber:x:data' type='form'>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/rc</value>
      </field>
      <field type='list-multi' var='groupchats'>
        <value>jdev@conference.jabber.org/juliet</value>
        <value>girlsonly@jabber.com/juliet</value>
      </field>
    </x>
  </command>
</iq>
        ]]></example>
		<p>The remote client leaves the requested groupchats, and informs the
		local client of completion.</p>
        <example caption='Remote Client Informs Local Client of Completion'><![CDATA[
<iq from='juliet@example.com/balcony' 
    to='juliet@example.com/chamber' 
    type='result' 
    id='leave-groupchats-2'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='http://jabber.org/protocol/rc#leave-groupchats'
           sessionid='leave-groupchats:20040727T0337Z'
           status='completed'/>
</iq>
        ]]></example>
    </section2>
</section1>

  
<section1 topic='Error Handling' anchor='errors'> 
    <p>Several error conditions are possible when an entity sends a command
    request to the service, as defined in the following table. If one of these
    errors occurs, the service MUST return an error stanza to the requesting
    entity.</p>

    <table caption='Error Conditions'>
        <tr>
            <th>Condition</th>
            <th>Cause</th>
        </tr>
        <!--<tr>
            <td>&conflict;</td>
            <td>The command cannot be completed because of a data or system
            conflict (e.g., ...)</td>
            </tr>-->
        <tr>
            <td>&feature;</td>
            <td>The specific command is not supported (even though the ad-hoc
            commands protocol is)</td>
        </tr>
        <tr>
            <td>&forbidden;</td>
            <td>The requesting entity does not have sufficient privileges to 
            perform the command</td>
        </tr>
        <tr>
            <td>&unavailable;</td>
            <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.</p>
</section1>


<section1 topic='Implementation Notes' anchor='implementation'> 
    <p>Implementations of this protocol MAY add or remove fields to forms as
    they see fit.  For example, when setting the status of a remote client that
    supports multiple accounts, the client may choose to add a boolean field 
    to allow the user to specify whether the status change should be applied
    globally or only to the receiving account.</p>

    <p> Implementations MAY also introduce extra forms for commands. For example,
    when forwarding unread messages, a client could return a form containing a 
    list 
    of short descriptions of unread messages, allowing the user to select the
    messages he wants to forward.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
      <p>The ability to complete the tasks specified herein MUST NOT be granted
      to users who lack privileges to control a client. A sensible 
      access policy is to only allow remote controlling by other 
      resources of the same account used by the client. If other accounts
      are to be able to remote control the client, the client needs more 
      complex access right management.</p>
</section1>


<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>


<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
    
    <section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
        <p>The XMPP Registrar includes 'http://jabber.org/protocol/rc' in its registry
        of protocol namespaces (see &NAMESPACES;).</p>
    </section2>

    <section2 topic='Field Standardization' anchor='registrar-formtype'>
        <p>&xep0068; defines a process for standardizing the fields used within
        Data Forms scoped by a particular namespace (see also &FORMTYPES;). 
        The reserved fields for the 'http://jabber.org/protocol/rc' namespace 
        are specified below.</p>
        <code caption='Registry Submission'><![CDATA[
<form_type>
  <name>http://jabber.org/protocol/rc</name>
  <doc>XEP-0146</doc>
  <desc>Forms used for remote controlling clients</desc>
  <field var='auto-auth'
         type='boolean'
         label='Whether to automatically authorize subscription requests'/>
  <field var='auto-files'
         type='boolean'
         label='Whether to automatically accept file transfers'/>
  <field var='auto-msg'
         type='boolean'
         label='Whether to automatically open new messages'/>
  <field var='auto-offline'
         type='boolean'
         label='Whether to automatically go offline when idle'/>
  <field var='sounds'
         type='boolean'
         label='Whether to play sounds'/>
  <field var='files'
         type='list-multi'
         label='A list of pending file transfers'/>
  <field var='groupchats'
         type='list-multi'
         label='A list of joined groupchat rooms'/>
  <field var='status'
         type='list-single'
         label='A presence or availability status'>
    <option label='Chat'> 
        <value>chat</value>
    </option>
    <option label='Online'> 
        <value>online</value>
    </option>
    <option label='Away'> 
        <value>away</value>
    </option>
    <option label='Extended Away'> 
        <value>xa</value>
    </option>
    <option label='Do Not Disturb'> 
        <value>dnd</value>
    </option>
    <option label='Invisible'> 
        <value>invisible</value>
    </option>
    <option label='Offline'> 
        <value>offline</value>
    </option>
  </field>
  <field var='status-message'
         type='text-multi'
         label='The status message text'/>
  <field var='status-priority'
         type='text-single'
         label='The new priority for the client'/>
</form_type>
    ]]></code>
  </section2>
</section1>


<section1 topic='XML Schema'>
    <p>Because the protocol defined here is a profile of <strong>XEP-0050: Ad-Hoc Commands</strong>, no schema definition is needed.</p>
</section1>

</xep>