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. |