There is an increasing need for more complex SIP scenarios, even for the Class 4 Switches. Such scenarios exceed the capabilities of a liner processing – something more powerful and flexible is needed in turns of driving the SIP routing.

The 2.1 OpenSIPS version brought a radical change in how the SIP traffic is handled – a more efficient processing and a better CPU harvesting were achieved by introducing the asynchronous (or non blocking) I/O operations.

Even if the performance and responsiveness of OpenSIPS was addressed, the handling (or processing) of the SIP messages is still linear. Once you start processing a SIP message you can do external queries (DB, REST, Exec and other), but it is limited to its own context, being unable to:

• communicate and exchange data with the processing of a different SIP message
• synchronize or wait for  actions related to the processing of a different SIP message

Such capabilities are essential in order to implement more complex SIP scenarios where multiple elements (calls, registrations, RTP events, B2B sessions) are involved and correlated at different moments in time. And some examples of such scenarios:

• Push Notification (call and registration correlation)
• Call Pickup (2 calls correlation)
• DMTF/IVR call driving (call and RTP correlation)

and many more.

Event based Routing

This is the way of performing SIP routing via events (generated by the Event Interface).  And this is a new mechanism provided by OpenSIPS 2.3 to address complex processing problems.

But what are these events ?

• Triggered by actions / data processing during runtime  – like a new contact is registered, a destination is marked as failed, a dialog ended – all are events;
• The events hold key/value attributes – these attributes are describing the event and they represent the data attached to the event;
• OpenSIPS has a list of events – the events are predefined (by modules) or custom defined in the OpenSIPS script.

Now, how are these events used to control the SIP routing ? The OpenSIPS 2.3 Event based Routing (or shortly EBR) relays on a subscriber – notify model :

• when processing a SIP message, you can subscribe to certain events;
• the event subscriptions may contain filtering attributes (to narrow down the interesting events);
• when an event is raised, it is dispatched to all relevant subscribers- this is the notification part.

And finally, how does the routing part work ?

• The subscriber waits in asynchronous  mode to receive the notification; the processing of the subscriber will suspend and it will be fully resumed when the notification is
  received.
• The subscriber continues its processing after subscription, without any waiting. Whenever a notification is received, a script route (armed by the subscription) will be executed.

Example time – Push Notification

Scenario

Alice calls Bob. Bob has a hardphone registered, but he may also use a mobile device as SIP client. The SIP client on the mobile device is not permanently SIP registered, and it requires a Push Notification (or similar) mechanism to force its registration when there is an incoming call.

Challenges

• we want to deliver the call right away to Bob’s hardphone, without any waiting due the PN logic.
• we want to do parallel forking (simultaneous ringing) to Bob’s mobile, as soon as it registers (as a result of PN)
• we want to keep the call on, even if the hardphone declines it (maybe due to DND settings) and give a chance to the PN to trigger the mobile device registration.

If we manage to address all the challenges above, we can say we have a fully flavored Push Notification implementation.

How to

When we route the call to the callee – to Bob, in our case – we need to follow these logical steps:

1. subscribe for the event to let us know when there is a new contact registered by Bob
2. fetch all existing registered contacts from user-location
3. if any contacts found, send the call to the existing contacts
4. when new contact events are notified, inject them into the call to Bob

OpenSIPS script

Here is the relevant OpenSIPS script doing the above . For a better understanding of the code and used functions, I strongly recommend to read the module documentation for the event_routing and tm modules.

route[route_to_user] {

    # prepare transaction for branch injection; it is mandatory
    # to create the transaction before the subscription, otherwise
    # the EBR module will not pass the transaction ID into the
    # notification route
    t_newtran();

    # keep the transaction alive (even if all branches will
    # terminate) until the FR INVITE timer hits (we want to wait
    # for new possible contacts being registered)
    t_wait_for_new_branches();

    # subscribe to new contact registration event, but for our callee only
    $avp(filter) = "aor="+$rU;
    notify_on_event("E_UL_CONTACT_INSERT","$avp(filter)", "fork_call", "20");

    # fetch already registered contacts and relay if any
    if (lookup("location"))
        route(relay);
    # if there were no contacts available (so no branches created so far),
    # the created transaction will still be waiting for new branches due 
    # to the usage of the t_wait_for_new_branches() function

    exit;
}

route[fork_call]  {
    xlog("user $avp(aor) registered the a new contact $avp(uri), "
        "injecting it in transaction\n");
    # take the contact described by the E_UL_CONTACT_INSERT
    # event and inject it as a new branch into the original transaction
    t_inject_branches("event");
}

Do you want to see this script in action ? We uploaded a demo recording on youtube, just for you to enjoy it 이 게시물을...