Next Previous Contents

1. Linuxconf's components

The technical documentation is organised by directory. This document is an overview. You may want to browse through the following documents to learn more.

This document is using cross-reference as much as possible to point you inside the above documents.

1.1 General purpose

These are the various objects and functions used throughout Linuxconf and its modules.

Strings and arrays

Linuxconf makes heavy use of the SSTRING and ARRAY objects to store information. The user interface expects its input in these forms.

The SSTRING is a general-purpose text container which has no size limitations. The content is allocated on the fly.

The SSTRINGS is a SSTRING container. It is based on the ARRAY object so it can grow without limit.

Most table in Linuxconf are defined with the ARRAY object. This object is not used directly. Most container classes are derived from this objects.

User interface

The user interface in Linuxconf is driven by the DIALOG object. This toolkit uses a classical model, often called modal. It is very simple to use and yields dialogs that

Here is a small example

        void editfoo()
        {
            DIALOG dia;
            SSTRING name,phone,fax,email;
            dia.newf_str ("Your name",name);
            dia.newf_str ("Phone number",phone);
            dia.newf_str ("Fax number",fax);
            dia.newf_str ("email",email);
            int nof = 0;
            while (1){
                MENU_STATUS code = dia.edit ("title"
                    ,"A small explanation of the dialog\n"
                     "that spans multiple line if needed"
                    ,help_nil   // Some help file object
                    ,nof);
                if (code == MENU_ESCAPE || code == MENU_CANCEL){
                    break;
                }else{
                    // We must validate the input
                    // the SSTRING variable now contain the input
                    if (all is fine){
                        break;
                    }
                }
            }
        }
        

Privileges

One may give the ability to manage some areas of a Linux server to an ordinary user. This is done with the PRIVILEGE object. Privilege object may be defined/added very easily and the user account dialog is automatically updated to manage this privilege.

Privileges are tested with the function perm_access() like this

        PRIVILEGE *p;
        if (perm_access(p,"manage this feature")){
            // Ok, we can do it
        }
        

Privileges are often used with the CONFIG_FILE object which will limit access/updates to a file based on privileges.

A privilege is simply defined like this

        static PRIVILEGE p_rootequiv ("rootequiv"
            ,P_MSG_U(T_PRIVROOTEQUIV,"SuperUser equivalence")
            ,P_MSG_U(T_PSYSCONTROL,"0-General system control"));
        

and used later. In this example, a privilege named "rootequiv" (this is the key used to uniquely identify it), will be presented in the section "General system control" of the user account dialog and the privilege title is "SuperUser equivalence".

By using the P_MSG_U macro, this make the privilege presentation text fully translatable.

Configuration files

The object CONFIG_FILE is handy to access various configuration files. By using it you are gaining

By using the CONFIG_FILE, you are simplifying your code and making it less error prone.

Help files

Each help file must be defined by a HELP_FILE object. HELP_FILE objects are simply defined (normally static variables) and passed as argument to various user interface functions.

An HELP_FILE is simply defined by providing two strings: A subdir name and the help file name. For example, the help file for the NIS management in the netconf project is defined like this:

        static HELP_FILE help_nis ("netconf","nis");
        

Managing the /etc/conf.linuxconf file

A set of function are provided to manage the file /etc/conf.linuxconf. This file is an ASCII database where each record is stored in a single text line. This format is handy. It provide the following advantages

Managing file like /etc/conf.linuxconf

Here is the API of the CONFDB object. conf.linuxconf is itself managed by a CONFDB object. The application may wish to store various information in a specific file instead of the general conf.linuxconf file. This is done for example for the PPP dialout configurations. Each configurations is stored in a separate file so they can be shared easily.

Misc functions

Coming soon ...

1.2 Application specific

User accounts and groups

Various objects are used to deal with user accounts, including virtual email accounts. Check out the object USER, USERS, GROUP, and GROUPS.

The class USERACCT_COMNG is useful to extend the user account dialog (and few others) with various field. By sub-classing it, you are allowed to add field, validation and can save the result the way you see fit. You are also informed if the account was deleted.

1.3 Module API

A Linuxconf's module is just a normal shared object. All supplied modules are includes in the modules subdirectory of the source tree. Pick one as an example. Modules are usually small (< 1000 lines of code).

The share object must derive an object from the LINUXCONF_MODULE class and override various virtual function. When done properly, a user can't tell if one part of Linuxconf is implemented as a module or as builtin functionality. Modules are sharing the same APIs as any other part of Linuxconf. By overriding some member functions of the LINUXCONF_MODULE class, a module is allowed to complete the processing of various aspects of Linuxconf.

1.4 Inter-module APIs

The inter-module API (see MODULE_API) is a technologu allowing one to define an API, implement it in a module and use it in another. The client module (or linuxconf's core) can test for the availability of an implementation (Is there a module installed that implement this API) and then use it like a simple function set.


Next Previous Contents