README

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)
     Name DevScore Commits Lines ++ Lines --
   1. Razvan Crainea (@razvancrainea) 22 6 1791 8
   2. Liviu Chircu (@liviuchircu) 5 3 11 31
   3. Bogdan-Andrei Iancu (@bogdan-iancu) 3 1 1 1

   (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
                     Name                   Commit Activity
   1. Razvan Crainea (@razvancrainea)     Mar 2018 - Nov 2018
   2. Bogdan-Andrei Iancu (@bogdan-iancu) Jun 2018 - Jun 2018
   3. Liviu Chircu (@liviuchircu)         Apr 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