Project

General

Profile

Protocol Buffers » History » Version 3

Sputnick, 02/27/2013 12:22 AM

1 1 Nevcairiel
h1. Protocol Buffers
2 1 Nevcairiel
3 1 Nevcairiel
"Google Protocol Buffers":http://code.google.com/apis/protocolbuffers/ is an open binary serialization format created by Google.
4 1 Nevcairiel
This page describes an attempt to create an alternate language and platform neutral protocol for Quassel using the Protocol Buffers format.
5 1 Nevcairiel
6 2 Nevcairiel
The initial plan was to use JSON for an alternate protocol, but using Protocol Buffers has some distinct advantages, so this is the successor of that idea.
7 2 Nevcairiel
8 1 Nevcairiel
h2. Why Protocol Buffers?
9 1 Nevcairiel
10 1 Nevcairiel
??
11 1 Nevcairiel
Protocol buffers are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data – *think XML, but smaller, faster, and simpler*
12 1 Nevcairiel
??
13 1 Nevcairiel
14 1 Nevcairiel
Protocol buffers are not just a format definition, but also include code generation for many different languages.
15 1 Nevcairiel
16 1 Nevcairiel
This offers several advantages, one being a absolutely clear defined, self-describing protocol, instead of protocol based on conventions and possibly outdated documentation.
17 1 Nevcairiel
Additionally, protocol buffers are a binary protocol, with highly optimized implementations in several languages. Official support by Google for C++, Java and Python, as well as third party extension for many other popular languages, including PHP, Obj-C, Perl, JS, and many more.
18 1 Nevcairiel
19 3 Sputnick
h2. Current State
20 3 Sputnick
21 3 Sputnick
Work is currently in progress for supporting alternative protocols, i.e. something else besides QDataStream serialization. This requires lots of refactoring first in order to abstract everything away properly.
22 3 Sputnick
23 3 Sputnick
Once this work is done, we'll look into offering something based on Protocol Buffers.
24 3 Sputnick
25 3 Sputnick
<b> Note that the information in the following sections is completely outdated and not in any way resembling the future implementation!</b>
26 3 Sputnick
Well just keep it here for now for reference.
27 3 Sputnick
28 3 Sputnick
h2. Protocol Definition
29 1 Nevcairiel
30 1 Nevcairiel
Note: The protocol is still being actively worked on.
31 1 Nevcairiel
The outlined protocol definitions are not final, and just listed here for documentation.
32 1 Nevcairiel
33 1 Nevcairiel
h3. Message Container
34 1 Nevcairiel
35 1 Nevcairiel
Every Message has to be wrapped in a container, since we otherwise can't determine the message type. This is done by the "QuasselServerMessage" and "QuasselClientMessage" message types. This design is modeled around the Protocol Buffers "Union Types":http://code.google.com/apis/protocolbuffers/docs/techniques.html#union example.
36 1 Nevcairiel
37 1 Nevcairiel
QuasselServerMessage are messages the server sends, while QuasselClientMessage are messages the client sends.
38 1 Nevcairiel
39 1 Nevcairiel
<pre>
40 1 Nevcairiel
message QuasselServerMessage {
41 1 Nevcairiel
  enum MessageType {
42 1 Nevcairiel
    ERROR = 0,         // Generic message for errors
43 1 Nevcairiel
    SUCCESS = 1,       // Generic message for success
44 1 Nevcairiel
    SESSION_STATE = 2, // State of current session, sent after init
45 1 Nevcairiel
    ...
46 1 Nevcairiel
  }
47 1 Nevcairiel
  required MessageType type = 1;
48 1 Nevcairiel
  
49 1 Nevcairiel
  optional ErrorMessage errorMessage = 100;
50 1 Nevcairiel
  optional SuccessMessage successMessage = 101;
51 1 Nevcairiel
  optional SessionState sessionState = 102;
52 1 Nevcairiel
  ...
53 1 Nevcairiel
}
54 1 Nevcairiel
</pre>
55 1 Nevcairiel
56 1 Nevcairiel
<pre>
57 1 Nevcairiel
message QuasselClientMessage {
58 1 Nevcairiel
  enum MessageType {
59 1 Nevcairiel
    REQUEST = 0,       // Generic Request message (request init, request login, request backlog, etc..)
60 1 Nevcairiel
    ...
61 1 Nevcairiel
  }
62 1 Nevcairiel
  required MessageType type = 1;
63 1 Nevcairiel
  
64 1 Nevcairiel
  optional RequestMessage request = 2;
65 1 Nevcairiel
  ...
66 1 Nevcairiel
}
67 1 Nevcairiel
</pre>
68 1 Nevcairiel
69 1 Nevcairiel
Once the protocol is better defined, the full protocol files will be available here.