Quassel IRC

h1. JSON

NOTE:

This is not in the main quassel distribution, and it will probably be a long time until it gets there (if ever).

This article is here for discussion purposes only.

h3. Abstract

This Article introduces a new communication protocol being developed for the core based on JSON.

JSON is a lightweight data format that is text-based and human readable to represent simple data structures.

A JSON library exists for most programming languages, so its really easy to use from any platform, which was the main motivation behind this project - enabling developers to write a Quassel Client without the lockin to Qt based systems.

h2. General Message Syntax

Every message follows this general syntax, and just adds new fields depending on the type.

<pre>

{

  "MsgType": "..."

}

</pre>

This is Version 1 of the JSON Protocol and might as well be extended if the need arises.

h2. Client Message Types

This is a list of message types the client should send, and the core will understand:

h3. Init

<pre>

{

  "MsgType": "ClientInit",

  "ProtocolVersion": 1

}

</pre>

h3. Login

<pre>

{

  "MsgType": "ClientLogin",

  "User": "UserName",

  "Password": "Password",

}

</pre>

h2. Server Message Types

These are the messages the server sends to the client.

h3. Responses to Init

"ClientTooOld" indicates that the client is using a protocol version that is too old for this core. The ProtocolVersion argument is the current version of the core.

<pre>

{

  "MsgType": "ClientTooOld",

  "ProtocolVersion": 1

}

</pre>

This message indicates that the core is not yet configured. Configuring is currently not possible with the JSON protocol, but might be changed.

<pre>

{

  "MsgType": "CoreNotConfigured",

}

</pre>

This messages indicates a successfull connection init. The Client should send login information now.

<pre>

{

  "MsgType": "ClientInitAck",

  "ProtocolVersion": 1,

}

</pre>

h3. Responses to Login

General purpose error if a client trys to login (or send anything besides ClientInit) without initializing before.

<pre>

{

  "MsgType": "ClientNotInitialized",

}

</pre>

The user details have not been accepted by the core.

<pre>

{

  "MsgType": "ClientLoginReject",

}

</pre>

The login was successfull and the session was established.

<pre>

{

  "MsgType": "ClientLoginAck",

}

</pre>

h3. Session

The Core will send the following message after login when the session is initialized.

<pre>

{

  "MsgType": "SessionInit",

  "SessionState": {

    "Networks": {

      "<networkname>": {

        "Id": <netid>, 

        "StatusBuffer": <bufferid>, 

        "Buffers": {

          "<buffername>": { "Id": <bufferid>, "Type": "Channel|Query|Group|Status|Invalid" },

          "<buffername>": { ... }

        }

      },

      "<networkname>": { ... },   

    ]

  }

}

</pre>

In protocol version 1, different chatview configurations are not yet supported, every network and every buffer known to this core account will be shown. This is planned to be changed in the future.

h3. Messages

NOTE: This message type is a temporary message for testing the message sending capabilities, and will change. But for discussions of the protocol, its added here as well.

This message will be send for a chat event while the client is connected:

<pre>

{

  "MsgType": "Message",

  "Data": {

    "MsgId": <id>,

    "BufId": <bufferid>,

    "Type": <msgtype>,

    "Time": <unix timestamp>,

    "Sender": "<sender>",

    "Contents": "<message>",

  }

}

</pre>

As a next step we'll need to define messages to request backlog and actually send commands to the core.