LibGII Functions
================


Initialize and uninitialize LibGII
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiInit giiExit


Synopsis
--------

::

  #include <ggi/gii.h>

  int giiInit(void);

  int giiExit(void);


Description
-----------

`giiInit` initializes the library. This function must be called before
using other LibGII functions; otherwise the results will be undefined.


`giiExit` uninitializes the library (after being initialized by
`giiInit`) and automatically cleanup if necessary.  This should be
called after an application is finished with the library.  If any GGI
functions are called after the library has been uninitialized, the
results will be undefined.


`giiInit` allows multiple invocations.  A reference count is
maintained, and to completely uninitialize the library, `giiExit` must
be called as many times as `giiInit` has been called beforehand.

Return value
------------

`giiInit` returns `0` for OK, otherwise an error code.

`giiExit` returns:

0
        after successfully cleaning up,

>0
        the number of 'open' `giiInit` calls, if there has been more
	than one call to `giiInit`.  As `giiInit` and `giiExit` must
	be used in properly nested pairs, e.g. the first `giiExit`
	after two `giiInit` will return 1.

<0
        error, especially if more `giiExit` calls have been done than
        `giiInit` calls.


Examples
--------

Initialize and uninitialize LibGII::

  if (!giiInit()) {
    exit(EXIT_FAILURE);  /* can't start! */
  }

  /* Do some libgii stuff */	

  giiExit();


See also
--------

:man:`giiMTInit(3)`, :man:`giiOpen(3)`






Make LibGII thread-safe
~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiMTInit


Synopsis
--------

::

  #include <ggi/gii.h>

  int giiMTInit(void);


Description
-----------

`giiMTInit` sets up LibGII so that it is fully thread-safe. This
allows the application to call LibGII functions (on the same input)
without doing its own locking. This will enable extra checks and locks
that are off by default to avoid overhead.

This function does not replace `giiInit`, which must still be called
at least once.


Return Value
------------

`giiMTInit` returns `0` on successful execution.


Known Bugs
----------

This function has not been well tested.


See Also
--------

:man:`giiInit(3)`






Exit LibGII programs for fatal errors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiPanic

Synopsis
--------

