[nautilus-actions] Reference manual: documente NAIIOProvider interface
- From: Pierre Wieser <pwieser src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [nautilus-actions] Reference manual: documente NAIIOProvider interface
- Date: Wed, 8 Dec 2010 21:34:40 +0000 (UTC)
commit af9615aaa59a95fd8cf95ef60fa22ba3286f40a8
Author: Pierre Wieser <pwieser trychlos org>
Date: Wed Dec 8 22:33:11 2010 +0100
Reference manual: documente NAIIOProvider interface
ChangeLog | 6 +
configure.ac | 8 +-
docs/reference/na-dist-content.xml | 20 +-
docs/reference/na-plugin-api.xml | 220 ++++++++++++++++++++
.../{na-plugin.xml => na-plugin-overview.xml} | 17 +-
docs/reference/nautilus-actions-docs.xml | 3 +-
docs/reference/nautilus-actions-sections.txt | 10 +-
docs/reference/version_dir.xml | 2 +-
src/api/na-iio-provider.h | 43 +++-
src/core/na-iio-provider.c | 20 +-
src/core/na-module.c | 6 +
11 files changed, 312 insertions(+), 43 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index dcd37e2..4c96e1c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2010-12-08 Pierre Wieser <pwieser trychlos org>
+
+ Update reference manual for NAIIOProvider interface.
+
+ * docs/reference/na-plugin-api.xml: New file.
+
2010-12-06 Pierre Wieser <pwieser trychlos org>
* docs/reference/na-compiling.xml:
diff --git a/configure.ac b/configure.ac
index 44ada2b..27ffca0 100644
--- a/configure.ac
+++ b/configure.ac
@@ -28,7 +28,7 @@
AC_PREREQ([2.53])
-AC_INIT([Nautilus-Actions],[3.1.0],[maintainer nautilus-actions org],,[http://www.nautilus-actions.org])
+AC_INIT([Nautilus-Actions],[3.0.3],[maintainer nautilus-actions org],,[http://www.nautilus-actions.org])
AC_CANONICAL_TARGET
@@ -192,7 +192,8 @@ if test "x${enable_schemas_install}" = "xno"; then
_ac_na_schemas_install="disabled"; else
_ac_na_schemas_install="enabled in ${GCONF_SCHEMA_FILE_DIR}"
fi
-_ac_na_gtk_doc=`if test "x${enable_gtk_doc}" = "xno"; then echo disabled; else echo enabled; fi`
+_ac_na_gtk_html_doc=`if test "x${enable_gtk_doc_html}" = "xno"; then echo disabled; else echo "enabled with gtk-doc"; fi`
+_ac_na_gtk_pdf_doc=`if test "x${enable_gtk_doc_pdf}" = "xno"; then echo disabled; else echo enabled; fi`
$as_echo "
${PACKAGE_STRING} configuration summary:
@@ -205,7 +206,8 @@ $as_echo "
Default I/O provider ${with_default_io_provider}
GConf schemas installation ${_ac_na_schemas_install}
Maintainer mode ${_ac_na_maintainer_mode}
- Gtk documentation ${_ac_na_gtk_doc}
+ HTML API Reference generation ${_ac_na_gtk_html_doc}
+ PDF API Reference generation ${_ac_na_gtk_pdf_doc}
HTML manuals generation ${_ac_na_html_manuals}
PDF manuals generation ${_ac_na_pdf_manuals}
"
diff --git a/docs/reference/na-dist-content.xml b/docs/reference/na-dist-content.xml
index 72e8b95..7c1aece 100644
--- a/docs/reference/na-dist-content.xml
+++ b/docs/reference/na-dist-content.xml
@@ -6,7 +6,7 @@
<!ENTITY nautilus "<productname>Nautilus</productname>">
]>
-<refentry id="na-dist-content" revision="6 Dec 2010">
+<refentry id="na-dist-content" revision="8 Dec 2010">
<refmeta>
<refentrytitle>Distribution content</refentrytitle>
@@ -29,13 +29,13 @@
<itemizedlist>
<listitem>
<para>
- Programs
+ Program sources
</para>
<itemizedlist>
<listitem>
a &nautilus; plugin, said <emphasis>menu</emphasis>,
responsible for managing displayed menus and actions
- through &nautilus; extensions;
+ through &nautilus; extension system;
</listitem>
<listitem>
a &nautilus; plugin, said <emphasis>tracker</emphasis>,
@@ -86,11 +86,15 @@
<para>
Samples
</para>
- <para>
- The sample menus and actions described in the
- &prodname; Configuration Tool User's Manual
- are included in the standard distribution.
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The sample menus and actions described in the
+ &prodname; Configuration Tool User's Manual
+ are included in the standard distribution.
+ </para>
+ </listitem>
+ </itemizedlist>
</listitem>
</itemizedlist>
</refsect1>
diff --git a/docs/reference/na-plugin-api.xml b/docs/reference/na-plugin-api.xml
new file mode 100644
index 0000000..20c3fb3
--- /dev/null
+++ b/docs/reference/na-plugin-api.xml
@@ -0,0 +1,220 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY prodname "<productname>Nautilus-Actions</productname>">
+ <!ENTITY nautilus "<productname>Nautilus</productname>">
+]>
+
+<refentry id="na-plugin-api" revision="8 Dec 2010">
+
+ <refmeta>
+ <refentrytitle>Developing a Nautilus-Actions plugin</refentrytitle>
+ <refmiscinfo>Nautilus-Actions</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>Plugin development</refname>
+ <refpurpose>
+ How to develop a plugin ?
+ </refpurpose>
+ </refnamediv>
+
+ <refsect1 id="plugin-what">
+ <title>What is a plugin ?</title>
+ <para>
+ Basically, a plugin is just a shared library,
+ which will be dynamically loaded by &prodname;
+ at startup.
+ </para>
+ <para>
+ In order to be recognized as a &prodname; plugin,
+ the library must export some well-known functions
+ (see <link linkend="plugin-api">Which functions the plugin must it export ?</link>).
+ </para>
+ <para>
+ When compiled with adequate options
+ (see <link linkend="plugin-compile">How to compile a plugin ?</link>),
+ and installed in the correct location
+ (see <link linkend="plugin-where">Where the plugin must it be installed ?</link>),
+ all &prodname; programs will automatically load the plugin
+ at startup time.
+ </para>
+ </refsect1>
+
+ <refsect1 id="plugin-compile">
+ <title>How to compile a plugin ?</title>
+ <para>
+ The suggested way of producing a dynamically loadable library
+ is to use <application>autoconf</application>,
+ <application>automake</application> and
+ <application>libtool</application> GNU applications.
+ </para>
+ <para>
+ In this case, it is enough to use the <option>-module</option>
+ option in your <filename>Makefile.am</filename>, as in:
+ <programlisting>
+ libna_io_desktop_la_LDFLAGS = -module -no-undefined -avoid-version
+ </programlisting>
+ </para>
+ </refsect1>
+
+ <refsect1 id="plugin-where">
+ <title>Where the plugin must it be installed ?</title>
+ <para>
+ &prodname; searches for its plugins in
+ <filename>pkglibdir</filename> directory,
+ which most often happens to be
+ <filename>/usr/lib/nautilus-actions/</filename> or
+ <filename>/usr/lib64/nautilus-actions/</filename>,
+ depending of your system.
+ </para>
+ </refsect1>
+
+ <refsect1 id="plugin-api">
+ <title>Which functions the plugin must it export ?</title>
+ <para>
+ The plugin MUST define and export following API:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <programlisting>
+ <funcdef>
+ gboolean na_extension_startup( GTypeModule *plugin );
+ </funcdef>
+ </programlisting>
+ <para>
+ This function is called by the &prodname; program
+ at startup time, while it is being loading the
+ plugins.
+ </para>
+ <para>
+ The plugin may run its own initialization process,
+ in particular registering the GTypes it manages.
+ The plugin must return <returnvalue>TRUE</returnvalue>
+ if it has been successully
+ initialized, <returnvalue>FALSE</returnvalue> else.
+ </para>
+ <example>
+ <programlisting>
+ static GType st_module_type = 0;
+
+ gboolean
+ na_extension_startup( GTypeModule *plugin )
+ {
+
+ static GTypeInfo info = {
+ sizeof( NadpDesktopProviderClass ),
+ NULL,
+ NULL,
+ ( GClassInitFunc ) class_init,
+ NULL,
+ NULL,
+ sizeof( NadpDesktopProvider ),
+ 0,
+ ( GInstanceInitFunc ) instance_init
+ };
+
+ static const GInterfaceInfo iio_provider_iface_info = {
+ ( GInterfaceInitFunc ) iio_provider_iface_init,
+ NULL,
+ NULL
+ };
+
+ st_module_type = g_type_module_register_type( plugin, G_TYPE_OBJECT, "NadpDesktopProvider", &info, 0 );
+
+ g_type_module_add_interface( plugin, st_module_type, NA_IIO_PROVIDER_TYPE, &iio_provider_iface_info );
+
+ return( TRUE );
+ }
+ </programlisting>
+ </example>
+ </listitem>
+ <listitem>
+ <programlisting>
+ <funcdef>
+ guint na_extension_list_types( const GType **types );
+ </funcdef>
+ </programlisting>
+ <para>
+ This function is called by the &prodname; program
+ after having received the successfull initialization
+ return code from <function>na_extension_startup</function>
+ function.
+ </para>
+ <para>
+ The plugin must populates the <parameter>types</parameter>
+ parameter with a null-terminated list of the GTypes the
+ plugin manages. Each GType returned will be later allocated
+ by the &prodname; program as a new GObjet-derived object.
+ The plugin must return the count of defined GType types.
+ </para>
+ <example>
+ <programlisting>
+ /* the count of GType types provided by this extension
+ * each new GType type must
+ * - be registered in na_extension_startup()
+ * - be addressed in na_extension_list_types().
+ */
+ #define NADP_TYPES_COUNT 1
+
+ guint
+ na_extension_list_types( const GType **types )
+ {
+ static GType types_list [1+NADP_TYPES_COUNT];
+
+ /* NADP_DESKTOP_PROVIDER_TYPE has been previously
+ * registered in na_extension_startup function
+ */
+ types_list[0] = NADP_DESKTOP_PROVIDER_TYPE;
+
+ types_list[NADP_TYPES_COUNT] = 0;
+ *types = types_list;
+
+ return( NADP_TYPES_COUNT );
+ }
+ </programlisting>
+ </example>
+ </listitem>
+ <listitem>
+ <programlisting>
+ <funcdef>
+ guint na_extension_get_version( void );
+ </funcdef>
+ </programlisting>
+ <para>
+ This function is called by the &prodname; program at
+ termination time, just before actually unloading the
+ plugin.
+ </para>
+ <para>
+ The plugin may take advantage of this to release all
+ previously allocated handle, resources and so on.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The plugin may define and export following optional API:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <programlisting>
+ <funcdef>
+ guint na_extension_get_version( void );
+ </funcdef>
+ </programlisting>
+ <para>
+ This function is called by the &prodname; program each time
+ it needs to know which version of this API the plugin
+ implements.
+ </para>
+ <para>
+ If the plugin does not implement this function, then
+ the &prodname; program considers that the plugin
+ implements version 1 of this API.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+</refentry>
\ No newline at end of file
diff --git a/docs/reference/na-plugin.xml b/docs/reference/na-plugin-overview.xml
similarity index 78%
rename from docs/reference/na-plugin.xml
rename to docs/reference/na-plugin-overview.xml
index 4c60442..a540685 100644
--- a/docs/reference/na-plugin.xml
+++ b/docs/reference/na-plugin-overview.xml
@@ -6,7 +6,7 @@
<!ENTITY nautilus "<productname>Nautilus</productname>">
]>
-<refentry id="na-plugin" revision="6 Dec 2010">
+<refentry id="na-plugin-overview" revision="8 Dec 2010">
<refmeta>
<refentrytitle>Extending Nautilus-Actions</refentrytitle>
@@ -14,13 +14,13 @@
</refmeta>
<refnamediv>
- <refname>Plugin development</refname>
+ <refname>Plugin overview</refname>
<refpurpose>
- How to extend Nautilus-Actions and develop new plugins ?
+ What are plugins and what is their perimeter ?
</refpurpose>
</refnamediv>
- <refsect1 id="plugin">
+ <refsect1 id="plugin-overview">
<title>Plugin Overview</title>
<para>
&prodname; may be extended by developing new extensions
@@ -38,7 +38,8 @@
Storing menus and actions in a specific storage subsystem
</title>
<para>
- This extension is provided via the public NAIIOProvider
+ This extension is provided via the public
+ <link linkend="NAIIOProvider">NAIIOProvider</link>
interface; it takes care of reading and writing menus
and actions to a specific storage subsystem.
</para>
@@ -50,7 +51,8 @@
Exporting menus and actions
</title>
<para>
- This extension is provided via the public NAIExporter
+ This extension is provided via the public
+ <link linkend="NAIExporter">NAIExporter</link>
interface; it takes care of exporting menus and actions
to the filesystem from the &prodname; Configuration Tool
user interface.
@@ -63,7 +65,8 @@
Importing menus and actions
</title>
<para>
- This extension is provided via the public NAIImporter
+ This extension is provided via the public
+ <link linkend="NAIImporter">NAIImporter</link>
interface; it takes care of importing menus and actions
from the filesystem into the &prodname; Configuration Tool
user interface.
diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml
index fc3c3e9..8425694 100644
--- a/docs/reference/nautilus-actions-docs.xml
+++ b/docs/reference/nautilus-actions-docs.xml
@@ -39,7 +39,8 @@
<chapter>
<title>Extending &prodname;</title>
- <xi:include href="na-plugin.xml" />
+ <xi:include href="na-plugin-overview.xml" />
+ <xi:include href="na-plugin-api.xml" />
</chapter>
<chapter>
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index 9d881a3..c19a281 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -1,20 +1,20 @@
<SECTION>
<FILE>iio-provider</FILE>
+NA_IIO_PROVIDER_TYPE
+NA_IIO_PROVIDER
+NA_IS_IIO_PROVIDER
+NA_IIO_PROVIDER_GET_INTERFACE
NAIIOProvider
NAIIOProviderInterface
na_iio_provider_item_changed
-IIO_PROVIDER_SIGNAL_ITEM_CHANGED
<SUBSECTION Standard>
-NA_IIO_PROVIDER
-NA_IS_IIO_PROVIDER
-NA_IIO_PROVIDER_TYPE
-NA_IIO_PROVIDER_GET_INTERFACE
<SUBSECTION Private>
NAIIOProviderInterfacePrivate
na_iio_provider_get_type
+IIO_PROVIDER_SIGNAL_ITEM_CHANGED
</SECTION>
<SECTION>
diff --git a/docs/reference/version_dir.xml b/docs/reference/version_dir.xml
index 8c50098..9f55b2c 100644
--- a/docs/reference/version_dir.xml
+++ b/docs/reference/version_dir.xml
@@ -1 +1 @@
-3.1
+3.0
diff --git a/src/api/na-iio-provider.h b/src/api/na-iio-provider.h
index ac91136..a608700 100644
--- a/src/api/na-iio-provider.h
+++ b/src/api/na-iio-provider.h
@@ -40,9 +40,9 @@ G_BEGIN_DECLS
#define NA_IS_IIO_PROVIDER( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IIO_PROVIDER_TYPE ))
#define NA_IIO_PROVIDER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IIO_PROVIDER_TYPE, NAIIOProviderInterface ))
-typedef struct NAIIOProvider NAIIOProvider;
+typedef struct _NAIIOProvider NAIIOProvider;
-typedef struct NAIIOProviderInterfacePrivate NAIIOProviderInterfacePrivate;
+typedef struct _NAIIOProviderInterfacePrivate NAIIOProviderInterfacePrivate;
typedef struct {
GTypeInterface parent;
@@ -68,7 +68,7 @@ typedef struct {
* To avoid any collision, the I/O provider id is allocated by the
* Nautilus-Actions maintainer team. If you wish develop a new I/O
* provider, and so need a new provider id, please contact the
- * maintainers (see #nautilus-actions.doap).
+ * maintainers (see nautilus-actions.doap).
*
* The I/O provider must implement this function.
*/
@@ -93,7 +93,7 @@ typedef struct {
*
* Reads the whole items list from the specified I/O provider.
*
- * Returns: a unordered flat #GList of #NAIFactoryObject-derived objects
+ * Returns: a unordered flat #GList of #NAObject-derived objects
* (menus or actions); the actions embed their own profiles.
*/
GList * ( *read_items ) ( const NAIIOProvider *instance, GSList **messages );
@@ -109,7 +109,7 @@ typedef struct {
* It is not supposed to make any assumption on the environment it is
* currently running on.
* This property just says that the developer/maintainer has released
- * the needed code in order to update/create/delete #NAIFactoryObject-
+ * the needed code in order to update/create/delete #NAObject-
* derived objects.
*
* Note that even if this property is %TRUE, there is yet many
@@ -186,7 +186,11 @@ typedef struct {
* @messages: a pointer to a #GSList list of strings; the provider
* may append messages to this list, but shouldn't reinitialize it.
*
- * Duplicates provider data (if any) from @source to @dest.
+ * Duplicates provider-specific data (if any) from @source to @dest.
+ *
+ * Note that this does not duplicate in any way any #NAObject-derived
+ * object. We are just dealing here with the provider-specific data
+ * which may have been attached to a #NAObject-derived object.
*
* Returns: %NA_IIO_PROVIDER_CODE_OK if the duplicate operation was
* successfull, or another code depending of the detected error.
@@ -241,12 +245,30 @@ enum {
NA_IIO_PROVIDER_STATUS_NO_API,
/*< private >*/
NA_IIO_PROVIDER_STATUS_LAST,
-};
+}
+ NAIIOProviderWritabilityStatus;
-/* return code of operations
- * adding a new code here should imply also adding a new label
+/* adding a new code here should imply also adding a new label
* in #na_io_provider_get_return_code_label().
*/
+/**
+ * NAIIOProviderOperationStatus:
+ *
+ * @NA_IIO_PROVIDER_CODE_OK: the requested operation has been successful.
+ *
+ * @NA_IIO_PROVIDER_CODE_PROGRAM_ERROR: a program error has been detected.
+ * You should open a bug in <ulink url="">Bugzilla</ulink>.
+ *
+ * @NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN:
+ *
+ * @NA_IIO_PROVIDER_CODE_WRITE_ERROR:
+ *
+ * @NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR:
+ *
+ * @NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR:
+ *
+ * The return code of operations.
+ */
enum {
NA_IIO_PROVIDER_CODE_OK = 0,
NA_IIO_PROVIDER_CODE_PROGRAM_ERROR = 1 + NA_IIO_PROVIDER_STATUS_LAST,
@@ -254,7 +276,8 @@ enum {
NA_IIO_PROVIDER_CODE_WRITE_ERROR,
NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR,
NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR,
-};
+}
+ NAIIOProviderOperationStatus;
G_END_DECLS
diff --git a/src/core/na-iio-provider.c b/src/core/na-iio-provider.c
index 2396396..da14078 100644
--- a/src/core/na-iio-provider.c
+++ b/src/core/na-iio-provider.c
@@ -36,14 +36,13 @@
/**
* SECTION: iio-provider
- * @section_id: iio-provider
* @title: NAIIOProvider
- * @short_description: An interface to provide I/O services
+ * @short_description: The I/O Provider Interface
* @include: nautilus-actions/na-iio-provider.h
*
- * The #NAIIOProvider interface has been defined in order to let internal
- * and external plugins be written. With this interface, a plugin may
- * provide read and write accesses to an alternate storage subsystem.
+ * The #NAIIOProvider interface is defined in order to let internal
+ * and external plugins provide read and write accesses
+ * to an alternate storage subsystem.
*
* The #NAIIOProvider interface provides three types of services:
* <itemizedlist>
@@ -59,8 +58,8 @@
* </listitem>
* <listitem>
* <para>
- * advertize Nautilus-Actions when an item has been modified on the
- * underlying storage subsystems.
+ * inform Nautilus-Actions when an item has been modified on the
+ * underlying storage subsystem.
* </para>
* </listitem>
* </itemizedlist>
@@ -74,7 +73,7 @@
/* private interface data
*/
-struct NAIIOProviderInterfacePrivate {
+struct _NAIIOProviderInterfacePrivate {
void *empty; /* so that gcc -pedantic is happy */
};
@@ -222,6 +221,11 @@ do_is_able_to_write( const NAIIOProvider *instance )
*
* This function should be triggered for each and every #NAObjectItem-
* derived modified objects, but (if possible) only once for each one.
+ *
+ * When receiving this signal, the current &prodname; program will
+ * automatically ask its I/O providers for a current list of menus and
+ * actions, or ask the user if he is willing to reload such a current
+ * list, depending of the exact running &prodname; program.
*/
void
na_iio_provider_item_changed( const NAIIOProvider *instance )
diff --git a/src/core/na-module.c b/src/core/na-module.c
index 3602e81..1343c5e 100644
--- a/src/core/na-module.c
+++ b/src/core/na-module.c
@@ -328,6 +328,11 @@ module_load( GTypeModule *gmodule )
* the module has been successfully loaded
* is it a Nautilus-Action plugin ?
* if ok, we ask the plugin to initialize itself
+ *
+ * As of API v 1:
+ * - na_extension_startup, na_extension_list_types and na_extension_shutdown
+ * are mandatory, and MUST be implemented by the plugin
+ * - na_extension_get_version is optional, and defaults to 1.
*/
static gboolean
is_a_na_plugin( NAModule *module )
@@ -338,6 +343,7 @@ is_a_na_plugin( NAModule *module )
ok =
plugin_check( module, "na_extension_startup" , ( gpointer * ) &module->private->startup) &&
plugin_check( module, "na_extension_list_types" , ( gpointer * ) &module->private->list_types ) &&
+ plugin_check( module, "na_extension_shutdown" , ( gpointer * ) &module->private->shutdown ) &&
module->private->startup( G_TYPE_MODULE( module ));
if( ok ){
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
