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