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