Iterate over input sources and devices

Name

giiIterSources, giiIterFillSources, giiIterDevices, giiIterFillDevices : Iterate over input sources and devices

Synopsis

#include <ggi/gg.h>
#include <ggi/gii.h>

struct gii_source_iter {
      struct gg_iter iter;

      /* These must be set by the caller before calling
       * giiIterSource
       */
      gii_input stem;

      /* Placeholders for results */
      uint32_t origin;
      void *src;

      /* Internal */
      void *_state;
};

#define giiIterFillSources(_iter, _stem)                        \
              (_iter)->stem = (_stem);

int giiIterSources(struct gii_source_iter *iter);


struct gii_device_iter {
      struct gg_iter iter;

      /* These must be set by the caller before calling
       * giiIterDevice
       */
      gii_input stem;
      uint32_t source_origin;
      void *src;              /* NULL means use source_origin */

      /* Placeholders for results */
      uint32_t origin;
      struct gii_cmddata_devinfo devinfo;

      /* Internal */
      void *_state;
};

#define giiIterFillDevices(_iter, _stem, _src, _src_origin)   \
              (_iter)->stem = (_stem);                        \
              (_iter)->src = (_src);                          \
              (_iter)->source_origin = (_src_origin);

int giiIterDevices(struct gii_device_iter *iter);

Description

These functions provide a way to iterate over input sources and devices.

input sources are per-target. A target can provide one or more input devices. Therefore, an input source can contain multiple input devices.

giiIterSources allows to iterate over all input sources. This function will prepare the iter structure to be used as an iterator. iter is a pointer to a gii_source_iter structure owned by the caller. This user part of the structure must be set by the caller before calling giiIterSources. The stem field must be filled with the stem associated with the input sources. origin and src are placeholders in which the results will be found along the iteration. origin contains the number of the input source and src is a pointer to the source. The resulting pointer belongs to libgii and must not be freed or altered, and they may be invalidated if not used during the iteration process. They must be copied if needed later. _state is an internal opaque pointer that keeps track of the iterator state. Its value must never be touched by the caller.

giiIterDevices allows to iterate over all input devices of a certain input source. This function will prepare the iter structure to be used as an iterator. iter is a pointer to a gii_device_iter structure owned by the caller. This user part of the structure must be set by the caller before calling giiIterDevices. The stem field must be filled with the stem associated with the input sources and devices. The source_origin and src fields determine the input source to iterate over. src can only be filled with the src result pointer from the gii_source_iter structure or must be set to NULL. If src is NULL, source_origin specifies the origin of an input source. It may be the origin from the gii_device_iter structure. When src is non-NULL, then source_origin value is not used, so setting both fields has the same effect as setting the src field only. Specifying invalid values that don't cover any specified cases above results in undefed behaviour. The origin and devinfo fields are placeholders in which the results will be found along the iteration. origin contains the origin number of the input device and devinfo contains the gii_cmddata_devinfo(3) structure of the device. The origin and devinfo fields are copies from the libgii internals and change during iteration. So changes to them have no effect and must be copied if needed later. _state is an internal opaque pointer that keeps track of the iterator state. Its value must never be touched by the caller.

giiIterFillSources is a helper macro that may be used to fill out the gii_source_iter structure.

giiIterFillDevices is a helper macro that may be used to fill out the gii_device_iter structure.

Return value

giiIterFillSources and giiIterFillDevices are helper macros. Their return type is void.

giiIterSources and giiIterDevices return GGI_OK on success or a gg-error(3) error code otherwise.

Example

This code demonstrates how to iterate over all input sources and input devices:

struct gii_source_iter src_iter;
struct gii_device_iter dev_iter;
uint32_t dev_origin;
struct gii_cmddata_devinfo *devinfo;

giiIterFillSources(&src_iter, stem);
giiIterSources(&src_iter);
GG_ITER_FOREACH(&src_iter) {
      giiIterFillDevices(&dev_iter, stem, src_iter.src, src_iter.origin);
      giiIterDevices(&dev_iter);
      GG_ITER_FOREACH(&dev_iter) {
              ...
              /* device origin */
              dev_origin = dev_iter.origin;
              /* device info */
              devinfo = &dev_iter.devinfo;

              ...

              /* do something with the device data */

              ...

      }
      GG_ITER_DONE(&dev_iter);
}
GG_ITER_DONE(&src_iter);

See Also