DEVELOPING A CLIENT FOR DARXITE 0.4
===================================

It's very easy to develop a client for the Darxite system. The easiest way
to do so is to program in C and use the provided library, libdarxite, but it
is not actually required.

USING THE DARXITE LIBRARY
-------------------------

If you want to use the Darxite library, you have to find it first. If you've
still got your Darxite source tree, the library you should link with is
"library/libdarxite.a". If you've built it as a shared library, it will be
"/usr/lib/libdarxite.so". As you can't rely on the user building the library
as shared, the best thing to do is to slot your client into an appropriate
subdirectory of the Darxite tree.

You will also need to #include the file "darxite.h", which can be found in
the root of the Darxite tree.

At the beginning of your program, call the library function
"DX_ConnectClient(<name>)", where <name> is the name of your program. This
will try to connect to the daemon and will return the file descriptor of its
client control socket if it's successful, or -1 otherwise. If it fails, the
variable DX_errno will be set appropriately.

To close your connection to the daemon (at the end of your program), you
should call "DX_DisconnectClient()".

If you want to connect to a daemon running on another computer, just call
"DX_ConnectRemoteClient(<host>, <port>, <password>, <client name>). You
should ask the user for the password before connecting. To disconnect from
it, just call DX_DisconnectClient() as usual.

NOT USING THE LIBRARY
---------------------

If you don't want to use the library or are writing in a language other than
C/C++, you can still write a Darxite client.

When the Darxite daemon is run, it creates a socket file in /tmp with the
name in the format "darxsock.<user>", where <user> is the current login
name. For a client to talk to the daemon, it must connect to this socket.
Once the client is connected, the first data it should send is its name,
terminated by a newline.

To finish talking to the daemon, just close the socket. For a clean exit,
the client should also send a "Disconnect" command first (see below).

SENDING COMMANDS
----------------

To send a command to the daemon, simply use the C function "write" (or its
equivalent) with the file descriptor of the daemon's client control socket
(which you obtained from DX_ConnectClient()). The format for commands is a
single line terminated by a newline character. You should NOT send a
terminating NULL character. Commands are not case-sensitive.

After sending a command, you should call DX_GetResponse() to get the
response. A response string can be multi-line and is terminated by a NULL
character. Usually, a response begins with a 3-digit FTP-like error code.
The values these correspond to are explained in "darxite.h".

If you're not using the library, just use "select()" or "read()" on the
socket like any normal file.

DAEMON COMMANDS
---------------

Get <url> | <local path> | <login> | <password> | <flags>
    Adds <url> to the batch. Note that the daemon will return an error if it
    couldn't add the file to the batch, but NOT if it can't get the file.
    All the other fields are optional. The flags are explained below, in the
    "file format" section.

Disconnect
    Disconnect the client from the daemon. If you're using the library, you
    shouldn't use this command but should call DX_DisconnectClient().

Version
    Returns the version and release number of the daemon as a string.

Kill
    Kills the daemon. Used by "darxite -k".

Open <server>
    Connects to a server. Note that you shouldn't specify a path.

Close
    Disconnect from the currently connected server.

FTP <command>
    Send <command> as a raw FTP command and get the response.

List, Nlst
    Get a list of the current remote directory. NB: you should always
    use this and not "FTP LIST" or whatever, because that won't work.

Status
    Returns the status of the daemon - ie. the connected clients and
    the status of the files being transferred.

FileStatus
    Returns the status of the files in the batch. This can easily be parsed
    by the library function ParseFileStatus().

FastFileStatus
    Returns a faster file status response - ie. one based around file IDs.
    Parse it with DX_ParseFastFileStatus.

FileCount
    Returns a count of files in the batch and some other information. Use
    DX_ParseFileCount() to parse it.

Pause <url>
    Pauses a file.

Continue <url>
    Resumes transfer of a file.

Cancel <url>
    Cancels transfer of a file.

ReloadConfig
    Reloads preferences from /etc/darxiterc and ~/.darxiterc.
    
ReloadBookmarks
    Reloads the servers file ~/.darxite/servers.

NotifyOnEvent <event>
    Requests the daemon to send the client a message when <event> happens.
    Valid events are listed below.

DeleteFileLog
    Causes the daemon to delete the file log, if it exists.

HostForAlias <alias>
    Returns the host name of the alias (or host) you pass it.

(other, undocumented commands can be found in the file "daemon/clients.c"...
use at your own risk!)

EVENTS
------

The following events may be useful. Event response codes are detailed in
"darxite.h".

Event            Trigger condition
-----            -----------------
FileCompletion   When any file in the batch is complete
ConfigChange     When the daemon's configuration is changed
Redirection      When a file is redirected (via an HTTP 301 header)
Error            When there is an error
Exit             When the daemon exits
NewFile          When a new file is added to the batch

FILE FORMATS
------------

The format of the configuration files "/etc/darxiterc" and "~/.darxiterc" is
explained elsewhere. Information about the batch of files being transferred
is stored in the file "~/.darxite/batch", and information about the servers
that have been visited is stored in "~/.darxite/servers". The format of
these files is that each file (or server) has a line for its information,
split up into a number of fields. A "line" may occupy more than one physical
line, with continued lines ending with "\". Fields are separated by the "|"
character and one or more spaces, eg. "field1 | field2". Fields with spaces
in should be enclosed by quotes. With flag fields, a capital letter disables
a flag, a lower-case letter enables it.

Batch file format
-----------------

In general, most clients shouldn't need to access this file directly. The
information stored about each file is:

<url> | <local path> | <login> | <password> | <flags> | <total size>

