PDFlib Text Extraction Toolkit (TET) Manual

3 TET Library Language Bindings
This chapter discusses specifics for the language bindings which are supplied for the
TET library. The TET distribution contains full sample code for several small TET applications
in all supported language bindings.
3.1 Exception Handling
Errors of a certain kind are called exceptions in many languages for good reasons – they
are mere exceptions, and are not expected to occur very often during the lifetime of a
program. The general strategy is to use conventional error reporting mechanisms (read:
special error return codes) for function calls which may go wrong often times, and use a
special exception mechanism for those rare occasions which don’t justify cluttering the
code with conditionals. This is exactly the path that TET goes: Some operations can be
expected to go wrong rather frequently, for example:
> Trying to open a PDF document for which one doesn’t have the proper password (but
see also the shrug feature described in Section 5.1, »Indexing protected PDF Documents«,
page 49);
> Trying to open a PDF document with a wrong file name;
> Trying to open a PDF document which is damaged beyond repair.
TET signals such errors by returning a value of –1 as documented in the API reference.
Other events may be considered harmful, but will occur rather infrequently, e.g.
> running out of virtual memory;
> supplying wrong function parameters (e.g. an invalid document handle);
> supplying malformed option lists;
> a required resource (e.g. a CMap file for CJK text extract) cannot be found.
When TET detects such a situation, an exception will be thrown instead of passing a special
error return value to the caller. In languages which support native exceptions
throwing the exception will be done using the standard means supplied by the language
or environment. For the C language binding TET supplies a custom exception
handling mechanism which must be used by clients (see Section 3.2, »C Binding«, page
22).
It is important to understand that processing a document must be stopped when an
exception occurred. The only methods which can safely be called after an exception are
TET_delete( ), TET_get_apiname( ), TET_get_errnum( ), and TET_get_errmsg( ). Calling any
other method after an exception may lead to unexpected results. The exception will
contain the following information:
> A unique error number;
> The name of the API function which caused the exception;
> A descriptive text containing details of the problem;
Querying the reason of a failed function call. Some TET function calls, e.g. TET_open_
document( ) or TET_open_page( ), can fail without throwing an exception (they will return
-1 in case of an error). In this situation the functions TET_get_errnum( ), TET_get_errmsg( ),
and TET_get_apiname( ) can be called immediately after a failed function call in order to
retrieve details about the nature of the problem.
3.1 Exception Handling 21