<?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>Message Processing Hints</title>
  <abstract>This document defines a way to include hints to entities routing or receiving a message.</abstract>
  &LEGALNOTICE;
  <number>0334</number>
  <status>Proposed</status>
  <lastcall>2017-02-22</lastcall>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>hints</shortname>
  &mwild;
  <revision>
    <version>0.2</version>
    <date>2015-09-01</date>
    <initials>dg</initials>
    <remark>
      <p>Fixed the wrong use of no-storage instead of no-store</p>
      <p>Added a message hint &lt;store/&gt;</p>
    </remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2013-07-11</date>
    <initials>psa</initials>
    <remark><p>Initial published version approved by the XMPP Council.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2013-06-18</date>
    <initials>mw</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>Message types ('normal', 'chat', 'headline', etc.) provide an existing framework for determining how an entity should deliver or handle a message. For example &xmppim; defines that messages of type 'headline' should not be stored offline by the server, and that messages of type 'groupchat' must not be directed to other resources.</p>
  <p>However this framework of rules is quite inflexible, and new extensions are being developed that push at the boundaries of what is capable of. This specification defines a more flexible approach that allows the sender to add finer-grained 'hints' to messages, which can be used as a generic mechanism for XMPP entities to handle messages.</p>
  <p>A similar but much more extensive framework is defined in &xep0079; for applications that need it.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>This specification aims to solve the following common problems, and allow a sender to hint to
    the recipient:</p>
  <ul>
    <li>Whether to store a message (e.g. for archival or as an 'offline message').</li>
    <li>Whether to copy a message to other resources.</li>
    <li>Whether to store a message that would not have been stored under normal conditions</li>
  </ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic="Session-based stanzas" anchor='usecases-session'>
  <p>Suppose that Romeo and Juliet are avoiding the surveillance of Prince Escalus and communicating using a session-based
    encryption protocol between their laptops. In order to prevent Juliet's tablet computer that uses &xep0280; from receiving
    copies of the encrypted messages (and not being able to decrypt them), Romeo inserts the &lt;no-copy/&gt; hint into the
    messages he sends. Since it is also useless for these messages to be archived, he additionally adds the &lt;no-store/&gt;
    hint:</p>
  <example caption='Sending a message with no-copy and no-store hints'><![CDATA[
<message
    from='romeo@montague.lit/laptop'
    to='juliet@capulet.lit/laptop'>
  <body>V unir avtug'f pybnx gb uvqr zr sebz gurve fvtug</body>
  <no-copy xmlns="urn:xmpp:hints"/>
  <no-store xmlns="urn:xmpp:hints"/>
</message>
]]></example>
</section2>
<section2 topic="Notifications" anchor='usecases-notification'>
  <p>Some automated notifications may be transient, and there would be no purpose in delaying their delivery. Such
    messages may be marked with the &lt;no-store/&gt; hint.</p>
</section2>
<section2 topic="Sensitive messages" anchor='usercases-sensitive'>
  <p>A sender may want to indicate their preference to have no permanent record of a message (also known as "off the
    record" messages), but may be happy for it to be stored temporarily as a normal part of delivery (e.g. if the
    recipient is offline at the time of sending). Such a message can be marked with the &lt;no-permanent-store/&gt; hint.
  </p>
</section2>
<section2 topic="Storage-worthy messages" anchor='store-worthy'>
  <p>Offline storage and &xep0313; can define their own rules on what messages to store and usually only store messages that contain a body element. However a sender may want to indicate that a message is worth storeing even though it might not match those rules (e.g. an encrypted message that carries the payload outside the body element). Such a message can be marked with a &lt;store/&gt; hint.</p>
</section2>
</section1>
<section1 topic="Hints" anchor="hints">
  <section2 topic="No permanent store" anchor="no-permanent-store">
    <p>The &lt;no-permanent-store/&gt; hint informs entities that they shouldn't store the message in
      any permanent or semi-permanent public or private archive (such as described in &xep0136; and &xep0313;)
      or in logs (such as chatroom logs).
    </p>
  </section2>
  <section2 topic="No store" anchor="no-store">
    <p>A message containing a &lt;no-store/&gt; hint should not be stored by a server either permanently (as above)
    or temporarily, e.g. for later delivery to an offline client, or to users not currently present in a chatroom.
    </p>
  </section2>
  <section2 topic="No copies" anchor="no-copy">
    <p>Messages with the &lt;no-copy/&gt; hint should not be copied to addresses other than the one to which it is
      addressed, for example through &xep0280;.</p>
    <p>This hint MUST only be included on messages addressed to full JIDs and explicitly does not override the behaviour
      defined in &xmppim; for handling messages to bare JIDs, which may involve copying to multiple resources, or multiple
      occupants in a &xep0045; room.
    </p>
  </section2>
  <section2 topic="Store">
    <p>A message containing the &lt;store/&gt; hint that is not of type 'error' SHOULD be stored by the entity.</p>
  </section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <p>It is important to note that message hints are, as the name implies, just hints. Implementations
    MUST NOT rely on other entities interpretation of the hints for any particular purpose.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>This specification introduces no known security considerations.</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'>
  <p>This document requires no interaction with &REGISTRAR;.</p>
</section1>
<section1 topic='XML Schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:hints'
    xmlns='urn:xmpp:hints'
    elementFormDefault='qualified'>

  <xs:element name='no-permanent-store' type='empty'/>
  <xs:element name='no-store' type='empty'/>
  <xs:element name='no-copy' type='empty'/>
  <xs:element name='store' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
]]></code>
</section1>
</xep>