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.