Embedding Appweb

When extending and embedding Appweb in your application or system, you have three options:

1. Use the existing Appweb main program and extend Appweb via a loadable module.
2. Use the existing Appweb main program and extend Appweb via the ESP web framework.
3. Link the Appweb HTTP library with your application main program.

Extending via a Loadable Module

You can extend the Appweb server program by creating an Appweb loadable module. You do this by creating a shared library that contains your application and some Appweb module interface code. This module is then specified in the Appweb configuration file so that the Appweb program will load it. It requires about 10 lines of code to create an Appweb module.

Extending via ESP

The Embedded Server Pages (ESP) web framework allows the direct embedding of "C" language code in HTML web pages. This is the easiest way to invoke "C" APIs in your program. ESP also supports the loading of Model/View/Controller (MVC-based) applications. ESP will compile and load controller source code. Controllers provide an easy and efficient way to invoke "C" code when requests are made to certain URIs.

Embed the Appweb Library

You can link the Appweb library with your application to enable it to listen for HTTP requests and thus become a HTTP server itself. Embedding the Appweb library is easy and can be done with as little as one line of code.

The Appweb Server Program

The Appweb product includes a fully-featured HTTP server program that uses the Appweb HTTP library. This server (called appweb) is run by default when you install the Appweb binary distribution or run "make install" after building from source.

The Appweb server program is ideal for embedded systems as it offers the following features:

• High performance
• Extendable via loadable modules
• Deterministic memory footprint and CPU loads
• Configurable sandbox limits that control memory usage
• Monitored and managed by the Appweb manager process

Creating a Module

You can extend the Appweb program by creating a loadable module for your application code.

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

maNameModuleInit(MaHttp *http)

Where Name is the name of your module.

This initialization function must call the mprCreateModule API to register with Appweb.

int mprSimpleModuleInit(Http *http, MprModule *module)
{
    /* Put custom code here */
    return 0;
}

See Creating Appweb Modules for more details.

Embed the Appweb Library

You can link the Appweb HTTP library with your main program to enable it to function as a HTTP server itself. This is ideal if your application is large and/or has a complex I/O, eventing or threading paradigm.

Linking with the Appweb Library

To include the Appweb library in your program you need to do the following things:

1. Add #include "appweb/appweb.h" to the relevant source files.
2. Add the Appweb library to your Makefiles or Windows project files. This will mean adding libappweb.dll on Windows or libappweb.so on Unix.
3. Use one of the embedding APIs to create the HTTP server.

One Line Embedding

The following code demonstrates the one-line Appweb embedding API. This will create and configure a web server based on the "server.conf" configuration file.

#include "appweb/appweb.h"
int main(int argc, char** argv)
{
    return maRunWebServer("server.conf");
}

To build this sample and link with the Appweb library:

cc -o server server.c -lappweb

Full Control API

The Appweb library also provides a lower level embedding interface where you can precisely control how the web server is created and configured. This API also exposes the inner event and threading mechanisms.

This example creates a web server using the "server.conf" configuration file and will service events until terminated.

#include "appweb/appweb.h"
int main(int argc, char **argv)
{
    Mpr         *mpr;
    MaServer    *server;
    MaAppweb    *appweb;
    /*
     *  Initialize and start the portable runtime services.
     */
    if ((mpr = mprCreate(0, NULL, 0)) == 0) {
        mprError("Can't create the web server runtime");
        return 0;
    }
    if (mprStart() < 0) {
        mprError("Can't start the web server runtime");
        return 0;
    }
    appweb = maCreateAppweb(mpr);
    mprAddRoot(appweb);
    if ((server = maCreateServer(appweb, 0)) == 0) {
        mprError("Can't create the web server");
        return 0;
    }
    if (maParseConfig(server, "server.conf") < 0) {
        mprError("Can't parse the config file %s", "server.conf");
        return 0;
    }
    if (maStartServer(server) < 0) {
        mprError("Can't start the web server");
        return MPR_ERR_CANT_CREATE;
    }
    mprServiceEvents(-1, 0);
    maStopServer(server);
    mprRemoveRoot(appweb);
    mprDestroy(MPR_EXIT_DEFAULT);
    return 0;
}

More Details

For more details about the embedding API, please consult the Appweb API and the Native APIs.