Development -> Sand Box -> Event Notification Interface

OpenSIPS will be improved with an event notification mechanism. This new feature will provide an interface for external applications to be notified when certain events occur.

Problem

External applications can interact with OpenSIPS through the MI commands. This is a pull based mechanism, meaning when you need an information you have to interrogate the proxy. If an application needs to take some actions based on a certain event, it needs to periodically query OpenSIPS and decide if that event occurred or not. As you figured out, this is not an optimal solution since the external application will spend a lot of time and load detecting if the event was raised or not, instead of executing the desired action. That's why we needed a push based mechanism, so that OpenSIPS can notify an external application each time an event is raised.

Solution

Each OpenSIPS module will export a number of events, managed by the event notification mechanism. External applications will be able to subscribe for these events through the event interface. When an event is raised by a module, OpenSIPS searches for all applications subscribed for it, and sends them a notification message. Once an external application receives a notification, it can execute the desired action.

Implementation

2011/05/25 - Initial implementation This version implements the following functions:

Events handling

You can push different events from script, modules and even core. There are two types of events:

• exported by modules and core - the information about these events will be available in the compilation phase. These events will be documented in the corresponding module that raises them.
• script events - these events can be dynamically declared and raised from the script using the following function:

This function receives the event name, and optionally two AVPs. 'attrs' should contain a list of attributes name. 'vals' should contain the attributes values. Note that 'attrs' and 'vals' cardinality must be the same. An example of usage is:

Events subscription

In order to subscribe for an event you should send to OpenSIPS MI command the command event_subscribe with three parameters:

• event name
• event listener socket
• subscription expiration in seconds (optional, the default is 3600s).

An example of FIFO subscribe command is:

This command subscribes the external application for the event E_DUMMY. It also informs OpenSIPS Event Interface that it wants to be notified when events occur using UDP transfer protocol on localhost, port 8081, and the subscription will expire after 1800 seconds.

For more information about socket description and transport modules you can consult OpenSIPS documentation.

Event unsubscription

You can unsubscribe for an event by simply send an MI command with the expiration field 0. Note that the socket must be the same with the initial subscription, otherwise it won't be matched.

Event notification

When an event is fired, OpenSIPS event notification will try to notify all the subscribers. For that it will search for the desired transport protocol, pack the data and send it to the destination specified in subscription.

This version contains only 'event_datagram' transport module that supports UNIX and UDP sockets.

Implemented events

• E_CORE_THRESHOLD - raised when using debugging bottleneck detection and the limit is exceeded.
• E_PIKE_BLOCKED - raised when 'pike' module decides an IP should be blocked.
• E_RTPPROXY_STATUS - raised when a RTPProxy connects or disconnects.
• E_DISPATCHER_STATUS - raised by the 'dispatcher' module when a destination address becomes active/inactive.

TODO

• Provide devel documentation for transport protocols and modules events
• Implement XMLRPC and SIP transport protocol
• Add events to other modules (acc, usrloc, etc.)