Adobe Acrobat SDK
Handling Exceptions
Developing Plug-ins and Applications
Returning a value from an exception handler 215
Returning a value from an exception handler
To return a value from a
DURING
HANDLER
block, do not use a return statement. Instead, use the
E_RETURN(x)
or
E_RTRN_VOID
macros. The
E_RETURN(x)
macro returns a value and the
E_RTRN_VOID
macro does not return a value (this is equivalent to a
void
function).
The
E_RETURN(x)
macro must not invoke a function that might raise an exception, because the macro
pops an exception frame off the stack before evaluating the expression to return. If this evaluation raises
an exception, it does not call your handler, but instead calls the next handler up the stack. For example,
consider the following application logic:
E_RETURN(myfn());
This is not recommended if there is any possibility that
myfn
could raise an exception. If you need to
invoke a function, it is best to do it this way:
result = myfn();
E_RETURN(result);
Now, if
myfn
raises an exception, your handler will be executed.
Raising exceptions
Although many Acrobat core API methods raise exceptions, some methods do return error codes or
NULL
if something goes wrong. Inside a
DURING HANDLER
block, if your plug-in detects one of these cases, it
can invoke the
ASRaise
method, which generates an exception. This has the effect of causing the
HANDLER END_HANDLER
code to execute, just as if the original method raised an exception.
You can also use the
RERAISE
macro when you do not want your exception handler to handle an
exception, but want to pass the exception to the next exception handler on the stack.
Note:
Your plug-in should use the
ASRegisterErrorString
method to define its own exceptions.
Exception handling scenarios
This section discusses the following potential problems with exception handling:
●
Goto statements
●
Nested exception handlers in a single function
●
Register usage
Using goto statements
It is recommended that you not use a
goto
within a
DURING HANDLER
block. Jumping outside a
DURING
HANDLER
block disrupts the stack frame, as shown in the following example:
DURING
goto error;
HANDLER
END_HANDLER
error: