[nautilus-actions] Reference manual: fix extension and NAIIOProvider
- From: Pierre Wieser <pwieser src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [nautilus-actions] Reference manual: fix extension and NAIIOProvider
- Date: Thu, 9 Dec 2010 00:46:45 +0000 (UTC)
commit e9c8c096d1a0f3645d88e798331f3fcf1ef182cd
Author: Pierre Wieser <pwieser trychlos org>
Date: Thu Dec 9 01:46:28 2010 +0100
Reference manual: fix extension and NAIIOProvider
ChangeLog | 3 +-
docs/reference/Makefile.am | 2 +-
docs/reference/na-about.xml | 41 +++++
docs/reference/na-plugin-api.xml | 220 -------------------------
docs/reference/na-plugin-overview.xml | 79 ---------
docs/reference/nautilus-actions-docs.xml | 7 +-
docs/reference/nautilus-actions-sections.txt | 19 ++-
src/api/na-extension.h | 221 +++++++++++++++++++++++---
src/api/na-iio-provider.h | 133 +++++++++++-----
src/core/na-iio-provider.c | 58 ++++++--
src/core/na-io-provider.c | 42 +++---
src/core/na-io-provider.h | 11 +-
12 files changed, 425 insertions(+), 411 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 4c96e1c..5438c7e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,8 +1,9 @@
2010-12-08 Pierre Wieser <pwieser trychlos org>
+ Update reference manual for extensions.
Update reference manual for NAIIOProvider interface.
- * docs/reference/na-plugin-api.xml: New file.
+ * docs/reference/na-about.xml: New file.
2010-12-06 Pierre Wieser <pwieser trychlos org>
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index c5fd68c..5f736d7 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -150,4 +150,4 @@ install-data-local-hook:
echo "written_xmls_regexp=$(written_xmls_regexp)"
echo "written_xmls=$(written_xmls)"
-#TESTS = $(GTKDOC_CHECK)
+TESTS = $(GTKDOC_CHECK)
diff --git a/docs/reference/na-about.xml b/docs/reference/na-about.xml
new file mode 100644
index 0000000..995244a
--- /dev/null
+++ b/docs/reference/na-about.xml
@@ -0,0 +1,41 @@
+<?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-about" revision="8 Dec 2010">
+
+ <refmeta>
+ <refentrytitle>About this document</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo>Nautilus-Actions</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>About this document</refname>
+ <refpurpose>
+ What is this document for ?
+ </refpurpose>
+ </refnamediv>
+
+ <refsect1 id="about">
+ <title>What does content this document ?</title>
+ <para>
+ This document targets two distinct populations.
+ </para>
+ <itemizedlist>
+ <listitem>
+ developers, whether they want provide extensions to &prodname;
+ or partipating to the development of &prodname; itself;
+ </listitem>
+ <listitem>
+ packagers, who will found here some relevant informations
+ about &prodname; internals.
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+</refentry>
\ No newline at end of file
diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml
index 8425694..7ef4029 100644
--- a/docs/reference/nautilus-actions-docs.xml
+++ b/docs/reference/nautilus-actions-docs.xml
@@ -6,6 +6,8 @@
<!ENTITY version SYSTEM "version.xml">
<!ENTITY prodname "<productname>Nautilus-Actions</productname>">
<!ENTITY nautilus "<productname>Nautilus</productname>">
+ <!ENTITY lcomment "/*">
+ <!ENTITY rcomment "*/">
]>
<!--
I miss several things here:
@@ -35,12 +37,12 @@
<xi:include href="na-getting.xml" />
<xi:include href="na-dist-content.xml" />
<xi:include href="na-compiling.xml" />
+ <xi:include href="na-about.xml" />
</chapter>
<chapter>
<title>Extending &prodname;</title>
- <xi:include href="na-plugin-overview.xml" />
- <xi:include href="na-plugin-api.xml" />
+ <xi:include href="xml/extension.xml" />
</chapter>
<chapter>
@@ -70,7 +72,6 @@
<xi:include href="xml/na-object-profile.xml"/>
<xi:include href="xml/na-iduplicable.xml"/>
<xi:include href="xml/na-ifactory-object-data.xml"/>
- <xi:include href="xml/na-extension.xml"/>
<xi:include href="xml/na-data-types.xml"/>
<xi:include href="xml/na-gconf-utils.xml"/>
<xi:include href="xml/na-ifactory-provider-provider.xml"/>
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index c19a281..a13e440 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -1,5 +1,13 @@
<SECTION>
+<FILE>extension</FILE>
+na_extension_startup
+na_extension_get_version
+na_extension_list_types
+na_extension_shutdown
+</SECTION>
+
+<SECTION>
<FILE>iio-provider</FILE>
NA_IIO_PROVIDER_TYPE
NA_IIO_PROVIDER
@@ -7,6 +15,8 @@ NA_IS_IIO_PROVIDER
NA_IIO_PROVIDER_GET_INTERFACE
NAIIOProvider
NAIIOProviderInterface
+NAIIOProviderWritabilityStatus
+NAIIOProviderOperationStatus
na_iio_provider_item_changed
<SUBSECTION Standard>
@@ -14,7 +24,6 @@ na_iio_provider_item_changed
<SUBSECTION Private>
NAIIOProviderInterfacePrivate
na_iio_provider_get_type
-IIO_PROVIDER_SIGNAL_ITEM_CHANGED
</SECTION>
<SECTION>
@@ -391,14 +400,6 @@ NAFO_DATA_CAPABILITITES
</SECTION>
<SECTION>
-<FILE>na-extension</FILE>
-na_extension_startup
-na_extension_get_version
-na_extension_list_types
-na_extension_shutdown
-</SECTION>
-
-<SECTION>
<FILE>na-data-types</FILE>
na_data_types_get_gconf_dump_key
</SECTION>
diff --git a/src/api/na-extension.h b/src/api/na-extension.h
index 89ed552..38c0fc7 100644
--- a/src/api/na-extension.h
+++ b/src/api/na-extension.h
@@ -32,18 +32,120 @@
#define __NAUTILUS_ACTIONS_API_NA_EXTENSION_H__
/**
- * SECTION: na_extension
+ * SECTION: extension
+ * @title: Plugins
* @short_description: Nautilus-Actions extension interface definition.
* @include: nautilus-actions/na-extension.h
*
- * Nautilus-Actions accepts extensions as dynamically loadable libraries
+ * &prodname; accepts extensions as dynamically loadable libraries
* (aka plugins).
*
- * At startup time, candidate libraries are searched for in PKGLIBDIR/
- * directory. A valid candidate must at least export the #na_extension_startup()
- * and #na_extension_list_types() functions.
+ * As of today, &prodname; may be extended in the following areas:
+ * <itemizedlist>
+ * <listitem>
+ * <formalpara>
+ * <title>
+ * Storing menus and actions in a specific storage subsystem
+ * </title>
+ * <para>
+ * 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>
+ * </formalpara>
+ * </listitem>
+ * <listitem>
+ * <formalpara>
+ * <title>
+ * Exporting menus and actions
+ * </title>
+ * <para>
+ * 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.
+ * </para>
+ * </formalpara>
+ * </listitem>
+ * <listitem>
+ * <formalpara>
+ * <title>
+ * Importing menus and actions
+ * </title>
+ * <para>
+ * 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.
+ * </para>
+ * </formalpara>
+ * </listitem>
+ * </itemizedlist>
*
- * Nautilus-Actions v 2.30 - API version: 1
+ * In order to be recognized as a valid &prodname; plugin, the library
+ * must at least export the functions described in this extension API.
+ *
+ * <refsect2>
+ * <title>Developing a &prodname; plugin</title>
+ * <refsect3>
+ * <title>Building the dynamically loadable library</title>
+ * <para>
+ * The suggested way of producing a dynamically loadable library is to
+ * use
+ * <application><ulink url="http://www.gnu.org/software/autoconf/";>autoconf</ulink></application>,
+ * <application><ulink url="http://www.gnu.org/software/automake/";>automake</ulink></application>
+ * and
+ * <application><ulink url="http://www.gnu.org/software/libtool/";>libtool</ulink></application>
+ * GNU applications.
+ * </para>
+ * <para>
+ * In this case, it should be 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>
+ * </refsect3>
+ * <refsect3>
+ * <title>Installing the library</title>
+ * <para>
+ * At startup time, &prodname; searches for its candidate libraries 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>
+ * </refsect3>
+ * </refsect2>
+ *
+ * <refsect2>
+ * <title>Versions historic</title>
+ * <table>
+ * <title>Historic of the versions of this extension API</title>
+ * <tgroup rowsep="1" colsep="1" align="center" cols="3">
+ * <colspec colname="na-version" />
+ * <colspec colname="api-version" />
+ * <colspec colname="current" />
+ * <thead>
+ * <row>
+ * <entry>&prodname; version</entry>
+ * <entry>extension API version</entry>
+ * <entry></entry>
+ * </row>
+ * </thead>
+ * <tbody>
+ * <row>
+ * <entry>since 2.30</entry>
+ * <entry>1</entry>
+ * <entry>current version</entry>
+ * </row>
+ * </tbody>
+ * </tgroup>
+ * </table>
+ * </refsect2>
*/
#include <glib-object.h>
@@ -52,29 +154,71 @@ G_BEGIN_DECLS
/**
* na_extension_startup:
- * @module: the #GTypeModule of the library being loaded.
+ * @module: the #GTypeModule of the plugin library being loaded.
*
* This function is called by the Nautilus-Actions plugin manager when
- * the library is first loaded in memory. The library may so take
+ * the plugin library is first loaded in memory. The library may so take
* advantage of this call by initializing itself, registering its
* internal #GType types, etc.
*
+ * A Nautilus-Actions extension must implement this function in order
+ * to be considered as a valid candidate to dynamic load.
+ *
+ * <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>
+ *
* Returns: %TRUE if the initialization is successfull, %FALSE else.
* In this later case, the library is unloaded and no more considered.
*
- * A Nautilus-Actions extension must implement this function in order
- * to be considered as a valid candidate to dynamic load.
+ * Since: Nautilus-Actions v 2.30, extension API v 1.
*/
gboolean na_extension_startup ( GTypeModule *module );
/**
* na_extension_get_version:
*
- * Returns: the version of this API supported by the module.
+ * This function is called by the &prodname; program each time
+ * it needs to know which version of this API the plugin
+ * implements.
*
- * If this function is not exported by the library, or returns zero,
+ * If this function is not exported by the library,
* the plugin manager considers that the library only implements the
- * version 1 of this API.
+ * version 1 of this extension API.
+ *
+ * Returns: the version of this API supported by the module.
+ *
+ * Since: Nautilus-Actions v 2.30, extension API v 1.
*/
guint na_extension_get_version( void );
@@ -84,23 +228,48 @@ guint na_extension_get_version( void );
* instantiable #GType types this library implements.
*
* Returned #GType types must already have been registered in the
- * #GType system (e.g. at #na_extension_startup() time), and may implement
- * one or more of the interfaces defined in Nautilus-Actions API.
+ * #GType system (e.g. at #na_extension_startup() time), and the objects
+ * they describe may implement one or more of the interfaces defined in
+ * this Nautilus-Actions public API.
*
* The Nautilus-Actions plugin manager will instantiate one #GTypeInstance-
* derived object for each returned #GType type, and associate these objects
* to this library.
*
- * Returns: the number of #GType types returned in the @types array, not
- * counting the terminating zero item.
- *
* A Nautilus-Actions extension must implement this function in order
* to be considered as a valid candidate to dynamic load.
*
- * If this function is not exported by the library, or returns zero,
- * the plugin manager considers that the library doesn't implement
- * any Nautilus-Action interface. In this case, the library is
- * unloaded and no more considered.
+ * <example>
+ * <programlisting>
+ * &lcomment; 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().
+ * &rcomment;
+ * #define NADP_TYPES_COUNT 1
+ *
+ * guint
+ * na_extension_list_types( const GType **types )
+ * {
+ * static GType types_list [1+NADP_TYPES_COUNT];
+ *
+ * &lcomment; NADP_DESKTOP_PROVIDER_TYPE has been previously
+ * * registered in na_extension_startup function
+ * &rcomment;
+ * types_list[0] = NADP_DESKTOP_PROVIDER_TYPE;
+ *
+ * types_list[NADP_TYPES_COUNT] = 0;
+ * *types = types_list;
+ *
+ * return( NADP_TYPES_COUNT );
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * Returns: the number of #GType types returned in the @types array, not
+ * counting the terminating zero item.
+ *
+ * Since: Nautilus-Actions v 2.30, extension API v 1.
*/
guint na_extension_list_types ( const GType **types );
@@ -111,7 +280,13 @@ guint na_extension_list_types ( const GType **types );
* shutdown itself.
*
* The dynamicaly loaded library may take advantage of this call to
- * release any resource it may have previously allocated.
+ * release any resource, handle, and so on, it may have previously
+ * allocated.
+ *
+ * A Nautilus-Actions extension must implement this function in order
+ * to be considered as a valid candidate to dynamic load.
+ *
+ * Since: Nautilus-Actions v 2.30, extension API v 1.
*/
void na_extension_shutdown ( void );
diff --git a/src/api/na-iio-provider.h b/src/api/na-iio-provider.h
index a608700..cde5b33 100644
--- a/src/api/na-iio-provider.h
+++ b/src/api/na-iio-provider.h
@@ -44,17 +44,42 @@ typedef struct _NAIIOProvider NAIIOProvider;
typedef struct _NAIIOProviderInterfacePrivate NAIIOProviderInterfacePrivate;
+/**
+ * NAIIOProviderInterface:
+ * @get_version: returns the version of this interface that the
+ * plugin implements.
+ * @get_id: returns the internal id of the plugin.
+ * @get_name: returns the public name of the plugin.
+ * @read_items: reads items.
+ * @is_willing_to_write: asks if the plugin is willing to write.
+ * @is_able_to_write: asks if the plugin is able to write.
+ * @write_item: writes an item.
+ * @delete_item: deletes an item.
+ * @duplicate_data: duplicates the provider-specific data.
+ *
+ * This defines the interface that a #NAIIOProvider should implement.
+ */
typedef struct {
+ /*< private >*/
GTypeInterface parent;
NAIIOProviderInterfacePrivate *private;
+ /*< public >*/
/**
* get_version:
* @instance: the #NAIIOProvider provider.
*
+ * This method is called by the &prodname; program each time
+ * it needs to know which version of this interface the plugin
+ * implements.
+ *
+ * If this method is not implemented by the plugin,
+ * the &prodname; program considers that the plugin only implements
+ * the version 1 of the #NAIIOProvider interface.
+ *
* Returns: the version of this interface supported by the I/O provider.
*
- * Defaults to 1.
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
guint ( *get_version ) ( const NAIIOProvider *instance );
@@ -62,15 +87,17 @@ typedef struct {
* get_id:
* @instance: the #NAIIOProvider provider.
*
- * Returns: the id of the I/O provider, as a newly allocated string
- * which should be g_free() by the caller.
- *
* 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).
*
- * The I/O provider must implement this function.
+ * The I/O provider must implement this method.
+ *
+ * Returns: the id of the I/O provider, as a newly allocated string
+ * which should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
gchar * ( *get_id ) ( const NAIIOProvider *instance );
@@ -78,10 +105,12 @@ typedef struct {
* get_name:
* @instance: the #NAIIOProvider provider.
*
+ * Defaults to an empty string.
+ *
* Returns: the name to be displayed for this I/O provider, as a
* newly allocated string which should be g_free() by the caller.
*
- * Defaults to an empty string.
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
gchar * ( *get_name ) ( const NAIIOProvider *instance );
@@ -93,8 +122,12 @@ typedef struct {
*
* Reads the whole items list from the specified I/O provider.
*
- * Returns: a unordered flat #GList of #NAObject-derived objects
+ * The I/O provider must implement this method.
+ *
+ * Returns: a unordered flat #GList of #NAObjectItem -derived objects
* (menus or actions); the actions embed their own profiles.
+ *
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
GList * ( *read_items ) ( const NAIIOProvider *instance, GSList **messages );
@@ -102,19 +135,23 @@ typedef struct {
* is_willing_to_write:
* @instance: the #NAIIOProvider provider.
*
- * Returns: %TRUE if this I/O provider is willing to write,
- * %FALSE else.
- *
* The 'willing_to_write' property is intrinsic to the I/O provider.
* 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 #NAObject-
- * derived objects.
+ * the needed code in order to update/create/delete #NAObjectItem
+ * -derived objects.
*
* Note that even if this property is %TRUE, there is yet many
* reasons for not being able to update/delete existing items or
* create new ones (see e.g. #is_able_to_write() below).
+ *
+ * Defaults to %FALSE.
+ *
+ * Returns: %TRUE if this I/O provider is willing to write,
+ * %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
gboolean ( *is_willing_to_write )( const NAIIOProvider *instance );
@@ -122,9 +159,6 @@ typedef struct {
* is_able_to_write:
* @instance: the #NAIIOProvider provider.
*
- * Returns: %TRUE if this I/O provider is able to do write
- * operations at runtime, %FALSE else.
- *
* The 'able_to_write' property is a runtime one.
* When returning %TRUE, the I/O provider insures that it has
* sucessfully checked that it was able to write some things
@@ -143,57 +177,76 @@ typedef struct {
* Note that even if this property is %TRUE, there is yet many
* reasons for not being able to update/delete existing items or
* create new ones (see e.g. 'locked' preference key).
+ *
+ * Defaults to %FALSE.
+ *
+ * Returns: %TRUE if this I/O provider is able to do write
+ * operations at runtime, %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
gboolean ( *is_able_to_write ) ( const NAIIOProvider *instance );
/**
* write_item:
* @instance: the #NAIIOProvider provider.
- * @item: a #NAObjectItem-derived item, menu or action.
+ * @item: a #NAObjectItem -derived item, menu or action.
* @messages: a pointer to a #GSList list of strings; the provider
* may append messages to this list, but shouldn't reinitialize it.
*
* Writes a new @item.
*
+ * There is no update_item function ; it is the responsability
+ * of the provider to delete the previous version of an item before
+ * actually writing the new one.
+ *
+ * The I/O provider should implement this method, or return
+ * %FALSE in is_willing_to_write() method above.
+ *
* Returns: %NA_IIO_PROVIDER_CODE_OK if the write operation
* was successfull, or another code depending of the detected error.
*
- * Note: there is no update_item function ; it is the responsability
- * of the provider to delete the previous version of an item before
- * actually writing the new one.
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
guint ( *write_item ) ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages );
/**
* delete_item:
* @instance: the #NAIIOProvider provider.
- * @item: a #NAObjectItem-derived item, menu or action.
+ * @item: a #NAObjectItem -derived item, menu or action.
* @messages: a pointer to a #GSList list of strings; the provider
* may append messages to this list, but shouldn't reinitialize it.
*
* Deletes an existing @item from the I/O subsystem.
*
+ * The I/O provider should implement this method, or return
+ * %FALSE in is_willing_to_write() method above.
+ *
* Returns: %NA_IIO_PROVIDER_CODE_OK if the delete operation was
* successfull, or another code depending of the detected error.
+ *
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
guint ( *delete_item ) ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages );
/**
* duplicate_data:
* @instance: the #NAIIOProvider provider.
- * @dest: a #NAObjectItem-derived item, menu or action.
- * @source: a #NAObjectItem-derived item, menu or action.
+ * @dest: a #NAObjectItem -derived item, menu or action.
+ * @source: a #NAObjectItem -derived item, menu or action.
* @messages: a pointer to a #GSList list of strings; the provider
* may append messages to this list, but shouldn't reinitialize it.
*
* 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.
+ * Note that this does not duplicate in any way any #NAObjectItem
+ * -derived object. We are just dealing here with the provider-specific
+ * data which may have been attached to a #NAObjectItem -derived object.
*
* Returns: %NA_IIO_PROVIDER_CODE_OK if the duplicate operation was
* successfull, or another code depending of the detected error.
+ *
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
guint ( *duplicate_data ) ( const NAIIOProvider *instance, NAObjectItem *dest, const NAObjectItem *source, GSList **messages );
}
@@ -207,14 +260,16 @@ GType na_iio_provider_get_type( void );
*/
void na_iio_provider_item_changed ( const NAIIOProvider *instance );
-#define IIO_PROVIDER_SIGNAL_ITEM_CHANGED "na-iio-provider-notify-pivot"
+/* signal sent from a NAIIOProvider
+ * via the na_iio_provider_item_changed() function
+ */
+#define IIO_PROVIDER_SIGNAL_ITEM_CHANGED "notify-pivot"
/* Adding a new status here should imply also adding a new tooltip
* in #na_io_provider_get_readonly_tooltip().
*/
/**
* NAIIOProviderWritabilityStatus:
- *
* @NA_IIO_PROVIDER_STATUS_UNDETERMINED: undertermined.
* @NA_IIO_PROVIDER_STATUS_WRITABLE: the item is writable.
* @NA_IIO_PROVIDER_STATUS_ITEM_READONLY: the item is read-only.
@@ -233,7 +288,7 @@ void na_iio_provider_item_changed ( const NAIIOProvider *instance );
*
* The reasons for which an item may not be writable.
*/
-enum {
+typedef enum {
NA_IIO_PROVIDER_STATUS_UNDETERMINED = 0,
NA_IIO_PROVIDER_STATUS_WRITABLE,
NA_IIO_PROVIDER_STATUS_ITEM_READONLY,
@@ -253,23 +308,21 @@ enum {
*/
/**
* 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:
+ * You should open a bug in
+ * <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions";>Bugzilla</ulink>.
+ * @NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN: the provider is not willing
+ * to do the requested action.
+ * @NA_IIO_PROVIDER_CODE_WRITE_ERROR: a write error has been detected.
+ * @NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR: the schemas could not be
+ * deleted.
+ * @NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR: the configuration could not
+ * be deleted.
*
* The return code of operations.
*/
-enum {
+typedef enum {
NA_IIO_PROVIDER_CODE_OK = 0,
NA_IIO_PROVIDER_CODE_PROGRAM_ERROR = 1 + NA_IIO_PROVIDER_STATUS_LAST,
NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN,
diff --git a/src/core/na-iio-provider.c b/src/core/na-iio-provider.c
index da14078..1622e03 100644
--- a/src/core/na-iio-provider.c
+++ b/src/core/na-iio-provider.c
@@ -58,7 +58,7 @@
* </listitem>
* <listitem>
* <para>
- * inform Nautilus-Actions when an item has been modified on the
+ * inform &prodname; when an item has been modified on the
* underlying storage subsystem.
* </para>
* </listitem>
@@ -66,9 +66,34 @@
*
* These services may be fully implemented by the I/O provider itself.
* Or, the I/O provider may also prefer to take advantage of the data
- * factory management (see #NAIFactoryObject and #NAIFactoryProvider interfaces).
+ * factory management (see #NAIFactoryObject and #NAIFactoryProvider
+ * interfaces).
*
- * Since Nautilus-Actions v 2.30 (API version 1)
+ * <refsect2>
+ * <title>Versions historic</title>
+ * <table>
+ * <title>Historic of the versions of the #NAIIOProvider interface</title>
+ * <tgroup rowsep="1" colsep="1" align="center" cols="3">
+ * <colspec colname="na-version" />
+ * <colspec colname="api-version" />
+ * <colspec colname="current" />
+ * <thead>
+ * <row>
+ * <entry>&prodname; version</entry>
+ * <entry>#NAIIOProvider interface version</entry>
+ * <entry></entry>
+ * </row>
+ * </thead>
+ * <tbody>
+ * <row>
+ * <entry>since 2.30</entry>
+ * <entry>1</entry>
+ * <entry>current version</entry>
+ * </row>
+ * </tbody>
+ * </tgroup>
+ * </table>
+ * </refsect2>
*/
/* private interface data
@@ -164,10 +189,18 @@ interface_base_init( NAIIOProviderInterface *klass )
klass->delete_item = NULL;
klass->duplicate_data = NULL;
- /* register the signal (without any default handler)
- * this signal should be sent by the #NAIIOProvider instance when
- * an item has changed in the underlying storage subsystem
- * #NAPivot is connected to this signal
+ /**
+ * NAIIOProvider::notify-pivot:
+ * @provider: the #NAIIOProvider which has called the
+ * na_iio_provider_item_changed() function.
+ * @arg1: not used, initialized to %NULL.
+ *
+ * This signal is not meant to be directly sent by a plugin.
+ * Instead, the plugin should call the na_iio_provider_item_changed()
+ * function.
+ *
+ * The signal is registered without any default handler.
+ * Only NAPivot object is connected to it.
*/
st_signals[ ITEM_CHANGED ] = g_signal_new(
IIO_PROVIDER_SIGNAL_ITEM_CHANGED,
@@ -216,16 +249,19 @@ do_is_able_to_write( const NAIIOProvider *instance )
* na_iio_provider_item_changed:
* @instance: the calling #NAIIOProvider.
*
- * Advertises Nautilus-Actions that this #NAIIOProvider @instance has
- * detected a modification in one of its configurations (menu or action).
+ * Informs Nautilus-Actions that this #NAIIOProvider @instance has
+ * detected a modification in one of its items (menu or action).
*
- * This function should be triggered for each and every #NAObjectItem-
- * derived modified objects, but (if possible) only once for each one.
+ * This function may be triggered for each and every
+ * #NAObjectItem -derived modified objects, and, at least, once
+ * for a coherent set of updates.
*
* 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.
+ *
+ * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
*/
void
na_iio_provider_item_changed( const NAIIOProvider *instance )
diff --git a/src/core/na-io-provider.c b/src/core/na-io-provider.c
index 473d5fb..857b077 100644
--- a/src/core/na-io-provider.c
+++ b/src/core/na-io-provider.c
@@ -295,7 +295,7 @@ instance_finalize( GObject *object )
}
}
-/**
+/*
* na_io_provider_terminate:
*
* Called by on #NAPivot dispose(), free here resources allocated to
@@ -309,7 +309,7 @@ na_io_provider_terminate( void )
st_io_providers = NULL;
}
-/**
+/*
* na_io_provider_get_providers_list:
* @pivot: the current #NAPivot instance.
*
@@ -502,7 +502,7 @@ add_io_providers_from_prefs( const NAPivot *pivot, GList *runtime_providers )
return( providers );
}
-/**
+/*
* na_io_provider_reorder_providers_list:
* @pivot: the #NAPivot instance of the application.
*
@@ -532,7 +532,7 @@ na_io_provider_reorder_providers_list( const NAPivot *pivot )
na_core_utils_slist_free( order );
}
-/**
+/*
* na_io_provider_dump_providers_list:
* @providers: the list of #NAIOProvider to be dumped.
*
@@ -562,7 +562,7 @@ dump( const NAIOProvider *provider )
g_debug( "%s: item_changed_handler=%lu", thisfn, provider->private->item_changed_handler );
}
-/**
+/*
* na_io_provider_find_provider_by_id:
* @providers: the current list of #NAIOProvider.
* @id: the searched internal id.
@@ -591,7 +591,7 @@ na_io_provider_find_provider_by_id( GList *providers, const gchar *id )
return( provider );
}
-/**
+/*
* na_io_provider_get_writable_provider:
* @pivot: the #NAPivot instance.
*
@@ -624,7 +624,7 @@ na_io_provider_get_writable_provider( const NAPivot *pivot )
return( provider );
}
-/**
+/*
* na_io_provider_read_items:
* @pivot: the #NAPivot object which owns the list of registered I/O
* storage providers.
@@ -900,7 +900,7 @@ filter_unwanted_items_rec( GList *hierarchy, gboolean load_disabled, gboolean lo
return( filtered );
}
-/**
+/*
* na_io_provider_get_id:
* @provider: this #NAIOProvider.
*
@@ -923,7 +923,7 @@ na_io_provider_get_id( const NAIOProvider *provider )
return( id );
}
-/**
+/*
* na_io_provider_get_name:
* @provider: this #NAIOProvider.
*
@@ -951,7 +951,7 @@ na_io_provider_get_name( const NAIOProvider *provider )
return( name );
}
-/**
+/*
* na_io_provider_is_user_readable_at_startup:
* @provider: this #NAIOProvider.
* @iprefs: an implementor of the #NAIPrefs interface.
@@ -994,7 +994,7 @@ na_io_provider_is_user_readable_at_startup( const NAIOProvider *provider, const
return( to_be_read );
}
-/**
+/*
* na_io_provider_is_user_writable:
* @provider: this #NAIOProvider.
* @iprefs: an implementor of the #NAIPrefs interface.
@@ -1033,7 +1033,7 @@ na_io_provider_is_user_writable( const NAIOProvider *provider, const NAIPrefs *i
return( writable );
}
-/**
+/*
* na_io_provider_is_locked_by_admin:
* @provider: this #NAIOProvider.
* @iprefs: an implementor of the #NAIPrefs interface.
@@ -1065,7 +1065,7 @@ na_io_provider_is_locked_by_admin( const NAIOProvider *provider, const NAIPrefs
return( locked );
}
-/**
+/*
* na_io_provider_get_provider:
* @provider: the #NAIOProvider object.
*
@@ -1090,7 +1090,7 @@ na_io_provider_get_provider( const NAIOProvider *provider )
return( instance );
}
-/**
+/*
* na_io_provider_is_willing_to_write:
* @provider: this #NAIOProvider.
*
@@ -1120,7 +1120,7 @@ na_io_provider_is_willing_to_write( const NAIOProvider *provider )
return( willing_to );
}
-/**
+/*
* na_io_provider_is_able_to_write:
* @provider: this #NAIOProvider.
*
@@ -1150,7 +1150,7 @@ na_io_provider_is_able_to_write( const NAIOProvider *provider )
return( able_to );
}
-/**
+/*
* na_io_provider_has_write_api:
* @provider: this #NAIOProvider.
*
@@ -1179,7 +1179,7 @@ na_io_provider_has_write_api( const NAIOProvider *provider )
return( has_api );
}
-/**
+/*
* na_io_provider_write_item:
* @provider: this #NAIOProvider object.
* @item: a #NAObjectItem to be written to the storage subsystem.
@@ -1216,7 +1216,7 @@ na_io_provider_write_item( const NAIOProvider *provider, const NAObjectItem *ite
return( ret );
}
-/**
+/*
* na_io_provider_delete_item:
* @provider: this #NAIOProvider object.
* @item: the #NAObjectItem item to be deleted.
@@ -1248,7 +1248,7 @@ na_io_provider_delete_item( const NAIOProvider *provider, const NAObjectItem *it
return( ret );
}
-/**
+/*
* na_io_provider_duplicate_data:
* @provider: this #NAIOProvider object.
* @dest: the target #NAObjectItem item.
@@ -1290,7 +1290,7 @@ na_io_provider_duplicate_data( const NAIOProvider *provider, NAObjectItem *dest,
return( ret );
}
-/**
+/*
* na_io_provider_get_readonly_tooltip:
* @reason: the reason for why an item is not writable.
*
@@ -1347,7 +1347,7 @@ na_io_provider_get_readonly_tooltip( guint reason )
return( tooltip );
}
-/**
+/*
* na_io_provider_get_return_code_label:
* @code: the return code of an operation.
*
diff --git a/src/core/na-io-provider.h b/src/core/na-io-provider.h
index 2f8fb39..e7cbf4a 100644
--- a/src/core/na-io-provider.h
+++ b/src/core/na-io-provider.h
@@ -31,13 +31,18 @@
#ifndef __CORE_NA_IO_PROVIDER_H__
#define __CORE_NA_IO_PROVIDER_H__
-/**
- * SECTION: na_io_provider
+/*
+ * SECTION: io-provider
+ * @title: NAIIOProvider internals.
* @short_description: #NAIOProvider class definition.
* @include: core/na-io-provider.h
*
* NAIOProvider is the Nautilus-Actions class which is used to manage
- * external I/O Providers which implement NAIIOProvider interface.
+ * external I/O Providers which implement #NAIIOProvider interface.
+ *
+ * Internal Nautilus-Actions code should never directly call a
+ * #NAIIOProvider interface method, but rather should call the
+ * corresponding NAIOProvider class method.
*/
#include "na-iprefs.h"
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
