		HAGELSLAG PROGRAMMERS MANUAL

1. Introduction
2. Requirements
3. Background
4. Gui-Api specs
4.1 Functions/Methods
4.1.1 Control
4.1.2 Interaction
5. Gui-Api c++

Appendix A. Hagelslag talk


1. Introduction

This manual is intended form those people that which to create a GUI for
hagelslag.


2. Requirements

To create a GUI, you will need :
	- This manual
	- Some knowledge of gnutella
	- an environment in which you can open a TCP/IP connection and
	  parse strings.

That is all.

Hints :
1) Read the Users Manual.
2) Read the README
3) Read the GNUtella specs from http://capnbry.dyndns.org/gnutella
4) Read the rest of this manual


3. Background

The general idea behind the hagelslag-GUI-creating-principle is that you
create a program (the GUI) that communicates with a hagelslag process
running as a daemon through a tcp/ip connection. You put strings into the 
connection, you read strings out, interpret those, read user interaction,
decide what you need to do, put some strings in, read strings out etc.
Because the only requirement for your program is that you can open a tcp
connection and parse strings, you are free to choose how you wish to
develop your GUI. In other words, what you do is completely independent of
any development of hagelslag. There is of course one exception to the
rule. Hagelslag has a defined way of communicating, described in the next
chapter. If the gnutella specifications change so radically that I must
change this hagelslag-talk, I will. Of course I tried to make it so that
that is not very likely. Lately, the only changes have been additions, only
one or two minor changes.

Because each GUI would have to contain certain functions to translate from
function calls to strings and vice versa, I decided that it would be much
more productive to create a Gui-Api, which implements this
functionality. That way, Gui-development can proceed even faster.


4. Gui-Api

The Gui-Api offers some functions and some datatypes, or methods and
classes, depending on your view on programming.

The descriptions are kept as general as possible, to ensure problemfree
implementation in any language. My own implementation in c++ is in the
directory gui-api/c++. HagelslagInterface.h is the file to look at.


4.1 Functions/Methods

Basically, four functions are Control functions and return boolean, the
rest are Interaction functions and return Lists. All Interaction functions
return a hopefully empty ErrorList. The 'list' Interaction function
returns a List of possibly any type of List, depending on what you
requested. At the end of the List returned by the 'list' function, there
might be some ErrorList elements. If you prefer to see a practical
example, I recommend looking at the source, especially
HagelslagInterface.h in the directory gui-api/c++.


4.1.1 Control

function :	startHagelslag
parameters :	string 'path', integer port
description :	Starts a 'hagelslagd' process by executing the string
		'path'. If 'path' is invalid, /usr/bin/hagelslagd and
		/usr/local/bin/hagelslagd are tried as well. The
		hagelslagd process will listen on port 'port'.
return value :	boolean

function :	stopHagelslag
parameters :	
description :	Stops the hagelslagd process
return value :	boolean

function :	disconnectHagelslag
parameters :	
description :	Detach from the hagelslagd pocess, but keep it running.
return value :	boolean

function :	connectHagelslag
parameters :	
description :	Connect to the hagelslagd process. Must be called after
		a succesfull call to startHagelslag or after a succesfull
		call to disconnectHagelslag.
return value :	boolean


4.1.2 Interaction

function :	list
parameters :	listType type
description :	Returns a list of objects of the specified type, possibly 
		followed by a list of ErrorList objects.
return value :	List

function :	set
parameters :	parameter p, value v
description :	set parameter 'p' to value 'v'
return value :	ErrorList

function :	host
parameters :	HostCommand hostDo, integer whichHost, string hostArg
description :	Execute one of the following hostCommends :
		add host 'hostArg', 
		delete host 'whichHost' or
		connect to host 'whichHost'.
return value :	ErrorList

function :	download
parameters :	DownloadMethod howToDownload, integer whichResult
description :	Start or continue downloading a result
return value :	ErrorList

function :	share
parameters :	ShareCommand shareDo, string path
description :	add or delete path from the list of shares, or clear
		the entire list of shares.
return value :	ErrorList

