PDFlib 8 Windows COM/.NET Tutorial

3 Creating PDF Documents
3.1 General PDFlib Programming Aspects
Cookbook Code samples regarding general programming issues can be found in the general category of
the PDFlib Cookbook.
3.1.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 (i.e.
special error return codes such as -1) for function calls which may often fail, and use a
special exception mechanism for those rare occasions which don’t warrant cluttering
the code with conditionals. This is exactly the path that PDFlib goes: Some operations
can be expected to go wrong rather frequently, for example:
> Trying to open an output file for which one doesn’t have permission
> Trying to open an input PDF with a wrong file name
> Trying to open a corrupt image file
PDFlib signals such errors by returning a special value (usually – 1) as documented in
the PDFlib API Reference. This error code must be checked by the application developer
for all functions which are documented to return -1 on error.
Other events may be considered harmful, but will occur rather infrequently, e.g.
> running out of virtual memory
> scope violations (e.g., closing a document before opening it)
> supplying wrong parameters to PDFlib API functions (e.g., trying to draw a circle with
negative radius), or supplying wrong options.
When PDFlib detects such a situation, an exception will be thrown instead of passing a
special error return value to the caller. It is important to understand that the generated
PDF document cannot be finished when an exception occurred. The only methods
which can safely be called after an exception are get_apiname( ), get_errnum( ), and get_
errmsg( ). Calling any other PDFlib method after an exception may lead to unexpected
results. The exception will contain the following information:
> A unique error number;
> The name of the PDFlib API function which caused the exception;
> A descriptive text containing details of the problem.
Querying the reason of a failed function call. As noted above, the generated PDF output
document must always be abandoned when an exception occurs. Some clients,
however, may prefer to continue the document by adjusting the program flow or supplying
different data. For example, when a particular font cannot be loaded most clients
will give up the document, while others may prefer to work with a different font. In this
case it may be desirable to retrieve an error message which describes the problem in
more detail. In this situation the functions get_errnum( ), get_errmsg( ), and get_
apiname( ) can be called immediately after a failed function call, i.e., a function call
which returned a -1 error value.
3.1 General PDFlib Programming Aspects 59