	GOOL	Alpha
	*************
	written by l0om	
	innate[@7]gmx.d3
	WWW.EXCLUDED.ORG
	*************

		0x1	Datentypen
			0x11	goo_t
			0x12	cli_ans
		0x2	Funktionen
			0x21	init_goo
			0x22	goo_cli
			0x23	goo_cli_set
			0x24	goo_cli_req
			0x25	goo_cli_cnt
			0x26	goo_results
			0x27	goo_prnt_er
			0x28	delete_goo
		0x3	Anmerkungen
			0x31	zu "goo_results"




------------]0x1	Datentypen




0x11	goo_t :

	typedef struct _goo_t {
		u_char resultc;			//last received result code
		int goo_results;
		struct _goo_client *cli;	//the client list
	} goo_t;


	resultc: 	Der result-Wert 
	goo_results: 	Der Message-Queue an den die Client Antworten gesendet werden
	cli:		Verkettete Liste mit Clientinformationen

0x12	cli_ans :

	typedef struct {
		long mtyp;
		u_char resultc;			//result code
		char data[10][URLLEN];		//the received urls
		char urls;			//have read this much results
		u_long	goo_res;		//results 
		char req[MAXREQ];
	} cli_ans;

	resultc:	Der result-Wert des Clients, der die Antwort gesandt hat
	data:		Wenn URLS angefordert wurden, sind diese hier gespeichert
	urls:		Wenn URLS angefordert wurden, ist hier die Anzahl der URLS
			zu finden; maximal 10 pro Antwort
	goo_res:	Wenn RESULTS angefordert wurden, dann ist hier die Anzahl
			der Google-Results zu finden
	req:		Hier ist der Request-String zu finden, der an den Client 
			gerichtet und bearbeitet wurde.





------------]0x2	Funktionen




0x21	init_goo
goo_t	init_goo()

	Funktion:
		Alle Funtionen von "gool" benötigen einen initialisierten "goo_t"
		Datentypen, der bei Erfolg als Rückgabewert geliefert wird.
	Rückgabewert:
		Erfolg: einen initialisierten "goo_t" Datentyp.
		Fehler: einen "goo_t" Datentyp; result-Werte ALLOC_ERR oder MQ_ERR.

0x22	goo_cli
int	goo_cli(int ncli, goo_t *ginf)

	Parameter:
		ncli: Anzahl der zu erzeugenen Clients
		ginf: erfolgreich initialisierter "goo_t" Datentyp
	Funktion:
		Alle Aktionen, die sich an Google richten, werden als Aufträge an
		die Clients gesendet. Diese Clienten sind voneinander unabhängig,
		arbeitetn parallel zueinander und können mit dieser Funktion 
		erstellt werden.
	Rückgabewert:
		Erfolg: liefert die Anzahl der erzeugten Clients
		Fehler: liefert 0; result-Werte FAILD, MQ_ERR oder FORK_ERR
	Note:
		- Diese Funktion kann bisher nur einmal aufgerufen werden und 
		  liefert beim zweiten aufruf FAILD.
		- Der erste Client trägt die ID 1 der zweite die ID 2...

0x23	goo_cli_set
void	goo_cli_set(int cli, u_char opt, void *data, goo_t *ginf)

	Parameter:
		cli: ID des zu konfigurierenden Clients
		opt: Gewünschte Option, die gesetzt werden soll
		data: Mögliche Parameter für bestimmte Optionen
		ginf: erfolgreich initialisierter "goo_t" Datentyp
	Funktion:
		Alle erzeugten Clients können ständig konfiguriert werden.
	Rückgabewert:
		Erfolg: result-Wert SUCCESS
		Fehler: result-Werte UNKNOWN oder NO_SUCH_CLI
	Note:
		Optionen:
			GETRESLT	<Kein Parameter>
			Client liefert die Anzahl der Google-Results als "long"	

			GETURLS		<Kein Parameter>
			Client liefert X URL Suchergebnisse 

			SETPRXY		<proxy:port>
			Weise einem Client einen Proxy zu
				zb:
				goo_cli_set(1, SETPRXY, "proxy.anony.net:1337", &goo);	

			NOPRXY		<Kein Parameter>
			Verwerfe aktuellen Proxy; nutze keinen 

			QUIT		<Kein Parameter>
			Beendet den Client

0x24	goo_cli_req
int	goo_cli_req(int cli, char *req, goo_t *ginf, u_int urls)

	Parameter:
		cli: ID des zu konfigurierenden Clients
		req: Der Request-String, der an Google geht
		ginf: erfolgreich initialisierter "goo_t" Datentyp
		urls: Anzahl der gewünschten URLs
	Funktion:
		Aufträge werden an erzeugte Clients zur abarbeitung gesandt
	Rückgabewert:
		Erfolg: liefert 1; result-Wert SUCCESS
		Fehler: liefert -1, bei fork() fehler; 
			liefert 0, falls der Client nicht gefunden wurde
			result-Werte FORK_ERR oder NO_SUCH_CLI

