moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

Channel Invitations

This commit is contained in:
Steve Kille 2016-10-05 15:34:40 +01:00
parent e9790010ee
commit 8f933bc919
1 changed files with 103 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
xep-0369.xml
View File

@ -480,7 +480,7 @@
<li>'JID Visibility'. Choice of "jid-hidden", "jid-optionally-visible", "jid-mandatory-visible". </li>
<li>'Open Presence'. If selected, any client may register presence. If not selected, only clients with bare JID in the participants list may register presence.</li>
<li>'Allow Message Retraction'. If this option is selected users will be able to retract messages sent to the MIX channel.</li>
<li>'Participation Extension by Invitation'. This option extends a channel so that an invitation from a channel participant will add the invited user to the allowed list.
<li>'Participation Addition by Invitation from Participant'. This option extends a channel so that a channel participant has rights to invite and enable other users as participants.
</li>
<li>'No Private Messages'. If this option is selected, private messages may not be used with the channel.</li>
@ -1293,50 +1293,117 @@ the participant is not be subscribed to all nodes associated with the channel (i
</p>
</section3>
<section3 topic='Telling another user about a Channel' anchor='usecase-user-tell'>
<section3 topic='Telling another User about a Channel' anchor='usecase-user-tell'>
<p>
A convenient way to reference another channel is to use &xep0372; which enables the JID of a channel to be shared. This might be used simply to inform the message recipient about the channel or as mechanism to invite the user to join the channel. This is useful as an invitation mechanism to a channel that any user can join or where the invitee knows that the user may join (e.g., because the channel is for all users in an organization).
</p>
</section3>
<section3 topic='Inviting another user to join a Channel' anchor='usecase-user-invite'>
<p>When a channel participant invites another user to join a channel, a sequence of steps are followed.
<section3 topic='Inviting another User to join a Channel that the user does not have Permission to Join' anchor='usecase-user-invite'>
<p> Invitation by reference, as described in the previous section, is a convenient approach to invite a user to join a channel that the user has permission to join. This section describes the approach used when the inviter has permission to grant rights for the invitee to become a channel participant. This might be because the inviter is an administrator of the channel or the channel may have a special mode where channel participants may grant rights for other users to join a channel ('Participation Addition by Invitation from Participant' enabled). This approach is used to avoid cluttering the allowed node with JIDs of users who are invited to join, but do not accept the invitation.
When a channel participant(the inviter) invites another user (the invitee) to join a channel, the following sequence of steps is followed:
</p>
<ol>
<li>The channel participant sends to the channel requesting an invite for the user.</li>
<li>The channel sends an invitation to the user requesting the invite.</li>
<li>The channel participant sends the invitation to the invitee.</li>
<li>The invitee uses the invitation to construct a request to join the channel.</li>
<li>The channel inviter sends to the channel requesting an invite for the invitee.</li>
<li>The channel sends an invitation to the inviter.</li>
<li>The inviter sends the invitation to the invitee.</li>
<li>The invitee MAY use the invitation to join the channel.</li>
<li>The invitee MAY send a response to the inviter, indicating if the invitation was accepted or declined.</li>
</ol>
<p> AUTHOR'S NOTES AND QUESTION: Need to consider including declines. To be expanded considerably and perhaps modified based on the following: Dave Cridland notes:
> There are three actors - the participant (who is the inviter), the Invitee, and
> the Channel.
>
> A) The participant obtains an Invitation (containing a verifiable token) from the
> Channel. This allows the Channel to reject attempts to invite users who
> should not be able to join the channel, but it might provide the token anyway
> to avoid probes discovering who is allowed to join the room. This is your step
> 1.
>
> B) The participant sends this Invitation (including the token) to the Invitee.
> (Step 2)
>
> C) The Invitee can optionally request from the Channel the validity of the
> Invitation. (Not included)
>
> D) The Invitee can use the Invitation. (Step 3)
>
> The idea behind my step C is that it allows a client to validate that the entity
> sending an invitation really is a participant of the channel, and could
> legitimately act as a participant. This could be folded into (D), although it
> depends on whether we want to present the Invitation without knowing its
> validity.
>
> It feels as if an Invitee executing on an Invitation ought to be able to tell if the
> Invitation was genuine or not.
>
. </p>
<p>
The first step is for the inviter to request an invitation from the channel. The invitation contains inviter, invitee and a token. The channel will evaluate if the inviter has rights to issue the invitation. This will be because the inviter is a channel administrator or if the inviter is a channel participant and the channel has 'Participation Addition by Invitation from Participant' mode enable. If the inviter has rights to make the invitation, the channel will return a token. The token is a string that the channel can subsequently use to validate an invitation. The format of the token is not specified in this standard. The encoded token MAY reflect a validity time.
</p>
<example caption='Inviter Requests and Receives Invitation'><![CDATA[
<iq from='hag66@shakespeare.lit/pda'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<query xmlns='urn:xmpp:mix:0#request-invitation'/>
<invitee>cat@shakespeare.lit</invitee>
</iq>
<iq from='coven@mix.shakespeare.lit'
id='kl2fax27'
to='hag66@shakespeare.lit/pda'
type='result'>
<query xmlns='urn:xmpp:mix:0#request-invitation'>
<invitation>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
</iq>
]]></example>
<p>
The inviter can now send the invitee a message containing the invitation, as shown in the following example.
</p>
<example caption='Inviter sends Invitation to Invitee'><![CDATA[
<message from='hag66@shakespeare.lit/pda'
id='foo'
to='cat@shakespeare.lit'>
<body>Would you like to join the coven?<body>
<invitation xmlns='urn:xmpp:mix:0'>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
</iq>
]]></example>
<p>The invitation can now be used by the invitee to join a channel. The invitation is simply added to the standard channel join, so that the channel can validate the invitation using the token. If the allowed node is present and the invitee is not matched against any item, the channel MUST add the invitee to the allowed node as part of the join.</p>
<example caption="User Joins a Channel with an Invitation"><![CDATA[
<iq type='set'
from='cat@shakespeare.example'
to='coven@mix.shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<join xmlns='urn:xmpp:mix:0'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
<invitation>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
</join>
</iq>
]]></example>
<p>The invitee may send an acknowledgement back to the inviter, noting the status of the invitation. Values are:</p>
<ul>
<li>'Joined': The invitee has joined the channel.</li>
<li>'Declined': The invitee is not taking up the invitation.</li>
<li>'Acknowledged': The invitation is acknowledged, without information on action taken or planned.</li>
</ul>
<example caption='Invitee sends Acknowledgement to Inviter'><![CDATA[
<message from='cat@shakespeare.lit/miaow'
id='bar'
to='hag66@shakespeare.lit/pda'>
<body>No Thanks - too busy chasing mice....<body>
<invitation-ack xmlns='urn:xmpp:mix:0'>
<value>Declined</value>
<invitation>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
</invitation-ack>
</iq>
]]></example>
</section3>