moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-30 21:22:15 -05:00
Code Issues Releases Wiki Activity
8e437965bd
xeps/xep-0146.xml

741 lines
26 KiB
XML
Raw Normal View History

Initial revision git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2 4b5297f7-1745-476d-ba37-a9c6900126ab
2006-10-02 18:22:13 -04:00
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
<!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
<title>Remote Controlling Clients</title>
<abstract>This JEP specifies recommended best practices for remote controlling clients using Ad-Hoc Commands.</abstract>
&LEGALNOTICE;
<number>0146</number>
<status>Active</status>
<type>Informational</type>
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0050</spec>
</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
<shortname>rc</shortname>
<author>
<firstname>Remko</firstname>
<surname>Tron&#231;on</surname>
<email>remko@el-tramo.be</email>
<jid>remko@fab4.be</jid>
</author>
&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 JEP-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 JEP describes a protocol to perform a set of common tasks on a
remote client, by specifying a profile of &jep0050;.
</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This JEP 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
&jep0030; (as described in <strong>JEP-0050: Ad-Hoc Commands</strong>).
&jep0115; can be used to query capability of remote controlling commands
in a client.
</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>This JEP defines a profile of <strong>JEP-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 JEP 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>JEP-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'
&jep0033; 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 &jep0086;. 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 JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
<p>The Jabber 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>&jep0068; 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>JEP-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>JEP-0050: Ad-Hoc Commands</strong>, no schema definition is needed.</p>
</section1>
</jep>
Reference in New Issue Copy Permalink