Refer rewrite

[egreenmachine]

This is intended to simplify the refer handling and address all of the issues under the refer refactor milestone. This documentation looks daunting, but it is a lot of different documentation for Refer handling. Most of this is not needed for the majority of use cases that people are using. It should be in a stable state, and merging this will cause the release of 0.9.0 as it is API breaking.

Documentation

Sending a refer

Sending a refer is mostly the same. You can call refer on any active session and it will send a refer. Refer takes a single argument options. When you call refer on the session a ReferClientContext will be created. The only function that can be called on a ReferClientContext is refer which will be called automatically on the session. You only need to call refer manually if you are sending an out of dialog refer.

refer(target, options)

target

This is the target of the refer. It can be a String or a session (InviteClientContext or InviteServerContext). If it is a String a blind transfer will be sent (Refer without replaces). If it is a session then an attended transfer will occur (Refer with replaces)

options

extraHeaders - Array of extra headers to use in the refer request.

receiveResponse - Function that will be called with the response of the refer after SIP.js does it's internal processing.

activeAfterTransfer - boolean if true, when the refer is successful it will not automatically terminate the applicant session. Default: false.

ReferClientContext

Advanced Topic
To send an out of dialog refer you need to create a ReferClientContext then call the refer function.

Constructor

var rcc = new SIP.ReferClientContext(ua, applicant, target, options);

ua

A valid UA to be used to send the refer with. See UA documentation.

applicant

Who is sending the refer. If this is an in dialog refer, the applicant is the currently active session. If this is an out of dialog refer, the applicant must have a contact field indicating the contact to use for the refer and must have a sendRequest function which will be used to send the request. In most cases, this should simply turn around and call the UA.request function with the appropriate headers etc.

target

See documentation above.

options

See documentation above

Methods

refer(options)

Send the actual refer. See above for documentation of options.

Receiving a refer

If you do nothing and receive a valid refer, SIP.js will automatically follow the refer

Receiving a refer is all new. No longer do you need to set up a listener and follow the refer yourself. If you would like more granular control, add a listener for the referRequested event on your session. This will give you a handle to the ReferServerContext

ReferServerContext

Constructor

var rsc = new SIP.ReferServerContext(ua, request)

ua

A valid ua that the refer request was received on. See UA documentation for more.

request

The SIP request of the REFER.

Methods

progress()

Send a 100 progress method to the REFER.

accept(options, modifiers)

Accept the refer. Sends a 202 Accepted.

The options object defines some additional options that you can use. If options.followRefer is truthy, then SIP.js will try and follow the refer on its own. options.inviteOptions are a set of options to pass to UA.invite(options). options.extraHeaders is an array of extra headers to use.

The modifiers array are standard modifiers to use on an invite for the new session.

reject()

Reject the refer.

sendNotify(body)

Used to send Notify messages about the status of the new SIP session to the referrer.

The body must be a valid sipfrag.

Events

All of the events emit with the ReferContext that they are using. All of the events are emitted on the ReferContext and applicant session unless otherwise noted.

referRequested

We have sent or received a refer.

outOfDialogReferRequested

Emitted on the UA only.
An out of dialog refer has been received. The UA option allowOutOfDialogRefers must be set to true.

referRequestAccepted

The request to do a refer was accepted. The endpoint is now attempting to do the refer.

referInviteSent

Only emitted on the ReferServerContext when the invite for the new SIP session is sent.

Following events indicate the progress of the new session

referProgress

The new session has transitioned into the progress state

referAccepted

The new session is set up successfully

referRejected

The new session did not set up correctly, and the old session should be resumed

UA Options

allowOutOfDialogRefer

SECURITY WARNING! If enabled a malicious endpoint could take control of your client

Default: false

This will enable you to receive refers out of any dialogs. Only enable if you have an outOfDialogReferRequested event listener on your UA. If there is no event listener the default behavior of SIP.js is to try and follow these Refer's.