Operation Overview

The following sections describe the key concepts for successful Glasswall Embedded Engine operation.

Sessions

The Application Programming Interface (API) is session based. Session is a type that represents a file and the mechanisms used to process that file.

• You create a Session object by calling GW2OpenSession which returns a session handle.

  • As more than one session may be active, the Session ID is used to access data and set variables for a particular session.

• You pass the session handle to other API functions to register the inputs and outputs and the forms of the inputs and outputs (memory or a file).

• You then process the file by calling the function GW2RunSession and close the session by calling GW2CloseSession.

When opened, each session is assigned its own series of memory buffers. These buffers remain accessible for as long as the session remains open. Once a session is closed, the data is no longer available and the allocated memory is released.

A session must always be closed. This includes scenarios where a processing issue occurs and the expected flow of operation is interrupted. In this instance, numerous defensive coding patterns can be adopted that are designed for managing resources e.g. try-with-resources in Java, or context-handlers in Python.

Note that the more sessions that are concurrently open, the larger the overall memory requirements will be. Processing files using multiple threads is not supported. Spawning multiple processes is advised in order to facilitate parallel processing.

Documentation on how to use the API's can be found on the API function pages.

Policy files

A policy file is used to determine how Glasswall should process supplied files. A sample policy file is provided in the Embedded Engine release package.

Whilst a policy file is not required for Glasswall to run, in most cases one is used to customise processing to match requirements. If a policy file is to be used, it must be registered to each session.

If no policy file is specified, content management settings are set to sanitise files by default. Default settings would also be applied for sysConfig options.

See Content Management and System Configuration for further information.

Return values from Glasswall

Most functions within the Glasswall API return an integer indicating success or failure. A 0 or a 1 will indicate success, whilst a negative number (such as -1) would indicate a failure.

Certain API calls do not follow this pattern; for example, the GW2OpenSession function will return either a -1 error or the ID of the newly-created session (positive integer).

A table of return values can be found on the API Overview page.

Data Management

Glasswall processes and saves data using files and/or buffers. The data requirements for these processes are described in the sections below.

Files

File-based Glasswall API calls require a file path as a parameter. This file name must be encoded as a C-type string; an array of characters terminated with a NULL character. UTF-8 encoding should be used.

Memory

Memory-based Glasswall API calls require the use of one or more memory buffers. These buffers are defined by a pointer to the first element and the length of the buffer in bytes. This approach allows files containing NULL characters to be processed correctly.

Import/Input Functions

These functions require a pointer to the first datum in the buffer and the length of the buffer in bytes.

Export/Output Functions

These functions specify the buffer that Glasswall should use when returning processed data. Glasswall requires pointers to both the buffer length and the pointer to the first element, as described below:

- A pointer-to-pointer to the buffer’s first element

- A pointer to the length of the buffer (size_t *)

This extra layer of abstraction is required as the size of this buffer is not known prior to running the session. Dereferencing these pointers allows access to the data returned from Glasswall.