A SIP leg describes both the dialog that creates a SIP transaction and a SIP dialog. The SIP Leg Manager provides a complete, fully functional interface for SIP feature development in Sentinel SIP.

How do you use the SIP Leg Manager?

The SIP Leg Manager can control multiple UAS, UAC, and B2BUA legs in the same SIP Sentinel Instance. This means you can use it to provide complex services, such as a conferencing service.

Without user-feature intervention, the default Sentinel SIP configuration acts as a B2BUA for a two-party Sentinel SIP instance. In this case, the Sentinel SIP instance has two legs that are linked: callingParty and calledParty. Sentinel SIP is capable of handling multiple legs for a Sentinel SIP instance.

Features can use the SIP Leg Manager API to interact with calling and called parties, as well as any other legs that features create.

Tip The Leg Manager API gives features control of all legs associated with a Sentinel SIP instance.

What can you do with SIP legs?

Independent legs let Sentinel SIP serve as a UAC and/or UAS. However, for complete UAC or UAS behaviour, some feature logic is required — for which you can use the LegManager interface. With LegManager, multiple independent legs can be controlled in one Sentinel SIP instance.

In particular, wo SIP legs can be linked. By linking legs, features can use the linking information to simplify the implementation of a B2BUA feature. Linking is used by the default Sentinel B2BUA system feature for this purpose. A leg may only be linked to one leg at a time.

You can use the SIP Leg Manager for all interactions of SIP requests and responses. A Sentinel SIP instance has a LegManager instance that is used to control all Leg instances for the instance.

Note The Leg Manager API is only applicable to the SIP service.

Features can use the Leg instructions in the API to:

  • send, remove, or modify a set of requests or responses being sent on a leg

  • instruct Sentinel SIP that two legs are no longer linked; subsequently, the B2BUA system feature will no longer act as a B2BUA between the two legs

  • instruct Sentinel SIP to link two legs; the B2BUA system feature will then act as a B2BUA between these legs

  • instruct Sentinel SIP to create a new leg

  • instruct Sentinel SIP to release a leg according to the leg’s current state

  • interact with forking — parallel and downstream

  • handle multiple legs in a Sentinel SIP instance (such as conferencing and announcements)

  • suspend and resume sending messages on a leg

  • set a proxy and do-not-record route on a leg

  • perform session refresh

  • end a subscription or subscriptions on a leg

  • end the leg’s session.

The SIP Leg Manager API

The LegManager and Leg API can be found in the the “multileg” section (com.opencloud.sentinel.multileg) of the Sentinel API Javadoc.

The Leg Manager Usage Examples show how to use this API to write features.

Accessing Leg Manager

Sentinel SIP controls a Sentinel SIP Instance using the Leg Manager. Features use the Leg Manager to control the legs and the SIP messages sent on the legs in a Sentinel SIP Instance. They can access the Leg Manager using the SentinelSipMultiLegFeatureEndpoint (or a subtype). For example:

    public MyFeature(SentinelSipMultiLegFeatureEndpoint caller, Facilities facilities, MyFeatureSessionState sessionState) {
        this.caller = caller;
        this.facilities = facilities;
        this.sessionState = sessionState;
        this.legManager = caller.getLegManager();
    }
Tip Features access SIP Requests/Responses using the LegManager and Leg interfaces of the Leg Manager.

Guidelines for using the API

Here are some guidelines on using the Leg Manager API within features.

Use unique leg names

The name that Sentinel SIP or the feature assigns to the leg should be unique for the Sentinel SIP instance (the LegManager instance). For SIP sessions initiated via SIP, Sentinel SIP will create a leg called callingParty for the originating calling party leg name.

Tip

To avoid any conflicts and negative interactions with legs amongst features, when a feature creates a new leg, the recommended naming convention is

<feature>-<featureFriendlyLegName>

for example, conferenceFeature-conferenceModerator.

Leg names are case sensitive.

Control SIP message handling

It isn’t always possible to let Sentinel SIP act as a B2BUA, so a feature may need to manage the messaging between two legs. For example, in Mid Call Play Announcement, the active party and the MRF cannot be linked since they are in different call phases (Active party in Mid session and the MRF in CallSetup). So the feature will need to send the appropriate message on a leg in response to receiving a message on the other leg.

Each leg has a org.jainslee.resources.sip.SipSession activity object instance associated with it. This is the activity the Sentinel SIP attaches to in order to receive SIP messages; it roughly corresponds to a SIP dialog.

The Leg Manager API is used to interact with a leg’s associated SipSession, to ensure the Sentinel SIP is aware of the state of each dialog.

Warning

It is possible for features to interact with the SipSession directly. This capability must be used sparingly, only when absolutely necessary and with caution — there may be undesirable side effects.

For example, if a BYE is sent on a leg using SipSession rather than leg.releaseLeg(), Sentinel SIP will not know that the dialog is ending (and to release the leg).

Manage legs to termination

A Sentinel SIP instance will only terminate once all legs have ended and when any other EventManagers (such as the Charging Manager) indicate that termination is possible. Therefore, any features managing the legs must ensure that all legs are managed to termination, to make sure that a call ends successfully.

Previous page Next page