csocket.specs.txt

JK Proxy Project - Version 0.1 ------------------------------ This was going to be a proxy serve

csocket.h specifications
-------------------------

This a more or less detailled description of what the code in this file
does, how it works and how it should be used.


Overview
--------
This header file defines the sockets base class which all socket
implementations in this project have to use. It defines the interface
that is used by all modules of the project to access sockets.


Requirements for socket implementations
---------------------------------------
Each socket implementation must implement 7 functions:

Connect()
Listen()
Close()
Send()
Sendsz()
GetPeerIP()
SetEventHandlers()

Below you find detailled descriptions what each of these functions
are supposed to do.


Connect(host, port)
-------------------
This function let's the object connect to a peer host (parameter 1) on
a certain port (parameter 2).

Listen(port)
------------
Starts listening for incoming connections on the port which is given
by the function's parameter.

Close(socket)
-------------
Closes a socket, meaning the connection which is currently established
using that socket.

Send(socket, data, length)
--------------------------
This function sends data from the buffer 'data' with the length
'length' to the connection on socket 'socket'.

Sendsz(socket, data)
--------------------
Pretty much the same as Send(), this function sends the zero-
terminated string 'data' to the connection on socket 'socket'.

GetPeerIP(socket)
-----------------
Returns a string containing the IP address of the peer on socket
'socket'.

SetEventHandlers(connect, accept, close, dataarrival, error)
------------------------------------------------------------
This function tells the socket class the function pointers of all
callback event handler routines. This socket class must save these
pointers and call those function whenever one of these events occurs.

About these five events:

- connect:		this event is called when a function to a peer server
				has been successfully established

- accept:		fires when an incoming connection was detected

- close:		called when a peer closes a connection

- dataarrival:	indicates that some data arrived, function contains
				pointer to data buffer and data length

- error:		event is called when a socket error occurs.