Join
After some much debate we have concluded that Rayo should include a Join API allowing fine grained control over call leg media. The goal of the Join API is to simplify the process of connecting endpoints without worrying about low level concepts like SDP and SIP transactions.
There is two ways of using the Join API. The first one is to use the Join Command for joining two calls together. The second way is to use a Nested Join element within a dial component. This latter way is a quick shortcut when you just want to call someone and join that call. Once you have your call legs joined, you will be able to use the Unjoin Command to unjoin the call legs. Apart from these commands, Unjoin and Join Events will be dispatched to each call leg after after each join/unjoin command execution.
The Join command lets you join calls together. A join command is always addressed to a concrete call (or mixer). The syntax is the following:
<iq id='5566' type='set' to='a@call.rayo.net/1' from='16577@app.rayo.net/1'>
<join xmlns="urn:xmpp:rayo:1"
call-id="b"
direction="duplex"
media="bridge" />
</iq>
As you can see in the example above, we are sending the Join command to call 'a' instructing it to join call 'b'. The result will be either an IQ success result or an error:
<iq id='5566' type='result' to='16577@app.rayo.net/1' from='a@call.rayo.net/1' />Once the calls are joined together, both call legs will receive a Joined Event:
<!-- Both calls get an event -->
<presence to='16577@app.rayo.net/1' from='a@call.rayo.net/1'>
<joined xmlns="urn:xmpp:rayo:1" call-id="b" />
</presence>
<presence to='16577@app.rayo.net/1' from='b@call.rayo.net/1'>
<joined xmlns="urn:xmpp:rayo:1" call-id="a" />
</presence>
The join command has a couple of attributes.
The 'direction' attribute lets you set the direction of the media flow. The possible values for the direction attribute are specified in the Joinable.Direction JSR-309 Java enumeration and are:
- DUPLEX: The media flows in both directions between the objects.
- RECV: The media flows into the object.
- SEND: The media flows out of the object.
The 'media' attribute lets you set how the media will be established by using the media attribute. There is two possible values for this attribute:
- BRIDGE: Media is bridged at the media server.
- DIRECT: Media is connected between two endpoints.
Joining a mixer is exactly the same as joining a call but you use the 'mixer-id' attribute instead of 'call-id'.
<iq id='5566' type='set' to='a@call.rayo.net/1' from='16577@app.rayo.net/1'>
<join xmlns="urn:xmpp:rayo:1"
mixer-id="b"
direction="duplex"
media="bridge" />
</iq>When a mixer is joined, a JoinedEvent is dispatched but it will have a mixer-id attribute instead of a call-id:
<presence to='16577@app.rayo.net/1' from='a@call.rayo.net/1'>
<joined xmlns="urn:xmpp:rayo:1" mixer-id="b" />
</presence>The Unjoin command can be used to unjoin calls from other calls or mixers. An unjoin command is always addressed to a concrete call or mixer id. The syntax is the following:
<iq id='3377' type='set' to='a@call.rayo.net/1' from='16577@app.rayo.net/1'>
<unjoin xmlns="urn:xmpp:rayo:1" call-id="b" />
</iq>
Again, we are sending the Unjoin command to call 'a' instructing it to unjoin call 'b'. The result will be either an IQ success result or an error:
<iq id='3377' type='result' to='16577@app.rayo.net/1' from='a@call.rayo.net/1' />As with join, once the calls are unjoined, both call legs will receive an Unjoined Event:
<!-- Both calls get an event -->
<presence to='16577@app.rayo.net/1' from='a@call.rayo.net/1'>
<unjoined xmlns="urn:xmpp:rayo:1" call-id="b" />
</presence>
<presence to='16577@app.rayo.net/1' from='b@call.rayo.net/1'>
<unjoined xmlns="urn:xmpp:rayo:1" call-id="a" />
</presence>
Unjoining a mixer is exactly the same as unjoining a call but you use the 'mixer-id' attribute instead of 'call-id'.
<iq id='3377' type='set' to='a@call.rayo.net/1' from='16577@app.rayo.net/1'>
<unjoin xmlns="urn:xmpp:rayo:1" mixer-id="b" />
</iq>And again, an unjoined event with mixer-id attribute will be fired:
When a mixer is joined, a JoinedEvent is dispatched but it will have a mixer-id attribute instead of a call-id:
<presence to='16577@app.rayo.net/1' from='a@call.rayo.net/1'>
<unjoined xmlns="urn:xmpp:rayo:1" mixer-id="b" />
</presence>Nested Joins are included within the Dial component and is a quick shortcut that gives the developer the chance to tweak how the connection between both call legs will be done. Please note that the use of nested joins is not mandatory. In regular dials, calls are always connected together in full duplex mode.
The syntax of a nested join is exactly the same as with a regular join but the join element comes embedded within the dial component. So the same rules apply and the same attributes can be used. The only real difference is that a Dial command is always addressed to a server instead of being addressed to a given call (as the call does not exist yet). The following example shows a typical sequence of events when doing a nested join:
<!-- This is a regular dial but with the nested join included -->
<iq id='5566' type='set' to='rayo.net' from='16577@app.rayo.net/1'>
<dial to='tel:+13055195825' from='tel:+14152226789' xmlns='urn:xmpp:ozone:1'>
<join xmlns="urn:xmpp:rayo:1"
call-id="b"
direction="duplex"
media="bridge" />
</dial>
</iq>
<!-- The new call reference -->
<iq type='result' to='16577@app.ozone.net/1' from='rayo.net'>
<ref xmlns="urn:xmpp:rayo:1" id="z" />
</iq>
<!-- Ringing event -->
<presence to='16577@app.rayo.net/1' from='z@call.rayo.net/1'>
<ringing xmlns="urn:xmpp:rayo:1" />
</presence>
<!-- Answered -->
<presence to='16577@app.rayo.net/1' from='z@call.rayo.net/1'>
<answered xmlns="urn:xmpp:rayo:1" />
</presence>
<!-- Both call legs get the joined event -->
<presence to='16577@app.rayo.net/1' from='b@call.rayo.net/1'>
<joined xmlns="urn:xmpp:rayo:1" call-id="z" />
</presence>
<presence to='16577@app.rayo.net/1' from='z@call.rayo.net/1'>
<joined xmlns="urn:xmpp:rayo:1" call-id="b" />
</presence>The exact names and additional config is still being defined. The initial proposal will be published soon.