xeps/xep-0249.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>Direct MUC Invitations</title>
  <abstract>This specification defines a method for inviting a contact to a multi-user chat room directly, instead of sending the invitation through the chat room.</abstract>
  &LEGALNOTICE;
  <number>0249</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0045</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>x-conference</shortname>
  &stpeter;
  <revision>
    <version>0.2</version>
    <date>2009-03-30</date>
    <initials>psa</initials>
    <remark><p>Added optional reason attribute for feature parity with XEP-0045.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2008-09-03</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.5</version>
    <date>2008-09-02</date>
    <initials>psa</initials>
    <remark><p>Modified to use old jabber:x:conference namespace.</p></remark>
  </revision>
  <revision>
    <version>0.0.4</version>
    <date>2008-08-18</date>
    <initials>psa</initials>
    <remark><p>Added note about handling multiple invitations.</p></remark>
  </revision>
  <revision>
    <version>0.0.3</version>
    <date>2008-08-16</date>
    <initials>psa</initials>
    <remark><p>Added implementation note about members-only rooms.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2008-08-14</date>
    <initials>psa</initials>
    <remark><p>Changed venue element to conference element.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2008-08-12</date>
    <initials>psa</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>&xep0045; defines a protocol for groupchat over XMPP. That specification includes a method for inviting a contact to a room, where the invitation is mediated by the room itself: the user sends the invitation to the room, which in turn sends it to the contact. Unfortunately, a mediated invitation might not be delivered to the contact, for example if the contact blocks communication with entities not in its roster as specified in &xep0016;. As privacy lists have become more common, MUC invitations have been increasingly blocked at the server side, resulting in an undesirable user experience. Therefore, this specification defines a method for sending an invitation directly from the user to the contact, which re-uses the original 'jabber:x:conference' namespace in use before XEP-0045 was written (with the addition of a 'reason' attribute for the sake of feature parity with XEP-0045).</p> 
</section1>

<section1 topic='How It Works' anchor='howitworks'>
  <p>A user invites a contact to a room by sending a &MESSAGE; stanza containing only an &lt;invitation/&gt; element qualified by the 'jabber:x:conference' namespace.</p>
  <example caption="A direct invitation"><![CDATA[
<message
    from='crone1@shakespeare.lit/desktop'
    to='hecate@shakespeare.lit'>
  <x xmlns='jabber:x:conference'
     jid='darkcave@macbeth.shakespeare.lit'
     reason='Hey Hecate, this is the place for all good witches!'/>
</message>
  ]]></example>
  <p>The 'jid' attribute, which is REQUIRED, specifies the address of the groupchat room.</p>
  <p>The 'reason' attribute, which is OPTIONAL, specifies a human-readable purpose for the invitation.</p>
  <p>Upon receiving a direct invitation, the contact's client SHOULD present the invitation to the contact so that the contact can accept it or decline it. If the contact accepts the invitation, the contact's client shall join the room as described in <cite>XEP-0045</cite>. If the contact declines the invitation, it shall silently discard the invitation.</p>
</section1>

<section1 topic='Determining Support' anchor='support'>
  <p>If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "jabber:x:conference" in response to &xep0030; information requests &NSNOTE;.</p>
  <example caption="Service discovery information request"><![CDATA[
<iq from='crone1@shakespeare.lit/desktop'
    id='disco1'
    to='hecate@shakespeare.lit/broom'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  ]]></example>
  <example caption="Service discovery information response"><![CDATA[
<iq from='hecate@shakespeare.lit/broom'
    id='disco1'
    to='crone1@shakespeare.lit/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='jabber:x:conference'/>
  </query>
</iq>
  ]]></example>
  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>

<section1 topic='Implementation Notes' anchor='impl'>
  <p>Before inviting a contact to a members-only room, a user SHOULD check to see if the contact is already a member and, if not, add the contact to the member list (or ask a room administrator to do so).</p>
  <p>If a client receives multiple invitations to the same room (e.g., a mediated invitation as defined in <cite>XEP-0045</cite> and a direct invitation as defined here), the client SHOULD present only one of the invitations to a human user. If a client receives an invitation to a room in which the user is already an occupant, the client SHOULD silently discard the invitation.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>There are no known security concerns related to this protocol.</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='ns'>
    <p>Upon advancement of this specification to a status of Draft, the &REGISTRAR; shall add 'jabber:x:conference' to its registry of protocol namespaces at &NAMESPACES;.</p>
  </section2>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='jabber:x:conference'
    xmlns='jabber:x:conference'
    elementFormDefault='qualified'>

  <xs:element name='x'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute
              name='jid'
              type='xs:string'
              use='required'/>
          <xs:attribute
              name='reason'
              type='xs:string'
              use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

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

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

<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Joe Hildebrand for his feedback.</p>
</section1>
</xep>