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])
4. data = cgi:getData()

## DESCRIPTION

The functions 1...3 give access to data that was posted by a client in a HTTP POST, PUT or PATCH request, using either of the content-types application/x-www-form-urlencoded or multipart/form-data.

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.

The function 4 must be used to access any other content-type that was posted by a client. In that case, the posted data is returned as an unmodified string. This function returns always nil if the data was using either of the content-types application/x-www-form-urlencoded or multipart/form-data.

## 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