moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-23 01:32:22 -05:00
Code Issues Releases Wiki Activity

Promote call-invites to 482

Browse Source
This commit is contained in:
Kevin Smith 2023-05-04 14:39:33 +01:00
parent fd1ab2461d
commit 675c73c859
2 changed files with 209 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
xep-0482.xml Normal file
View File

@ -0,0 +1,207 @@
<?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>Call Invites</title>
<abstract>
This document defines how to invite someone to a call and how to respond to the invite.
</abstract>
&LEGALNOTICE;
<number>0482</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies/>
<supersedes/>
<supersededby/>
<shortname>call-invites</shortname>
<author>
<firstname>Natalie</firstname>
<surname>Wirth</surname>
<email>nataliew@laposte.net</email>
</author>
<author>
<firstname>Marvin</firstname>
<surname>Wissfeld</surname>
<email>xsf@larma.de</email>
<jid>jabber@larma.de</jid>
</author>
<revision>
<version>0.1.0</version>
<date>2023-05-04</date>
<initials>XEP Editor: ks</initials>
<remark>
<p>Promoting to Experimental.</p>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2022-01-01</date>
<initials>nw/mw</initials>
<remark>
<p>First draft.</p>
</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>
A call can take place between two or more parties and can be initiated and conducted via various protocols. This
specification defines a way to invite someone to a call providing one or more ways in which to join.
</p>
<p>
&xep0353; provides partially overlapping functionality. It allows to initiate any kind of Jingle session, for
example calls but also file transfers. However, it is not suitable for inviting someone to any kind of call, since
a call can also be established through other means than a simple Jingle session-initiate.
</p>
<p>
This specification defines a way to invite someone to a call. The call can for example be initiated via &xep0167;
or via an external URI. It also allows to define multiple ways to join the same call. Furthermore, it defines how
to retract, accept and reject the call invite and how to indicate that a client left the call.
</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Proposing a call'>
<p>
To invite someone to a call, a message containing an &lt;invite&gt; element in the urn:xmpp:call-invites:0
namespace is sent. The element has an optional 'video' attribute that indicates if the call is intended to be
joined with participants sending video ("true") or not ("false", default). An 'audio' attribute is defined
analogously, defaulting to "true". The &lt;invite&gt; element contains one sub-element for each way to join the
call.
</p>
<p>
In order to invite someone to a &xep0167; call, a &lt;jingle&gt; element is placed in the &lt;invite&gt;
element. The &lt;jingle&gt; element has a 'sid' attribute specifying the ID of the Jingle session. It can
optionally also contain a 'jid' element, to indicate the JID the Jingle session will be initiated from. If no
'jid' element is provided, the default is the sender of the message stanza.
</p>
<example caption="Invite to a Jingle video call"><![CDATA[
<message to='mara@example.com' id='id1' type='chat'>
<invite video='true' xmlns='urn:xmpp:call-invites:0'>
<jingle sid='sid1'/>
</invite>
</message>]]></example>
<p>
External ways to join the call can be specified via an &lt;external&gt; element placed in the &lt;invite&gt;
element with an 'uri' attribute that contains a URI. The URI can for example contain a URL to a browser
webclient or a dial-in telephone number.
</p>
<example caption="Invite to a mixer groupcall with webclient and dial-in fallback"><![CDATA[
<message to='mara@example.com' id='id2' type='chat'>
<invite xmlns='urn:xmpp:call-invites:0'>
<jingle sid='sid2' jid='mixer@example.com/uuid' />
<external uri='https://example.com/uuid' />
<external uri='tel:+12345678' />
</invite>
</message>]]></example>
<p>
Specifications that describe further ways to join a call define their own sub-elements to the &lt;invite&gt;
element containing all necessary information for joining.
</p>
</section2>
<section2 topic='Retracting a call'>
<p>
A call invite can be retracted by sending a message containing a &lt;retract&gt; element with an 'id' attribute
containing the id of the invite message qualified by the urn:xmpp:call-invites:0 namespace.
</p>
<example caption="Retracting a call"><![CDATA[
<message to='mara@example.com' type='chat'>
<retract id='id1' xmlns='urn:xmpp:call-invites:0' />
</message>]]></example>
</section2>
<section2 topic='Accepting a call'>
<p>
A call invite can be accepted by sending a message containing an &lt;accept&gt; element with an 'id' attribute
containing the id of the invite message and qualified by the urn:xmpp:call-invites:0 namespace.
</p>
<p>
The element describing the connection method used by the accepting client (e.g. &lt;jingle&gt; or &lt;external&gt;)
including all of its attributes and children is placed in the &lt;accept&gt; element.
</p>
<example caption="Accepting a call"><![CDATA[
<message to='mara@example.com' type='chat'>
<accept id='id1' xmlns='urn:xmpp:call-invites:0'>
<jingle sid='sid1' jid='mixer@example.com/uuid' />
</accept>
</message>]]></example>
<p>
After the &lt;accept&gt; was sent, the initiating or accepting client continues to establish the call depending
on the selected connection method: If an &lt;external&gt; method was selected, the accepting client handles the
URI. The exact behaviour of opening the URI is implementation specific. If a &lt;jingle&gt; method was selected,
the initiating client triggers a Jingle session-initiate from the JID and with the session ID specified in the
'jid' and 'sid' attributes of the &lt;jingle&gt; element, respectively.
</p>
</section2>
<section2 topic='Rejecting a call'>
<p>
A call invite can be rejected by sending a message containing a &lt;reject&gt; element with an 'id' attribute
containing the id of the invite message and qualified by the urn:xmpp:call-invites:0 namespace.
</p>
<example caption="Rejecting a call"><![CDATA[
<message to='mara@example.com' type='chat'>
<reject id='id1' xmlns='urn:xmpp:call-invites:0' />
</message>]]></example>
</section2>
<section2 topic='Leaving a call'>
<p>
When a client leaves a call, it sends a message containing a &lt;left&gt; element with an 'id' attribute
containing the id of the invite message and qualified by the urn:xmpp:call-invites:0 namespace.
</p>
<example caption="Leaving a call"><![CDATA[
<message to='mara@example.com' type='chat'>
<left id='id1' xmlns='urn:xmpp:call-invites:0' />
</message>]]></example>
</section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<p>
Clients must ensure that they will receive the accept or reject responses of other resources by the same user (if
any) when implementing this specification. This can be achieved by implementing &xep0280;.
</p>
<section2 topic='Using the correct ID' anchor='business-id'>
<p>
For messages of type 'groupchat', the stanza's 'id' attribute MUST NOT be used for call retracts, accepts,
rejects or lefts. Instead, in group chat situations, the ID assigned to the stanza by the group chat itself must
be used. This is discovered in a &lt;stanza-id&gt; element with a 'by' attribute that matches the bare JID of
the group chat, as defined in &xep0359;.
</p>
<p>
This implies that invite messages should only be sent in group chats that attach a &xep0359; stanza-id.
</p>
<p>
For other message types the sender should use the 'id' from a &xep0359;
&lt;origin-id&gt; if present, or the value of the 'id' attribute on the
&lt;message&gt; otherwise.
</p>
</section2>
</section1>
<section1 topic="Security Considerations" anchor="security">
<p>
None.
</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>
</xep>

