Embedthis 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.