JSON-RPC:Rpc

JSON Methods

• rpc: set_issuer, info, add_timer, del_timer
• stats: get
• log: send, list, subscribe, unsubscribe
• user: list, get, set_nick, set_username, set_realname, set_vhost, set_mode, set_snomask, set_oper
• whowas: get
• server: list, get, rehash, connect, disconnect
• channel: list, get, set_mode, set_topic, kick
• server_ban: list, get, add, del
• server_ban_exception: list, get, add, del
• spamfilter: list, get, add, del
• name_ban: list, get, add, del

JSON Basics

• JSON-RPC Technical documentation

The rpc.* JSON RPC calls give information about the RPC methods available and the version of those modules.

API Calls

rpc.set_issuer

Set who is the issuer of all the subsequent commands that are done. This information will be used by the logging system and communicate to servers and IRCOps in the unrealircd.org/issued-by message tag.

This method only exists in UnrealIRCd 6.1.0 and later

Request arguments

Mandatory:

• name: the name of the person who is issuing the commands, eg. the current logged in person to the admin panel. NOTE: This name must conform to the regular nickname rules, eg. may not contain spaces and the like.

Response

Returns true in the result on success.

rpc.info

Request arguments

None

Response

A response object, with in the result object a "methods" object which is a list of: the API method with in that the name, module name and module version. Like this:

{
  "jsonrpc": "2.0",
  "method": "rpc.info",
  "id": 123,
  "result": {
    "methods": {
      "user.get": {
        "name": "user.get",
        "module": "rpc/user",
        "version": "1.0.0"
      },
      "user.list": {
        "name": "user.list",
        "module": "rpc/user",
        "version": "1.0.0"
      },
..etc..

Example

Request:

{"jsonrpc": "2.0", "method": "rpc.info", "params": {}, "id": 123}

Response:

{"jsonrpc": "2.0", "method": "rpc.info", "id": 123, "result": {"methods": {"user.get": {"name": "user.get", "module": "rpc/user", "version": "1.0.0"}, "user.list": {"name": "user.list", "module": "rpc/user", "version": "1.0.0"}, "channel.list": {"name": "channel.list", "module": "rpc/channel", "version": "1.0.0"}, "server_ban.add": {"name": "server_ban.add", "module": "rpc/server_ban", "version": "1.0.1"}, "server_ban.del": {"name": "server_ban.del", "module": "rpc/server_ban", "version": "1.0.1"}, "server_ban.get": {"name": "server_ban.get", "module": "rpc/server_ban", "version": "1.0.1"}, "server_ban.list": {"name": "server_ban.list", "module": "rpc/server_ban", "version": "1.0.1"}, "spamfilter.add": {"name": "spamfilter.add", "module": "rpc/spamfilter", "version": "1.0.2"}, "spamfilter.del": {"name": "spamfilter.del", "module": "rpc/spamfilter", "version": "1.0.2"}, "spamfilter.get": {"name": "spamfilter.get", "module": "rpc/spamfilter", "version": "1.0.2"}, "spamfilter.list": {"name": "spamfilter.list", "module": "rpc/spamfilter", "version": "1.0.2"}, "rpc.info": {"name": "rpc.info", "module": "rpc/rpc", "version": "1.0.0"}}}}

rpc.add_timer

Add a timer so a JSON-RPC request is executed at certain intervals.

This method only exists in UnrealIRCd 6.1.0 and later

Request arguments

Mandatory:

• timer_id: the name/id of the timer, this so you can cancel it via rpc.del_timer later. It must be unique for this RPC connection.
• every_msec: the timer will be executed every -this- milliseconds. The minimum value is 250 (a quarter of a second).
• request: the full JSON-RPC request, so {"jsonrpc":"2.0" etc. etc.

Response

Returns true in the result on success.

Example

Add a timer for a stats.get to be executed every second (1000msec).

Request:

{"jsonrpc": "2.0", "method": "rpc.add_timer", "params": {"timer_id":"test","every_msec":1000,"request":{"jsonrpc": "2.0", "method": "stats.get", "params": {}, "id": 555}}, "id": 123}

Response:

<pre>{"jsonrpc": "2.0", "method": "rpc.del_timer", "id": "123", "result": true}

Timer result every second:

{
  "jsonrpc": "2.0",
  "method": "stats.get",
  "id": 555,
  "result": {
    "server": {
      "total": 1,
      "ulined": 0
    },
etc...

Note that the id for the rpc.add_timer is 123 and the timer will be executed every second with an id of 555.

rpc.del_timer

Remove a previously added timer. Note that you can only cancel timers that belong to your own connection.

This method only exists in UnrealIRCd 6.1.0 and later

Request arguments

Mandatory:

• timer_id: the name/id of the timer that needs to be canceled.

Response

Returns true in the result on success.

Example

In the rpc.add_timer example from earlier we added a timer, this deletes that timer:

Request:

{"jsonrpc": "2.0", "method": "rpc.del_timer", "params": {"timer_id":"test"}, "id": "666"}

Response:

{"jsonrpc": "2.0", "method": "rpc.del_timer", "id": "666", "result": true}