Test Error Handling and Recovery

The KeyView Filter SDK includes a testing utility, poisonsr, which you can use to test error handling and recovery. This utility can replicate various error conditions, such as crashes and hangs.

CAUTION: This reader is for testing purposes only. You must not redistribute it.

Setup

The poisonsr reader is provided in the poisonsr directory of your installation.

To use poisonsr for testing

  1. Add the poisonsr shared library binary to the bin directory.

  2. Add the following entry to the [Formats] section of the formats.ini configuration file.

    -100=poison

When you add this line to formats.ini, KeyView detects any plain text file that begins poisonsr_command_file as the format KeyView_Poison_Fmt (-100), and sends it to poisonsr. The reader then interprets the rest of the input file as a series of commands to run.

Send commands to poisonsr

You send commands to poisonsr by using the input file. The first line of the input file must read poisonsr_command_file, followed by a Line Feed (\n, 0x0A). Each subsequent line must be a command, ending with a Line Feed. These commands have the following general syntax:

operation_name poisonsr_command optional_arguments

NOTE: If an operation receives a command with a different operation_name, it either does nothing or returns a default value.

For example, if you set getMetadata crash in your input file, and run a filtering operation, the command does not run and poisonsr returns an empty text object.

Operation names

You can use one of the following values for the operation_name, which map to public API calls:

  • autodet

  • getMetadata

  • filter

  • openFile

  • getMainFileInfo

  • getSubFileInfo

  • extractSubFile

  • getSubFileMetaData

In the case of the autodet operation, the command runs as part of file format detection. File format detection occurs retrieving document information, but also as part of other calls.

Command names

The following table describes the commands that you can use for poisonsr.

sleep milliseconds

Poisonsr sleeps for the specified number of milliseconds. If the argument is missing, it sleeps forever.

For example, filter sleep 10000 sleeps filter for 10 seconds. openFile sleep makes extraction hang.

crash

Poisonsr dereferences a null pointer, causing a crash. This command does not take any arguments.

For example, autodet crash causes file format detection to crash.

throw KeyViewErrorNumber

Poisonsr throws an exception corresponding to the given KeyView error.

NOTE: In some cases, the error might be transformed into a different error by the time it is returned by the public API, or in some cases it might not be reported as an error at all.

For example, openFile throw 4 causes extraction to trigger a KVError_BadInputStream error.