SPI main loop and initialization

SPI main loop and initialization

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.