Skip to content

event.md

Latest commit

 

History

History
59 lines (39 loc) · 3.96 KB

event.md

File metadata and controls

59 lines (39 loc) · 3.96 KB
Raw

OpenSIPS Python Packages - Event Interface

This package can be used to subscribe to OpenSIPS events.

Supported backend protocols

The following event transport protocols are supported:

  • datagram (Default) - uses either UDP or UNIX datagram to receive notifications for subscribed events. By default, the UDP protocol is used with the ip and port parameters set to 0.0.0.0 and 0 (any available port) respectively, but you can tune them to your needs. To use the UNIX datagram, set the socket_path parameter.
  • stream - uses TCP to communicate with the Event Interface. Default values for ip and port are 0.0.0.0 and 0 (any available port) respectively, but you can change them as needed.

How to use

To subscribe to events, you must instantiate an OpenSIPSEventHandler. This class can be used to subscribe and unsubscribe from events. It uses an OpenSIPSMI object to communicate with the OpenSIPS MI interface. By default, a MI connector is created with the fifo type, but you can set it as a parameter in the constructor. As said before, the default transport protocol is datagram, but you can change it by setting the _type parameter.

Next step is to create an OpenSIPSEvent object. This can be done by calling the subscribe method of the OpenSIPSEventHandler object or by creating an OpenSIPSEvent object directly. The subscribe method will return an OpenSIPSEvent object.

To unsubscribe from an event, you can call the unsubscribe method of the OpenSIPSEvent object or the unsubscribe method of the OpenSIPSEventHandler object.

from opensips.mi import OpenSIPSMI, OpenSIPSMIException
from opensips.event import OpenSIPSEvent, OpenSIPSEventException

# simple way
hdl = OpenSIPSEventHandler()

# tuned way
mi_connector = OpenSIPSMI('http', url='http://localhost:8888/mi')
hdl = OpenSIPSEventHandler(mi_connector, 'datagram', ip='127.0.0.1', port=50012)

try:
    ev = hdl.subscribe('E_PIKE_BLOCKED', some_callback)
except OpenSIPSEventException as e:
    # handle the exception

# or create an OpenSIPSEvent object directly
ev = OpenSIPSEvent(hdl, 'E_PIKE_BLOCKED', some_callback)

try:
    ev.unsubscribe()
    # or
    hdl.unsubscribe('E_PIKE_BLOCKED')
except OpenSIPSEventException as e:
    # handle the exception

If callback function is called with None as a parameter, it means that there was an error while receiving the event and no JSON object could be parsed from the received data after 10 retries, or that the subscription expired or could not be refreshed.

Subscribing

By default, the subscription will be permanent with a resubscribing interval of 1 hour. If you want to set a timeout, you can use the expires parameter. The value should be an integer representing the number of seconds the subscription will be active.

How it works

All the events subscribed through the same OpenSIPSEventHandler share a single socket: OpenSIPS sends all their notifications to the same address, and each notification is passed to the callback of the event it belongs to (based on its method, i.e. the event name). This means that a handler configured with a fixed port can subscribe to any number of events; to receive events on different ports, use a different handler for each port.

When subscribing to the first event of a handler, the socket is created, together with a thread that listens for notifications (or, for async_subscribe, a reader in the asyncio event loop). The thread calls the callback function of the matching event when a notification is received, and refreshes the subscriptions before they expire. When unsubscribing, the event stops receiving notifications; once the last event of the handler is unsubscribed, the thread is stopped and the socket is closed. You can also use the stop method to stop receiving notifications without unsubscribing from OpenSIPS.

Synchronous (subscribe) and asynchronous (async_subscribe) subscriptions use separate sockets, so they should not be mixed on a handler with a fixed port.