function :	save
parameters :	SaveCommand saveDo
description :	save some variables to disk.
return value :	ErrorList

function :	scan
parameters :	
description :	scan the shared directories for files to share
return value :	ErrorList

function :	search
parameters :	integer minimumSpeed, string pattern
description :	issue a search on the GNUtella network
return value :	ErrorList

function :	version
parameters :	
desciption :	print one string with the hagelslag version and one string
		with the API version
return value :	Errorlist

In addition to the 'list' function, some 'macro's' are defined, for the
objects that require an offset. These functions may use a lot of resources!

functions : listAllHosts, listAllResults, listAllConnections
parameters :
description : return an entire list in stead of a limited list.
return value : List


Appendix A. Hagelslag talk

This chapter is a description of hagelslag talk. The following conventions
are used :

|		= means or
LABEL		= a previously defined string or character.
n		= a number (note : a string representing a number!)
str		= a string
param		= n | str
parameter	= <param[|param[|param]]>
<parameter>	= an obligatory parameter
[parameter]	= an optional parameter
*		= list

Still with us ? If not, read the following human understandable version.

HALLO	= "Hallo"	means	if you see HALLO I mean "Hallo"
HI	= "Hi"		means	if you see HI I mean "Hi"
GREETING = HALLO|HI	means	if you see GREETING I mean "Hallo" or "Hi"
REPLY	= "What's up?"|"Shut up!" 
			means 	if you see REPLY I mean "What's up?" or
					"Shut up!"
a|b			means	a or b
<n>			means	you must put a number here
<a|b>			means	you must put a or b here
[n]			means	you may put a number here
[a|b|c]			means	you may put a or b or c here
<HALLO>			means	you must put "Hallo" here
<HI>*			means	you must put 0 or more times "Hi" here
[GREETING]		means	you may put "Hallo" or "Hi" here

< <"say"> <"How are you"> ["today" | "doing"] > 

means : there MUST be a structure 
	in which
		- there MUST be "say"
		- there MUST be "How are you"
		- there MAY be "today" OR "doing"

get it ?
By the way, starting hagelslag and typing help might help you along the
way. The help has all the information that is here too.

COMMAND is the final definition of a command, something you put in
	hagelslag.

COMMAND_HOLDON is only available when hagelslag is compiled as a daemon.

4.2

SPACE		= ' '
TAB		= '	' (or '\t' in c)

NEWLINE		= '
'			(or "\r\n" in c)

DOTTEDHOST	= < <n> <"."> <n> <"."> <n> <"."> <n> <":"> <n> >

PROMPT		= "Hagelslag > "

BOOL		= <"YES"|"NO">

4.2.1
COMMAND		= <COMMAND_HOST|COMMAND_SET|COMMAND_HELP|COMMAND_LIST
			|COMMAND_DOWNLOAD|COMMAND_SEARCH|COMMAND_KILL
			|COMMAND_SHARE|COMMAND_SCAN|COMMAND_HOLDON
			|COMMAND_SAVE|COMMAND_QUIT>

4.2.2
COMMAND_HOST		= <KEYWORD_HOST> <SPACE> <HOST_PARAMETERS>

COMMAND_SET		= <KEYWORD_SET>	 <SPACE> <SET_PARAMETERS>

COMMAND_HELP		= <KEYWORD_HELP> <SPACE> <HELP_PARAMETERS>

COMMAND_LIST		= <KEYWORD_LIST> <SPACE> <LIST_PARAMETERS>

COMMAND_DOWNLOAD	= <KEYWORD_DOWNLOAD> <SPACE> <DOWNLOAD_PARAMETERS>

COMMAND_SEARCH		= <KEYWORD_SEARCH> <SPACE> <SEARCH_PARAMETERS>

COMMAND_KILL		= <KEYWORD_KILL> <SPACE> <KILL_PARAMETERS>

COMMAND_SHARE		= <KEYWORD_SHARE> <SPACE> <SHARE_PARAMETERS>

COMMAND_SCAN		= <KEYWORD_SCAN>

