typedef ASEnum8 ASErrSeverity; typedef ASInt32 ASErrorCode; void restoreEnvironProc(void *asEnviron); asEnviron | The environment to restore.
|
const char *ASGetErrorString(ASErrorCode errorCode, char *buffer, ASTArraySize lenBuffer); errorCode | The exception whose error string is obtained. This must be a full error code, built with the ErrBuildCode() macro or a user-defined exception returned from ASRegisterErrorString(). See Errors for a list of predefined exceptions.
|
buffer | (Filled by the method) A buffer into which the string is written. Make sure to
memset the buffer to 0 before calling ASGetErrorString(). |
lenBuffer | The number of characters that buffer can hold.
|
buffer. This does not mean that the function worked. You must call strlen on the returned buffer (as long as you memset the buffer to 0) to determine whether the error code was valid. void ASGetErrorStringASText(ASErrorCode errorCode, ASText errorString); errorCode | The exception whose error string is obtained. This must be a full error code, built with the ErrBuildCode macro or a user-defined exception returned from ASRegisterErrorString(). See Error Systems for a list of predefined exceptions.
|
errorString | (Filled by the method) The text object containing the error string. The client must pass a valid ASText object. The routine does not allocate it.
|
ASErrorCode ASGetExceptionErrorCode(void); Note: You will probably never call ASPopExceptionFrame() directly; it is called for you as appropriate from within the HANDLER, E_RETURN and E_RTRN_VOID macros.
void ASPopExceptionFrame(void); restoreFunc should be a function matching the following prototype. Note: You will probably never call ASPushExceptionFrame() directly; use the DURING macro instead.
void ASPushExceptionFrame(void *asEnviron, ACRestoreEnvironProc restoreFunc); asEnviron | IN/OUT Represents a stack environment that is restored if an exception occurs. On Windows and Mac OS, this is a
jmp_buf, which is an array of integers. |
restoreFunc | IN/OUT Should be a function matching the following prototype:
ACCB1 void ACCB2 RestorePlugInFrame( void * asEnviron) |
Raises an exception. Plug-ins can raise any exception defined in the AcroErr.h header file using the ErrBuildCode macro, or can define their own exceptions using ASRegisterErrorString(). See Errors for a list of predefined exceptions.
If the code that calls ASRaise() gets control as a result of a non-Acrobat event (such as a drag and drop event on some platforms), this method fails since there is no Acrobat viewer code in the stack to handle the exception.
void ASRaise(ASErrorCode error); error | An error code for the exception to raise. Error codes have three parts: severity, system, and error number. Use
ErrBuildCode to build an error code for an existing error. |
Registers a new error and string. The error can be used to raise a plug-in-specific exception using ASRaise(). When the exception is raised, its error string can be retrieved using ASGetErrorString() and reported to the user using AVAlertNote().
The error system is automatically forced to be ErrSysXtn. (See the list of Error Systems).
The error is automatically assigned an error code that is not used by any other plug-in (in the current implementation, the Acrobat viewer increments a counter each time any plug-in requests an error code, and returns the value of the counter). As a result, plug-ins cannot rely on being assigned the same error code each time the Acrobat viewer is launched.
ASErrorCode ASRegisterErrorString(ASErrSeverity severity, const char *errorString); severity | The severity of the error being defined. It must be one of the Severities.
|
errorString | The string describing the exception. This string is used by ASGetErrorString(), and is copied by ASRegisterErrorString(); it may be freed by the plug-in after registering the error.
|
ASErrorCode ASRegisterErrorStringASText(ASErrSeverity severity, const ASText errorString); severity | The severity of the error being defined. It must be one of the Error Severities.
|
errorString | The text object containing the error string to be set.
|