| blob | 67289679b7d43e4754d7bdc3bbd60bb0b08e232e |
1 /*
2 * Nautilus-Actions
3 * A Nautilus extension which offers configurable context menu actions.
4 *
5 * Copyright (C) 2005 The GNOME Foundation
6 * Copyright (C) 2006, 2007, 2008 Frederic Ruaudel and others (see AUTHORS)
7 * Copyright (C) 2009, 2010, 2011 Pierre Wieser and others (see AUTHORS)
8 *
9 * This Program is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License as
11 * published by the Free Software Foundation; either version 2 of
12 * the License, or (at your option) any later version.
13 *
14 * This Program 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
20 * License along with this Library; see the file COPYING. If not,
21 * write to the Free Software Foundation, Inc., 59 Temple Place,
22 * Suite 330, Boston, MA 02111-1307, USA.
23 *
24 * Authors:
25 * Frederic Ruaudel <grumz@grumz.net>
26 * Rodrigo Moya <rodrigo@gnome-db.org>
27 * Pierre Wieser <pwieser@trychlos.org>
28 * ... and many others (see AUTHORS)
29 */
31 #ifndef __NAUTILUS_ACTIONS_API_NA_EXTENSION_H__
32 #define __NAUTILUS_ACTIONS_API_NA_EXTENSION_H__
34 /**
35 * SECTION: extension
36 * @title: Plugins
37 * @short_description: The Nautilus-Actions Extension Interface Definition v 1
38 * @include: nautilus-actions/na-extension.h
39 *
40 * &prodname; accepts extensions as dynamically loadable libraries
41 * (aka plugins).
42 *
43 * As of today, &prodname; may be extended in the following areas:
44 * <itemizedlist>
45 * <listitem>
46 * <formalpara>
47 * <title>
48 * Storing menus and actions in a specific storage subsystem
49 * </title>
50 * <para>
51 * This extension is provided via the public
52 * <link linkend="NAIIOProvider">NAIIOProvider</link>
53 * interface; it takes care of reading and writing menus
54 * and actions to a specific storage subsystem.
55 * </para>
56 * </formalpara>
57 * </listitem>
58 * <listitem>
59 * <formalpara>
60 * <title>
61 * Exporting menus and actions
62 * </title>
63 * <para>
64 * This extension is provided via the public
65 * <link linkend="NAIExporter">NAIExporter</link>
66 * interface; it takes care of exporting menus and actions
67 * to the filesystem from the &prodname; Configuration Tool
68 * user interface.
69 * </para>
70 * </formalpara>
71 * </listitem>
72 * <listitem>
73 * <formalpara>
74 * <title>
75 * Importing menus and actions
76 * </title>
77 * <para>
78 * This extension is provided via the public
79 * <link linkend="NAIImporter">NAIImporter</link>
80 * interface; it takes care of importing menus and actions
81 * from the filesystem into the &prodname; Configuration Tool
82 * user interface.
83 * </para>
84 * </formalpara>
85 * </listitem>
86 * </itemizedlist>
87 *
88 * In order to be recognized as a valid &prodname; plugin, the library
89 * must at least export the functions described in this extension API.
90 *
91 * <refsect2>
92 * <title>Developing a &prodname; plugin</title>
93 * <refsect3>
94 * <title>Building the dynamically loadable library</title>
95 * <para>
96 * The suggested way of producing a dynamically loadable library is to
97 * use
98 * <application><ulink url="http://www.gnu.org/software/autoconf/">autoconf</ulink></application>,
99 * <application><ulink url="http://www.gnu.org/software/automake/">automake</ulink></application>
100 * and
101 * <application><ulink url="http://www.gnu.org/software/libtool/">libtool</ulink></application>
102 * GNU applications.
103 * </para>
104 * <para>
105 * In this case, it should be enough to use the <option>-module</option>
106 * option in your <filename>Makefile.am</filename>, as in:
107 * <programlisting>
108 * libna_io_desktop_la_LDFLAGS = -module -no-undefined -avoid-version
109 * </programlisting>
110 * </para>
111 * </refsect3>
112 * <refsect3>
113 * <title>Installing the library</title>
114 * <para>
115 * At startup time, &prodname; searches for its candidate libraries in
116 * <filename>PKGLIBDIR</filename> directory, which most often happens to
117 * be <filename>/usr/lib/nautilus-actions/</filename> or
118 * <filename>/usr/lib64/nautilus-actions/</filename>,
119 * depending of your system.
120 * </para>
121 * </refsect3>
122 * </refsect2>
123 *
124 * <refsect2>
125 * <title>Versions historic</title>
126 * <table>
127 * <title>Historic of the versions of this extension API</title>
128 * <tgroup rowsep="1" colsep="1" align="center" cols="3">
129 * <colspec colname="na-version" />
130 * <colspec colname="api-version" />
131 * <colspec colname="current" />
132 * <thead>
133 * <row>
134 * <entry>&prodname; version</entry>
135 * <entry>extension API version</entry>
136 * <entry></entry>
137 * </row>
138 * </thead>
139 * <tbody>
140 * <row>
141 * <entry>since 2.30</entry>
142 * <entry>1</entry>
143 * <entry>current version</entry>
144 * </row>
145 * </tbody>
146 * </tgroup>
147 * </table>
148 * </refsect2>
149 */
151 #include <glib-object.h>
153 G_BEGIN_DECLS
155 /**
156 * na_extension_startup:
157 * @module: the #GTypeModule of the plugin library being loaded.
158 *
159 * This function is called by the Nautilus-Actions plugin manager when
160 * the plugin library is first loaded in memory. The library may so take
161 * advantage of this call by initializing itself, registering its
162 * internal #GType types, etc.
163 *
164 * A Nautilus-Actions extension must implement this function in order
165 * to be considered as a valid candidate to dynamic load.
166 *
167 * <example>
168 * <programlisting>
169 * static GType st_module_type = 0;
170 *
171 * gboolean
172 * na_extension_startup( GTypeModule *plugin )
173 * {
174 * static GTypeInfo info = {
175 * sizeof( NadpDesktopProviderClass ),
176 * NULL,
177 * NULL,
178 * ( GClassInitFunc ) class_init,
179 * NULL,
180 * NULL,
181 * sizeof( NadpDesktopProvider ),
182 * 0,
183 * ( GInstanceInitFunc ) instance_init
184 * };
185 *
186 * static const GInterfaceInfo iio_provider_iface_info = {
187 * ( GInterfaceInitFunc ) iio_provider_iface_init,
188 * NULL,
189 * NULL
190 * };
191 *
192 * st_module_type = g_type_module_register_type( plugin, G_TYPE_OBJECT, "NadpDesktopProvider", &info, 0 );
193 *
194 * g_type_module_add_interface( plugin, st_module_type, NA_IIO_PROVIDER_TYPE, &iio_provider_iface_info );
195 *
196 * return( TRUE );
197 * }
198 * </programlisting>
199 * </example>
200 *
201 * Returns: %TRUE if the initialization is successful, %FALSE else.
202 * In this later case, the library is unloaded and no more considered.
203 *
204 * Since: 2.30
205 */
208 /**
209 * na_extension_get_version:
210 *
211 * This function is called by the &prodname; program each time
212 * it needs to know which version of this API the plugin
213 * implements.
214 *
215 * If this function is not exported by the library,
216 * the plugin manager considers that the library only implements the
217 * version 1 of this extension API.
218 *
219 * Returns: the version of this API supported by the module.
220 *
221 * Since: 2.30
222 */
225 /**
226 * na_extension_list_types:
227 * @types: the address where to store the zero-terminated array of
228 * instantiable #GType types this library implements.
229 *
230 * Returned #GType types must already have been registered in the
231 * #GType system (e.g. at #na_extension_startup() time), and the objects
232 * they describe may implement one or more of the interfaces defined in
233 * this Nautilus-Actions public API.
234 *
235 * The Nautilus-Actions plugin manager will instantiate one #GTypeInstance-
236 * derived object for each returned #GType type, and associate these objects
237 * to this library.
238 *
239 * A Nautilus-Actions extension must implement this function in order
240 * to be considered as a valid candidate to dynamic load.
241 *
242 * <example>
243 * <programlisting>
244 * &lcomment; the count of GType types provided by this extension
245 * * each new GType type must
246 * * - be registered in na_extension_startup()
247 * * - be addressed in na_extension_list_types().
248 * &rcomment;
249 * #define NADP_TYPES_COUNT 1
250 *
251 * guint
252 * na_extension_list_types( const GType **types )
253 * {
254 * static GType types_list [1+NADP_TYPES_COUNT];
255 *
256 * &lcomment; NADP_DESKTOP_PROVIDER_TYPE has been previously
257 * * registered in na_extension_startup function
258 * &rcomment;
259 * types_list[0] = NADP_DESKTOP_PROVIDER_TYPE;
260 *
261 * types_list[NADP_TYPES_COUNT] = 0;
262 * *types = types_list;
263 *
264 * return( NADP_TYPES_COUNT );
265 * }
266 * </programlisting>
267 * </example>
268 *
269 * Returns: the number of #GType types returned in the @types array, not
270 * counting the terminating zero item.
271 *
272 * Since: 2.30
273 */
276 /**
277 * na_extension_shutdown:
278 *
279 * This function is called by Nautilus-Actions when it is about to
280 * shutdown itself.
281 *
282 * The dynamically loaded library may take advantage of this call to
283 * release any resource, handle, and so on, it may have previously
284 * allocated.
285 *
286 * A Nautilus-Actions extension must implement this function in order
287 * to be considered as a valid candidate to dynamic load.
288 *
289 * Since: 2.30
290 */
293 G_END_DECLS