<refentry id="at-spi-cspi-SPI-main-loop-and-initialization">
<refmeta>
<refentrytitle role="top_of_page" id="at-spi-cspi-SPI-main-loop-and-initialization.top_of_page">SPI main loop and initialization</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>AT-SPI-CSPI Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>SPI main loop and initialization</refname>
<refpurpose></refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="at-spi-cspi-SPI-main-loop-and-initialization.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
<link linkend="int">int</link>                 <link linkend="SPI-init">SPI_init</link>                            (void);
<link linkend="void">void</link>                <link linkend="SPI-event-main">SPI_event_main</link>                      (void);
<link linkend="void">void</link>                <link linkend="SPI-event-quit">SPI_event_quit</link>                      (void);
<link linkend="SPIBoolean">SPIBoolean</link>          <link linkend="SPI-eventIsReady">SPI_eventIsReady</link>                    (void);
<link linkend="AccessibleEvent">AccessibleEvent</link>*    <link linkend="SPI-nextEvent">SPI_nextEvent</link>                       (<link linkend="SPIBoolean">SPIBoolean</link> waitForEvent);
<link linkend="int">int</link>                 <link linkend="SPI-exit">SPI_exit</link>                            (void);

<link linkend="void">void</link>                <link linkend="SPI-freeString">SPI_freeString</link>                      (<link linkend="char">char</link> *s);
<link linkend="Accessible">Accessible</link>*         <link linkend="SPIAccessibleException-getSource">SPIAccessibleException_getSource</link>    (<link linkend="SPIException">SPIException</link> *err);
<link linkend="char">char</link>*               <link linkend="SPIException-getDescription">SPIException_getDescription</link>         (<link linkend="SPIException">SPIException</link> *err);
<link linkend="SPIExceptionCode">SPIExceptionCode</link>    <link linkend="SPIException-getExceptionCode">SPIException_getExceptionCode</link>       (<link linkend="SPIException">SPIException</link> *err);
<link linkend="SPIExceptionType">SPIExceptionType</link>    <link linkend="SPIException-getSourceType">SPIException_getSourceType</link>          (<link linkend="SPIException">SPIException</link> *err);
                    <link linkend="SPIException">SPIException</link>;
enum                <link linkend="SPIExceptionCode">SPIExceptionCode</link>;
enum                <link linkend="SPIExceptionType">SPIExceptionType</link>;
<link linkend="SPIBoolean">SPIBoolean</link>          (<link linkend="SPIExceptionHandler">*SPIExceptionHandler</link>)              (<link linkend="SPIException">SPIException</link> *err,
                                                         <link linkend="SPIBoolean">SPIBoolean</link> is_fatal);
                    <link linkend="SPIRect">SPIRect</link>;
<link linkend="void">void</link>                <link linkend="SPI-freeRect">SPI_freeRect</link>                        (<link linkend="SPIRect">SPIRect</link> *r);
<link linkend="char">char</link>*               <link linkend="SPI-dupString">SPI_dupString</link>                       (<link linkend="char">char</link> *s);
<link linkend="SPIBoolean">SPIBoolean</link>          <link linkend="SPI-exceptionHandlerPush">SPI_exceptionHandlerPush</link>            (<link linkend="SPIExceptionHandler">SPIExceptionHandler</link> *handler);
<link linkend="SPIExceptionHandler">SPIExceptionHandler</link>* <link linkend="SPI-exceptionHandlerPop">SPI_exceptionHandlerPop</link>            (void);
</synopsis>
</refsynopsisdiv>









<refsect1 id="at-spi-cspi-SPI-main-loop-and-initialization.description" role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="at-spi-cspi-SPI-main-loop-and-initialization.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="SPI-init" role="function">
<title>SPI_init ()</title>
<indexterm zone="SPI-init"><primary>SPI_init</primary></indexterm><programlisting><link linkend="int">int</link>                 SPI_init                            (void);</programlisting>
<para>
Connects to the accessibility registry and initializes the SPI.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 on success, otherwise an integer error code.  
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPI-event-main" role="function">
<title>SPI_event_main ()</title>
<indexterm zone="SPI-event-main"><primary>SPI_event_main</primary></indexterm><programlisting><link linkend="void">void</link>                SPI_event_main                      (void);</programlisting>
<para>
Starts/enters the main event loop for the SPI services.
</para>
<para>
(NOTE: This method does not return control, it is exited via a call to
 <link linkend="SPI-event-quit"><function>SPI_event_quit()</function></link> from within an event handler).</para>
<para>

</para></refsect2>
<refsect2 id="SPI-event-quit" role="function">
<title>SPI_event_quit ()</title>
<indexterm zone="SPI-event-quit"><primary>SPI_event_quit</primary></indexterm><programlisting><link linkend="void">void</link>                SPI_event_quit                      (void);</programlisting>
<para>
Quits the last main event loop for the SPI services,
see SPI_event_main</para>
<para>

