# Module: Formats

## About this module

The Formats module encodes and decodes several formats to and from internal representation, including

- Base64
- Quoted Printable
- Parameter syntax from MIME and HTML headers, including RFC 2231 style encoding
- Parsing of MIME/HTTP headers

The internal formats for parameters and headers include enumerations of often used names.

Supported protocols:

- HTTP 1.1
- Netscape Cookies
- RFC 2965
- MIME 1 2 3 4 5
- RFC 2231

## Interface overview and API documentation

API documentation generated by Doxygen contains all necessary information for the external APIs.

### An overview of the module's implementation

The module contains a collection of utility functions handling the formats used in http header handling, cookies and encoding. Collections of key-value pairs are created or data encoded/decoded. Calling functions are responsible for memory management of the objects.

The Sequence splitter creates lists of objects that may either contain allocated strings or reference an externally managed string. The sequence can be initialized based on one of several profiles specifying how each key/value pair is separated from each other, and how the parts of the pair are separated. The splitteer can process several kinds of data, in particular RFC2231 encoded values, when requested to.

The list of objects are searchable on the name field, either by name or by an associated enumerated value.

The encoders are used to create a binary string in binary, Qouted-Printable or Base64 format. There is also a decoder for base64.

The DataFile and Record classes are base on DataStream classes to read and write the format used by the cache and cookie index files, as well as the storage file of several other modules.

### Footprint

The module is of moderate size. Various features can be enabled or disabled, either thorugh feature defines or specific defines.

### Dynamic memory use and OOM handling

OOM policies

  Most of internal module functions handles OOM by LEAVing, and the caller must TRAP errors and handle them.

Who handles OOM?
  In the case of LEAVE functions the caller must TRAP the errors, and handle the OOM situations.
Flow

  The module is client push based, the caller request an action and gets aresult.

Heap memory usage

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

  The encoders allocate memory that must be freed by the caller.

Stack memory usage

  Usually large objects are allocated

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

Static memory usage

  A number of compiled const arrays exists.

Caching and freeing memory

  No caching is performed. Caller must manage the objects

Freeing memory on exit

  Const arrays in pseudo const mode are deleted on exit

Temp buffers

  No shared temp buffers are used.

Memory tuning

  At present there are no opportunities to tune memory use.

Tests

  Selftests, but they do not check memory usage.

Coverage

  Selftests, ordinary surfing, reading email.

Design choices

  The sequence splitter will use a single string and chop it into pieces handed to each sub element. This reduces memory consumption and allocation overhead.

Improvements

  There are currently no planned improvements.