API Overview
Glossary
| Term | Description |
|---|---|
| Session | A session encapsulates the processing of a single file, specified either as a file path or a pointer to a memory image of the file. |
| Base name | The base name is the component left after all leading directory components have been removed. The base name can refer to a directory or file. |
The session is given information regarding the required output of the session, the policies to be applied, and any other actions required.
Glasswall Technology
Glasswall provides file inspection, remediation, sanitisation and reporting. The Glasswall API functions give third-party users the ability to fine-tune an interface to the Glasswall functionality.
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. You pass the session handle to other API functions to register the inputs and outputs, the forms of the inputs and outputs (memory or a file) and which processing mode is required (Analysis, Manage & Protect, Import, Export). You then process the file by calling function GW2RunSession and close the session calling GW2CloseSession, after processing any non-persistent storage, or saving non-persistent storage.
The encapsulation of the processing of each file in a Session object allows multi-thread processing.
Types
The API makes available two enumerations for use by clients as argument types to certain API functions. Include the header file “glasswall.core2.api.h” in your source file and use the enumerators when calling the API functions.
Policy_format
The enumeration Policy_format is used to specify the format of the policies file. The following enumerator is available:
PF_XML
Analysis_format
The enumeration Analysis_format is used to specify the format of the analysis file. The following enumerator is available:
AF_XML
ft_t
The enumeration Ft_t is used to indicate the file type (file format) of a file. Include header file “filetype.h” in your source code files to use them.
Note: This is marked for change to 'Ft_t'. Examples in the document use 'Ft_t'.
Session
Session is a type that represents a file and the mechanisms used to process that file. It is used by all Glasswall file processing API functions. All sessions have an ID greater than 0.
Note:
This is marked for change to 'SessionHandle'.
Return Types
Most of the functions in the Glasswall API return a value that indicates success or failure. The values and their meaning are listed below.
| Value | System name | Meaning | Processing Response |
|---|---|---|---|
| 1 | gw2ret_ok_withcleaning | The file was processed successfully. Sanitisations or remedies, or both, have been applied. | Managed file produced |
| 0 | gw2ret_ok | The file was processed successfully. No sanitisations or remedies have been applied. | Managed file produced |
| -1 | gw2ret_generalfail | General failure during processing, a system or resource problem | Engine Error. |
| -2 | gw2ret_unexpectedEndOfFile | End of file, or End of file marker was detected unexpectedly. | File Processed but discarded. |
| -3 | gw2ret_licenseExpired | License file expired, data incorrect or missing. | Engine Error. |
| -4 | gw2ret_incorrectSessionSetup | A policy file setting is not a valid value (see XSD). Or a registration is incompatible. e.g. trying to register and input file and input buffer when you can only have one source. | Engine Error. |
| -5 | gw2ret_incorrectPolicySetup | Policy file unable to be loaded or content error. | Engine Error. |
| -6 | gw2ret_unableToLoadInput | Unable to load input file or access the buffer containing it. | Engine Error. |
| -7 | gw2ret_fileTypeUnknown | Unable to determine filetype | Unrecognized File. |
| -8 | gw2ret_unknownSessionID | Session ID used in API call did not appear in list of active Sessions. Session either not created or already deleted. | Engine Error. |
| -9 | gw2ret_argumentError | One of the arguments in a API call was invalid. | Engine Error. |
| -10 | gw2ret_unableToLoadImport | Unable to load import data file or access the buffer containing it. | Engine Error. |
| -11 | gw2ret_cameraDidNotInitialise | A camera plugin failed to initialize. | Engine Error. |
| -12 | gw2ret_noCamerasConnected | No camera plugins have been loaded. | Engine Error. |
| -13 | gw2ret_engineeringOnlyGoesToFile | Unused. Reserved for future use. | Engine Error. |
| -14 | gw2ret_unableToWriteOutput | Unable to write output file or the buffer expecting it. | Engine Error. |
| -15 | gw2ret_unableToWriteExport | Unable to write export data file or the buffer expecting it. | Engine Error. |
| -16 | gw2ret_fileRejected | File was Processed successfully but disallowed by policy setting. See analysis or GW2FileErrorMsg API call. | File Processed but discarded. |
| -17 | gw2ret_unableToWriteExportTextDump | Unable to write text export output file. | Engine Error. |
| -18 | gw2ret_unableToWriteAnalysisReport | Unable to write analysis report output file. | Engine Error. |
| -19 | gw2ret_inputTooLarge | Input file size is above 2GiB limit. | Invalid File. |
| -20 | gw2ret_inputZeroBytes | Input file size is 0 bytes. | Invalid File. |
Clean Recognised
| Value | System name |
|---|---|
| 1 | gw2ret_ok_withcleaning |
| 0 | gw2ret_ok |
CorruptedRecognised
| Value | System name |
|---|---|
| -2 | gw2ret_unexpectedEndOfFile |
| -16 | gw2ret_fileRejected |
Unrecognised File
| Value | System name |
|---|---|
| -7 | gw2ret_fileTypeUnknown |
Engine Error
| Value | System name |
|---|---|
| -1 | gw2ret_generalfail |
| -3 | gw2ret_licenseExpired |
| -4 | gw2ret_incorrectSessionSetup |
| -5 | gw2ret_incorrectPolicySetup |
| -6 | gw2ret_unableToLoadInput |
| -8 | gw2ret_unknownSessionID |
| -9 | gw2ret_argumentError |
| -10 | gw2ret_unableToLoadImport |
| -11 | gw2ret_cameraDidNotInitialise |
| -12 | gw2ret_noCamerasConnected |
| -13 | gw2ret_engineeringOnlyGoesToFile |
| -14 | gw2ret_unableToWriteOutput |
| -15 | gw2ret_unableToWriteExport |
| -17 | gw2ret_unableToWriteExportTextDump |
| -18 | gw2ret_unableToWriteAnalysisReport |
Invalid File
| Value | System name |
|---|---|
| -19 | gw2ret_inputTooLarge |
| -20 | gw2ret_inputZeroBytes |
Each of the functions described in API Functions assumes that one of these values is returned unless stated otherwise in the detailed description.