</para></refsect2>
<refsect2 id="SPI-eventIsReady" role="function">
<title>SPI_eventIsReady ()</title>
<indexterm zone="SPI-eventIsReady"><primary>SPI_eventIsReady</primary></indexterm><programlisting><link linkend="SPIBoolean">SPIBoolean</link>          SPI_eventIsReady                    (void);</programlisting>
<para>
Checks to see if an SPI event is waiting in the event queue.
Used by clients that don't wish to use <link linkend="SPI-event-main"><function>SPI_event_main()</function></link>.
</para>
<para>
Not Yet Implemented.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><type>TRUE</type></link> if an event is waiting, otherwise <link linkend="FALSE:CAPS"><type>FALSE</type></link>.

</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPI-nextEvent" role="function">
<title>SPI_nextEvent ()</title>
<indexterm zone="SPI-nextEvent"><primary>SPI_nextEvent</primary></indexterm><programlisting><link linkend="AccessibleEvent">AccessibleEvent</link>*    SPI_nextEvent                       (<link linkend="SPIBoolean">SPIBoolean</link> waitForEvent);</programlisting>
<para>
Gets the next event in the SPI event queue; blocks if no event
is pending and <parameter>waitForEvent</parameter> is <link linkend="TRUE:CAPS"><type>TRUE</type></link>.
Used by clients that don't wish to use <link linkend="SPI-event-main"><function>SPI_event_main()</function></link>.
</para>
<para>
Not Yet Implemented.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>waitForEvent</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="SPIBoolean"><type>SPIBoolean</type></link> indicating whether to block or not.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the next <link linkend="AccessibleEvent"><type>AccessibleEvent</type></link> in the SPI event queue.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPI-exit" role="function">
<title>SPI_exit ()</title>
<indexterm zone="SPI-exit"><primary>SPI_exit</primary></indexterm><programlisting><link linkend="int">int</link>                 SPI_exit                            (void);</programlisting>
<para>
Disconnects from the Accessibility Registry and releases 
any floating resources. Call only once at exit.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 if there were no leaks, otherwise non zero.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPI-freeString" role="function">
<title>SPI_freeString ()</title>
<indexterm zone="SPI-freeString"><primary>SPI_freeString</primary></indexterm><programlisting><link linkend="void">void</link>                SPI_freeString                      (<link linkend="char">char</link> *s);</programlisting>
<para>
Free a character string returned from an at-spi call.  Clients of
at-spi should use this function instead of <link linkend="free"><function>free()</function></link> or <link linkend="g-free"><function>g_free()</function></link>.
A NULL string <parameter>s</parameter> will be silently ignored.
This API should not be used to free strings
from other libraries or allocated by the client.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
<listitem><simpara> a character string returned from another at-spi call.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIAccessibleException-getSource" role="function">
<title>SPIAccessibleException_getSource ()</title>
<indexterm zone="SPIAccessibleException-getSource"><primary>SPIAccessibleException_getSource</primary></indexterm><programlisting><link linkend="Accessible">Accessible</link>*         SPIAccessibleException_getSource    (<link linkend="SPIException">SPIException</link> *err);</programlisting>
<para>
Get the identity of the object which threw an exception.
</para>
<para>
<parameter>Since</parameter>: AT-SPI 1.4</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="SPIException"><type>SPIException</type></link> being queried.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a pointer to the <link linkend="Accessible"><type>Accessible</type></link> object which threw the exception.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIException-getDescription" role="function">
<title>SPIException_getDescription ()</title>
<indexterm zone="SPIException-getDescription"><primary>SPIException_getDescription</primary></indexterm><programlisting><link linkend="char">char</link>*               SPIException_getDescription         (<link linkend="SPIException">SPIException</link> *err);</programlisting>
<para>
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.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="SPIException"><type>SPIException</type></link> being queried.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a brief character string describing the exception.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIException-getExceptionCode" role="function">
<title>SPIException_getExceptionCode ()</title>
<indexterm zone="SPIException-getExceptionCode"><primary>SPIException_getExceptionCode</primary></indexterm><programlisting><link linkend="SPIExceptionCode">SPIExceptionCode</link>    SPIException_getExceptionCode       (<link linkend="SPIException">SPIException</link> *err);</programlisting>
<para>
Get the <link linkend="SPIExceptionCode"><type>SPIExceptionCode</type></link> telling what type of exception condition has occurred.
</para>
<para>
<parameter>Since</parameter>: AT-SPI 1.4</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="SPIException"><type>SPIException</type></link> being queried.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the <link linkend="SPIExceptionCode"><type>SPIExceptionCode</type></link> corresponding to exception <parameter>err</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIException-getSourceType" role="function">
<title>SPIException_getSourceType ()</title>
<indexterm zone="SPIException-getSourceType"><primary>SPIException_getSourceType</primary></indexterm><programlisting><link linkend="SPIExceptionType">SPIExceptionType</link>    SPIException_getSourceType          (<link linkend="SPIException">SPIException</link> *err);</programlisting>
<para>
Get the <link linkend="SPIExceptionType"><type>SPIExceptionType</type></link> of an exception which has been thrown.
</para>
<para>
<parameter>Since</parameter>: AT-SPI 1.4</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> the exception being queried
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the <link linkend="SPIExceptionType"><type>SPIExceptionType</type></link> corresponding to exception <parameter>err</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIException" role="struct">
<title>SPIException</title>
<indexterm zone="SPIException"><primary>SPIException</primary></indexterm><programlisting>typedef struct {
  SPIExceptionType type;
  CORBA_Object source;
  CORBA_Environment *ev;
  SPIExceptionCode code;
  char * desc;
} SPIException;
</programlisting>
<para>
An opaque object encapsulating information about thrown exceptions.</para>
<para>

