Home Contents | # cgi:getData | Httpd/CGI | Core4 Lua Event System

## SYNOPSIS

1. data = cgi:getData(name)
2. result, error, errno = cgi:saveData(name, filename)
3. ok, error, errcode = cgi:installData(name [, callback])

## DESCRIPTION

All three functions give access to data that was posted by a client in a HTTP post request. Usually this is an uploaded file.

While normally all item values that where posted by the client are directly available in the cgi structure, this does not happen if the data is larger than 4096 bytes. This is done to avoid needles copying. Larger data blocks must be explicitly queried with one of the functions described here.

The first form simply returns the posted data as a Lua string. If there is no data under the given name, returns nil.

The function cgi:saveData() directly saves the received data to a file, bypassing Lua and avoiding to copy it more often than needed.

The last form cgi:installData() interprets the uploaded data as a firmware image and installs it onto the controller. During the lengthy install phase, the whole Lua program is suspended. This also means that no further HTTP requests are processed until the install phase ends. There is the option of passing a callback function which will be called during the install.

The callback is of the form function progress(httpd, cgi, percent, message). The first two arguments are the webserver instance httpd and the cgi request information that led to the firmware update. The value of percent indicates the percentage done of the install (0..100). The final value message is a short description of what the installer is currently doing.

## RETURN VALUE

cgi:getData() returns a copy of the posted data or nil if not found.

On success, the function cgi:saveData() returns the number of bytes written, cgi:installData() returns true.

On failure, three values are returned: nil, a string describing the error and the numeric error code.

## SEE ALSO

cgi