AOLserver C Module Development

$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/c-module.html,v 1.2 2002/09/26 19:51:33 kriston Exp $

AOLserver can be extended by loading one or more C modules dynamically. You write these modules using your ordinary C code development environment and compile them as shared library modules on Unix as described below.

Each module must include an initialization routine that typically calls one or more AOLserver C API functions for registering the procedures within your module. The procedures within your module can handle URLs (operation procedures) or do other special-purpose functions. To register a C function in your module with the AOLserver, pass a pointer to your function as an argument to one of the AOLserver C API registration functions.

Module initialization functions can also set up any state required by your functions. For example, the AOLserver database services module's initialization routine creates a pool of database connections.

Creating a Loadable Module

To create a dynamically loadable C module, compile your code and then link the resulting object module into a shared library module on Unix.

Your C source code file must include the ns.h header file, which can be found in the include subdirectory of the AOLserver home directory. To compile and link your module. It must have a Makefile that sources $NSHOME/include/Makefile.module. All build ruiles are kept in include/Makefile.module and include/Makefile.global. Makefile.module includes Makefile.global so you only need to include one. See the nsexample module for an excellent example.

Using a Loadable Module

For each library you would like to have the AOLserver load at startup time, add an entry in the server's Module section in the AOLserver configuration file. The format of a load entry is a nickname for the module, an equal sign, the filename of the module, and, optionally, the name of an initialization routine in parentheses. For example: mymodule=mymodule.so(MyInit)

Module filenames typically end in .so on Unix platforms. If the module filename is not an absolute path name, the AOLserver searches for the module in the bin subdirectory of the AOLserver home directory. The name of the initialization routine defaults to "Ns_ModuleInit".