source: roaraudio/include/libroar/plugincontainer.h @ 6052:d48765b2475e

Last change on this file since 6052:d48765b2475e was 6052:d48765b2475e, checked in by phi, 9 years ago

updated copyright headers

File size: 7.9 KB
Line 
1//plugincontainer.h:
2
3/*
4 *      Copyright (C) Philipp 'ph3-der-loewe' Schafft - 2008-2015
5 *
6 *  This file is part of libroar a part of RoarAudio,
7 *  a cross-platform sound system for both, home and professional use.
8 *  See README for details.
9 *
10 *  This file is free software; you can redistribute it and/or modify
11 *  it under the terms of the GNU General Public License version 3
12 *  as published by the Free Software Foundation.
13 *
14 *  libroar is distributed in the hope that it will be useful,
15 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
16 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 *  GNU General Public License for more details.
18 *
19 *  You should have received a copy of the GNU General Public License
20 *  along with this software; see the file COPYING.  If not, write to
21 *  the Free Software Foundation, 51 Franklin Street, Fifth Floor,
22 *  Boston, MA 02110-1301, USA.
23 *
24 *  NOTE for everyone want's to change something and send patches:
25 *  read README and HACKING! There a addition information on
26 *  the license of this document you need to read before you send
27 *  any patches.
28 *
29 *  NOTE for uses of non-GPL (LGPL,...) software using libesd, libartsc
30 *  or libpulse*:
31 *  The libs libroaresd, libroararts and libroarpulse link this lib
32 *  and are therefore GPL. Because of this it may be illigal to use
33 *  them with any software that uses libesd, libartsc or libpulse*.
34 */
35
36#ifndef _LIBROARPLUGINCONTAINER_H_
37#define _LIBROARPLUGINCONTAINER_H_
38
39#include "libroar.h"
40
41struct roar_plugincontainer;
42
43struct roar_plugincontainer_callbacks {
44 /* prefree() is called before the container is freed.
45  */
46 int (*prefree)(struct roar_plugincontainer * cont, void ** userdata);
47
48 /* freeuserdata() is called when the userdata needs to be freed.
49  * This is the case then the container is freed.
50  * It is not called when the current userdata is NULL.
51  * If not set or userdata is still non-NULL after this call the userdata
52  * is freed using roar_mm_free().
53  */
54 int (*freeuserdata)(struct roar_plugincontainer * cont, void ** userdata);
55
56 /* freecontext() is called when the context needs to be freed.
57  * It is not called when the current context is NULL.
58  * If not set or context is still non-NULL after this call the context
59  * is freed using roar_mm_free().
60  */
61 int (*freecontext)(struct roar_plugincontainer * cont, void ** context);
62
63 /* preload() and postload() are called before and after a plugin is loaded.
64  */
65 int (*preload) (struct roar_plugincontainer * cont, void ** context,
66                 const char * name, int flags, struct roar_dl_librarypara * para);
67 int (*postload)(struct roar_plugincontainer * cont, void ** context, struct roar_dl_lhandle * lhandle,
68                 const char * name, int flags, struct roar_dl_librarypara * para);
69
70 /* preunload() and postunload() are called before and after a plugin is unloaded.
71  * Those functions are also called if the plugin was loaded but ra_init was not yet done or failed.
72  */
73 int (*preunload) (struct roar_plugincontainer * cont, void ** context, struct roar_dl_lhandle * lhandle);
74 int (*postunload)(struct roar_plugincontainer * cont, void ** context);
75
76 /* prera_init() and postra_init() are called before and after a plugin is ra_init-ed.
77  * This is also true if the plugin is ra_init-ed while being loaded.
78  * Note the limits of roar_plugincontainer_ra_init() if this is used
79  * with roar_plugincontainer_ra_init().
80  * postra_init() is also called in case the ra_init failed.
81  */
82 int (*prera_init) (struct roar_plugincontainer * cont, void ** context, struct roar_dl_lhandle * lhandle,
83                    struct roar_dl_librarypara * para);
84 int (*postra_init)(struct roar_plugincontainer * cont, void ** context, struct roar_dl_lhandle * lhandle,
85                    struct roar_dl_librarypara * para);
86};
87
88struct roar_plugincontainer_plugininfo {
89 /* The name of the plugin.
90  */
91 const char * libname;
92 /* The roardl's library handle.
93  */
94 struct roar_dl_lhandle * handle;
95 /* The number of librarys/plugins depending on this plugin.
96  */
97 size_t rdepends;
98 /* A pointer to the current user context.
99  */
100 void ** context;
101};
102
103/* Create a new plugin container.
104 * Takes a default parameter set.
105 */
106struct roar_plugincontainer * roar_plugincontainer_new(struct roar_dl_librarypara * default_para);
107
108/* Create a new plugin container.
109 * Takes host application's appname and abiversion.
110 */
111struct roar_plugincontainer * roar_plugincontainer_new_simple(const char * appname, const char * abiversion);
112
113// Increment the refrence counter.
114int roar_plugincontainer_ref(struct roar_plugincontainer * cont);
115/* Decrement the refrence counter.
116 * Unloads all plugins and frees all resources when there are no refreneces left.
117 */
118int roar_plugincontainer_unref(struct roar_plugincontainer * cont);
119
120/* Set Autoappsched.
121 * If set the INIT and FREE appsched events are send automatically.
122 */
123int roar_plugincontainer_set_autoappsched(struct roar_plugincontainer * cont, int val);
124
125/* Set callbacks.
126 */
127int roar_plugincontainer_set_callbacks(struct roar_plugincontainer * cont,
128                                       const struct roar_plugincontainer_callbacks * callbacks);
129
130/* Set container's userdata.
131 */
132int roar_plugincontainer_set_userdata(struct roar_plugincontainer * cont, void * userdata);
133
134/* Get container's userdata.
135 */
136void * roar_plugincontainer_get_userdata(struct roar_plugincontainer * cont);
137
138/* Get a lhandle by name of the loaded plugin.
139 */
140struct roar_dl_lhandle * roar_plugincontainer_get_lhandle_by_name (struct roar_plugincontainer * cont,
141                                                                   const char * name);
142
143/* Get infos about current state of plugin.
144 */
145struct roar_plugincontainer_plugininfo roar_plugincontainer_get_info_by_name (struct roar_plugincontainer * cont,
146                                                                              const char * name);
147
148// plugin loading and unloading:
149
150// Load a plugin by name.
151int                      roar_plugincontainer_load            (struct roar_plugincontainer * cont,
152                                                               const char * name,
153                                                               struct roar_dl_librarypara * para);
154
155/* Load a plugin by name with extra options.
156 * This is for advanced applications only.
157 * NOTE: Using this handle after the plugin has been unloaded from the
158 *       container results in undefind behavior.
159 */
160struct roar_dl_lhandle * roar_plugincontainer_load_lhandle    (struct roar_plugincontainer * cont,
161                                                               const char * name,
162                                                               int flags,
163                                                               int ra_init,
164                                                               struct roar_dl_librarypara * para);
165/* Unload a plugin by name.
166 * NOTE: The name here is from the plugin and may not match the name you load
167 *       the plugin with.
168 */
169int                      roar_plugincontainer_unload          (struct roar_plugincontainer * cont,
170                                                               const char * name);
171/* Load a plugin by roardl handle.
172 * This is for advanced applications only.
173 */
174int                      roar_plugincontainer_unload_lhandle  (struct roar_plugincontainer * cont,
175                                                               struct roar_dl_lhandle * lhandle);
176/* Post ra_init plugins not yet inited.
177 * NOTE: This uses the default para,
178 *       not the one given with roar_plugincontainer_load_lhandle().
179 * This is for advanced applications only.
180 */
181int                      roar_plugincontainer_ra_init         (struct roar_plugincontainer * cont);
182
183// appsched:
184// Trigger an application schedule event on all plugins.
185int                      roar_plugincontainer_appsched_trigger(struct roar_plugincontainer * cont, enum roar_dl_appsched_trigger trigger);
186
187#endif
188
189//ll
Note: See TracBrowser for help on using the repository browser.