COMMAND_SAVE		= <KEYWORD_SAVE> <SPACE> <SAVE_PAREMETERS>

COMMAND_HOLDON		= <KEYWORD_HOLDON> 

COMMAND_QUIT		= <KEYWORD_QUIT> 

4.2.3
KEYWORD_HOST		= "host"

KEYWORD_SET		= "set"

KEYWORD_HELP		= "help"

KEYWORD_LIST		= "list"

KEYWORD_DOWNLOAD	= "download"

KEYWORD_SEARCH		= "search"

KEYWORD_KILL		= "kill"

KEYWORD_SHARE		= "share"

KEYWORD_SCAN		= "scan"

KEYWORD_SAVE		= "save"

KEYWORD_HOLDON		= "holdon"

KEYWORD_QUIT		= "quit"

4.2.4
HOST_PARAMETERS		= < 	<"add"> <SPACE> <DOTTEDHOST> |
				<"del"|"connect"> <SPACE> <n> >

SET_PARAMETERS		= <	<SET_PARAM> <SPACE> <n|str>	>

SET_PARAM		= <"MAX_TTL" | "DEFAULT_TTL" | "MAX_CONNECTIONS" |
				"ROUTING_TABLE_SIZE" | "MAX_HOPS" |
				"MAX_UPLOADS" | "MAX_DOWNLOADS" |
				"MAX_RESULTS" | "PORT" | "SPEED" |
				"DOWNLOAD_DIR" | "AUTO_PUSH" |
				"AUTO_CLEAR_COMPLETE" | "AUTO_CONNECTION" |
				"MAX_MONITOR_LENGTH" | "AUTO_PUSH" |
				"AUTO_CLEAR_COMPLETE" | "AUTO_SAVE_HOSTS" |
				"AUTO_CLEAR_RESULTS" | "MAX_HOST_CON_FAIL" |
				"MAX_FILES_SHARED" | "MAX_CON_ERROR">

HELP_PARAMETERS		= [<SPACE> <"help">]

LIST_PARAMETERS		= <	
		< <"results"|"hosts"> <SPACE> <n> > |
			<"downloads"|"uploads"|"connections"|
				"shares"|"options"|"stats"|"queries">
			  >

DOWNLOAD_PARAMETERS	= < <"start"|"continue"|"push"> <SPACE> <n> >

SEARCH_PARAMETERS	= < <n> <SPACE> <str> >

KILL_PARAMETERS		= < <"upload"|"download"|"connection"> <SPACE> <n> >

SHARE_PARAMETERS	= < <"add"|"del"> <SPACE> <str> | <"clear"> >

SAVE_PARAMETERS		= <"options"|"hosts"|"shares">

4.3 Answers.

ANSWER is the final definition of the answer that you may expect from
hagelslag. hagelslag will consider your connection a reason to confirm its
presence by sending a PROMPT to you.

4.3.1.
ANSWER		= <SPECIFIC_ANSWER> <PROMPT>

4.3.2.
SPECIFIC_ANSWER	= <HELP_ANSWER|LIST_ANSWER>

4.3.3.
HELP_ANSWER	=	<HELP|HELP_COMMAND_ANSWER>

HELP		= Just type "help" in the command line!
			That's what I wrote it for!
HELP_COMMAND_ANSER = See help

4.3.4.
LIST_ANSWER	= <	LIST_RESULTS_ANSWER|
			LIST_DOWNLOADS_ANSWER|
			LIST_UPLOADS_ANSWER|
			LIST_CONNECTIONS_ANSWER|
			LIST_SHARES_ANSWER|
			LIST_HOSTS_ANSWER|
			LIST_OPTIONS_ANSWER|
			LIST_STATS_ANSWER|
			LIST_QUERIES_ANSWER
		>

4.3.5.
LIST_RESULTS_ANSWER	= [RESULT]*

RESULT	= < <n> <" :"> <TAB> <filename> <NEWLINE> <TAB> <"FileIndex: ">
		<n> <TAB> <"Size: "> <n><TAB> <"Host: "> <HOSTDOTTED>
		<TAB> <"Speed: "> <n> <"."> <NEWLINE> >

