code.delx.au - pulseaudio/blob - polyp/mainloop-api.h

   1 #ifndef foomainloopapihfoo
   2 #define foomainloopapihfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of polypaudio.
   8
   9   polypaudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as
  11   published by the Free Software Foundation; either version 2.1 of the
  12   License, or (at your option) any later version.
  13
  14   polypaudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public
  20   License along with polypaudio; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 #include <sys/time.h>
  26 #include <time.h>
  27
  28 #include "cdecl.h"
  29
  30 /** \file
  31  *
  32  * Main loop abstraction layer. Both the polypaudio core and the
  33  * polypaudio client library use a main loop abstraction layer. Due to
  34  * this it is possible to embed polypaudio into other
  35  * applications easily. Two main loop implemenations are
  36  * currently available:
  37  * \li A minimal implementation based on the C library's poll() function (See \ref mainloop.h)
  38  * \li A wrapper around the GLIB main loop. Use this to embed polypaudio into your GLIB/GTK+/GNOME programs (See \ref glib-mainloop.h)
  39  *
  40  * The structure pa_mainloop_api is used as vtable for the main loop abstraction.
  41  *
  42  * This mainloop abstraction layer has no direct support for UNIX signals. Generic, mainloop implementation agnostic support is available throught \ref mainloop-signal.h.
  43  * */
  44
  45 PA_C_DECL_BEGIN
  46
  47 /** A bitmask for IO events */
  48 enum pa_io_event_flags {
  49     PA_IO_EVENT_NULL = 0,     /**< No event */
  50     PA_IO_EVENT_INPUT = 1,    /**< Input event */
  51     PA_IO_EVENT_OUTPUT = 2,   /**< Output event */
  52     PA_IO_EVENT_HANGUP = 4,   /**< Hangup event */
  53     PA_IO_EVENT_ERROR = 8     /**< Error event */
  54 };
  55
  56 /** \struct pa_io_event
  57  * An opaque IO event source object */
  58 struct pa_io_event;
  59
  60 /** \struct pa_defer_event
  61  * An opaque deferred event source object. Events of this type are triggered once in every main loop iteration */
  62 struct pa_defer_event;
  63
  64 /** \struct pa_time_event
  65  * An opaque timer event source object */
  66 struct pa_time_event;
  67
  68 /** An abstract mainloop API vtable */
  69 struct pa_mainloop_api {
  70     /** A pointer to some private, arbitrary data of the main loop implementation */
  71     void *userdata;
  72
  73     /** Create a new IO event source object */
  74     struct pa_io_event* (*io_new)(struct pa_mainloop_api*a, int fd, enum pa_io_event_flags events, void (*callback) (struct pa_mainloop_api*a, struct pa_io_event* e, int fd, enum pa_io_event_flags events, void *userdata), void *userdata);
  75
  76     /** Enable or disable IO events on this object */
  77     void (*io_enable)(struct pa_io_event* e, enum pa_io_event_flags events);
  78
  79     /** Free a IO event source object */
  80     void (*io_free)(struct pa_io_event* e);
  81
  82     /** Set a function that is called when the IO event source is destroyed. Use this to free the userdata argument if required */
  83     void (*io_set_destroy)(struct pa_io_event *e, void (*callback) (struct pa_mainloop_api*a, struct pa_io_event *e, void *userdata));
  84
  85     /** Create a new timer event source object for the specified Unix time */
  86     struct pa_time_event* (*time_new)(struct pa_mainloop_api*a, const struct timeval *tv, void (*callback) (struct pa_mainloop_api*a, struct pa_time_event* e, const struct timeval *tv, void *userdata), void *userdata);
  87
  88     /** Restart a running or expired timer event source with a new Unix time */
  89     void (*time_restart)(struct pa_time_event* e, const struct timeval *tv);
  90
  91     /** Free a deferred timer event source object */
  92     void (*time_free)(struct pa_time_event* e);
  93
  94     /** Set a function that is called when the timer event source is destroyed. Use this to free the userdata argument if required */
  95     void (*time_set_destroy)(struct pa_time_event *e, void (*callback) (struct pa_mainloop_api*a, struct pa_time_event *e, void *userdata));
  96
  97     /** Create a new deferred event source object */
  98     struct pa_defer_event* (*defer_new)(struct pa_mainloop_api*a, void (*callback) (struct pa_mainloop_api*a, struct pa_defer_event* e, void *userdata), void *userdata);
  99
 100     /** Enable or disable a deferred event source temporarily */
 101     void (*defer_enable)(struct pa_defer_event* e, int b);
 102
 103     /** Free a deferred event source object */
 104     void (*defer_free)(struct pa_defer_event* e);
 105
 106     /** Set a function that is called when the deferred event source is destroyed. Use this to free the userdata argument if required */
 107     void (*defer_set_destroy)(struct pa_defer_event *e, void (*callback) (struct pa_mainloop_api*a, struct pa_defer_event *e, void *userdata));
 108
 109     /** Exit the main loop and return the specfied retval*/
 110     void (*quit)(struct pa_mainloop_api*a, int retval);
 111 };
 112
 113 /** Run the specified callback function once from the main loop using an anonymous defer event. */
 114 void pa_mainloop_api_once(struct pa_mainloop_api*m, void (*callback)(struct pa_mainloop_api*m, void *userdata), void *userdata);
 115
 116 PA_C_DECL_END
 117
 118 #endif