Project

General

Profile

JSON » History » Version 3

Nevcairiel, 03/25/2010 09:47 AM

1 1 Nevcairiel
h1. JSON
2 1 Nevcairiel
3 1 Nevcairiel
This Article introduces a new communication protocol for the core based on JSON.
4 1 Nevcairiel
JSON is a lightweight data format that is text-based and human readable to represent simple data structures.
5 1 Nevcairiel
6 1 Nevcairiel
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.
7 1 Nevcairiel
8 1 Nevcairiel
h2. General Message Syntax
9 1 Nevcairiel
10 1 Nevcairiel
Every message follows this general syntax, and just adds new fields depending on the type.
11 1 Nevcairiel
12 1 Nevcairiel
<pre>
13 1 Nevcairiel
{
14 1 Nevcairiel
  "MsgType": "..."
15 1 Nevcairiel
}
16 1 Nevcairiel
</pre>
17 1 Nevcairiel
18 1 Nevcairiel
This is Version 1 of the JSON Protocol and might as well be extended if the need arises.
19 1 Nevcairiel
20 1 Nevcairiel
h2. Client Message Types
21 1 Nevcairiel
22 1 Nevcairiel
This is a list of message types the client should send, and the core will understand:
23 1 Nevcairiel
24 1 Nevcairiel
h3. Init
25 2 Nevcairiel
26 1 Nevcairiel
<pre>
27 1 Nevcairiel
{
28 1 Nevcairiel
  "MsgType": "ClientInit",
29 1 Nevcairiel
  "ProtocolVersion": 1
30 1 Nevcairiel
}
31 1 Nevcairiel
</pre>
32 1 Nevcairiel
33 1 Nevcairiel
h3. Login
34 2 Nevcairiel
35 1 Nevcairiel
<pre>
36 1 Nevcairiel
{
37 1 Nevcairiel
  "MsgType": "ClientLogin",
38 1 Nevcairiel
  "User": "UserName",
39 1 Nevcairiel
  "Password": "Password",
40 1 Nevcairiel
}
41 1 Nevcairiel
</pre>
42 1 Nevcairiel
43 1 Nevcairiel
h2. Server Message Types
44 1 Nevcairiel
45 1 Nevcairiel
These are the messages the server sends to the client.
46 1 Nevcairiel
47 1 Nevcairiel
h3. Responses to Init
48 1 Nevcairiel
49 1 Nevcairiel
"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.
50 1 Nevcairiel
<pre>
51 1 Nevcairiel
{
52 1 Nevcairiel
  "MsgType": "ClientTooOld",
53 1 Nevcairiel
  "ProtocolVersion": 1
54 1 Nevcairiel
}
55 1 Nevcairiel
</pre>
56 1 Nevcairiel
57 1 Nevcairiel
This message indicates that the core is not yet configured. Configuring is currently not possible with the JSON protocol, but might be changed.
58 1 Nevcairiel
59 1 Nevcairiel
<pre>
60 1 Nevcairiel
{
61 1 Nevcairiel
  "MsgType": "CoreNotConfigured",
62 1 Nevcairiel
}
63 3 Nevcairiel
</pre>
64 1 Nevcairiel
65 1 Nevcairiel
This messages indicates a successfull connection init. The Client should send login information now.
66 1 Nevcairiel
<pre>
67 1 Nevcairiel
{
68 1 Nevcairiel
  "MsgType": "ClientInitAck",
69 1 Nevcairiel
  "ProtocolVersion": 1,
70 1 Nevcairiel
}
71 1 Nevcairiel
</pre>
72 1 Nevcairiel
73 1 Nevcairiel
h3. Responses to Login
74 1 Nevcairiel
75 1 Nevcairiel
General purpose error if a client trys to login (or send anything besides ClientInit) without initializing before.
76 1 Nevcairiel
<pre>
77 1 Nevcairiel
{
78 1 Nevcairiel
  "MsgType": "ClientNotInitialized",
79 1 Nevcairiel
}
80 3 Nevcairiel
</pre>
81 1 Nevcairiel
82 1 Nevcairiel
The user details have not been accepted by the core.
83 1 Nevcairiel
<pre>
84 1 Nevcairiel
{
85 1 Nevcairiel
  "MsgType": "ClientLoginReject",
86 1 Nevcairiel
}
87 1 Nevcairiel
</pre>
88 1 Nevcairiel
89 1 Nevcairiel
The login was successfull and the session was established.
90 1 Nevcairiel
<pre>
91 1 Nevcairiel
{
92 1 Nevcairiel
  "MsgType": "ClientLoginAck",
93 1 Nevcairiel
}
94 1 Nevcairiel
</pre>
95 1 Nevcairiel
96 1 Nevcairiel
h3. Session
97 1 Nevcairiel
98 1 Nevcairiel
The Core will send the following message after login when the session is initialized.
99 1 Nevcairiel
100 1 Nevcairiel
<pre>
101 1 Nevcairiel
{
102 1 Nevcairiel
  "MsgType": "SessionInit",
103 1 Nevcairiel
  "SessionState": {
104 1 Nevcairiel
    "Networks": {
105 1 Nevcairiel
      "<networkname>": {
106 1 Nevcairiel
        "Id": <netid>, 
107 1 Nevcairiel
        "StatusBuffer": <bufferid>, 
108 1 Nevcairiel
        "Buffers": {
109 1 Nevcairiel
          "<buffername>": { "Id": <bufferid>, "Type": "Channel|Query|Group|Status|Invalid" },
110 1 Nevcairiel
          "<buffername>": { ... }
111 1 Nevcairiel
        }
112 1 Nevcairiel
      },
113 1 Nevcairiel
      "<networkname>": { ... },   
114 1 Nevcairiel
    ]
115 1 Nevcairiel
  }
116 1 Nevcairiel
}
117 1 Nevcairiel
</pre>
118 1 Nevcairiel
119 1 Nevcairiel
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.
120 1 Nevcairiel
121 1 Nevcairiel
h3. Messages
122 1 Nevcairiel
123 1 Nevcairiel
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.
124 1 Nevcairiel
125 1 Nevcairiel
This message will be send for a chat event while the client is connected:
126 1 Nevcairiel
127 1 Nevcairiel
<pre>
128 1 Nevcairiel
{
129 1 Nevcairiel
  "MsgType": "Message",
130 1 Nevcairiel
  "Data": {
131 1 Nevcairiel
    "MsgId": <id>,
132 1 Nevcairiel
    "BufId": <bufferid>,
133 1 Nevcairiel
    "Type": <msgtype>,
134 1 Nevcairiel
    "Time": <unix timestamp>,
135 1 Nevcairiel
    "Sender": "<sender>",
136 1 Nevcairiel
    "Contents": "<message>",
137 1 Nevcairiel
  }
138 1 Nevcairiel
}
139 1 Nevcairiel
</pre>
140 1 Nevcairiel
141 1 Nevcairiel
As a next step we'll need to define messages to request backlog and actually send commands to the core.