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.
224 lines
8.2 KiB
224 lines
8.2 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>Reminders</title> |
|
<abstract>This specification provides a way to set up reminders.</abstract> |
|
&LEGALNOTICE; |
|
<number>0435</number> |
|
<status>Deferred</status> |
|
<type>Standards Track</type> |
|
<sig>Standards</sig> |
|
<approver>Council</approver> |
|
<dependencies> |
|
<spec>XMPP Core</spec> |
|
<spec>XEP-0082</spec> |
|
</dependencies> |
|
<supersedes/> |
|
<supersededby/> |
|
<shortname>NOT_YET_ASSIGNED</shortname> |
|
<author> |
|
<firstname>Marcos</firstname> |
|
<surname>De Vera Piquero</surname> |
|
<email>marcos@tenak.net</email> |
|
<jid>marcos@tenak.net</jid> |
|
</author> |
|
<revision> |
|
<version>0.1.0</version> |
|
<date>2020-03-31</date> |
|
<initials>XEP Editor (jsc)</initials> |
|
<remark>Accepted by vote of Council on 2020-03-04.</remark> |
|
</revision> |
|
<revision> |
|
<version>0.0.1</version> |
|
<date>2020-02-17</date> |
|
<initials>mdvp</initials> |
|
<remark><p>Initial version</p></remark> |
|
</revision> |
|
</header> |
|
<section1 topic='Introduction' anchor='intro'> |
|
<p>It is sometimes useful, while reading some conversations, to be |
|
reminded about it at some point in the future. This specification |
|
proposes a mechanism to allow clients to set up such reminders.</p> |
|
</section1> |
|
<!-- <section1 topic='Requirements' anchor='reqs'> --> |
|
<!-- <p>STRONGLY RECOMMENDED.</p> --> |
|
<!-- </section1> --> |
|
<section1 topic='Glossary' anchor='glossary'> |
|
<dl> |
|
<di> |
|
<dt>Reminder</dt> |
|
<dd> |
|
An automatically generated message addressed to an entity sent |
|
at a given time. Its goal is to remind the creating entity |
|
about something. |
|
</dd> |
|
</di> |
|
</dl> |
|
</section1> |
|
<section1 topic='Requirements' anchor='requirements'> |
|
<p>This protocol requires handling of dates and times, as such it conforms to &xep0082;.</p> |
|
</section1> |
|
<section1 topic='Discovering support' anchor='disco'> |
|
<p>An entity may wish to discover if a service supports the Reminders feature; in order to do so, it sends a service discovery information query to the server..</p> |
|
<example caption='Client requests information about a server'><![CDATA[ |
|
<iq from='juliet@capulet.net/balcony' |
|
id='disco1' |
|
to='capulet.net' |
|
type='get'> |
|
<query xmlns='http://jabber.org/protocol/disco#info'/> |
|
</iq>]]></example> |
|
<p>If the server supports the Reminders feature, it MUST specify the |
|
'urn:xmpp:reminders:0' feature in its service discovery information |
|
features as specified in &xep0030;</p> |
|
<example caption='Server advertises support for reminders'><![CDATA[ |
|
<iq to='juliet@capulet.net/balcony' id='disco1' from='capulet.net' |
|
type='result'> |
|
<query xmlns='http://jabber.org/protocol/disco#info'> |
|
… |
|
<feature var='urn:xmpp:reminders:0'/> |
|
… |
|
</query> |
|
</iq>]]></example> |
|
</section1> |
|
<section1 topic='Use Cases' anchor='usecases'> |
|
<p>For end users, this provides a way to be reminded about stuff |
|
while being in a conversation, without the need to leave it and go |
|
to some calendar application or similar and create a full event |
|
there. By setting a reminder, a user will be notified by the server |
|
at whatever given time the reminder is created with and with |
|
whatever the description was set for such a reminder.</p> |
|
<section2 topic='Creating a reminder' anchor='creating'> |
|
<p>A user wants to create a new reminder. For creating a |
|
reminder, an entity MUST send an IQ stanza with the 'type' |
|
attribute with a value of "set" and a direct <reminder/> |
|
child qualified by the "urn:xmpp:reminders:0" namespace.</p> |
|
<example caption='User creates a new reminder'><![CDATA[ |
|
<iq from='juliet@capulet.net/balcony' |
|
to='capulet.net' |
|
id='abc123' |
|
type='set'> |
|
<reminder xmlns='urn:xmpp:reminders:0'> |
|
<date>2020-02-19T23:41:00Z</date> |
|
<text xml:lang='en'>Please go sleep before it's too late</text> |
|
</reminder> |
|
</iq>]]> </example> |
|
<example caption='Server acknowledges the reminder creation'><![CDATA[ |
|
<iq id='abc123' |
|
to='juliet@capulet.net/balcony' |
|
from='capulet.net' |
|
type='result'> |
|
<reminder xmlns='urn:xmpp:reminders:0' id='d414cec2-5369-11ea-9455-8b8d265047d9'> |
|
<date>2020-02-19T23:41:00Z</date> |
|
<text xml:lang='en'>Please go sleep before it's too late</text> |
|
</reminder> |
|
</iq>]]></example> |
|
<p>Whenever the reminder's data sent by a client is not complete or |
|
in an invalid format, the server MUST send an error stanza of type |
|
'modify' and a 'bad-request' condition.</p> |
|
<example caption='Server sends a bad-request error response'><![CDATA[ |
|
<iq id='bad1' |
|
to='capulet.net' |
|
from='juliet@capulet.net/balcony' |
|
type='set'> |
|
<reminder xmlns='urn:xmpp:reminders:0'> |
|
<date>Tomorrow at noon</date> |
|
<text xml:lang='en'>Lunch at Romeo's</text> |
|
</reminder> |
|
</iq> |
|
|
|
<iq id='bad1' |
|
to='juliet@capulet.net/balcony' |
|
from='capulet.net' |
|
type='error'> |
|
<error type='modify'> |
|
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> |
|
</error> |
|
</iq>]]></example> |
|
<p>In the event of a client trying to set a reminder in the |
|
past, the server MUST send an error stanza of type 'modify' and |
|
a 'gone' condition.</p> |
|
<example caption='Server sends a gone error response'><![CDATA[ |
|
<iq id='bad2' |
|
to='capulet.net' |
|
from='juliet@capulet.net/balcony' |
|
type='set'> |
|
<reminder xmlns='urn:xmpp:reminders:0'> |
|
<date>2000-01-01T00:00:00Z</date> |
|
<text xml:lang='en'>New Year's party</text> |
|
</reminder> |
|
</iq> |
|
|
|
<iq id='bad2' |
|
to='juliet@capulet.net/balcony' |
|
from='capulet.net' |
|
type='error'> |
|
<error type='modify'> |
|
<gone xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> |
|
</error> |
|
</iq>]]></example> |
|
</section2> |
|
<section2 topic='Server sends a reminder' anchor='send'> |
|
<p>Whenever the time for a reminder arrives, the server MUST send |
|
a message with the reminder to the creating entity.</p> |
|
<example caption='Server sends a reminder'><![CDATA[ |
|
<message from='capulet.net' to='juliet@capulet.net/balcony' id='reminder1'> |
|
<reminder xmlns='urn:xmpp:reminders:0' id='d414cec2-5369-11ea-9455-8b8d265047d9'> |
|
<date timezone='UTC'>2020-02-19T23:41:00Z</date> |
|
<text xml:lang='en'>Please go sleep before it's too late</text> |
|
</reminder> |
|
</message>]]></example> |
|
<p>After sending a reminder, the server MAY choose to delete it |
|
from its storage.</p> |
|
</section2> |
|
<section2 topic='Client cancels a reminder' anchor='cancel'> |
|
<p>There may be the case where a user wants to cancel an already |
|
set reminder. To do so, the client MUST send an IQ stanza of |
|
type 'set' with a 'reminder' child containing the 'id' attribute |
|
of the reminder to be deleted, without any additional child.</p> |
|
<example caption='Client deletes a reminder'><![CDATA[ |
|
<iq id='abc2' |
|
from='juliet@capulet.net/balcony' |
|
to='capulet.net' |
|
type='set'> |
|
<reminder xmlns='urn:xmpp:reminders:0' id='d414cec2-5369-11ea-9455-8b8d265047d9'/> |
|
</iq>]]></example> |
|
<example caption='Server acknowledges a reminder deletion'><![CDATA[ |
|
<iq id='abc2' |
|
to='juliet@capulet.net/balcony' |
|
from='capulet.net' |
|
type='result'> |
|
<reminder xmlns='urn:xmpp:reminders:0' id='d414cec2-5369-11ea-9455-8b8d265047d9'/> |
|
</iq>]]></example> |
|
</section2> |
|
</section1> |
|
<section1 topic='Internationalization Considerations' anchor='i18n'> |
|
<p>As stated in the requirements, the 'date' element MUST contain |
|
a valid &xep0082; DateTime value.</p> |
|
</section1> |
|
<section1 topic='Security Considerations' anchor='security'> |
|
<p>This document introduces no additional security considerations |
|
above and beyond those defined in the documents on which it |
|
depends.</p> |
|
</section1> |
|
<section1 topic='IANA Considerations' anchor='iana'> |
|
<p>No interaction with &IANA; is required as a result of this document.</p> |
|
</section1> |
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'> |
|
<p>This specification defines the following XML namespace:</p> |
|
<ul> |
|
<li>urn:xmpp:reminders:0</li> |
|
</ul> |
|
<p>Upon advancement of this specification from a status of |
|
Experimental to a status of Draft, the ®ISTRAR; shall add the |
|
foregoing namespace to the registry located at &NAMESPACES;, as |
|
described in Section 4 of &xep0053;.</p> |
|
</section1> |
|
<section1 topic='XML Schema' anchor='schema'> |
|
<p>TODO</p> |
|
</section1> |
|
</xep>
|
|
|