1. Introduction
This document is a working draft of the protocol used by the Bookmark-Manager Daemon. The protocol builds on the top of TCP. So it expects the packets to be complete and in the correct order.
2. Header
The header is 9 bytes long:
| Size | Name |
| 1 Byte | Release |
| 4 Bytes | Packet size |
| 2 Bytes | Message type |
| 1 Byte | Attributes |
| 1 Byte | Sequence number |
2.1. Release
The release is a number indicating what release sent the packet. This number is used by the receiving site to determine what behavior is expected. The release number also implies the size of the header.
2.2. Packet size
The packet size must contain the full size of this packet, including the header. This is the only possibility to detect the end of the packet, because there isn't any "end of packet" token.
2.3. Message type
2.3.1. Sections
There are currently four sections defined:
| Section | Title |
| 1xx | Basics |
| 3xx | Functions, usually be the client |
| 30xxx | Response, usually by the server |
| 50xxx | Error, usually by the server |
2.3.2. Detailed listing of message types
2.3.2.1. Basics
| Message Type | Meaning | Expected Response | Data |
| 101 | Echo / Heartbeat. One side of the connection requests a response. | 30301 | No data |
| 102 | Continue | Depends | Continued data of the previous packet |
2.3.2.2. Functions
| Message Type | Meaning | Expected Response | Data |
| 301 | Get sub items of a parent | 30301 |
|
| 306 | Get single item | 30301 or 30306 |
|
| 307 | Get an item by special title | 30301 | Reserved title. Currently only 'trash' is defined. |
| 308 | Unlock | 30102 |
|
| 321 | Empty folder | 30102 |
|
| 326 | Delete item | 30102 |
|
| 331 | Search | 30301 | One search pattern on every line. |
| 341 | Store item | 30102 |
|
| 351 | Move item | 30102 |
|
2.3.2.3. Response
| Message Type | Meaning | Data |
| 30101 | Echo response | No data |
| 30102 | OK | No data |
| 30301 | Data follows | XBel document with at least one item |
| 30306 | Lock-ID and Data follow |
|
2.3.2.4. Error
| Message Type | Meaning | Triggered by | Data |
| 50001 | Release unknown | (Header) | Release |
| 50002 | Parameter error | (All messages) | No data |
| 50003 | Busy, please try later | (All messages) | No data. May include a description to be displayed to the end user. |
| 50004 | Message type unknown | (All messages) | Message type |
| 50005 | Message type not implemented | (All messages) | Message type |
| 50101 | Quota reached or disk full | 341 | Paths of items |
| 50301 | Item does not exist | 306, 308, 326, 351 | Paths of items |
| 50302 | Folder does not exist | 301, 321, 351 | Paths of folders |
| 50303 | Bookmark does not exist | Paths of bookmarks | |
| 50307 | Invalid special title | 307 | The title specified by the client |
| 50311 | Item is locked out | 306, 308, 321, 326, 351 | Paths of the items |
| 50312 | Item isn't locked out | 308, 341 | Paths of the items |
| 50313 | Invalid Lock-ID | 308, 341 | Paths of the items |
| 50314 | Lock-ID timed out | 308, 341 | Paths of the items |
| 50331 | No search results | 331 | No data |
| 50341 | Item already exists | 341, 351 | Paths of the items |
2.3.3. Data
The data directly follows the header. If not stated otherwise, multiple parameters are split by a newline token. (LF)
Boolean values are specified as numbers. The value 0 indicates a false value, every other value indicates true.
2.4. Attributes
This header field is reserved for multiple boolean values. Every attribute uses one bit. If a bit is set to 0 it's false and vice versa.
Currently, two bits are set.
- The first bit is set, if the sending site sends compact data. The clients must set this flag to request compact data. This is very useful for handhelds or other devices with a small bandwidth.
The client is required to set this flag for every request, if it wants compact data. The server mustn't store the value of this flag for future packets. - The second bit is set, if this packet will be continued. The message type of the next packet must be 102. See the comments to message type 102 for more details.
2.5. Sequence number
The server will copy the sequence number into the sequence number of it's response. This number is useful for the client application, if it wants to distinguish the responses of the server. For example if the client wants to send multiple search requests at once.
A. Search
This is the format of every line of the search pattern. (Message type 331)
[AND|OR] [(] [+|-] field (=|!|>|>=|<|<=) pattern [)]
A.1. Components
| Boolean operators: | |||||||||||||
| AND/OR | The boolean operators AND/OR allow very complex patterns. | ||||||||||||
| (, ) | The optional braces are for grouping. | ||||||||||||
| Include/Exclude: | |||||||||||||
| + | Specifies that this expression must be included in the result set. This is the default. | ||||||||||||
| - | This expression must not be included in the result set. | ||||||||||||
| Comparison: | |||||||||||||
| field |
This is one of the search able fields. Only lower case ASCII chars and the underline are allowed. At the moment the possible fields include:
The field is case insensitive. |
||||||||||||
| operators |
There are six logical operators defined:
|
||||||||||||
| pattern | The pattern to search for enclosed in quotation marks. Quotation marks must be escaped with a backslash. The backslash is also escaped. No newline tokens are allowed in the search pattern. |
B. Some useful notes
B.1. Stateful / Stateless design
This protocol can be implemented stateful and stateless. The server might want to use a stateless connection for local users and a stateful connection for users far away. Future releases, which will allow login, the server may decide to use a stateful connection for everyone logged in.
Future releases, too, will try to support both possibilities without much overhead.
If one side of the connections wants to know, whether the other side has implemented stateful or stateless, it may send an 101 message. If the other side sends back a 30101, it's a stateful connection. A stateless implementation is required to send a 50005 response.