Download - Multivac!

3 PDFlib Programming3.1 General ProgrammingCookbook Code samples regarding general programming issues can be found in the general category ofthe PDFlib Cookbook.3.1.1 Exception HandlingErrors of a certain kind are called exceptions in many languages for good reasons – theyare mere exceptions, and are not expected to occur very often during the lifetime of aprogram. 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 aspecial exception mechanism for those rare occasions which don’t warrant clutteringthe code with conditionals. This is exactly the path that PDFlib goes: Some operationscan 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 filePDFlib signals such errors by returning a special value (usually – 1, but 0 in the PHPbinding) as documented in the PDFlib Reference. This error code must be checked by theapplication 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 withnegative radius), or supplying wrong options.When PDFlib detects such a situation, an exception will be thrown instead of passing aspecial error return value to the caller. It is important to understand that the generatedPDF document cannot be finished when an exception occurred. The only methodswhich can safely be called after an exception are PDF_delete( ), PDF_get_apiname( ), PDF_get_errnum( ), and PDF_get_errmsg( ). Calling any other PDFlib method after an exceptionmay 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 outputdocument must always be abandoned when an exception occurs. Some clients,however, may prefer to continue the document by adjusting the program flow or supplyingdifferent data. For example, when a particular font cannot be loaded most clientswill give up the document, while others may prefer to work with a different font. In thiscase it may be desirable to retrieve an error message which describes the problem inmore detail. In this situation the functions PDF_get_errnum( ), PDF_get_errmsg( ), andPDF_get_apiname( ) can be called immediately after a failed function call, i.e., a functioncall which returned a -1 (in PHP: 0) error value.3.1 General Programming 45