Creating Appweb Modules

Appweb supports extension modules that can augment the capability of Appweb by adding new features, handlers, protocols or any arbitrary code.

Appweb includes four loadable modules: CGI, ESP, PHP and SSL. The core appweb HTTP server includes some basic document serving functionality, but modules are used to extend the core with loadable web frameworks and custom handlers.

This document describes the Appweb Module Interface and how to create Appweb modules. The Appweb Module interface supports both dynamically loaded and statically linked modules from a single "C" code base.

Overview

To create an Appweb module, you must create an initialization function that is called when Appweb loads your module. This must be named according to the form:

maNameInit(Http *http, MprModule *module)

where Name is the name of your module. For example: maCgiHandlerInit is the library initialization entry point for the cgiHandler. Note: The first letter must be upper case. This function will be called immediately after loading the module code.

The init function is passed a reference to the Http service object and a module object for this module.

int maSimpleModuleInit(Http *http, MprModule *mp)
{
    HttpStage   *handler;
    if ((handler = httpCreateHandler(http, "simpleHandler")) == 0) {
        return MPR_ERR_CANT_CREATE;
    }
    handler->open = openSimple;
    handler->close = closeSimple;
    handler->start = startSimple;
    return 0;
}

You can put any custom code in the initialization function. Often a module will create a request handler or request pipeline filter. If you call mprSetModuleFinalizer you can register a callback to run before the module is stopped or unloaded.

Modules can be loaded at startup in response to the LoadModule Appweb configuration directive. You can also load modules at run-time via the maLoadModule "C" API.

To package your module, you must create a DLL/shared library containing your module. On Windows, you also must export the initialization function. If you want to statically link your module, you need to ensure the main program explicitly calls your initialization function during its initialization.

More Info

See the samples/simple-module source code sample for a working module example.