0x25	goo_cli_cnt
int	goo_cli_cnt(goo_t *ginf)

	Parameter:
		ginf: erfolgreich initialisierter "goo_t" Datentyp
	Funktion:
		Liefert die Anzahl der erfolgreich erzeugten Clients
	Rückgabewert:
		Erfolg: liefert die Anzahl der erfolgreich erzeugten Clients

0x26	goo_results
cli_ans	goo_results(cli_ans *rcv, goo_t *ginf)

	Parameter:
		rcv: "cli_ans" Datentyp um mögliche Ergebnisse zu speichern
		ginf: erfolgreich initialisierter "goo_t" Datentyp
	Funktion:
		Liest die Antworten der Clients
	Rückgabewert:
		Erfolg: (1) Liefert cli_ans; result-Werte ist der result-Wert des
			Clients, der diese Antwort gesandt hat. Der result-Wert
			trägt NICHT den Wert der Konstanten NOANSWERT
			(2) Liefert cli_ans; keine Clientantwort; result-Wert ist
			NOANSWER
		Fehler: 
			FATAL ERROR; Exit with 0
	Note:
		Diese Funktion ist nicht blockierend und kehrt sofort zurück.
		Es ist Aufgabe des Programmierers je nach Anforderung die Client
		Antworten zu lesen.  

		!! !  !   !Beispiele in EXAMPLE*.txt!   !  ! !!

0x27	goo_prnt_er
void	goo_prnt_er(goo_t *ginf)

	Parameter:
		ginf: erfolgreich initialisierter "goo_t" Datentyp
	Funktion:
		Überprüft den result-Wert und gibt entsprechenden String auf
		dem Monitor aus
	Rückgabewert:
		Keinen

0x28	delete_goo
int	delete_goo(goo_t *ginf);

	Parameter:
		ginf: erfolgreich initialisierter "goo_t" Datentyp
	Funktion:
		Gibt Speicher im Heap frei, beendet alle Clients und löscht
		Message-Queues
	Rückgabewert:
		Liefert 1




------------]0x3 Anmerkungen




0x31	zu "goo_results"

//	goo_results(cli_ans *rcv, goo_t *ginf)

Die Funktion "goo_results" wird benötigt um Antworten der Clients zu lesen, die
die gewünschten Anfragen bearbeitet haben. Wie unter 0x26 erwähnt, ist die Funktion
nicht-bockierend und kehrt sofort zurück. Einige Beispiele sollen die Funktionalität
verständlicher machen:

Der folgender Codefetzen gibt:

- gibt empfangene URLS zurück, falls goo_results Ergebnisse zurückliefert:

[...]
	ans = goo_results(&goo);
	if(goo.resultc != NOANSWER)   {  // read answers for 10 seconds
		if(goo.resultc != SUCCESS) {
			goo_prnt_er(&goo);
			return;	//break loop, exit function - whatever...
		}
		for(i = 0; i < ans.urls; i++)
			printf("%s\n",ans.data[i]);
[...]

- gibt empfangene RESULTS zurück, falls goo_results Ergebnisse zurückliefert:

[...]
	ans = goo_results(&goo);
	if(goo.resultc != NOANSWER)   {  // read answers for 10 seconds
		if(goo.resultc != SUCCESS) {
			goo_prnt_er(&goo); //no success - print error mess
			return;	//break loop, exit function - whatever...
		}
		printf("\t\t%s: %u results\n",ans.req,ans.goo_res);
		break;
	}
[...]

- wartet 20 Sekunden auf Client Antworten und endet

[...]
thetime = time(NULL);
while(1) {
	if(thetime < (time(NULL)-20)) break;
	ans = goo_results(&goo);
	if(goo.resultc != NOANSWER)   {  // read answers for 10 seconds
		if(goo.resultc != SUCCESS) {
			goo_prnt_er(&goo); //no success - print error mess
			return;	//break loop, exit function - whatever...
		}
		printf("\t\t%s: %u results\n",ans.req,ans.goo_res);
	}
	usleep(400000); //  <----  dont harm your cpu...
}
[...]

- wartet 20 Sekunden auf Client Antworten oder endet vorzeitig nach fünf 
	empfangenen Antworten

[...]
max = 0;
max += goo_cli_req(1, "kant", &test, 10);
max += goo_cli_req(1, "rousseau", &test, 10);
max += goo_cli_req(1, "hume", &test, 10);
max += goo_cli_req(2, "schiller", &test, 10);*/
max += goo_cli_req(2, "goethe", &test, 10);

thetime = time(NULL);
while(max) {			//wait max 5 results 
	if(thetime < (time(NULL)-20)) break;	//or wait for max 5 results
	ans = goo_results(&goo);
	if(goo.resultc != NOANSWER)   {  // read answers for 10 seconds
		if(goo.resultc != SUCCESS) {
			goo_prnt_er(&goo); //no success - print error mess
			return;	//break loop, exit function - whatever...
		}
		printf("\t\t%s: %u results\n",ans.req,ans.goo_res);
	}
	usleep(400000); // <---- dont harm your cpu...
}
[...]


