PDFlib 8 Windows COM/.NET Tutorial

Error policies. When PDFlib detects an error condition, it will react according to one of
several strategies which can be configured with the errorpolicy parameter. All functions
which can return error codes also support an errorpolicy option. The following error policies
are supported:
> errorpolicy=legacy: this deprecated setting ensures behavior which is compatible to
earlier versions of PDFlib, where exceptions and error return values are controlled by
parameters and options such as fontwarning, imagewarning, etc. This is only recommended
for applications which require source code compatibility with PDFlib 6. It
should not be used for new applications. The legacy setting is the default error policy.
> errorpolicy=return: when an error condition is detected, the respective function will
return with a -1 error value regardless of any warning parameters or options. The application
developer must check the return value to identify problems, and must react
on the problem in whatever way is appropriate for the application. This is the
recommended approach since it allows a unified approach to error handling.
> errorpolicy=exception: an exception will be thrown when an error condition is detected.
However, the output document will be unusable after an exception. This can be
used for lazy programming without any error conditionals at the expense of sacrificing
the output document even for problems which may be fixable by the application.
The following code fragments demonstrate different strategies with respect to exception
handling. The examples try to load a font which may or may not be available.
If errorpolicy=return the return value must be checked for an error. If it indicates failure,
the reason of the failure can be queried in order to properly deal with the situation:
font = p.load_font("MyFontName", "unicode", "errorpolicy=return");
if (font == -1)
{
/* font handle is invalid; find out what happened. */
errmsg = p.get_errmsg());
/* Try a different font or give up */
...
}
/* font handle is valid; continue */
If errorpolicy=exception the document must be abandoned if an error occurs:
font = p.load_font("MyFontName", "unicode", "errorpolicy=exception");
/* Unless an exception was thrown the font handle is valid;
* if an exception occurred, the PDF output cannot be continued
*/
Cookbook A full code sample can be found in the Cookbook topic general/error_handling.
Warnings. Some problem conditions can be detected by PDFlib internally, but do not
justify interrupting the program flow by throwing an exception. While earlier versions
of PDFlib supported the concept of non-fatal exceptions which can be disabled, PDFlib 7
never throws an exception for non-fatal conditions. Instead, a description of the condition
will be logged (if logging is enabled). Logging can be enabled as follows:
p.set_parameter("logging", "filename=private.log");
We recommend the following approach with respect to warnings:
60 Chapter 3: Creating PDF Documents (Edition for COM, .NET, and REALbasic)