Module: Upload

About this module

The Upload module encodes mailmessages and HTTP form upload

Supported protocols:

Interface overview and API documentation

Upload classes

The Upload classes (derived from Upload_Base) are used to construct and generate various forms of MIME formatted bodies for transmission either through HTTP (HTTP requests are based on the Upload classes), SMTP, NNTP or other formats.

Upload_Base maintains the list of headers and manages the overall generation process, while subclasses perform payload operations.

Implementation description

API documentation generated by Doxygen contains information about the internal organization of the module.

The module is moderately large

Various features can be enabled or disabled, either through feature defines or specific defines

Dynamic memory use and OOM handling

OOM policies

Most of the functions LEAVE in case of OOM

Who handles OOM?
In the case of LEAVE functions the caller must TRAP the errors, and handle the OOM situations. In the case of the internal functions these usually aborts their operation with an error message, and a raised status flag, which must be handled either by the caller, or the document.
Flow

Most of the module is client pull based, and OOM is reported to the caller

Heap memory usage

Upload elements are usually not kept for long, and their allocated size depends on the number of elements and actual bodysize.

Stack memory usage

Usually large objects are allocated. In some cases sizeable objects are placed on the stack but only for shorter periods.

In most cases stack consumption should be less than 300 bytes.

Static memory usage

The module does not use global variables, but few small const arrays exist

Caching and freeing memory

No caching is performed. All storage is for the current request and only lives as long as the owner permits it.

Freeing memory on exit

No persistent memory is allocated by the module. The owners of the Upload elements must make sure to delete the objects they have created.

Temp buffers

The RFC 2231 header parameter construction use the shared TempBuf and TempBuf2 buffers. No check about previous use are made

Memory tuning

At present there are no opportunities to tune memory use.

Tests

Selftests, but they do not check memory usage.

Coverage

Selftests, uploading files, posting forms, sending email, ordinary HTTP surfing.

Design choices

Headers and uploade elements are implemented as lists to ease construction

Improvements

No improvements planned

An overview of the module's implementation

The central code is in Upload_Handler and Upload_Base with implementations adapted to specific use as sub-classes of the Upload_Handler class. The classes include

Headers are organized as lists of individual headers that contain a list of parameters. Each parameter can be represented as a more complex implementation used to prepare the resulting header. The primary API for adding headers and parameters are on the upload element. It is possible to add pregenerated header blocks, but these are usually subject to filtering to avoid security problems. The base classes extract and output the header informations as a header block, and then extract the actual content from the implementations into a caller created buffer. Repeated requests are often necessary to complete the process.