Most of these fields are self-explanatory. If <login> and <password> are not
present, then "anonymous" will be used. Valid flags are:
b - do a "reget" - get the file from the beginning (the default for uploads)
c - resume transferring the file, don't reget (the default for downloads)
d - download a directory recursively
e - force massive download
E - force massive download off
l - download all links within <file>
m - enable auto-mirroring system for this file
M - disable auto-mirroring
n - send another response when the file's complete
p - the file is paused - ie. it shouldn't be transferred yet
r - rename file while it's being transferred
R - don't rename the file
s - spool the file and copy when it's complete
S - don't spool the file
v - the file is part of a "massive download" session
w - enable auto-bookmarking of the server
! - scramble the local filename
The "total size" value is set automatically by the daemon.

Server file format
------------------

This file contains information about visited servers, like an address book
or bookmark list. In general, most clients shouldn't need to access this
file directly. The information stored about each server is:

<url> | <login> | <password> | <alias> | <comment> | <ping> | <flags> |
<mirrors>

The "ping time" and "flags" fields are currently unused. Most of the other
fields are self-explanatory. The "mirrors" field contains a list of servers
that are mirrors for this one, with each server being separated by spaces.

Client file format
------------------

This file contains information about installed clients. In general, most
clients shouldn't need to use this file directly. The DX_ReadClientDB
function will read the client database files and place them in a linked
list. The format of the file is:

<name> | <path> | <type> | <description>

Where "type" is the sort of client it is. Current types are "util",
"cmdline", "gtk", and "gnome".

LIBRARY FUNCTIONS
-----------------

void DX_SayHello(void);
    Prints out "Hello". Useful for testing the library.

int DX_ConnectClient(const char *name);
    Connects a client called "name" to the daemon. Returns the file
    descriptor of its socket, or -1 on failure, with DX_errno set
    appropriately.

int DX_ConnectRemoteClient(const char *host, int port, const char *name);
    Connects a client to a daemon running on a remote host. Same as above.

int DX_DisconnectClient(int fd);
    Disconnects the client using the socket with file descriptor fd.
    
const char DX_GlobalConfigPath(void);
    Returns a const string containing the pathname of the global darxiterc
    file; typically "/usr/etc".  This string is const; it cannot be modified
    nor free()d.

const char DX_BinPath(void);
    Returns a const string containing the pathname of the darxite binary;
    typically "/usr/bin".  This string is const; it cannot be modified nor
    free()d.

void DX_ReadConfigFiles(void);
    Reads the config files "/etc/darxiterc" and "~/.darxiterc" and stores
    the values from them in a number of variables prefixed with "DX_".

int DX_GetResponse(int fd, char *response, int response_max, int timeout);
    Gets the response to a command from the daemon. This is a BLOCKING call
    that returns when the response is complete or after <timeout> seconds.

int DX_ParseFileStatus(const char *status_line, char *protocol,
                       char *server, int server_max, char *path,
                       int path_max, char *local_path, int local_path_max,
		       int *current_size, int *total_size, int *total_time,
                       int *rate_overall, char *activity, int activity_max);
    A utility function that will parse the result of a "FileStatus" command
    into its different fields, and save the result in the provided variables.
    
int DX_ParseUrl(const char *url, char *protocol, char *server,
                 int server_max, char *path, int path_max);
    A utility function that parses a URL into its constituent parts and
    saves them in the variables provided.

char *DX_ReadFileLine(char *s, int size, FILE *stream);
    Reads a line from a Darxite config file. Should probably not be used by
    clients.
    
char *DX_StripComments(char *line);
    Strips comments from a Darxite config line. Shouldn't be used by clients.
    
char *DX_GetNextField(char *line);
    Gets the next field in a Darxite config line. Probably shouldn't be used
    by clients.

int DX_ReadClientDB(DX_ClientInfo **client_list);
    Reads the client database. A linked list in the format specified in
    darxite.h will be created, containing information about all installed
    clients. The information is read from the files "/etc/darxite-clients"
    and "~/.darxite/clients".

int DX_FindClients(const char *name, const char *type,
                   DX_ClientInfo *search_clients,
		   DX_ClientInfo **found_clients);
    Finds certain clients in a previously read clients database. All clients
    with name "name" and type "type" will be returned in "found_clients". If
    either "name" or "type" is NULL, any client will be returned.
    
void DX_FreeClientList(DX_ClientInfo *client_list);
    Frees the memory allocated for a client list.

Activity values
---------------

When the status-getting commands are used, one field of the reply is
"activity", which represents what's happening to the file at that time. The
format of this field is not fixed, so don't rely on it! But at the moment,
the following values may be returned in it:
 - "Sleeping" (the file is not being transferred at the moment)
 - "Paused" (the file is paused)
 - "Complete" (the file is complete - you should never get this)
 - "Despooling file..." (the file is complete and is being despooled)
 - "Preparing for data transfer..." (the file is starting download)
 - "Transferring file" (the file is being downloaded)
 - "Getting file size..." (getting file size during start of transfer)
 - "Looking up host x" (looking up a host at start of transfer)
 - "Connecting to host..." (after it's been looked up)
 - "Connected; waiting for reply..." (sometimes takes a while)
 - "Log in as x..." (trying to log in to the host as x)
 - "Sending password..." (the next step)

Completion reason values
------------------------

Here is a list of some values that may occur in the "reason" field of a
file's entry in the file log. They also appear as a field in a
"FileCompletion" event response. In general, they provide more information
than a standard FileStatus "Complete" response.
 - "File complete" (standard "OK" error message)
 - "File cancelled"
 - "Couldn't log in" (invalid user/password)
 - "Recursive transfer started"
 - "Error getting file size" (should never happen!)
 - "File does not exist"
 - "File is zero-length" (we don't bother transferring it)
 - "Couldn't get file" (RETR command failed)
 - "File moved" (we are following an HTTP 301/302 header)
 - "Write error" (should never happen!)