3
xep.ent
View File

@ -1676,4 +1676,5 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates</link></span> <note>
<!ENTITY xep0478 "<span class='ref'><link url='https://xmpp.org/extensions/xep-0478.html'>Stream Limits Advertisement (XEP-0478)</link></span><note>XEP-0478: Stream Limits Advertisement &lt;<link url='https://xmpp.org/extensions/xep-0478.html'>https://xmpp.org/extensions/xep-0478.html</link>&gt;.</note>">
<!ENTITY xep0479 "<span class='ref'><link url='https://xmpp.org/extensions/xep-0479.html'>XMPP Compliance Suites 2023 (XEP-0479)</link></span><note>XEP-0479: XMPP Compliance Suites 2023 &lt;<link url='https://xmpp.org/extensions/xep-0479.html'>https://xmpp.org/extensions/xep-0479.html</link>&gt;.</note>">
<!ENTITY xep0480 "<span class='ref'><link url='https://xmpp.org/extensions/xep-0480.html'>SASL Upgrade Tasks (XEP-0480)</link></span><note>XEP-0480: SASL Upgrade Tasks &lt;<link url='https://xmpp.org/extensions/xep-0480.html'>https://xmpp.org/extensions/xep-0480.html</link>&gt;.</note>">
<!ENTITY xep0480 "<span class='ref'><link url='https://xmpp.org/extensions/xep-0481.html'>SASL Upgrade Tasks (XEP-0481)</link></span><note>XEP-0481: SASL Upgrade Tasks &lt;<link url='https://xmpp.org/extensions/xep-0481.html'>https://xmpp.org/extensions/xep-0481.html</link>&gt;.</note>">
<!ENTITY xep0481 "<span class='ref'><link url='https://xmpp.org/extensions/xep-0481.html'>Content Types in Messages (XEP-0481)</link></span><note>XEP-0481: Content Types in Messages &lt;<link url='https://xmpp.org/extensions/xep-0481.html'>https://xmpp.org/extensions/xep-0481.html</link>&gt;.</note>">
<!ENTITY xep0482 "<span class='ref'><link url='https://xmpp.org/extensions/xep-0482.html'>Call Invites (XEP-0482)</link></span><note>XEP-0482: Call Invites &lt;<link url='https://xmpp.org/extensions/xep-0482.html'>https://xmpp.org/extensions/xep-0482.html</link>&gt;.</note>">