Specification of the Day Planner services protocol version 1 DRAFT
by Eskild Hustvedt
------------------------------------------------------------

This is only a draft, and is not yet a full spec.

Table of contents:
1 - Introduction

2 - Connection
3 - Commands
4 - Data

5 - Planned features
6 - Comments issues and feedback

1 - Introduction
----------------
Day Planner services is a server<->client system for calendars.
It allows you to have the same calendar data on multiple machines,
synchronizing them when needed. It should be pretty transparent
for the user, and the data should just be there and work.
It uses complete files instead of single events and does not do
any parsing of iCalendar itself. It /can/ therefore be used
to save any kind of data, but you should never use it for anything
but the calendar data it is designed for.

It includes additional features such as the ability to encrypt the data
on the server. It encrypts the data before sending it so there is no
way for any of the server admins to retrieve the unencrypted data.
Also, for those that don't want encrypted data, it can autogenerate
an HTML version of the data and make that available, using the same
username/password as is used to connect to the service itself.

In time calendar sharing and such will also be available through this service.

Ideally (and as it is in the primary implementation «Day Planner services»)
it is a simple daemon that doesn't do any fancy processing. It reads and
writes the data and authenticates users, that's about it. The HTML
processing will be done by external software, and as the data
should be in the iCalendar format, any iCalendar compliant parser
can generate it. The primary implementation uses Day Planner for this.

2 - Connection
--------------
The connection is simple. You connect, authenticate, send commands, disconnect.
Here is an example session (using the current cleartext password sending):

APILEVEL 1
AUTH username password
GET_MD5

There is no need for a specific "bye" command. The only requirement of the
protocol is that the first thing a client does is run the APILEVEL command, and
after that authenticates. From there on the client is free to do whatever
is needed.

3 - Commands
------------

	APILEVEL
Syntax: APILEVEL [NUMBER]
Possible replies:	OK
			ERR Unsupported
Description: This command specifies the API level the client is compatible with.
	That is the version number of the spec. For the version 1 spec the client
	would issue a APILEVEL 1. It replies "ERR Unsupported" if the APILEVEL
	requested is not supported by the server. This command is required.
	If not issued the server will simply reply: "REFUSED NO_APILEVEL"
	to all commands.

	-=-

	AUTH
Syntax: AUTH [USERNAME] [PASSWORD]
Possible replies:	OK
			REFUSED ALREADY_AUTHED [as user]
			REFUSED IN_USE
			EXPIRED
			REFUSED
Description: This command authenticates a client as the user specified. This
	gives the client access to the useful commands. It replies OK when
	the client got successfully logged in as that user. If not issued
	after APILEVEL before running additional commands the server will simply
	reply: "REFUSED AUTHFIRST"

	-=-

	GETDATA
Syntax: GETDATA
Possible replies:	ERR NO_DATA
			ERR NO_MD5
			ERR MD5_FAILURE
			OK [MD5] [DATA]
Description: This command supplies the client with the data of the user it is
	authenticated as, from the server. It replies "ERR NO_DATA" when no data
	is available, "ERR NO_MD5" when there is no MD5 sum for the data available
	on the server and "ERR MD5_FAILURE" when there is data corruption on the
	server itself. When everything is fine it will reply "OK [THE MD5 SUM OF THE
	DATA] [THE DATA]". The data is an base64 encoded iCalendar file (or encrypted
	iCalendar file - depending upon the users settings).

	-=-

	SENDDATA
Syntax: SENDDATA [MD5] [LAST MD5] [DATA] [FORCE?]
Possible replies:	ERR FORMATERROR
			ERR LASTMD5_NOMATCH [LAST MD5 IN SERVER CONF] - [LAST MD5 FROM SENDDATA COMMAND]
			ERR MD5_MISMATCH # [MD5 OF RECIEVED DATA] [MD5 FROM SENDDATA COMMAND]
			ERR WRITEFAILURE
			OK
Description: This command is used to upload new data to the server. The syntax is
	SENDDATA [MD5 SUM OF DATA PORTION] [LAST MD5 UPLOADED] [DATA] [FORCE?].
	LAST MD5 UPLOADED is either an MD5 sum or the value UNDEF (for undefined, ie.
	nothing uploaded before). DATA is an base64 encoded iCalendar file.
	If FORCE is true then it disables certain on-server sanity checks (such as
	verification between last md5 in senddata and last md5 in server conf).
	It replies FORMATERROR when the SENDDATA line syntax is invalid, LASTMD5_NOMATCH
	when the last md5 supplied doesn't match the one in the server config, MD5_MISMATCH
	if the recieved data doesn't match the recieved MD5 sum and WRITEFAILURE if 
	the server couldn't write the new data to disk. OK is replied if the transfer
	was successful.