SignDoc SDK (C)  5.0.0
SIGNDOC_Exception Class Reference

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_ExceptionSIGNDOC_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

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_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().

[in]aExThe 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.

[in]aExA 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.

Do not call SIGNDOC_free() on the return value.
[in]aExA pointer to a SIGNDOC_Exception object.
A pointer to the message string or NULL.
See also
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().

[in]aTypeThe type of the message:
[in]aMessageA 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.

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

[in]aHandlerException handler function, NULL to disable.

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