cfgfiles.specs.txt

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

'cfgfiles.cpp' 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
--------
The code of 'cfgfiles.cpp' is responsible for opening config files and
extracting the commands and it's parameters. All config files in the
proxy project consist of commands and their parameters. The format is:

command[space]para1[comma]para2[comma]...

Only one open config file at a time can be handled by this module!


Functions
---------
There are 4 functions which can be accessed by all modules that include
cfgfiles.h (exported functions):

OpenConfigFile()
ReleaseConfigFile()
GetNextFullCommand()
ReleaseCommand()


OpenConfigFile()
----------------
This function takes one parameter: the path to the config file to be
opened. It reads the full contents of the file and saves it in memory.

This function MUST be called to initiate the working with a 
config file. After its call the other three functions may be used.


ReleaseConfigFile()
-------------------
Frees all memory which was allocated to store the file contents. After
calling this function, GetNextFullCommand() and ReleaseCommand() MUST
NOT be called anymore, unless another config file is opened via
OpenConfigFile().


GetNextFullCommand()
--------------------
This function returns a COMMAND struct (i.e. a command string and an
array of parameters) for the next command in the current config file.

It does so by first calling GetNextLine() to retrieve the next full
line in the current config file, and then GetFullCommand() which
extracts a complete command (a COMMAND struct) from a given line.


ReleaseCommand()
----------------
As the program allocates extra memory in each call of 
GetNextFullCommand() we need to let the module free this memory after
processing a command. 

This function takes a single parameter, a COMMAND struct, and frees
all related memory. The COMMAND struct may not be used anymore after
calling this function.