::

  #include <ggi/gii.h>

  `int giiPanic(const char * format, ...);


Description
-----------

`ggiPanic` shuts down the application, closing all inputs, with
:man:`printf(3)`-style reporting to stderr, taking a format string and
any additional variables.

`giiPanic` should only be used by usermode programs when something is
really screwed, and they do not know what to do. The same applies for
libraries, but might be used in rare situations such as corruption of
critical data structures.

Examples
--------

An unrecoverable error::

  if (my_important_struct->magic != MAGIC) {
    giiPanic("Fatal error: magic corrupted\n");
  }






Open, join, split and close inputs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiOpen giiJoinInputs giiSplitInputs giiClose

Synopsis
--------

::

  #include <ggi/gii.h>

  gii_input_t giiOpen(const char * input, ...);

  gii_input_t giiJoinInputs(gii_input_t inp, gii_input_t inp2);

  int giiSplitInputs(gii_input_t inp, gii_input_t *newhand,
		     uint32 origin, uint32 flags);

  int gii_input_t giiClose(gii_input_t inp);


Description
-----------

`giiOpen` opens an input. This function is given the name of an input
driver to load. Passing `NULL` here results in an auto-select
mechanism, which currently means examining the contents of
`GII_INPUT`.


The optional arguments are a `NULL`-terminated list of pointers, which
are used to give additional information to the targets.  Currently
only the first pointer is specified: `void *` :p:`argptr`, a pointer
to a library-specific struct. It is used to pass parameters that are
not easily transferable in textual form.


Parameters which can be represented in text format are usually
transfered in the :p:`input` parameter, in the format:
``library_name:arguments``


`giiJoinInputs` joins two inputs into one. From a programmers' point
of view, this closes both :p:`inp` and :p:`inp2` and opens an new
input that combines both inputs into one. That is, after
`giiJoinInputs` has completed, there is no need to `giiClose` :p:`inp`
and :p:`inp2` any more. When cleaning up, you need to close the
returned input instead. See the example for details. However the
inputs are not actually closed or reopened internally. That is, you
will not get any startup-events or similar the driver generates,
though pending events of both old inputs are transferred to the newly
created input.


`giiSplitInputs` splits one of the inputs from a group of joined
inputs and returns the handle. The parameter :p:`origin` can be used
to choose which input to detach (use `GGI_EV_ORIGIN_NONE` to match any
input.)  The detached handle is returned in newhand. Note, though,
that if the detached input is the same one given in :p:`inp`, then the
handle returned in :p:`newhand` will be that of the rest of the joined
inputs instead.  You can tell whether this happened by checking the
return code.  Events queued in the joined input for the newly split
input are not transferred automatically.  You must drain them out
yourself. The parameter :p:`flags` is reserved for future use and
should be set to 0.


`giiClose` releases and destroys an open input and its associated
internal control structures. This will put back input streams to their
default modes, etc.

.. important::

    If you want to handle input while also using LibGGI, using LibGII
    functions such as `giiOpen` is almost certainly **not** what you
    want.  Use LibGGI functions such as :man:`ggiEventRead(3)` with
    the LibGGI visual instead.


Return value
------------

`giiOpen` and `giiJoin` return the opened or joined input, or `NULL`
for error.  The `gii_input_t` type is opaque to the programmer and can
only be used through GGI functions.


`giiClose` returns `GGI_OK` (== 0) for OK, otherwise an error code.


`giiSplitInputs` returns `GGI_OK` (== `0`) for normal success, or `1`
if the input which was split off was the same as the one passed in
:p:`inp` (in which case, :p:`newhand` may contain a handle to a joined
set of visuals.)  Otherwise, it returns an error code.


Examples
--------

GII input management::

  gii_input_t inp, inp2, inp3;

  /* Initialize the GII library. This must be called before any other
   * GII function. */
  if (giiInit() != 0) exit(1);

  /* Open the nulldevice for testing ... */
  if ((inp=giiOpen("input-null",NULL)) == NULL) {
      giiExit();
      exit(1);
  }

  /* Open stdin for testing ... */
  if ((inp2=giiOpen("input-stdin",NULL)) == NULL) {
      giiExit();
      exit(1);
  }

  /* Open evdev for testing ... */
  if ((inp3=giiOpen("input-linux-evdev",NULL)) == NULL) {
      giiExit();
      exit(1);
  }

  /* Now join them. Note the usage of _i_n_p_=_giiJoin(inp,inp2);
   * This is the recommended way to do this. */
  inp=giiJoinInputs(inp,inp2);

  /* Note that this mends inp2 into inp. That is you may not call
     giiClose(inp2) - this happens together with giiClose(inp) ! */

  /* Join another */
  inp=giiJoinInputs(inp,inp3);

  /* ... do the real work here ... */

  /* Split one of them back out of the join. */
  res = ggiSplitInputs(inp, &inp2, GII_EV_ORIGIN_NONE, 0);
  if (res == 1) {
      gii_input_t tmp;
      tmp = imp2;
      imp2 = imp1;
      imp1 = tmp;
  }
  else if (res &lt; 0) fprintf(stderr, "Failed to split inputs\n");

  /* Close the single input */
  giiClose(inp2);

  /* Close the joined input */
  giiClose(inp);

  /* Now close down LibGII. */
  giiExit();


See Also
--------

:man:`giiInit(3)`






Set the types of events queued
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiSetEventMask giiGetEventMask giiAddEventMask giiRemoveEventMask


Synopsis
--------

::

  #include <ggi/gii.h>

  int giiSetEventMask(gii_input_t inp, gii_event_mask evm);

  gii_event_mask giiGetEventMask(gii_input_t inp);

  int giiAddEventMask(gii_input_t inp, gii_event_mask evm);

  int giiRemoveEventMask(gii_input_t inp, gii_event_mask evm);


Description
-----------


Calling `giiSetEventMask` indicates to LibGII that only the types of
events that match the specified event mask will be read by the
application in subsequent `giiEventPoll` or `giiEventRead` calls.
LibGII can then save time and memory by skipping checks and not
allocating queues for events that will never be read out.  The default
mask allows all events.

`giiAddEventMask` and `giiRemoveEventMask` are macros that set or
delete individual bits in the bitmask.


.. note::

    `giiSetEventMask` is an advisory call.  For correct operation, the
    application still needs to pass a restrictive event mask to the
    event reading functions.


Return value
------------

`giiSetEventMask`, `giiAddEventMask` and `giiRemoveEventMask` return
`0` on success or an error code otherwise.


`giiGetEventMask` returns the currently set mask.


See Also
--------

:man:`gii_event_mask(3)`






Wait for and receive events
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiEventPoll giiEventSelect giiEventsQueued giiEventRead

Synopsis
--------

::

  #include <ggi/gii.h>

  gii_event_mask giiEventPoll(gii_input_t inp, gii_event_mask mask,
			      struct timeval *t);

  int giiEventSelect(gii_input_t inp, gii_event_mask *mask, int n,
                     fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
		     struct timeval *timeout);

  int giiEventsQueued(gii_input_t inp, gii_event_mask mask);

  int giiEventRead(gii_input_t inp, gii_event *ev, gii_event_mask mask);


Description
-----------

`giiEventPoll` waits for specific events to become available on an
input. This call somewhat resembles the Unix :man:`select(2)` call,
but only for LibGII events and is more portable.  The function returns
after an event matching the given event mask is available or after the
amount of time specified by :p:`t` has elapsed, whichever occurs
first.  If :p:`t` is `NULL`, there is no timeout.


The timeout value on return is updated to the time that would have
been remaining. So make sure to re-setup this value when calling
`giiEventPoll` in a loop.


`giiEventSelect` is the combination of `giiEventPoll` and
:man:`select(2)` allowing to wait for both LibGII events and arbitrary
file descriptors in any of the three states.  However, this function
is **not** available if the operating system does not support the
:man:`select(2)` call, not even as a stub.


`giiEventsQueued` returns the number of events matching the specified
event mask that are currently queued in the input.


`giiEventRead` blocks for and transfers an event from the given input
to the location pointed to by :p:`ev`. The event with the earliest
timestamp that matches the given mask is returned to the application.


Return value
------------


`giiEventPoll` returns a mask of available events (constrained by the
given mask).  It is `0` if no events are available.  On error, a
negative error code is returned.


`giiEventSelect` returns the same values as :man:`select(2)`.  Unlike
other LibGGI/LibGII functions, it also uses `errno`. It will update
the timeout regardless of whether or not the system call does so.


`giiEventsQueued` returns the number of events.


`giiEventRead` returns the size of event on success, and `0` on error.


Examples
--------

This is one of the various ways of coding an event-polling loop::

  for(;;) {
      tv.tv_sec = 0;
      tv.tv_usec = 100; /* change to 0 for non-blocking behaviour */

      ggiEventPoll(vis, emAll, &tv);
      n = ggiEventsQueued(vis, emAll);

      /* Process events in one gulp, when available */
      while(n--) {
          ggiEventRead(vis, &ggievent, emAll);
	  switch(ggievent.any.type) {
              /* ... */
	  }
      }

      /* Do other stuff */
  }

.. note::

    This code uses the LibGGI functions and types instead of the
    LibGII ones, since the former is the more common case.






Inject an event into the input
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiEventSend

Synopsis
--------

::

  #include <ggi/gii.h>

  int giiEventSend(gii_input_t inp, gii_event *ev);


Description
-----------

`giiEventSend` injects an event into the queue. Such events can be
identified by ``(event->any.target == GII_EV_TARGET_QUEUE)``.  There
are three main uses for this function:

1. *Simulating* input for independent subprograms.
2. Sending events to externally attached programs via specialized
       *inputs*, that are actually rather *outputs*.
3. Sending command events to inputs, like querying the axis
       of a valuator device.


Return value
------------

`giiEventSend` returns `0` on success, or an error code otherwise.


See Also
--------

:man:`giiEventPoll(3)`






Get information about input sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiQueryDeviceInfo giiQueryDeviceInfoByNumber


Synopsis
--------

::

  #include <ggi/gii.h>`

  int giiQueryDeviceInfo (gii_input_t inp, uint32 origin,
			  gii_cmddata_getdevinfo *info);

  int giiQueryDeviceInfoByNumber(gii_input_t inp, uint32 number,
                                 uint32 *origin, gii_cmddata_getdevinfo *info);