</para><variablelist role="struct">
<varlistentry>
<term><link linkend="SPIExceptionType">SPIExceptionType</link>&nbsp;<structfield>type</structfield>;</term>
<listitem><simpara> private
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="CORBA-Object">CORBA_Object</link>&nbsp;<structfield>source</structfield>;</term>
<listitem><simpara> private
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="CORBA-Environment">CORBA_Environment</link>&nbsp;*<structfield>ev</structfield>;</term>
<listitem><simpara> private
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="SPIExceptionCode">SPIExceptionCode</link>&nbsp;<structfield>code</structfield>;</term>
<listitem><simpara> private
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="char">char</link>&nbsp;*<structfield>desc</structfield>;</term>
<listitem><simpara> private
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIExceptionCode" role="enum">
<title>enum SPIExceptionCode</title>
<indexterm zone="SPIExceptionCode"><primary>SPIExceptionCode</primary></indexterm><programlisting>typedef enum {
	SPI_EXCEPTION_UNSPECIFIED,
	SPI_EXCEPTION_DISCONNECT,
	SPI_EXCEPTION_NO_IMPL,
	SPI_EXCEPTION_IO,
	SPI_EXCEPTION_BAD_DATA
} SPIExceptionCode;
</programlisting>
<para>
Exception codes indicating what's gone wrong in an AT-SPI call.</para>
<para>

</para><variablelist role="enum">
<varlistentry id="SPI-EXCEPTION-UNSPECIFIED:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_UNSPECIFIED</literal></term>
<listitem><simpara> An exception of unknown type, or which doesn't fit the other types.
</simpara></listitem>
</varlistentry>
<varlistentry id="SPI-EXCEPTION-DISCONNECT:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_DISCONNECT</literal></term>
<listitem><simpara> Communication with the object or service has been disconnected;
this usually means that the object or service has died or exited.
</simpara></listitem>
</varlistentry>
<varlistentry id="SPI-EXCEPTION-NO-IMPL:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_NO_IMPL</literal></term>
<listitem><simpara> The object or service is missing the implementation for a request.
</simpara></listitem>
</varlistentry>
<varlistentry id="SPI-EXCEPTION-IO:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_IO</literal></term>
<listitem><simpara> The communications channel has become corrupted, blocked, or is otherwise in a bad state.
</simpara></listitem>
</varlistentry>
<varlistentry id="SPI-EXCEPTION-BAD-DATA:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_BAD_DATA</literal></term>
<listitem><simpara> The data received or sent over the interface has been identified as 
improperly formatted or otherwise fails to match the expectations.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIExceptionType" role="enum">
<title>enum SPIExceptionType</title>
<indexterm zone="SPIExceptionType"><primary>SPIExceptionType</primary></indexterm><programlisting>typedef enum {
	SPI_EXCEPTION_SOURCE_UNSPECIFIED,
	SPI_EXCEPTION_SOURCE_ACCESSIBLE,
	SPI_EXCEPTION_SOURCE_REGISTRY,
	SPI_EXCEPTION_SOURCE_DEVICE
} SPIExceptionType;
</programlisting>
<para>
The general source of the failure, i.e. whether the app, registry, or device system has encountered trouble.</para>
<para>

