Home Contents | # httpd:request | Httpd | Core4 Lua Event System

## SYNOPSIS

function httpd:request(cgi) ... end

## DESCRIPTION

This callback is called for each client request that is received. When called, the client request has been fully received. It is passed inside the cgi variable. No reply has been sent to the client yet.

Typically this callback is used to do basic authentication. With basic authentication, the browser asks the user for a user name and password in a pop-up dialog. For more information on how to do this see the description of the command cgi:authenticate().

Another use could be the management of client sessions. The callback implementation could check for a session cookie. If none is present it sets up a new session and sets the cookie with cgi:cookie(). If a cookie was sent by the client, the callback looks it up in a session cache and restores the session. In both cases, the session information can be stored into the variable cgi.session. Any further scripting called via a lua page (.lp) or lua script (.lua) file then has access to the session information.

The callback runs as a protected function (See pcall()). If there is a Lua exception while the callback runs, the webserver will send an error message to the client and end the request. The main Lua application will not exit.

It is possible to handle each request completely in this callback. This can be used to dynamically generate content on the fly or for using HTTP as a remote control protocol.

Start the response by sending a header with cgi:addheader(), cgi:contentheader() or cgi:htmlheader(), followed by the response data using cgi:write(). Other ways to process requests dynamically are using lua page (.lp) or lua script (.lua) files. See web server overview for more information.

## BUGS

Up to SDK version 2.18.0 the callback was not called when the requested file does not exist in the filesystem. A 404 error was reported automatically, preventing support for dynamically generated content. This was fixed in SDK 2.19.0.