## SPI main loop and initialization

SPI main loop and initialization

## Synopsis

    int                 SPI_init                            (void);
    void                SPI_event_main                      (void);
    void                SPI_event_quit                      (void);
    SPIBoolean          SPI_eventIsReady                    (void);
    AccessibleEvent *   SPI_nextEvent                       (SPIBoolean waitForEvent);
    int                 SPI_exit                            (void);

    void                SPI_freeString                      (char *s);
    Accessible*         SPIAccessibleException_getSource    (SPIException *err);
    char*               SPIException_getDescription         (SPIException *err);
    SPIExceptionCode    SPIException_getExceptionCode       (SPIException *err);
    SPIExceptionType    SPIException_getSourceType          (SPIException *err);
                        SPIException;
    enum                SPIExceptionCode;
    enum                SPIExceptionType;
    SPIBoolean          (*SPIExceptionHandler)              (SPIException *err,
                                                             SPIBoolean is_fatal);
                        SPIRect;
    void                SPI_freeRect                        (SPIRect *r);
    char*               SPI_dupString                       (char *s);
    SPIBoolean          SPI_exceptionHandlerPush            (SPIExceptionHandler *handler);
    SPIExceptionHandler* SPI_exceptionHandlerPop            (void);

## Description

## Details

### SPI_init ()

    int                 SPI_init                            (void);

Connects to the accessibility registry and initializes the SPI.

Returns : | 0 on success, otherwise an integer error code.

### SPI_event_main ()

    void                SPI_event_main                      (void);

Starts/enters the main event loop for the SPI services.

(NOTE: This method does not return control, it is exited via a call to `SPI_event_quit()` from within an event handler).

### SPI_event_quit ()

    void                SPI_event_quit                      (void);

Quits the last main event loop for the SPI services, see SPI_event_main

### SPI_eventIsReady ()

    SPIBoolean          SPI_eventIsReady                    (void);

Checks to see if an SPI event is waiting in the event queue. Used by clients that don't wish to use `SPI_event_main()`.

Not Yet Implemented.

Returns : | TRUE if an event is waiting, otherwise FALSE.

### SPI_nextEvent ()

    AccessibleEvent *   SPI_nextEvent                       (SPIBoolean waitForEvent);

Gets the next event in the SPI event queue; blocks if no event is pending and `waitForEvent` is TRUE. Used by clients that don't wish to use `SPI_event_main()`.

Not Yet Implemented.

`waitForEvent` : | a SPIBoolean indicating whether to block or not.
Returns : | the next AccessibleEvent in the SPI event queue.

### SPI_exit ()

    int                 SPI_exit                            (void);

Disconnects from the Accessibility Registry and releases any floating resources. Call only once at exit.

Returns : | 0 if there were no leaks, otherwise non zero.

### SPI_freeString ()

    void                SPI_freeString                      (char *s);

Free a character string returned from an at-spi call. Clients of at-spi should use this function instead of `free()` or `g_free()`. A NULL string `s` will be silently ignored. This API should not be used to free strings from other libraries or allocated by the client.

`s` : | a character string returned from another at-spi call.

### SPIAccessibleException_getSource ()

    Accessible*         SPIAccessibleException_getSource    (SPIException *err);

Get the identity of the object which threw an exception.

`Since`: AT-SPI 1.4

`err` : | the SPIException being queried.
Returns : | a pointer to the Accessible object which threw the exception.

### SPIException_getDescription ()

    char*               SPIException_getDescription         (SPIException *err);

Get a text description of the exception that has been thrown. Unfortunately these descriptions tend to be terse and limited in the detail which they can provide.

`err` : | the SPIException being queried.
Returns : | a brief character string describing the exception.

### SPIException_getExceptionCode ()

    SPIExceptionCode    SPIException_getExceptionCode       (SPIException *err);

Get the SPIExceptionCode telling what type of exception condition has occurred.

`Since`: AT-SPI 1.4

`err` : | the SPIException being queried.
Returns : | the SPIExceptionCode corresponding to exception `err`.

### SPIException_getSourceType ()

    SPIExceptionType    SPIException_getSourceType          (SPIException *err);

Get the SPIExceptionType of an exception which has been thrown.

`Since`: AT-SPI 1.4

`err` : | the exception being queried
Returns : | the SPIExceptionType corresponding to exception `err`.

