mirror of https://github.com/moparisthebest/xeps
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.
744 lines
26 KiB
744 lines
26 KiB
<?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>
|
|
|