giiOpen, giiJoinInputs, giiSplitInputs, giiClose : Open,
join, split and close inputs

#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_t origin, uint32_t flags);

int giiClose(gii_input_t inp);

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 * 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 input parameter, in the format:

giiJoinInputs joins two inputs into one. From a programmers’
point of view, this closes both inp and inp2 and opens an
new input that combines both inputs into one. That is, after
giiJoinInputs has completed, there is no need to giiClose
inp and 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 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 inp, then the handle returned
in 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 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 ggiEventRead(3) with the LibGGI
     visual instead.

giiOpen and giiJoinInputs 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 GII functions.

giiClose returns GGI_OK (== 0) on success, otherwise an gii‐
error(3) code.

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

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) {

/* Open stdin for testing ... */
if ((inp2=giiOpen("input‐stdin",NULL)) == NULL) {

/* Open evdev for testing ... */
if ((inp3=giiOpen("input‐linux‐evdev",NULL)) == NULL) {

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


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

/* Join another */

/* ... 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 < 0) fprintf(stderr, "Failed to split inputs\n");

/* Close the single input */

/* Close the joined input */

/* Now close down LibGII. */