Support for SIP transfers

[lminiero]

As the title says, this pull request is aimed at adding support for SIP transfers in the SIP plugin. This was first asked for in #978, and has been a commonly asked feature since, e.g., to build more effective Janus-based softphones in the web, for contact/call centers, etc. This is part of a new series of developments (including #1768 for SIP SUBSCRIBE/NOTIFY and #1772 for multiple calls), sponsored by a Colombian Company with 21 years of experience on developing Telecommunication Solutions.

Since this is part of a set of activities I've been working on related to the SIP plugin, this is actually based on another PR I published a few weeks ago (#1772), that is the one that implements support for multiple SIP calls at the same time for the same account. In fact, SIP transfers, whether they're blind or attended, always end up in someone having two calls at a time in some moments, and as such they wouldn't be possible without the multiple calls support implemented there. The patch includes a documentation of the feature, in a dedicated section that can be generated when compiling the docs via doxygen and that I'll briefly describe here.

The request to ask for a transfer (blind or attended) is called transfer, which will originate a SIP REFER in the plugin, and its syntax is the following:

{
	"request": "transfer",
	"uri": "SIP URI to transfer to",
	"replace": "call-ID to replace (optional)"
}

The only mandatory argument is the uri of the transfer target; the replace one is optional, if you omit it, it will be a blind transfer, otherwise it will be an attended one. Notice that the transfer request must be sent during a call, and cannot be sent if you're not in a conversation with the person you want to transfer.

You'll get a transferring event in response to that request. This will also automatically trigger a subscription for the call progress events, so you can expect notify events formatted like we already
discussed when talking about the #1768 branch. That will allow the transferor to see how the transfer is proceeding.

On the transferee side (the person receiving the REFER), they'll receive a transfer event formatted like this:

{
	"sip": "event",
	"result": {
		"event": "transfer",
		"refer_id": <unique ID, internal to Janus>,
		"refer_to": "SIP URI to call",
		"referred_by": "SIP URI of the transferor; optional",
		"replaces": "call-ID of the call to replace; optional"
	}
}

The refer_to is the URI that they need to call, referred_by is the SIP URI of the transferor; replaces will only be there if the REFER did include a replaces parameter, as discussed above.

What's truly important in the plugin messaging, though, is refer_id, which is a unique numeric identifier, internal to the plugin, to address this transfer request. It's important because, if you want to
accept the transfer and do the call, you simply place a regular call request (as you're already doing), but adding a refer_id attribute with the value you just received: this tells the SIP plugin that this
is not a call you're startin on your own, but you're actually following up on the REFER, and so will add the additional SIP headers (e.g., Replaces if it was provided). Of course, remember that, since the
transferee is already in a call with the transferor, to follow up on the REFER you'll need to place the new call on a new helper, as introduced in the above-mentioned #1772 branch.

For what concerns the transfer targer (the person the REFER tells you to call), it's pretty much a normal incoming call, so you should expect a normal incomingcall event; in case this incoming call was originated from a transfer, though, the incomingcall event will also include a referred_by (URI of the transferor) and optionally a replaces attribute. Notice that, in case this is an attended
transfer, the transfer target is in a call with the transferor already: this means that, in order to be able to receive the new call from the transferee as well, they'll need to have a helper ready BEFORE this
happens, otherwise the incoming call will be automatically rejected by the plugin with a 486 Busy, without even involing the application. Again, please refer to the multiple calls stuff for that.

As a final note, please beware that, in case this is an attended transfer, and there's a replaces attribute involved, the plugin will NOT hangup that call for you. It's up to the application to use that
information to hangup the replaced call, if they want. Same thing for putting calls on hold while transfering: the plugin will NOT do that for you, control of that part is left entirely up to the application,
to give it more control on what should be done and how.

Hope this is clear enough, and that I'll get some more feedback on it. I didn't get any feedback at all on #1768, which was surprising and annoying: this is a more complex feature, so you want to test it before I merge it.

[lminiero]

Note: fixed a typo in the PR text, where for the transfer request I was mentioning a replaces property that doesn't actually exist, since it's called replace instead (notice the missing "s"). For the transfer target, the incomingcall event does include a replaces property instead.

[karimsiam]

I Have Tested this update and it worked perfectly.
I was able to have multiple calls and was able to do both blind and attended transfer.

It would also be very nice to be able to merge calls (confrencing).

looking forward to have this pull merged in master.
many Thanks.

[lminiero]

I Have Tested this update and it worked perfectly.
I was able to have multiple calls and was able to do both blind and attended transfer.

Cool, thanks!

It would also be very nice to be able to merge calls (confrencing).

Not going to happen, sorry. We're never going to decode/transcode in the SIP plugin.

[lminiero]

Merging.