Information about an exception. More...

#include <SignDocSDK-c.h>

Public Types
typedef void(*	SIGNDOC_ExceptionHandler) (struct SIGNDOC_Exception **aEx)
	Exception handler. More...

Public Member Functions
void	SIGNDOC_Exception_setHandler (SIGNDOC_ExceptionHandler aHandler)
	Sets an exception handler that is called when an exception occurs. More...

struct SIGNDOC_Exception *	SIGNDOC_Exception_new (unsigned aType, const char *aMessage)
	Create a new SIGNDOC_Exception object. More...

void	SIGNDOC_Exception_delete (struct SIGNDOC_Exception *aEx)
	Destroy a SIGNDOC_Exception object. More...

const char *	SIGNDOC_Exception_getText (const struct SIGNDOC_Exception *aEx)
	Get the message text of an SIGNDOC_Exception object. More...

unsigned	SIGNDOC_Exception_getType (const struct SIGNDOC_Exception *aEx)
	Get the type of the exception. More...

Detailed Description

Information about an exception.

Functions which can throw exceptions take a

struct SIGNDOC_Exception **aEx

argument. You must pass a pointer to a variable of type

struct SIGNDOC_Exception *

On entry, functions will check if the pointer is non-NULL. If it's NULL, abort() will be called. Otherwise, NULL will be stored to the object pointed to by that pointer.

When an exception occurs, an object of type SIGNDOC_Exception is created and a pointer to that exception is stored in the object pointed to by the aEx argument.

There are two ways to handle exceptions:

check the pointer after each function calls that can throw an exception. To continue after the exception, you should call SIGNDOC_Exception_delete() to destroy the SIGNDOC_Exception object. This method is preferred when wrapping the C API in another programming language.
install a global exception handler with SIGNDOC_Exception_setHandler(). The exception handler will be called when an exception occurs. This method might be preferred if your application won't continue after an exception is thrown.

The most common exceptions are

SIGNDOC_EXCEPTION_TYPE_BAD_ALLOC (out of memory)
SIGNDOC_EXCEPTION_TYPE_SPOOC_ENCODING_ERROR (argument not encoded correctly or the output of a function cannot be encoded according to the specified encoding). Example: using SIGNDOC_ENCODING_NATIVE with SIGNDOC_Field_getValue() for printing the value of a field on the console will throw an exception if the field's value cannot be represented by the console's character set. You might want to use SIGNDOC_ENCODING_UTF_8 instead and then convert the value with SIGNDOC_recodeStringRelaxed() to native encoding.

Out of memory situations are always reported via an exception. Some but not all functions check for encoding errors and report any problems via return values.

Member Typedef Documentation

typedef void( * SIGNDOC_ExceptionHandler) (struct SIGNDOC_Exception **aEx)

Exception handler.

The exception handler passed to SIGNDOC_Exception_setHandler().

Parameters

[in] aEx The aEx argument of the SignDoc SDK function which reports the exception. The pointer to the SIGNDOC_Exception object has already been stored to *aEx. If you call SIGNDOC_Exception_delete(*aEx), you must set *aEx to NULL.

Member Function Documentation

void SIGNDOC_Exception_delete ( struct SIGNDOC_Exception * aEx )

Destroy a SIGNDOC_Exception object.

If aEx points to the statically allocated object returned by SIGNDOC_Exception_new() in an out-of-memory situation, this function will do nothing.

Parameters

[in] aEx A pointer to a SIGNDOC_Exception object, can be NULL.

const char * SIGNDOC_Exception_getText ( const struct SIGNDOC_Exception * aEx )

Get the message text of an SIGNDOC_Exception object.

Note: Do not call SIGNDOC_free() on the return value.

Parameters

[in] aEx A pointer to a SIGNDOC_Exception object.

Returns: A pointer to the message string or NULL.

See also: SIGNDOC_Exception_getType()

unsigned SIGNDOC_Exception_getType ( const struct SIGNDOC_Exception * aEx )

Get the type of the exception.

Parameters

[in] aEx A pointer to a SIGNDOC_Exception object.

Returns

The type of the exception:

See also: SIGNDOC_Exception_getText()

struct SIGNDOC_Exception * SIGNDOC_Exception_new	(	unsigned	aType,
		const char *	aMessage
	)

Create a new SIGNDOC_Exception object.

This function is needed only for throwing exceptions from callback functions such as SIGNDOC_UserInputStream_read().

Parameters

[in]	aType	The type of the message: SIGNDOC_EXCEPTION_TYPE_BAD_ALLOC SIGNDOC_EXCEPTION_TYPE_PDF SIGNDOC_EXCEPTION_TYPE_STL SIGNDOC_EXCEPTION_TYPE_GENERIC SIGNDOC_EXCEPTION_TYPE_SPOOC_GENERIC SIGNDOC_EXCEPTION_TYPE_SPOOC_ENCODING_ERROR SIGNDOC_EXCEPTION_TYPE_SPOOC_IO SIGNDOC_EXCEPTION_TYPE_INVALID_ARGUMENT
[in]	aMessage	A pointer to the message or NULL. The string will be copied.

If creating the object or copying aMessage fails (due to lack of memory), this function will return a pointer to a special, statically SIGNDOC_Exception object which has type SIGNDOC_EXCEPTION_TYPE_BAD_ALLOC and a suitable message.

Returns: A pointer to a new SIGNDOC_Exception object or to a statically allocated SIGNDOC_Exception_object with type SIGNDOC_EXCEPTION_TYPE_BAD_ALLOC.

See also: SIGNDOC_Exception_delete()

void SIGNDOC_Exception_setHandler ( SIGNDOC_ExceptionHandler aHandler )

Sets an exception handler that is called when an exception occurs.

Usage of this function is discouraged, check the object passed as aEx after each function call instead. The handler is global to the process.

Parameters

[in] aHandler Exception handler function, NULL to disable.

The documentation for this class was generated from the following file:

SignDocSDK-c.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Function Documentation