From 4ae8ca60d9cf588ee3860cca8ac9155a8a260f71 Mon Sep 17 00:00:00 2001 From: Fredrik Tolf Date: Fri, 6 Jul 2007 04:41:01 +0200 Subject: [PATCH] Add initial protocol documentation. --- doc/protocol/protocol.tex | 69 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 doc/protocol/protocol.tex diff --git a/doc/protocol/protocol.tex b/doc/protocol/protocol.tex new file mode 100644 index 0000000..36d9505 --- /dev/null +++ b/doc/protocol/protocol.tex @@ -0,0 +1,69 @@ +\documentclass[twoside,a4paper,11pt]{article} + +\newcommand{\url}[1]{\texttt{<#1>}} +\newcommand{\unix}{\textsc{Unix}} + +\title{Dolda Connect protocol} +\author{Fredrik Tolf\\\texttt{}} + +\begin{document} + +\maketitle + +\section{Introduction} +Dolda Connect consists partly of a daemon (a.k.a. server) that runs in +the background and carries out all the actual work, and a number of +client programs (a.k.a. user interfaces) that connect to the daemon in +order to tell it what to do. In order for the daemon and the clients +to be able to talk to each other, a protocol is needed. This document +intends to document that protocol, so that third parties can write +their own client programs. + +It is worthy of note that there exists a library, called +\texttt{libdcui} that carries out much of the low level work of +speaking the protocol, facilitating the creation of new client +programs. In itself, \texttt{libdcui} is written in the C programming +language and is intended to be used by other programs written in C, +but there also exist wrapper libraries for both GNU Guile (the GNU +project's Scheme interpreter) and for Python. The former is +distributed with the main Dolda Connect source tree, while the latter +is distributed separately (for technical reasons). To get a copy, +please refer to Dolda Connect's homepage at +\url{http://www.dolda2000.com}. + +\section{Transport format} +The protocol can be spoken over any channel that features a +byte-oriented, reliable virtual (or not) circuit. Usually, it is +spoken over a TCP connection or a byte-oriented \unix\ socket. The +usual port number for TCP connections is 1500, but any port could be +used\footnote{However, port 1500 is what the \texttt{libdcui} library + uses if no port is explicitly stated, so it is probably to be + preferred}. What follows hereon is an informal description of the +protocol. + +On top of the provided byte-oriented connection, the most basic level +of the protocol is a stream of Unicode characters, encoded with +UTF-8. The Unicode stream is then grouped in two levels: lines +consisting of words (a.k.a. tokens). Lines are separated by CRLF +sequences (\emph{not} just CR or LF), and words are separated by +whitespace. Both whitespace and CRLFs can be quoted, however, +overriding their normal interpretation of separators and allowing them +to be parts of words. NUL characters are not allowed to be transferred +at all, but all other Unicode codepoints are allowed. + +Lines transmitted from the daemon to the client are slightly +different, however. They all start with a three-digit code, followed +by either a space or a dash\footnote{Yes, this is inspired by FTP and + SMTP.}, followed by the normal sequence of words. The three-digit +code identifies that type of line. Overall, the protocol is a +lock-step protocol, where the clients sends one line that is +interpreted as a request, and the daemon replies with one or more +lines. In a multi-line response, all lines except the last have the +three-digit code followed by a dash. The last line of a multi-line +response and the only line of a single-line response have the +three-digit code followed by a space. All lines of a multi-line +response have the same three-digit code. The client is not allowed to +send another request until the last line of the previous response has +been received. + +\end{document} -- 2.11.0