AS_Layer.Errors (Acrobat)

	Define
	ASGetExceptionErrorCode
	ASRaise
	DURING
	DURING
	END_HANDLER
	END_HANDLER
	ERRORCODE A macro defined to call ASGetExceptionErrorCode(). It returns an ASInt32 object containing an exception error code.
	ERRORCODE A macro defined to call ASGetExceptionErrorCode(). It returns an ASInt32 object containing an exception error code.
	HANDLER
	HANDLER
	RERAISE Deprecated in Acrobat 8.0. Re-raises the most recently raised exception and passes it to the next exception handler in the stack.

	Typedef
	ASErrorCode An error code value for use in ASFile and ASFileSys methods and callbacks. Introduced in Acrobat 6.0.
	ASErrSeverity

	Callback
	restoreEnvironProc Environment-restoration functions are called when an exception is raised.

	Method
	const char* ASGetErrorString(ASErrorCode errorCode, char* buffer, ASTArraySize lenBuffer) Gets a string describing the specified error/exception.
	void ASGetErrorStringASText(ASErrorCode errorCode, ASText errorString) Gets an ASText object containing a string describing the specified exception.
	void ASRaise(ASErrorCode error) 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.
	ASErrorCode ASRegisterErrorString(ASErrSeverity severity, const char* errorString) 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().
	ASErrorCode ASRegisterErrorStringASText(ASErrSeverity severity, const ASText errorString) Registers a new error and string.
	void ACCB2 RestorePlugInFrame(void* environ)

Defines Detail

ASGetExceptionErrorCode

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ASGetExceptionErrorCode ACGetExceptionErrorCode

File: CorCalls.h

Line: 355

ASRaise

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ASRaise ASRaiseImpl(err)

File: CorCalls.h

Line: 421

DURING

Product availability: All

Platform availability: All

Syntax


#define DURING DURING usage must be compiled with C++

File: CorCalls.h

Line: 236

DURING

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define DURING { \ _E_SUPPRESS_NESTED_DURING_HANDLER_WARNINGS \ ACROjmp_buf ASException; \ ASPushExceptionFrame(&ASException, &RestorePlugInFrame); \ if (!ACROsetjmp(ASException)) {

File: CorCalls.h

Line: 732

END_HANDLER

Product availability: All

Platform availability: All

Syntax


#define END_HANDLER END_HANDLER usage must be compiled with C++

File: CorCalls.h

Line: 238

END_HANDLER

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define END_HANDLER }}

File: CorCalls.h

Line: 735

ERRORCODE

Product availability: All

Platform availability: All

Syntax


#define ERRORCODE (ACGetExceptionErrorCode())

Description

A macro defined to call ASGetExceptionErrorCode(). It returns an ASInt32 object containing an exception error code.

See Also

DURING
END_HANDLER
E_RTRN_VOID
HANDLER

File: CorCalls.h

Line: 298

ERRORCODE

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define ERRORCODE (ASGetExceptionErrorCode())

Description

A macro defined to call ASGetExceptionErrorCode(). It returns an ASInt32 object containing an exception error code.

See Also

DURING
END_HANDLER
E_RTRN_VOID
HANDLER

File: CorCalls.h

Line: 556

HANDLER

Product availability: All

Platform availability: All

Syntax


#define HANDLER HANDLER usage must be compiled with C++

File: CorCalls.h

Line: 237

HANDLER

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define HANDLER _E_RESTORE; } else { _E_RESTORE;

File: CorCalls.h

Line: 734

RERAISE

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define RERAISE ASRaise(ERRORCODE)

Description

Deprecated in Acrobat 8.0. Re-raises the most recently raised exception and passes it to the next exception handler in the stack.

File: CorCalls.h

Line: 554

Typedefs Detail

ASErrorCode

Product availability: All

Platform availability: All

Syntax

typedef ASInt32 ASErrorCode;

An error code value for use in ASFile and ASFileSys methods and callbacks. Introduced in Acrobat 6.0.

File: ASExpT.h

Line: 92

ASErrSeverity

Product availability: All

Platform availability: All

Syntax

typedef ASEnum8 ASErrSeverity;

File: ASExpT.h

Line: 260

Callbacks Detail

restoreEnvironProc

Product availability: All

Platform availability: All

Syntax

void (*restoreEnvironProc)(void *asEnviron)

Environment-restoration functions are called when an exception is raised.

File: CoreExpT.h

Line: 203

Method Detail

ASGetErrorString

()

Product availability: All

Platform availability: All

Syntax





const char* ASGetErrorString(ASErrorCode errorCode, char* buffer, ASTArraySize lenBuffer)

Gets a string describing the specified error/exception.

Parameters

	`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.

Returns

A useful pointer to 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.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 138

ASGetErrorStringASText

()

Product availability: All

Platform availability: All

Syntax





void ASGetErrorStringASText(ASErrorCode errorCode, ASText errorString)

Gets an ASText object containing a string describing the specified exception.

Parameters

	`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.

Since

PI_ACROSUPPORT_VERSION >= 0x00080000

File: ASProcs.h

Line: 2792

ASRaise

()

Product availability: All

Platform availability: All

Syntax





void ASRaise(ASErrorCode error)

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.

Parameters

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.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: CorProcs.h

Line: 51

ASRegisterErrorString

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASRegisterErrorString(ASErrSeverity severity, const char* errorString)

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.

Parameters

	`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.

Returns

The newly created error code. Plug-ins should assign the error code returned by this method to a variable if they will use the error code later in the current session.

See Also

ASGetErrorString
ASRaise

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 172

ASRegisterErrorStringASText

()

Product availability: All

Platform availability: All

Syntax





ASErrorCode ASRegisterErrorStringASText(ASErrSeverity severity, const ASText errorString)

Registers a new error and string.

Parameters

	`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.

Returns

The newly created error code. Plug-ins should assign the error code returned by this method to a variable if they wish to use the error code later in the current session.

Since

PI_ACROSUPPORT_VERSION >= 0x00080000

File: ASProcs.h

Line: 2811

RestorePlugInFrame

()

Product availability: All

Platform availability: All

Syntax





void ACCB2 RestorePlugInFrame(void* environ)

Parameters

environ

Returns

File: CorCalls.h

Line: 182

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
Errors	Defines \| Typedefs \| Callbacks \| Methods

Layer	AS_Layer
Object	Errors