event_jsonrpc Module


Table of Contents

1. Admin Guide
1.1. Overview
1.2. JSON-RPC socket syntax
1.3. Dependencies
1.3.1. OpenSIPS Modules
1.3.2. External Libraries or Applications
1.4. Exported Parameters
1.4.1. sync_mode (integer)
1.4.2. timeout (integer)
1.4.3. event_param (string)
1.5. Exported Functions
1.6. Examples
1.6.1.
1.6.2. JSON-RPC notification
1.6.3. JSON-RPC Request
1.6.4. JSON-RPC Notification with Event's name
1.6.5. Custom JSON-RPC Notification from script
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. Set sync_mode parameter
1.2. Set timeout parameter
1.3. Set event_param parameter
1.4. JSON-RPC socket
1.5. E_PIKE_BLOCKED JSON-RPC notification
1.6. E_PIKE_BLOCKED JSON-RPC request (sync_mode)
1.7. E_PIKE_BLOCKED notification with event name
1.8. E_PIKE_BLOCKED event

Chapter 1. Admin Guide

1.1. Overview

This module is an implementation of an JSON-RPC v2.0 client http://www.jsonrpc.org/specification. that can send a RPC to a JSON-RPC server (when used in sync_mode), or send a notification (when sync_mode is disabled) whenever whenever OpenSIPS raises a notification through the Event Interface. This module acts as a transport layer for the Event Notification Interface.

This module sends the JSON-RPC directly over TCP, avoiding the any application transport layer (such as HTTP). This makes this module a very lightweight and reliable module to deliver events to an application server.

In order to be notified, a JSON-RPC server has to subscribe for a certain event provided by OpenSIPS. This can be done using the generic MI Interface (event_subscribe function) or from OpenSIPS script (subscribe_event core function).

1.2. JSON-RPC socket syntax

'jsonrpc:' host ':' port ['/' method]

Meaning:

  • 'jsonrpc:' - specifies the transport protocol used by the Event Interface to send the command. the jsonrpc token indicates that the subscriber's events should be notified using the event_jsonrpc module.

  • host - host name of the JSON-RPC server.

  • port - port of the JSON-RPC server.

  • method - method called remotely by the JSON-RPC client.

    NOTE: this parameter is optional - if it is missing, the method used is the actual event subscribed to (i.e. if localhost:8080 subscribes to the E_PIKE_BLOCKED event, the RPC call will use the E_PIKE_BLOCKED method.

The JSON-RPC command is built as it follows:

  • id - uniquly generated if sync_mode is used, otherwise (for notifications) null.

  • method - if no method is specified in the socket, the name of the event is set as method, otherwise the token specified is used.

  • params - if the event sent contains named parameters, then this parameter contains a JSON object with an object for each parameter. If the event sent only contains values, the parameters will be sent as an array.

1.3. Dependencies

1.3.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • none.

1.3.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

  • none

1.4. Exported Parameters

1.4.1. sync_mode (integer)

This parameter controls the way the event_jsonrpc module communicates with the JSON-RPC server. If enabled, (set to yes), each event is translated to a JSON-RPC request. If disabled, each event will be sent as a JSON-RPC notification - there will be no reply expected by our client.

Note that if you need a reliable communication with the JSON-RPC server, where each event sent needs to be confirmed, you must set this parameter to 1/yes. Also, if you are using this module in a failover setup (using the event_virtual module), you should also set this parameter to 1/yes.

Default value is 0 (disabled).

Example 1.1. Set sync_mode parameter

...
modparam("event_jsonrpc", "sync_mode", yes)
...

1.4.2. timeout (integer)

Specified the amount of milliseconds the module waits for a command to complete. In sync_mode, it specifies the time module waits the request to be sent and a reply received. In non-sync_mode, it represents only the time opensips takes to send the JSON-RPC notification.

NOTE that if the event is not using names for its parameters, the event will be the first parameter in the JSON-RPC command.

Default value is 1000 milliseconds = 1 second.

Example 1.2. Set timeout parameter

...
# only wait for 200 milliseonds for a reply
modparam("event_jsonrpc", "timeout", 200)
...

1.4.3. event_param (string)

By default, the name of the event subscribed to is not send in the JSON-RPC command. If one needs to send the name of the event as well, you can use this parameter to specify the name of JSON object within the params that will contain the name of the event.

Default value is disabled - event is not added.

Example 1.3. Set event_param parameter

...
modparam("event_jsonrpc", "event_param", "opensips_event")
# json resulted will contain the "opensips_event": EVENT token
...

1.5. Exported Functions

No function exported to be used from configuration file.

1.6. Examples

Example 1.4. JSON-RPC socket


	# calls the 'block_ip' method
	jsonrpc:127.0.0.1:8080/block_ip

	# calls the 'E_PIKE_BLOCKED' method, if subscribed to the E_PIKE_BLOCKED event
	jsonrpc:127.0.0.1:8080


1.6.2. JSON-RPC notification

This is an example of an event raised when sync_mode is disabled by the pike module when it decides an ip should be blocked:

Example 1.5. E_PIKE_BLOCKED JSON-RPC notification


{
	"id": null,
	"jsonrpc": "2.0",
	"method": "E_PIKE_BLOCKED",
	"params": {
		"ip": "192.168.2.11"
	}
}


1.6.3. JSON-RPC Request

This is an example of an event raised in sync_mode by the pike module when it decides an ip should be blocked:

Example 1.6. E_PIKE_BLOCKED JSON-RPC request (sync_mode)


# request
{
	"id": 915243442,
	"jsonrpc": "2.0",
	"method": "E_PIKE_BLOCKED",
	"params": {
		"ip": "192.168.2.11"
	}
}

# reply
{
	"jsonrpc": "2.0",
	"result": 8,
	"id": 915243442
}


1.6.4. JSON-RPC Notification with Event's name

when having the event_param set to opensips_event, the event raised by the pike module will look like the following:

Example 1.7. E_PIKE_BLOCKED notification with event name


# module configuration
modparam("event_jsonrpc", "event_param", "opensips_event")

# JSON-RPC socket: jsonrpc:HOST:PORT/handle_cmd

# JSON-RPC command sent
{
	"id": null,
	"jsonrpc": "2.0",
	"method": "handle_cmd",
	"params": {
		"opensips_event": "E_PIKE_BLOCKED"
		"ip": "192.168.2.11"
	}
}


1.6.5. Custom JSON-RPC Notification from script

This example contains a snippet to send a custom event from the script using the event_jsonrpc module.

Note that we are only populating values for the event, we are not assinging names to those values. Therefore, the parameters will be sent as an array.

Example 1.8. E_PIKE_BLOCKED event


startup_route {
	subscribe_event("E_MY_EVENT", "jsonrpc:127.0.0.1:8080");
}

route {
	...
	$avp(attr-val) = 3;
	$avp(attr-val) = 5;
	raise_event("E_MY_EVENT", $avp(attr-val));
	...
}

# JSON-RPC command sent
{
	"id": null,
	"jsonrpc": "2.0",
	"method": "E_MY_EVENT",
	"params": [3, 5]
}


Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Razvan Crainea (@razvancrainea)2610179510
2. Liviu Chircu (@liviuchircu)641333
3. Bogdan-Andrei Iancu (@bogdan-iancu)3111

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Razvan Crainea (@razvancrainea)Mar 2018 - Sep 2019
2. Liviu Chircu (@liviuchircu)Apr 2018 - Nov 2018
3. Bogdan-Andrei Iancu (@bogdan-iancu)Jun 2018 - Jun 2018

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea).

doc copyrights:

Copyright © 2018 www.opensips-solutions.com