</para><variablelist role="enum">
<varlistentry id="SPI-EXCEPTION-SOURCE-UNSPECIFIED:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_SOURCE_UNSPECIFIED</literal></term>
<listitem><simpara> Don't know or can't tell where the problem is
</simpara></listitem>
</varlistentry>
<varlistentry id="SPI-EXCEPTION-SOURCE-ACCESSIBLE:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_SOURCE_ACCESSIBLE</literal></term>
<listitem><simpara> The source of an event or query (i.e. an app) has thrown the exception.
</simpara></listitem>
</varlistentry>
<varlistentry id="SPI-EXCEPTION-SOURCE-REGISTRY:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_SOURCE_REGISTRY</literal></term>
<listitem><simpara> The AT-SPI registry has thrown the exception or cannot be reached.
</simpara></listitem>
</varlistentry>
<varlistentry id="SPI-EXCEPTION-SOURCE-DEVICE:CAPS" role="constant">
<term><literal>SPI_EXCEPTION_SOURCE_DEVICE</literal></term>
<listitem><simpara> The device event subsystem has encountered an error condition.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIExceptionHandler" role="function">
<title>SPIExceptionHandler ()</title>
<indexterm zone="SPIExceptionHandler"><primary>SPIExceptionHandler</primary></indexterm><programlisting><link linkend="SPIBoolean">SPIBoolean</link>          (*SPIExceptionHandler)              (<link linkend="SPIException">SPIException</link> *err,
                                                         <link linkend="SPIBoolean">SPIBoolean</link> is_fatal);</programlisting>
<para>
A function type for functions to be called when exceptions occur.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
<listitem><simpara> points to the SPIException opaque object.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>is_fatal</parameter>&nbsp;:</term>
<listitem><simpara> indicates whether the exception is a fatal error or not.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPIRect" role="struct">
<title>SPIRect</title>
<indexterm zone="SPIRect"><primary>SPIRect</primary></indexterm><programlisting>typedef struct {
	long x;
	long y;
	long width;
	long height;
} SPIRect;
</programlisting>
<para>
A structure encapsulating a rectangle.</para>
<para>

</para><variablelist role="struct">
</variablelist></refsect2>
<refsect2 id="SPI-freeRect" role="function">
<title>SPI_freeRect ()</title>
<indexterm zone="SPI-freeRect"><primary>SPI_freeRect</primary></indexterm><programlisting><link linkend="void">void</link>                SPI_freeRect                        (<link linkend="SPIRect">SPIRect</link> *r);</programlisting>
<para>
Free a SPIRect structure returned from an at-spi call.  Clients of
at-spi should use this function instead of <link linkend="free"><function>free()</function></link> or <link linkend="g-free"><function>g_free()</function></link>.
A NULL rect <parameter>r</parameter> will be silently ignored.
This API should not be used to free data
from other libraries or allocated by the client.
</para>
<para>
<parameter>Since</parameter>: AT-SPI 1.6</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>r</parameter>&nbsp;:</term>
<listitem><simpara> a pointer to an SPIRect returned from another at-spi call.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPI-dupString" role="function">
<title>SPI_dupString ()</title>
<indexterm zone="SPI-dupString"><primary>SPI_dupString</primary></indexterm><programlisting><link linkend="char">char</link>*               SPI_dupString                       (<link linkend="char">char</link> *s);</programlisting>
<para>
<parameter>Since</parameter>: AT-SPI 1.4</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
<listitem><simpara> a UTF-8 string to be duplicated
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a duplicate of the string passed as a parameter, which should
be freed via SPI_freeString after use.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPI-exceptionHandlerPush" role="function">
<title>SPI_exceptionHandlerPush ()</title>
<indexterm zone="SPI-exceptionHandlerPush"><primary>SPI_exceptionHandlerPush</primary></indexterm><programlisting><link linkend="SPIBoolean">SPIBoolean</link>          SPI_exceptionHandlerPush            (<link linkend="SPIExceptionHandler">SPIExceptionHandler</link> *handler);</programlisting>
<para>
Install a client-side handler for <link linkend="SPIException"><type>SPIException</type></link> instances, which can see and handle any
exceptions before chaining them to the next exception handler in the stack.
</para>
<para>
<parameter>Since</parameter>: AT-SPI 1.4</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>handler</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="SPIExceptionHandler"><type>SPIExceptionHandler</type></link> to install as the first code to deal with exceptions.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the result succeeded, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if <parameter>hander</parameter> could not be registered.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="SPI-exceptionHandlerPop" role="function">
<title>SPI_exceptionHandlerPop ()</title>
<indexterm zone="SPI-exceptionHandlerPop"><primary>SPI_exceptionHandlerPop</primary></indexterm><programlisting><link linkend="SPIExceptionHandler">SPIExceptionHandler</link>* SPI_exceptionHandlerPop            (void);</programlisting>
<para>
Remove/pop an <link linkend="SPIExceptionHandler"><type>SPIExceptionHandler</type></link> off the error handler stack and return the new handler.
</para>
<para>
<parameter>Since</parameter>: AT-SPI 1.4</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="SPIExceptionHandler"><type>SPIExceptionHandler</type></link> which is now at the top of the error handler stack after the call.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
