BKM Network Protocol Design Draft (V 0.3a)

Patrice Neff <patricech@sourceforge.net>
10 June 2001

Table of Contents

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

Message Type Meaning Expected Response  Data
301 Get sub items of a parent 30301
  1. Path to a folder
  2. Number of levels to fetch. Default is 1, fetching only the items directly below the specified folder. Set to 0 to fetch all ancillary levels.
306 Get single item 30301 or 30306
  1. Path to the item
  2. Open for editing? Boolean value. Default is false.
307 Get an item by special title 30301 Reserved title. Currently only 'trash' is defined.
308 Unlock 30102
  1. Path of the locked item
  2. Lock-ID
321 Empty folder 30102
  1. Path
  2. Recurse? Boolean value. Default is false.
326 Delete item 30102
  1. Path
  2. Recurse? Boolean value. Default is false.
331 Search 30301 One search pattern on every line.
341 Store item 30102
  1. Replace. Numeric with the following possible values:
    1. No (Default)
    2. Absolutely
    3. Compressed. Only the given fields are replaced. This is very useful, if the client doesn't want to submit all the data. It might suppress the description, for example.

    If the compress bit is set, The value "absolutely" isn't allowed and replaced with the value "compressed".
  2. Lock-Id's of the stored documents. Separated by comma.
  3. XBel document. For the documents without a title, "New Bookmark/Folder" will be inserted by the server. The server is required to automatically add an index then. For example "New Bookmark 2"
351 Move item 30102
  1. Path
  2. Target path. If it's a folder, the filename will be retained.
  3. Replace? Default is false. 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
  1. Lock-ID
  2. XBel document with exactly one item. 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.

  1. 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.
  2. 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.
+ 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.
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:
  • title
  • url
  • description
  • date_mod

The field is case insensitive.

operators There are six logical operators defined:
= Is equal
! Is not equal
< Is less
<= Is less or equal
> Is greater
>= Is greater or equal
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.