major update. server clean up and much added documentation

1 files changed, 411 insertions, 178 deletions

diff --git a/src/engine/e_system.h b/src/engine/e_system.h
index 38c2b076..0b1cbaab 100644
--- a/src/engine/e_system.h
+++ b/src/engine/e_system.h
@@ -1,4 +1,9 @@
 /* copyright (c) 2007 magnus auvinen, see licence.txt for more info */
+
+/*
+	Title: OS Abstraction
+*/
+
 #ifndef BASE_SYSTEM_H
 #define BASE_SYSTEM_H
 
@@ -9,10 +14,9 @@ extern "C" {
 #endif
 
 /* Group: Debug */
-/**********
+/*
 	Function: dbg_assert
-	
-	Breaks into the debugger based on a test.
+		Breaks into the debugger based on a test.
 	
 	Parameters:
 		test - Result of the test.
@@ -23,25 +27,24 @@ extern "C" {
 	
 	See Also:
 		<dbg_break>
-**********/
+*/
 void dbg_assert(int test, const char *msg);
 #define dbg_assert(test,msg) dbg_assert_imp(__FILE__, __LINE__, test,  msg)
 void dbg_assert_imp(const char *filename, int line, int test, const char *msg);
 
-/**********
+/*
 	Function: dbg_break
-	
-	Breaks into the debugger.
+		Breaks into the debugger.
 	
 	Remarks:
 		Does nothing in release version of the library.
 	
 	See Also:
 		<dbg_assert>
-**********/
+*/
 void dbg_break();
 
-/**********
+/*
 	Function: dbg_msg
 	
 	Prints a debug message.
@@ -55,15 +58,14 @@ void dbg_break();
 		
 	See Also:
 		<dbg_assert>
-**********/
+*/
 void dbg_msg(const char *sys, const char *fmt, ...);
 
 /* Group: Memory */
 
-/**********
+/*
 	Function: mem_alloc
-	
-	Allocates memory.
+		Allocates memory.
 	
 	Parameters:
 		size - Size of the needed block.
@@ -79,14 +81,13 @@ void dbg_msg(const char *sys, const char *fmt, ...);
 
 	See Also:
 		<mem_free>
-**********/
+*/
 void *mem_alloc_debug(const char *filename, int line, unsigned size, unsigned alignment);
 #define mem_alloc(s,a) mem_alloc_debug(__FILE__, __LINE__, (s), (a))
 
-/**********
+/*
 	Function: mem_free
-	
-	Frees a block allocated through <mem_alloc>.
+		Frees a block allocated through <mem_alloc>.
 	
 	Remarks:
 		- In the debug version of the library the function will assert if
@@ -95,10 +96,10 @@ void *mem_alloc_debug(const char *filename, int line, unsigned size, unsigned al
 	
 	See Also:
 		<mem_alloc>
-**********/
+*/
 void mem_free(void *block);
 
-/**********
+/*
 	Function: mem_copy
 		Copies a a memory block.
 	
@@ -113,37 +114,54 @@ void mem_free(void *block);
 	
 	See Also:
 		<mem_move>
-**********/
+*/
 void mem_copy(void *dest, const void *source, unsigned size);
 
-/**********
+/*
 	Function: mem_move
-		Copies a a memory block.
+		Copies a a memory block
 	
 	Parameters:
-		dest - Destination.
-		source - Source to copy.
-		size - Size of the block to copy.
+		dest - Destination
+		source - Source to copy
+		size - Size of the block to copy
 	
 	Remarks:
-		- This functions handles cases where source and destination is overlapping.
+		- This functions handles cases where source and destination
+		is overlapping
 	
 	See Also:
 		<mem_copy>
-**********/
+*/
 void mem_move(void *dest, const void *source, unsigned size);
 
-/**********
+/*
 	Function: mem_zero
-		Sets a complete memory block to 0.
+		Sets a complete memory block to 0
 	
 	Parameters:
-		block - Pointer to the block to zero out.
-		size - Size of the block.
-**********/
+		block - Pointer to the block to zero out
+		size - Size of the block
+*/
 void mem_zero(void *block, unsigned size);
 
-/* ------- io ------- */
+/*
+	Function: mem_comp
+		Compares two blocks of memory
+	
+	Parameters:
+		a - First block of data
+		b - Second block of data
+		size - Size of the data to compare
+		
+	Returns:
+		<0 - Block a is lesser then block b
+		0 - Block a is equal to block b
+		>0 - Block a is greater then block b
+*/
+int mem_comp(const void *a, const void *b, int size);
+
+/* Group: File IO */
 enum {
 	IOFLAG_READ = 1,
 	IOFLAG_WRITE = 2,
@@ -156,9 +174,7 @@ enum {
 
 typedef struct IOINTERNAL *IOHANDLE;
 
-/**** Group: File IO ****/
-
-/****
+/*
 	Function: io_open
 		Opens a file.
 
@@ -169,10 +185,10 @@ typedef struct IOINTERNAL *IOHANDLE;
 	Returns:
 		Returns a handle to the file on success and 0 on failure.
 
-****/
+*/
 IOHANDLE io_open(const char *filename, int flags);
 
-/****
+/*
 	Function: io_read
 		Reads data into a buffer from a file.
 
@@ -184,10 +200,10 @@ IOHANDLE io_open(const char *filename, int flags);
 	Returns:
 		Number of bytes read.
 
-****/
+*/
 unsigned io_read(IOHANDLE io, void *buffer, unsigned size);
 
-/*****
+/*
 	Function: io_skip
 		Skips data in a file.
 	
@@ -197,13 +213,12 @@ unsigned io_read(IOHANDLE io, void *buffer, unsigned size);
 		
 	Returns:
 		Number of bytes skipped.
-****/
+*/
 unsigned io_skip(IOHANDLE io, unsigned size);
 
-/*****
+/*
 	Function: io_write
-	
-	Writes data from a buffer to file.
+		Writes data from a buffer to file.
 	
 	Parameters:
 		io - Handle to the file.
@@ -212,10 +227,10 @@ unsigned io_skip(IOHANDLE io, unsigned size);
 		
 	Returns:
 		Number of bytes written.
-*****/
+*/
 unsigned io_write(IOHANDLE io, const void *buffer, unsigned size);
 
-/*****
+/*
 	Function: io_seek
 		Seeks to a specified offset in the file.
 	
@@ -226,10 +241,10 @@ unsigned io_write(IOHANDLE io, const void *buffer, unsigned size);
 		
 	Returns:
 		Returns 0 on success.
-*****/
+*/
 int io_seek(IOHANDLE io, int offset, int origin);
 
-/*****
+/*
 	Function: io_tell
 		Gets the current position in the file.
 	
@@ -238,10 +253,10 @@ int io_seek(IOHANDLE io, int offset, int origin);
 		
 	Returns:
 		Returns the current position. -1L if an error occured.
-*****/
+*/
 long int io_tell(IOHANDLE io);
 
-/*****
+/*
 	Function: io_length
 		Gets the total length of the file. Resetting cursor to the beginning
 	
@@ -250,10 +265,10 @@ long int io_tell(IOHANDLE io);
 		
 	Returns:
 		Returns the total size. -1L if an error occured.
-*****/
+*/
 long int io_length(IOHANDLE io);
 
-/*****
+/*
 	Function: io_close
 		Closes a file.
 	
@@ -262,10 +277,10 @@ long int io_length(IOHANDLE io);
 		
 	Returns:
 		Returns 0 on success.
-*****/
+*/
 int io_close(IOHANDLE io);
 
-/*****
+/*
 	Function: io_flush
 		Empties all buffers and writes all pending data.
 	
@@ -274,22 +289,77 @@ int io_close(IOHANDLE io);
 		
 	Returns:
 		Returns 0 on success.
-*****/
+*/
 int io_flush(IOHANDLE io);
 
-/**** Group: Threads ****/
 
-/*****
+/*
+	Function: io_stdin
+		Returns an <IOHANDLE> to the standard input.
+*/
+IOHANDLE io_stdin();
+
+/*
+	Function: io_stdout
+		Returns an <IOHANDLE> to the standard output.
+*/
+IOHANDLE io_stdout();
+
+/*
+	Function: io_stderr
+		Returns an <IOHANDLE> to the standard error.
+*/
+IOHANDLE io_stderr();
+
+
+/* Group: Threads */
+
+/*
 	Function: thread_sleep
-	
-	Suspends the current thread for a given period.
+		Suspends the current thread for a given period.
 	
 	Parameters:
 		milliseconds - Number of milliseconds to sleep.
-*****/
+*/
 void thread_sleep(int milliseconds);
 
-/**** Group: Locks ****/
+/*
+	Function: thread_create
+		Creates a new thread.
+	
+	Parameters:
+		threadfunc - Entry point for the new thread.
+		user - Pointer to pass to the thread.
+		
+*/
+void *thread_create(void (*threadfunc)(void *), void *user);
+
+/*
+	Function: thread_wait
+		Waits for a thread to be done or destroyed.
+	
+	Parameters:
+		thread - Thread to wait for.
+*/
+void thread_wait(void *thread);
+
+/*
+	Function: thread_destoy
+		Destroys a thread.
+	
+	Parameters:
+		thread - Thread to destroy.
+*/
+void thread_destroy(void *thread);
+
+/*
+	Function: thread_yeild
+		Yeild the current threads execution slice.
+*/
+void thread_yield();
+
+
+/* Group: Locks */
 typedef void* LOCK;
 
 LOCK lock_create();
@@ -299,7 +369,7 @@ int lock_try(LOCK lock);
 void lock_wait(LOCK lock);
 void lock_release(LOCK lock);
 
-/**** Group: Timer ****/
+/* Group: Timer */
 #ifdef __GNUC__
 /* if compiled with -pedantic-errors it will complain about long
 	not being a C90 thing.
@@ -308,71 +378,88 @@ __extension__ typedef long long int64;
 #else
 typedef long long int64;
 #endif
-/*****
+/*
 	Function: time_get
-	
-	Fetches a sample from a high resolution timer.
+		Fetches a sample from a high resolution timer.
 	
 	Returns:
 		Current value of the timer.
 
 	Remarks:
 		To know how fast the timer is ticking, see <time_freq>.
-*****/
+*/
 int64 time_get();
 
-/*****
+/*
 	Function: time_freq
-	
-	Returns the frequency of the high resolution timer.
+		Returns the frequency of the high resolution timer.
 	
 	Returns:
 		Returns the frequency of the high resolution timer.
-*****/
+*/
 int64 time_freq();
 
-/**** Group: Network General ipv4 ****/
+/*
+	Function: time_timestamp
+		Retrives the current time as a UNIX timestamp
+	
+	Returns:
+		The time as a UNIX timestamp
+*/
+unsigned time_timestamp();
+
+/* Group: Network General ipv4 */
 typedef int NETSOCKET;
 enum
 {
-	NETSOCKET_INVALID = -1
+	NETSOCKET_INVALID = -1,
+	
+	NETTYPE_INVALID = 0,
+	NETTYPE_IPV4 = 1,
+	NETTYPE_IPV6 = 2,
+	NETTYPE_ALL = ~0
 };
 
-typedef struct 
+/*
+typedef struct
 {
 	unsigned char ip[4];
 	unsigned short port;
-} NETADDR4;
+} NETADDR4;*/
 
-/*****
+typedef struct
+{
+	unsigned int type;
+	unsigned char ip[16];
+	unsigned short port;
+} NETADDR;
+
+/*
 	Function: net_host_lookup
-	
-	Does a hostname lookup by name and fills out the passed NETADDE4 struct with the recieved details.
+		Does a hostname lookup by name and fills out the passed NETADDR struct with the recieved details.
 
 	Returns:
 		0 on success.
-*****/
-int net_host_lookup(const char *hostname, unsigned short port, NETADDR4 *addr);
+*/
+int net_host_lookup(const char *hostname, NETADDR *addr, int types);
 
-/**** Group: Network UDP4 ****/
+/* Group: Network UDP */
 
-/*****
-	Function: net_udp4_create
-	
-	Creates a UDP4 socket and binds it to a port.
+/*
+	Function: net_udp_create
+		Creates a UDP socket and binds it to a port.
 
 	Parameters:
 		port - Port to bind the socket to.
 	
 	Returns:
 		On success it returns an handle to the socket. On failure it returns NETSOCKET_INVALID.
-*****/
-NETSOCKET net_udp4_create(NETADDR4 bindaddr);
+*/
+NETSOCKET net_udp_create(NETADDR bindaddr);
 
-/*****
-	Function: net_udp4_send
-	
-	Sends a packet over an UDP4 socket.
+/*
+	Function: net_udp_send
+		Sends a packet over an UDP socket.
 
 	Parameters:
 		sock - Socket to use.
@@ -382,177 +469,322 @@ NETSOCKET net_udp4_create(NETADDR4 bindaddr);
 	
 	Returns:
 		On success it returns the number of bytes sent. Returns -1 on error.
-*****/
-int net_udp4_send(NETSOCKET sock, const NETADDR4 *addr, const void *data, int size);
+*/
+int net_udp_send(NETSOCKET sock, const NETADDR *addr, const void *data, int size);
 
-/*****
-	Function: net_udp4_recv
-	
-	Recives a packet over an UDP4 socket.
+/*
+	Function: net_udp_recv
+		Recives a packet over an UDP socket.
 
 	Parameters:
 		sock - Socket to use.
-		addr - Pointer to an NETADDR4 that will recive the address.
+		addr - Pointer to an NETADDR that will recive the address.
 		data - Pointer to a buffer that will recive the data.
 		maxsize - Maximum size to recive.
 	
 	Returns:
 		On success it returns the number of bytes recived. Returns -1 on error.
-*****/
-int net_udp4_recv(NETSOCKET sock, NETADDR4 *addr, void *data, int maxsize);
+*/
+int net_udp_recv(NETSOCKET sock, NETADDR *addr, void *data, int maxsize);
 
-/*****
-	Function: net_udp4_close
-	
-	Closes an UDP4 socket.
+/*
+	Function: net_udp_close
+		Closes an UDP socket.
 
 	Parameters:
 		sock - Socket to close.
 	
 	Returns:
 		Returns 0 on success. -1 on error.
-*****/
-int net_udp4_close(NETSOCKET sock);
+*/
+int net_udp_close(NETSOCKET sock);
 
 
-/**** Group: Network TCP4 ****/
+/* Group: Network TCP */
 
-/*****
-	Function: net_tcp4_create
+/*
+	Function: net_tcp_create
 	
 	DOCTODO: serp
-*****/
-NETSOCKET net_tcp4_create(const NETADDR4 *a);
+*/
+NETSOCKET net_tcp_create(const NETADDR *a);
 
-/*****
-	Function: net_tcp4_set_non_blocking
+/*
+	Function: net_tcp_set_non_blocking
 
 	DOCTODO: serp
-*****/
-int net_tcp4_set_non_blocking(NETSOCKET sock);
+*/
+int net_tcp_set_non_blocking(NETSOCKET sock);
 
-/*****
-	Function: net_tcp4_set_non_blocking
+/*
+	Function: net_tcp_set_non_blocking
 
 	DOCTODO: serp
-*****/
-int net_tcp4_set_blocking(NETSOCKET sock);
+*/
+int net_tcp_set_blocking(NETSOCKET sock);
 
-/*****
-	Function: net_tcp4_listen
+/*
+	Function: net_tcp_listen
 
 	DOCTODO: serp 
-*****/
-int net_tcp4_listen(NETSOCKET sock, int backlog);
+*/
+int net_tcp_listen(NETSOCKET sock, int backlog);
 
-/*****
-	Function: net_tcp4_accept
+/*
+	Function: net_tcp_accept
 	
 	DOCTODO: serp
-*****/
-int net_tcp4_accept(NETSOCKET sock, NETSOCKET *new_sock, NETADDR4 *a);
+*/
+int net_tcp_accept(NETSOCKET sock, NETSOCKET *new_sock, NETADDR *a);
 
-/*****
-	Function: net_tcp4_connect
+/*
+	Function: net_tcp_connect
 	
 	DOCTODO: serp
-*****/
-int net_tcp4_connect(NETSOCKET sock, const NETADDR4 *a);
+*/
+int net_tcp_connect(NETSOCKET sock, const NETADDR *a);
 
-/*****
-	Function: net_tcp4_connect_non_blocking
+/*
+	Function: net_tcp_connect_non_blocking
 	
 	DOCTODO: serp
-*****/
-int net_tcp4_connect_non_blocking(NETSOCKET sock, const NETADDR4 *a);
+*/
+int net_tcp_connect_non_blocking(NETSOCKET sock, const NETADDR *a);
 
-/*****
-	Function: net_tcp4_send
+/*
+	Function: net_tcp_send
 	
 	DOCTODO: serp
-*****/
-int net_tcp4_send(NETSOCKET sock, const void *data, int size);
+*/
+int net_tcp_send(NETSOCKET sock, const void *data, int size);
 
-/*****
-	Function: net_tcp4_recv
+/*
+	Function: net_tcp_recv
 	
 	DOCTODO: serp
-*****/
-int net_tcp4_recv(NETSOCKET sock, void *data, int maxsize);
+*/
+int net_tcp_recv(NETSOCKET sock, void *data, int maxsize);
 
-/*****
-	Function: net_tcp4_close
+/*
+	Function: net_tcp_close
 	
 	DOCTODO: serp
-*****/
-int net_tcp4_close(NETSOCKET sock);
+*/
+int net_tcp_close(NETSOCKET sock);
 
-/*****
+/*
 	Function: net_errno
 
 	DOCTODO: serp
-*****/
+*/
 int net_errno();
 
-/*****
+/*
 	Function: net_would_block
 
 	DOCTODO: serp
-*****/
+*/
 int net_would_block();
 
-/*****
+/*
 	Function: net_init
 
 	DOCTODO: serp
-*****/
+*/
 int net_init();
 
+/* Group: Strings */
 
+/*
+	Function: str_append
+		Appends a string to another.
+	
+	Parameters:
+		dst - Pointer to a buffer that contains a string.
+		src - String to append.
+		dst_size - Size of the buffer of the dst string.
+		
+	Remarks:
+		- The strings are treated as zero-termineted strings.
+		- Garantees that dst string will contain zero-termination.
+*/
+void str_append(char *dst, const char *src, int dst_size);
 
-/* NOT DOCUMENTED */
-typedef void (*fs_listdir_callback)(const char *name, int is_dir, void *user);
-int fs_listdir(const char *dir, fs_listdir_callback cb, void *user);
-int fs_storage_path(const char *appname, char *path, int max);
-int fs_makedir(const char *path);
-int net_addr4_cmp(const NETADDR4 *a, const NETADDR4 *b);
-int net_socket_read_wait(NETSOCKET sock, int time);
-
-void mem_debug_dump();
-int mem_allocated();
+/*
+	Function: str_copy
+		Copies a string to another.
+		
+	Parameters:
+		dst - Pointer to a buffer that shall recive the string.
+		src - String to be copied.
+		dst_size - Size of the buffer dst.
 
-void *thread_create(void (*threadfunc)(void *), void *user);
-void thread_wait(void *thread);
-void thread_destroy(void *thread);
-void thread_yield();
-unsigned time_timestamp();
+	Remarks:
+		- The strings are treated as zero-termineted strings.
+		- Garantees that dst string will contain zero-termination.
+*/
+void str_copy(char *dst, const char *src, int dst_size);
 
-void swap_endian(void *data, unsigned elem_size, unsigned num);
+/*
+	Function: str_format
+		Performs printf formating into a buffer.
+		
+	Parameters:
+		buffer - Pointer to the buffer to recive the formated string.
+		buffer_size - Size of the buffer.
+		format - printf formating string.
+		... - Parameters for the formating.
 
-/* #define cache_prefetch(addr) __builtin_prefetch(addr) */
+	Remarks:
+		- See the C manual for syntax for the printf formating string.
+		- The strings are treated as zero-termineted strings.
+		- Garantees that dst string will contain zero-termination.
+*/
+void str_format(char *buffer, int buffer_size, const char *format, ...);
 
-/*typedef unsigned char [256] pstr;
-void pstr_format(pstr *str, )*/
+/*
+	Function: str_sanitize_strong
+		Replaces all characters below 32 and above 127 with whitespace.
+	
+	Parameters:
+		str - String to sanitize.
 
-void str_append(char *dst, const char *src, int dst_size);
-void str_copy(char *dst, const char *src, int dst_size);
-void str_format(char *buffer, int buffer_size, const char *format, ...);
+	Remarks:
+		- The strings are treated as zero-termineted strings.
+*/
 void str_sanitize_strong(char *str);
+
+/*
+	Function: str_sanitize
+		Replaces all characters below 32 and above 127 with whitespace with
+		exception to \r, \n and \r.
+	
+	Parameters:
+		str - String to sanitize.
+
+	Remarks:
+		- The strings are treated as zero-termineted strings.
+*/
 void str_sanitize(char *str);
+
+/*
+	Function: str_comp_nocase
+		Compares to strings case insensitive.
+	
+	Parameters:
+		a - String to compare.
+		b - String to compare.
+	
+	Returns:	
+		<0 - String g a is lesser then string b
+		0 - String a is equal to string b
+		>0 - String a is greater then string b
+
+	Remarks:
+		- Only garanted to work with a-z/A-Z.
+		- The strings are treated as zero-termineted strings.
+*/
 int str_comp_nocase(const char *a, const char *b);
+
+/*
+	Function: str_find_nocase
+		Finds a string inside another string case insensitive.
+
+	Parameters:
+		haystack - String to search in
+		needle - String to search for
+		
+	Returns:
+		A pointer into haystack where the needle was found.
+		Returns NULL of needle could not be found.
+
+	Remarks:
+		- Only garanted to work with a-z/A-Z.
+		- The strings are treated as zero-termineted strings.
+*/
 const char *str_find_nocase(const char *haystack, const char *needle);
+
+
+/*
+	Function: str_hex
+		Takes a datablock and generates a hexstring of it.
+
+	Parameters:
+		dst - Buffer to fill with hex data
+		dst_size - size of the buffer
+		data - Data to turn into hex
+		data - Size of the data
+
+	Remarks:
+		- The desination buffer will be zero-terminated
+*/
 void str_hex(char *dst, int dst_size, const void *data, int data_size);
 
+
+/*
+	Function: fs_listdir
+		Lists the files in a directory
+		
+	Parameters:
+		dir - Directory to list
+		cb - Callback function to call for each entry
+		user - Pointer to give to the callback
+	
+	Returns:
+		DOCTODO
+*/
+typedef void (*fs_listdir_callback)(const char *name, int is_dir, void *user);
+int fs_listdir(const char *dir, fs_listdir_callback cb, void *user);
+
+/*
+	Function: fs_makedir
+		Creates a directory
+	
+	Parameters:
+		path - Directory to create
+	
+	Returns:
+		DOCTODO
+	
+	Remarks:
+		Does not create several directories if needed. "a/b/c" will result
+		in a failure if b or a does not exist.
+*/
+int fs_makedir(const char *path);
+
+/*
+	Function: fs_storage_path
+		Fetches per user configuration directory.
+	
+	Returns:
+		DOCTODO
+	
+	Remarks:
+		- Returns ~/.appname on UNIX based systems
+		- Returns %APPDATA%/Appname on Windows based systems
+*/
+int fs_storage_path(const char *appname, char *path, int max);
+
+
+/*
+	Group: Undocumented
+*/
+
+int net_addr_comp(const NETADDR *a, const NETADDR *b);
+int net_addr_str(const NETADDR *addr, char *string, int max_length);
+int net_socket_read_wait(NETSOCKET sock, int time);
+
+void mem_debug_dump();
+int mem_allocated();
+
+void swap_endian(void *data, unsigned elem_size, unsigned num);
+
 typedef void (*DBG_LOGGER)(const char *line);
 void dbg_logger(DBG_LOGGER logger);
 void dbg_logger_stdout();
 void dbg_logger_debugger();
 void dbg_logger_file(const char *filename);
 
-IOHANDLE io_stdin();
-IOHANDLE io_stdout();
-IOHANDLE io_stderr();
-
 typedef struct
 {
 	int sent_packets;
@@ -561,6 +793,7 @@ typedef struct
 	int recv_bytes;
 } NETSTATS;
 
+
 void net_stats(NETSTATS *stats);
 
 #ifdef __cplusplus