Embedded Gateway Interface™

The Embedded Gateway Interface (EGI) is an Appweb handler that responds to HTTP POST and GET requests. It is an efficient replacement for the Common Gateway Interface (CGI). The EGI allows you to execute code in your application in response to client submitted forms and URL requests. Whereas CGI always runs as an external process, EGI runs in-process with very little overhead. Furthermore, because it executes code in your application it is easy to selectively expose application logic via the EGI. The Embedded Gateway Interface was designed exclusively to be suitable for embedding in applications and devices. It provides a close binding between your application and the web page to be displayed making it very easy to process submitted requests.

However, In most cases you should use Embedded Server Pages instead of EGI or CGI as it offers more flexibility. ESP supports post-back which allows a single web page to function as both the displayable form and the processing logic when the user clicks submit.

Example EGI Web Form

A web page that will invoke an EGI form looks identical to its CGI counterpart. You declare a FORM HTML tag and specify the name of the EGI procedure via the action keyword.

<FORM action="/myEgiTest.egi" method=POST>

The complete web page would be:

<HTML><HEAD><TITLE>Simple EGI Test Form</TITLE></HEAD>
<BODY>
<h1>EGI Test Form</h1>
                                                                                
<FORM action="/myEgiTest.egi" method=POST>
<TABLE>
<TR>
    <TD>Name:</TD><TD><input type=text name=name size=50 value=""></TD>
</TR>
<TR>
    <TD>Address:</TD><TD><input type=text name=address size=50 value=""></TD>
</TR>
<TR>
    <TD ALIGN="CENTER">
        <input type=submit name=ok value="OK">
        <input type=submit name=OK value="Cancel">
    </TD>
</TR>
</TABLE>
</FORM>
</BODY>
</HTML>

The name of the EGI procedure is nominated in the defining C/C++ code. See How to Create EGI Forms below for details.

How to Create EGI Procedures

You can easily create Embedded Gateway Interface procedures in both C and C++ languages.

EGI Procedures in C++

To create an EGI procedure you subclass the MaEgiForm class and override the run method. The run method is called whenever a URL is invoked either by a POST request from a FORM/action directive in a HTML page or by a GET request to the URL. The EGI procedure is run by the EGI handler when it receives such a request.

For example, the following code fragment creates an EGI procedure.

#include "appweb/appweb.h"

class MyEgi : public MaEgiForm {
  public:
    MyEgi() : MaEgiForm("myEgi") {};
    ~MyEgi() {};
    void    run(MaRequest *rq, char *script, char *path, char *query, 
                char *postData, int postLen);
};

void MyEgi::run(MaRequest *rq, char *script, char *uri, char *query, 
    char *postData, int postLen)
{
    //
    //  For convenience, decode and convert each post data variable
    //  into the hashed environment
    //
    if (postLen > 0) {
        rq->createEnvVars(postData, postLen);
    }
    rq->write("<HTML><TITLE>simpleEgi</TITLE><BODY>\r\n");
    rq->writeFmt("<p>Name: %s</p>\n", rq->getVar("name", "-"));
    rq->writeFmt("<p>Address: %s</p>\n", rq->getVar("address", "-"));
    rq->write("</BODY></HTML>\r\n");
}

// Somewhere in the main program
new MyEgi();

You can also provide constructors and destructors for your class if you have persistent data structures that you need create.

NOTE: the run method is essentially stateless. Per session data storage is not explicitly supported by EGI though you can easily construct this yourself.

EGI Procedures in C

To create an EGI procedure in C, you create a function to execute when the EGI procedure is invoked and bind that function to the EGI URL name. For example, the following code fragment creates an EGI procedure that will be invoked when the URL /myEgi?name=Peter&Address=400+Lake+Wood+Drive is invoked.

#include "appweb/appweb.h"

static void myEgi(MaRequest *rq, char *script, char *uri, char *query,
    char *postData, int postLen)
{
    /*
     *  For convenience, decode and convert each post data variable
     *  into the hashed environment
     */
    if (postLen > 0) {
        maCreateEnvVars(rq, postData, postLen);
    }
    maWriteStr(rq, "<HTML><TITLE>simpleEgi</TITLE><BODY>\r\n");
    maWriteFmt(rq, "<p>Name: %s</p>\n", maGetVar(rq, "name", "-"));
    maWriteFmt(rq, "<p>Address: %s</p>\n", maGetVar(rq, "address", "-"));
    maWriteFmt(rq, "</BODY></HTML>\r\n");
}


// Somewhere in the main program
maDefineEsp("myEsp", myEspProc);

NOTE: the run method is essentially stateless. Per session data storage is not explicitly supported by EGI. Embedded Server Pages offers a complete Session Data solution.

Quick Nav