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 is itself comprised of thirteen different modules. The core appweb HTTP server cannot serve any pages or documents by itself. It relies on request handlers packaged as modules to actually serve HTTP requests. Other Appweb modules provide SSL, authorization and file upload.

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 *module)
{
    HttpStage   *handler;
    handler = httpCreateHandler(http, "testHandler", 0, module);
    if (handler == 0) {
        return MPR_ERR_CANT_CREATE;
    }
    handler->open = openTest; 
    handler->close = closeTest; 
    handler->start = startTest; 
    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.