mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-13 21:05:09 -05:00
745 lines
26 KiB
XML
745 lines
26 KiB
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>Obsolete</status>
|
|
<type>Informational</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XEP-0050</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>rc</shortname>
|
|
&remko;
|
|
&stpeter;
|
|
<revision>
|
|
<version>1.1</version>
|
|
<date>2017-11-07</date>
|
|
<initials>XEP Editor (ssw)</initials>
|
|
<remark><p>Per a vote of the XMPP Council, advanced to Obsolete.</p></remark>
|
|
</revision>
|
|
<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>
|
|
<p>
|
|
For example, suppose Romeo sends a message to Juliet, thinking she is
|
|
still on her balcony.
|
|
The balcony client receives the message:
|
|
</p>
|
|
<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>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<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>
|
|
<p>
|
|
The client forwards all unread messages to the local client, adding
|
|
information about the origin of the message (using the 'ofrom' &xep0033;
|
|
address, and the &xep0203; timestamp of the original message).
|
|
The chamber client receives both these messages and a confirmation that
|
|
the command was completed.
|
|
</p>
|
|
<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>
|
|
<delay xmlns='urn:xmpp:delay'
|
|
from='juliet@capulet.com/balcony'
|
|
stamp='2002-09-10T23:41:07Z'/>
|
|
</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>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</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>
|
|
<p>
|
|
The remote client accepts the selected file transfers, 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='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>
|