Admpanel Backend Library API (libadmpanel) (v0.3)

The main concern of admpanel now is a Clean Implementation,
a clear API will greatly help and will help newcomers to
adapt rapidly to the project and start coding.

The Library will have 2 kind of functions, backend and 
utility, the first one is to help manipulate configurations, 
the second provides utilities for debuging, string handling,
parsing, etc.

All the calls should be very much the same, all backend
must have at least the following core functions:

* Load   (load configuration)
* Unload (cleanup, don't save)
* Save   (to file)
* Apply  (restart the server)

There is the need of diferencing between the loading
function of a backend and another, weŽll use prefix
acording the backend for this, for example the samba
backend will have the following core functions:

samba_load
samba_unload
samba_save
samba_apply

We need to define a standar parameters for this functions:

* Load functions should have a string param that will indicate
where is the config file, this must be optionally.
* Unload functions dosen't need any parameters, it must clean all
allocated memory, structures and file descriptors, without saving.
* Save function should have a string param defining where
the configuration will be saved, this must be optionall,
and by defaul the file opened in Load should be used to
save the configuration.
* Apply function dosenŽt need any parameter at all.

[v0.3]
* Load will only load main configuration, if some backends needs to
load more files, they can create a similar function to load but ending
with a word that indicates what are you loading, you can even load other
files on normal load, and use another function to modify them or access
them (not recomended). Example:

samba_load_users

--------------------------------------------------------------------------------
[v0.2]

A thing that should be decided before this document reaches
v1.0 should be the way that information will be handled,
if we gonna handle all internally, or just trow all the
data on a structure to the user. the last one sems quite
reasonable to me, as it will give flexibility without losing
the API reference.

[Sugestion from Vikas GP]

"As far as returning data to the user is concerned,
I feel that the backend must give the frontend the
ability to deal with higher level constructs such as
attribute names and values, instead of exposing
low-level details."

We may be able to accomplish this to a certain level using
constructs that contain the name of the attribute, the value
type, and the data itself, the problems will araise when handling
herarchical configurations with repeated parameter values.

struct apAttribute{
    char *attName;
    int  attType;
    void *attData;
};

We can also use the past example in combination with apList to create
a tweaked list of attributes, though it has the same problem that
last attempt, it dosen't handle herarchical data:

struct apAttribute{
    char *attName;
    int  attType;
    void *attData;
    apAttribute *next;
    apAttribute *prev;
};

Vikas is right, we should not expose the frontend to all the low level 
structures, they often end being a 20 or more elements structures...
it whould be quite a nightmare for frontend developers.

[v0.3]

Well after a while not working here are some new ideas i'm testing.

The use of a structure called Key or IKey (wich sounds prettyer :-)):

struct IKey{
       char *key;
       void *val;
       int type;
       char changed;
       struct IKey *next;
};

Key will be the name of the property, like 'workgroup', val can be the value
of that key, we can also use recursive keys, one key can hold another key
list; type is the type of value, i already maked a constants for basic types
wich can be bitwise compared with type to know how to deal with it and also
have more information, we can have enumeration as a type, and also point
on wich enumeration. Changed can help to optimize the saving time, bye only 
changing modified Keys. And as you see is a simple list, one way.

This works well on most backends, but there is some backends as NFS that
have a configuration will lots of parameters... It can be handled with
the Key scheme but is a bit akward.

I also have a sugesstion from one of the team members to use OO programing,
he maded a demo on Java, wich loaded the file and separated each param, it
was good, and i tried a bit of OO, heck, horrible, go back to SP... pew, ok
this change on structs is a bit like what you sugested but oriented to C,
wich is our languaje by excelence (that's pure personal preference only).

--------------------------------------------------------------------------------
[v0.2]

Admpanel Development Package

libadmpanel and frontends will be distrubuted in 2 diferent 
packages, as libadmpanel dosen't need any frontend to compile.

Also all headers should be stored on include/amdpanel/*
we need to decide if we gonna use an utility like pkgconfig
or make our own admpanel-config (something like that) or
force the user to install all in the same place...

[v0.3]

admpanel-config tool sounded good, already coded it, any complains?
suggestions about it?

The project will need some documentation too!, document everything
that is not standar from the api, such as extensions to load, or
specific behaviours of your functions, this is crucial.