Description
-----------

Though when using GII inputs the exact type of device is fully
transparent to the program, information about the device that is
actually attached to a given gii input and origin id can be queried,
e.g. for configuration interfaces.

For `giiQueryDeviceInfo` the parameters :p:`inp` and :p:`origin`
select the input to query. This version is usually used, if you want
to identify a device after getting an event from it.

For `giiQueryDeviceInfoByNumber` the parameters :p:`inp` and
:p:`number` select the input to query - :p:`origin` gets set to the
origin ID the queried device has. This version is used, when you want
to query all known devices.


The queried data is put into :p:`info`.  See
:man:`gii_cmddata_getdevinfo(3)` for the description of the structure.


Return value
------------

Returns `0` on success (info is valid, then) or `-1` otherwise. 


See Also
--------

:man:`giiQueryValInfo(3)`






Get data about valuators
~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 giiQueryValInfo


Synopsis
--------

::

  #include <ggi/gii.h>

  int giiQueryValInfo(gii_input_t inp, uint32 origin,
                      uint32 valnumber, gii_cmddata_getvalinfo *info);


Description
-----------


Though when using GII inputs the exact type of device is fully
transparent to the program, information about the device that is
actually attached to a given gii input and origin id can be queried,
e.g. for configuration interfaces.


For `giiQueryValInfo` is used on devices, where `giiQueryDeviceInfo`
has indicated that the device has one or more valuator axes and you
want to gather additional info about the physical equivalent of each
axis.The parameters :p:`inp` and :p:`origin` select the input to query
and :p:`valnumber` selects the specific valuator (an input can have
multiple valuators).


The queried data is put into :p:`info`.  See
:man:`gii_cmddata_getvalinfo(3)` for the description of the structure.


Return value
------------

Returns `0` on success (:p:`info` is valid, then) or `-1` otherwise.


See Also
--------

:man:`giiQueryDeviceInfo(3)`
