giiOpen(3gii)

NAME
giiOpen, giiJoinInputs, giiClose - Open, join and close inputs

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 giiClose(gii_input_t inp); .SH "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* 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: <library_name>: <arguments>

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.

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.

RETURN VALUE

giiOpen and giiJoin return the opened or joined input (gii_input_t), or NULL for error.

giiClose returns 0 for OK, otherwise an error code.

EXAMPLES

gii_input_t inp,inp2;
/* 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);
}
/* 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) ! */
... do the real work here ...
/* Close the joined input */
giiClose(inp);
/* Now close down LibGII. */
giiExit();

SEE ALSO
giiInit(3)