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