1. What's this ?
2. Design goals
3. The basic idea
4. Program structure
5. Data structures
6. Class reference


1. What's this ?

This document contains information for those interested in the design and
implementation of Hagelslag.


2. Design goals

The demands that are defined are the following :
	1) Compatibility with the original windows GNUtella client.
	2) Scalability
	3) Flexibility
	4) Portability
	5) Robustness

Ad. 1 This means that it will comply with the standard of the protocol.
Ad. 2 The performance must not drop dramatically if a large number of files
	is shared or a large number of connections is made, or anything else
	suddenly is larger than it was.
Ad. 3. Everything must be tuneable as much as it can. If there is a feature,
	make sure it can be turned off or it's value can be changed to a
	sane value as the user wants that.
Ad. 4. Linux based OS'ses are nice, but there's more in this world.
Ad. 5. Protecting the program from whatever idiotic stuff other people send us.
And protect the program from whatever insane things a user can do - but NOT by 
limiting flexibility!!! What I mean is that it is sensible to make sure the TTL 
is not set to negative, it is NOT sensible to prevent a user from tampering
with it. There is nothing I hate so much as something that I can't change
something because someone decided that it is not user-friendly that there
are complicated configuration tools.


3. The basic idea

Everybody who took a programming class must be familiar to the following
cycle :
read input -- process data -- produce output

That just how hagelslag works :

1) read packets
2) process packets
3) forward packets / send reply

Hagelslag centers around the Backend, in a sense. 
This is the main program cycle :

while (!quit)
{
	if (userInput)
		process user input in Commander;

	poll the backend;
}

Polling the Backend is what keeps Hagelslag doing it's thing. What the
Backend does in a poll cycle looks like this :

{
	try to establish Connections for AUTO_CONNECTIONS in Backend;

	poll the Downloader;
	poll the FServer;

	listen for new connections in Networker;
	Handle new Connections in Backend;

	handle Pending (unestablished) Outgoing connections in Backend;

	Listen for new packets in Networker;
	
	while (there are unprocessed packets)
	{
		handle the incoming packet in Backend (and perhaps more);
		Make routing decisions concerning the packet in GnutellaRouter;
		delete the packet from memory;
	}

	Send outgoing data in Networker.
}

'Handle the incoming packet' is something which is different per packet. It
might be a search request (handled by the monitor & the FServer), an init
request (handled by the Backend itself), a search response (handled by the
Searchmanager) etc.


4. Program structure.

Well ... have a look at the picture 'Hagelslag Program Structure'. It shows
clearly how Hagelslag works, especially with the previous chapter in mind.
If this is not clear enough, please send me an e-mail.

There are two type of classes in Hagelslag : Classes with an 'acting'
character, and classes with a 'datastructure' character. Each class is
described in Chapter 6.


5. Data structures

Have a look at the picture 'Hagelslag Data Structures'. It shows the
inheritance of all classes with a datastructure character. Please use
chapter 6 as a reference.


6. Class reference

6.1 Acting Classes:

6.1.1 Highlevel:

Hagelslag.
Reads input from the user, calls Commander to process that and polls the
Backend. Also sends output to back to the user.

Commander.
Interprets what the user ordered and calls the Backend to do that. Then
creates output data, which is handled by Hagelslag.

Backend.
Forms an interface for the 6 underlying modules. Contains a DB with all
'Connection's and a DB with all known 'Host's. All AUTO_* support is here
too.

6.1.2 Lowlevel:

FServer:
The fileserver, the upload manager, whatever you wish to call it. this is
also the 'local database', all searches by other people are handled here.
Contains a DB with all shared 'Files' and one with all 'PushRequest's.

SearchManager:
Handles search responses, contains a DB with all 'SearchResult's.

Downloader:
Handles all our downloads. Contains a DB with all 'Download's.

GnutellaRouter:
Decides what packet should be send where. Contains a DB with all 'Mesg's.

Monitor:
Contains a list of 'Query's, which are things other people have requested.

Networker:
Does all network related stuff, such as listening for connections, reading
data from the net and sending data to other people.


6.2 Datastructure Classes:

DB:
The DataBase structure. Used to store data.

DBElement:
Base class of everything that is stored in a DB.

GnutellaPacket:
One packet in a Gnutella Network.

Packet:
A subclass of GnutellaPacket which contains mostly usefull functions to
buildt GnutelaPackets.

File:
Data of one file shared by us.

Host:
One Host on the Gnutella Network.

PushRequest:
Contains what file we should push to whom.

Mesg:
The signature of a GnutellaPacket. Used to make routing decisions.

SearchResult:
One result to a search request from us. One SearchResult holds data on only
one file, so one response takes possibly several SearchResults.

Connection:
The base class of types of connections. Contains two 'Buffer's, one ingoing,
one outgoing.

GnutellaConnection:
One GnutellaNetwork connection.

Transfer:
Base class of Upload and Download.

Download:
One of our downloads.

Upload:
One of our uploads.

ControlCentre:
There's just one ControlCentre in Hagelslag, lot's of things have a pointer
to it. It contains all global variables which are used to do thing flexible.

Path:
One shared path.

Buffer:
A buffer structure used in Connection to provide robust data transfer.

Query:
One thing that someone requested for.

TransferStatus:
Almost similar to Transfer, contains data from a Transfer object ready to be
transformed into data for the user by Commander.

LocalResult:
Something the FServer uses when processing an external search request.

6.3 Other files

Config.h:
Contains thing to tune during compilation time, such as the current version
number.

