Event unsubscription

Event notification

Implemented events

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:

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.

Events 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.

Events 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.

Events implemented

• 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.)

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 should 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:

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.

When loaded, each module will need to publish a list of exported events. They will also take care of raising each event in the appropriate moment (see Use cases section).

We will also need to implement (or update the existing ones) different modules for transport (and data encoding) protocol.

Event Notification Interface will be implemented in OpenSIPS core and will provide the following functionalities:

When loaded, each module will publish a list of events.

There will be different modules for each transport (and data encoding) protocol.

1. when dispatcher module disables an entity, notify an application to send an email to the administrator

TODO

Define:

• subscription algorithm
• data packing
• transport protocol

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.

External applications can interact with OpenSIPS through the MI mechanism. 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.

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.

Event Notification Interface will provide the following functionalities:

• allow external application to subscribe for events
• trigger a raised event event

• notify all external applications subscribed for the triggered event

Use cases

External applications can interact with OpenSIPS through MI mechanism. 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. As you figured out, this is not an optimal solution since the external application will spend a lot of time and load in detecting if the event occurred instead of executing the desired action.

Each OpenSIPS module will export a number of events. Event Notification module will manage them, and will also provide an interface for the external applications to register for certain events. When an event raises, the module will notify all the applications that registered for that event. Once an external application receives a notification, it can execute the desired action.

Implementation

Event Notification module will provide the following functionalities:

• manage the events exported by the OpenSIPS modules

• trigger when an event raises
• build a notification message

Development -> Sand Box -> Event Notification Interface

A new feature will be added to OpenSIPS that will provide an event notification mechanism. This new module will supply an interface for external applications to be notified when certain events occur.

Problem

External applications can interact with OpenSIPS through MI mechanism. 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.

Solution

Event Notification Interface module will provide the following features:

• allow OpenSIPS modules to register certain events for publishing
• allow external application to register or deregister for some events
• trigger when an events occurs and build a notification message
• notify all external applications registered for the triggered event

Examples

1. when pike module detects flood traffic, notify an external application that activates firewall
2. when dispatcher module disables an entity, notify an application to send an email to the administrator