Events API

RCN Events API is a thread based watching for events to occur, it automatically takes care for calling the handler when a event is triggered. It requires two methods an invoker and a handler.

Note The events API is available in version >= 2.1.1 for cndi

Invoker Method

Invoker method decides weather to call a event handler or not, It's that simple this method is a custom method and should return a dict object containing a key trigger a boolean, if it returns true the event is triggered otherwise it's not.

{
    trigger: booleanValue,
    otherAttributes...
}

Handler Method

Handler Method is the method which takes care of an event when its triggered.

Code

Invoker Method:

As discussed above the invoker method will decide if a event should be triggered or not. Below we will define a invoker method that will trigger event every time it's called

def invokerMethod(eventObject):
    return dict(trigger=True)

Here we are return trigger as true, so it will trigger event everytime we can manage the event triggering through this.

Handler Method

Below is a event handler method with two arguments, the first argument is the dictObject that we returned from the InvokerMethod, the second object is the interesting one this is the same object we are pass as single object in invoker method. Lets have a look when we create an EventObject below.

def handle(callEvent, eventObject):
    # do something
    pass

Register Event

Let's check how to register a event into context.

# Event Object
event = Event(event_name="testing_event",                       # Event Name
                event_handler=handle,                           # Set Handler Method
                event_object=dict(informativeData="hello"),     # Set Initial EventData
                event_invoker=invokerMethod)                    # Set Handler Method

# Create a Event Handler object
# Note: The event handler should be invoked as a cndi component, rather initializing it manually 
eventHandler = EventHandler()

eventHandler.registerEvent(event=event)

# Start Event Handler
eventHandler.start()

Configuration Properties

The below keys should be prefixed with rcn.events. in order to work with events api.

Key	Default Value	Description
enable	False	Enables Events API
waittime	2.0 sec	The time to wait for event cycle to call invoker method
expected.invoker.time	3 millis	The expected time for invoker method to run, exceding the expected time will result in raising a warning log