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.