1
@comment $Id: plugin.texi,v 1.11 2001/04/27 13:02:37 richi Exp $
3
@node Plugin Interface, GLAME Database Interface, GLAME Project Structure Management, Top
4
@chapter Plugin Interface
6
The plugin interface is very simple. There are actually two functions,
7
one to add paths to the existing plugin path list and one to query the
10
@deftypefun int plugin_add_path (const char *@var{path})
11
This function will add @var{path} to the list of paths used to search
16
@deftypefun int plugin_load (const char *@var{filename})
17
@code{plugin_load()} will try to register all available plugins
18
out of the specified file @var{filename}. If the specified file
19
could not be opened or is not a valid plugin file, -1 is returned.
20
On success, that is after registering zero or more plugins, 0 is
25
@deftypefun {plugin_t *} plugin_get (const char *@var{name})
26
This function will return a handle to the plugin with the name @var{name}.
27
If the plugin is not already loaded it will be loaded from one of the
28
paths in the path list. @code{plugin_get()} returns @code{NULL} if the plugin
29
can't be found or an error occured during its initialization phase.
32
To manually add a plugin not contained in some shared library you
33
should call the following function.
35
@deftypefun {plugin_t *} plugin_add (const char *@var{name})
36
This function will add a new empty plugin to the database. You should
37
populate its database using the @code{plugin_set()} function. On success
38
a plugin handle is returned, @code{NULL} is returned on failure.
41
To access parts of the plugin the following wrapper macros should be used
42
on the @code{plugin_t} handle.
45
@deftypefun {const char *} plugin_name (plugin_t *@var{p})
46
This function returns the plugin's name.
50
@deftypefun int plugin_set (plugin_t *@var{p}, const char *@var{key}, void *@var{val})
51
@deftypefunx {void *} plugin_query (plugin_t *@var{p})
52
Using these functions you can set and query key/value pairs either stored
53
through dynamic library symbols or through a little per plugin database.
54
@code{plugin_query()} returns @code{NULL}, if there is no information about
55
the specified key. As a general rule of dumb you should start your keywords
56
with a '!' to prevent conflicts with dynamic symbols.
57
Standard keywords are accessible using the defines @code{PLUGIN_DESCRIPTION},
58
@code{PLUGIN_PIXMAP}, @code{PLUGIN_CATEGORY} and the internally used
59
keywords @code{PLUGIN_FILTER} and @code{PLUGIN_PARENT}.
62
To browse through all registered plugins you can use the following function.
64
@deftypefun {plugin_t *} plugin_next (plugin_t *@var{p})
65
@code{plugin_next()} gets you the next plugin in the database or the
66
first one if you supply @code{NULL}. @code{NULL} is returned if no
67
further plugins are available.
71
If you want to create a plugin, your dynamic object should contain the
72
following standard symbols with the described information attached. The
73
targeted subsystem may require additional defined symbols. Please refer
74
to the subsystems' documentation for information about those symbol
75
names and required contents. You should substitute the plugins name for
76
the @code{plugin} prefix of the symbols to prevent symbol name clashes.
80
A function of type @code{(int (*)(plugin_t *p))} which does everything
81
necessary to register anything in the plugin to any subsystem.
83
This optional symbol of the type @code{char *} should contain a list
84
of additional @code{plugin} names inside the object file seperated
85
by spaces. You will need a seperate @code{_register} symbol for each
86
of the specified additional plugin names. Use the @code{PLUGIN_SET}
87
macro to create a symbol like that. Provide two arguments, the first
88
should be an identifier matching the file name without filename extension,
89
the second one should be the space seperated plugin list string.
added
removed
doc/plugin.texi
