Creating AppWeb Modules

Mbedthis AppWeb supports extension modules that can augment the capability of AppWeb by adding new features, handlers or protocols. In fact, you can put into an AppWeb modules almost anything -- only limited by your imagination.

AppWeb is itself comprised of 11 different modules. The core appWeb HTTP server cannot serve any pages or documents by itself. It relies on URL handlers delivered as modules to actually serve HTTP requests. Other AppWeb modules include SSL handling, a file upload capability and authorization handling.

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

See also how to configure loadable modules and the simpleModule sample for sample code implementing a simple Module.

Overview

To create an AppWeb module, all you need to do is create an instance of a subclass of the MaModule class. When instantiated, this class informs AppWeb about your module and makes it available for service.

If you want to statically link your module, you need to ensure the main program creates an instance of the MaModule class during its initialization.

You can also, optionally, make your module dynamically loadable. To do this, your code must do two more things:

• It must be packaged as a DLL / shared library
• The DLL must export a specific initialization function

The MaModule Class

You should subclass MaModule and create your own derived class so that you can optionally implement the constructor, destructor, start, stop and parseConfig methods. These methods will be invoked at various stages of the construction and initialization of your module.

The constructor will be called when your Module class is instantiated and the destructor method will be called when it is destroyed. The start method will be called when the AppWeb server is started in reponse to the start method of the MaServer being called. The stop method is usually called only when AppWeb is being shutdown. The parseConfig method is called to allow your method to implement custom parsing of the AppWeb configuration file.

The class definition for an AppWeb Module is described below. Note that all methods are optional.

class MyMod : public MaModule {
  public:
                    MyMod(void *handle);
                    ~MyMod();
    int             parseConfig(char *key, char *value, MaServer *server,
                        MaHost *host, MaAuth *auth, MaDir* dir,
                        MaLocation *location);
    int             start();
    void            stop();
};

The start and parseConfig methods should return 0 if successful. Otherwise they should return an MPR error code described in mpr.h. The parseConfig method is given a directive key and it's value. Other parameters provide context information for the directive.

Initialization Function

If your module is to be named MyMod, then you must create an initialization function of the name mprMyModInit. This function is used if you want your module to be a dynamically loadable module.

extern "C" int mprMyModInit(void *handle) 
{
  new MyMod();
}

The extern "C" is necessary so that the function will be exported without the usual C++ name mangling.  You can put any initialization in the initialization function, although it is usual to put most of this in the module contructor.