LIST_DOWNLOADS_ANSWER	= < 
		<n> <TAB> <": "> <str> <" ---> "> <str> <NEWLINE>
		<TAB> <"State: "> <STATE> <"FileID: :> <n> <TAB>
		<n> <" / "> <n> <" bytes "> <n> <"."> <n> <" KB/s.">
		<NEWLINE>	
			>

LIST_UPLOADS_ANSWER	= <
		<n> <TAB> <": "> <str> <" ---> "> <str> <NEWLINE>
		<TAB> <"State: "> <STATE> <"FileID: :> <n> <TAB>
		<n> <" / "> <n> <" bytes "> <n> <"."> <n> <" KB/s.">
		<NEWLINE>	
			>

LIST_CONNECTIONS_ANSWER	= [ <n> <" : "> <HOSTDOTTED> <TAB> <"STATE: ">
				<STATE> <TAB> <"CID: "> <BOOL> <NEWLINE> 
				<"SEND: "> <n> <TAB> <"RECEIVED: "> <n>
				<TAB> <"DROPPED: "> <n> <TAB>
				<"OUTGOING: "> <BOOL> <NEWLINE> ]*

4.3.6.
STATE			= <	"INACTIVE"	|
				"CONNECTING"	|
				"CONNECTED"	|
				"LOGIN_SENT"	|
				"ACTIVE"	|
				"DONE"	|
				"CONNECTION FAILED"	|
				"LOGIN FAILED"	|
				"CONNECTION ERROR"	|
				"CANCELLED"	|
				"CLOSED"	|
				"INVALID"
			>

4.3.7.
LIST_SHARES_ANSWER	= [ <str> <NEWLINE> ]*

LIST_HOSTS_ANSWER	= [ <n> <TAB> <"Host: "> <HOSTDOTTED> <TAB>
				<"REAL: "> <BOOL> <TAB> <"CID: "> 
				<BOOL> <NEWLINE> ]*

LIST_OPTIONS_ANSWER	= <
				<"MAX_TTL "> 		<n>	<NEWLINE>
				<"DEFAULT_TTL "> 	<n> 	<NEWLINE>
				<"ROUTING_TABLE_SIZE "> <n> 	<NEWLINE>
				<"MAX_CONNECTIONS "> 	<n> 	<NEWLINE>
				<"MAX_RESULTS "> 	<n>	<NEWLINE>
				<"MAX_HOPS "> 		<n>	<NEWLINE>
				<"MAX_PUSH_REQUESTS "> 	<n>	<NEWLINE>
				<"MAX_UPLOADS "> 	<n> 	<NEWLINE>
				<"MAX_DOWNLOADS "> 	<n> 	<NEWLINE>
				<"MAX_HOSTS "> 		<n> 	<NEWLINE>
				<"PORT "> 		<n> 	<NEWLINE>
				<"SPEED "> 		<n> 	<NEWLINE>
				<"MAX_MONITOR_LENGTH ">	<n>	<NEWLINE>
				<"AUTO_PUSH ">		<n>	<NEWLINE>
				<"AUTO_CLEAR_COMPLETE "><n>	<NEWLINE>
				<"AUTO_CONNECTIONS ">	<n>	<NEWLINE>
				<"DOWNLOAD_DIR "> 	<str> 	<NEWLINE>
				<"DAEMON_PORT "> 	<n> 	<NEWLINE>
			>
LIST_STATS_ANSWER	= <
				<"Hosts: "> <n> <TAB> <"Files On Net: ">
				<n> <TAB> <"Size on Net: "> <n> <NEWLINE>
				<"Files Shared: "> <n> <TAB>
				<"Size Shared: "> <n> <NEWLINE>
			>
LIST_QUERIES_ANSWER	= [ <n> <SPACE> <str> <NEWLINE> ]*

4.4.
Error messages will be of the following form :
ERROR_MESSAGE	= < <"Error : "> [str] <NEWLINE> >
and may appear every now and then at the end of the output.

There. That's all. 