### SPIException

    typedef struct {
      SPIExceptionType type;
      CORBA_Object source;
      CORBA_Environment *ev;
      SPIExceptionCode code;
      char * desc;
    } SPIException;

An opaque object encapsulating information about thrown exceptions.

SPIExceptionType `type`; | private
CORBA_Object `source`; | private
CORBA_Environment *`ev`; | private
SPIExceptionCode `code`; | private
char *`desc`; | private

### enum SPIExceptionCode

    typedef enum {
    	SPI_EXCEPTION_UNSPECIFIED,
    	SPI_EXCEPTION_DISCONNECT,
    	SPI_EXCEPTION_NO_IMPL,
    	SPI_EXCEPTION_IO,
    	SPI_EXCEPTION_BAD_DATA
    } SPIExceptionCode;

Exception codes indicating what's gone wrong in an AT-SPI call.

`SPI_EXCEPTION_UNSPECIFIED` | An exception of unknown type, or which doesn't fit the other types.
`SPI_EXCEPTION_DISCONNECT` | Communication with the object or service has been disconnected; this usually means that the object or service has died or exited.
`SPI_EXCEPTION_NO_IMPL` | The object or service is missing the implementation for a request.
`SPI_EXCEPTION_IO` | The communications channel has become corrupted, blocked, or is otherwise in a bad state.
`SPI_EXCEPTION_BAD_DATA` | The data received or sent over the interface has been identified as improperly formatted or otherwise fails to match the expectations.

### enum SPIExceptionType

    typedef enum {
    	SPI_EXCEPTION_SOURCE_UNSPECIFIED,
    	SPI_EXCEPTION_SOURCE_ACCESSIBLE,
    	SPI_EXCEPTION_SOURCE_REGISTRY,
    	SPI_EXCEPTION_SOURCE_DEVICE
    } SPIExceptionType;

The general source of the failure, i.e. whether the app, registry, or device system has encountered trouble.

`SPI_EXCEPTION_SOURCE_UNSPECIFIED` | Don't know or can't tell where the problem is
`SPI_EXCEPTION_SOURCE_ACCESSIBLE` | The source of an event or query (i.e. an app) has thrown the exception.
`SPI_EXCEPTION_SOURCE_REGISTRY` | The AT-SPI registry has thrown the exception or cannot be reached.
`SPI_EXCEPTION_SOURCE_DEVICE` | The device event subsystem has encountered an error condition.

### SPIExceptionHandler ()

    SPIBoolean          (*SPIExceptionHandler)              (SPIException *err,
                                                             SPIBoolean is_fatal);

A function type for functions to be called when exceptions occur.

`err` : | points to the SPIException opaque object.
`is_fatal` : | indicates whether the exception is a fatal error or not.
Returns : |

### SPIRect

    typedef struct {
    	long x;
    	long y;
    	long width;
    	long height;
    } SPIRect;

A structure encapsulating a rectangle.

### SPI_freeRect ()

    void                SPI_freeRect                        (SPIRect *r);

Free a SPIRect structure returned from an at-spi call. Clients of at-spi should use this function instead of `free()` or `g_free()`. A NULL rect `r` will be silently ignored. This API should not be used to free data from other libraries or allocated by the client.

`Since`: AT-SPI 1.6

`r` : | a pointer to an SPIRect returned from another at-spi call.

### SPI_dupString ()

    char*               SPI_dupString                       (char *s);

`Since`: AT-SPI 1.4

`s` : | a UTF-8 string to be duplicated
Returns : | a duplicate of the string passed as a parameter, which should be freed via SPI_freeString after use.

### SPI_exceptionHandlerPush ()

    SPIBoolean          SPI_exceptionHandlerPush            (SPIExceptionHandler *handler);

Install a client-side handler for SPIException instances, which can see and handle any exceptions before chaining them to the next exception handler in the stack.

`Since`: AT-SPI 1.4

`handler` : | an SPIExceptionHandler to install as the first code to deal with exceptions.
Returns : | `TRUE` if the result succeeded, `FALSE` if `hander` could not be registered.

### SPI_exceptionHandlerPop ()

    SPIExceptionHandler* SPI_exceptionHandlerPop            (void);

Remove/pop an SPIExceptionHandler off the error handler stack and return the new handler.

`Since`: AT-SPI 1.4

Returns : | the SPIExceptionHandler which is now at the top of the error handler stack after the call.