fdselect input

Name

input-fdselect : fdselect input

Synopsis

#include <ggi/input/fdselect.h>

input-fdselect: [-auto=no] [-notify=fd|set] [-read=<fd>[,<fd>...]]
                [-write=<fd>[,<fd>...]] [-except=<fd>[,<fd>...]]

Description

Adds file descriptors to the libgii 'reactor' that break out of a call to giiEventPoll(3) or giiEventRead(3).

Options

'-auto=no'

By default, file descriptors that are ready are not removed from the reactor when they are ready. Specify '-auto=no' to have them removed when ready and thus avoid multiple notifications about the same file descriptors.

'-notify=fd|set'

Selects which kind of notifications are broadcasted. See the section Notifications below for details.

'-read=<fd>[,<fd>...]'

List of file descriptors to check if they are ready to read.

'-write=<fd>[,<fd>...]'

List of file descriptors to check if they are ready to write.

'-except=<fd>[,<fd>...]'

List of file descriptors to check if they are in an exceptional state.

Controls

An input-fdselect module understands the following command codes sent by ggControl(3):

GII_FDSELECT_RELOAD

Reloads all file descriptors into the reactor that have been signalled as ready.

GII_FDSELECT_ADD

Adds the file descriptor fd to the sets indicated by mode.

Data:

struct gii_fdselect_fd {
        int fd;
        int mode;
};
GII_FDSELECT_DEL

Deletes the file descriptor fd from the sets indicated by mode.

Data:

struct gii_fdselect_fd {
        int fd;
        int mode;
};
GII_FDSELECT_DEL_ALL

Deletes all file descriptors from all the sets.

GII_FDSELECT_SET_FDSET

Sets the file descriptor sets to the content indicated by the three members rfd, wfd and efd. rfd is file descriptors to check if they are ready to reading, 'wfd' to check if they are ready for writing and efd is to check if they are in an exceptional state. The maxfd member should be larger that the largest file descriptor in any of those sets. If NULL is supplied as one of the fd_set variables, that is interpreted as an empty set.

Data:

struct gii_fdselect_fdset {
        fd_set *rfd;
        fd_set *wfd;
        fd_set *efd;
        int maxfd;
};
GII_FDSELECT_GET_FDSET

Gets the currently active file descriptor sets, i.e. the complement to those which have been notified since the last GII_FDSELECT_RELOAD operation when -auto=no has been specified. For the default case (w/o -auto=no), all added file descriptors are returned. The maxfd member is one larger than the largest file descriptor in any of those sets, and zero when there are no file descriptors in any of the sets. If NULL is supplied as one of the fd_set variables, file descriptors of that category are not returned.

Data:

struct gii_fdselect_fdset {
        fd_set *rfd;
        fd_set *wfd;
        fd_set *efd;
        int maxfd;
};

Notifications

An input-fdselect module will report the following events via ggBroadcast(3):

GII_FDSELECT_READY

Signals that the fd is ready for the actions indicated by mode.

This type of notification can be requested by supplying the -notify=fd option, but it is the default notification.

Data:

struct gii_fdselect_fd {
        int fd;
        int mode;
};
GII_FDSELECT_READY_FDSET

Signals all file descriptors that are ready and in what way they are ready. If the file descriptor is a member of rfd, it is ready for reading, if it is a member of wfd, it is ready for writing and if it is a member of efd it is in an exceptional state. The maxfd member is one larger than the largest file descriptor in any of those sets, and zero when there are no file descriptors in any of the sets.

This type of notification can be requested by supplying the -notify=set option.

Data:

struct gii_fdselect_fdset {
        fd_set *rfd;
        fd_set *wfd;
        fd_set *efd;
        int maxfd;
};

Note, the mode member of struct gii_fdselect_fd used by the controls GII_FDSELECT_ADD and GII_FDSELECT_DEL and the notification GII_FDSELECT_READY is a bitwise or of the following bits:

GII_FDSELECT_READ
GII_FDSELECT_WRITE
GII_FDSELECT_EXCEPT

Examples

Initialize input-fdselect:

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

struct context {
        struct gg_stem *stem;
        struct gg_plugin *fdselect;
        int fd;
};

int
callback(void *arg, uint32_t flag, void *data)
{
        struct context *ctx = arg;
        struct gii_fdselect_fd *fd = data;

        if (flag != GII_FDSELECT_READY)
                return GGI_OK;

        if (fd->fd != ctx->fd)
                return GGI_OK;

        if (!(fd->mode & GII_FDSELECT_READ))
                return GGI_OK;

        /* handle read */

        return GGI_OK;
}

int
init_read(struct context *ctx)
{
        struct gii_fdselect_fd fd;

        ctx->fdselect = ggPlugModule(libgii, ctx->stem,
                "input-fdselect", "-notify=fd", NULL);

        fd.fd = ctx->fd;
        fd.mode = GII_FDSELECT_READ;
        ggControl(ctx->fdselect->channel, GII_FDSELECT_ADD, &fd);

        ggObserve(ctx->fdselect->channel, callback, ctx);
}

int
cleanup(struct context *ctx)
{
        ggClosePlugin(ctx->fdselect);
}