GNOME.org
 

[nautilus-actions] Reference manual: document NAIFactoryProvider interface

commit a74c8942c9a23ffe1da29219dd7aa8f0f893b968
Author: Pierre Wieser <pwieser trychlos org>
Date:   Fri Dec 10 00:10:32 2010 +0100

    Reference manual: document NAIFactoryProvider interface

 ChangeLog                                    |    9 ++
 docs/reference/nautilus-actions-docs.xml     |    8 +-
 docs/reference/nautilus-actions-sections.txt |   38 +++----
 src/api/na-ifactory-provider-provider.h      |   10 +--
 src/api/na-ifactory-provider.h               |   74 ++++++++-----
 src/core/na-factory-provider.h               |    5 +-
 src/core/na-ifactory-provider.c              |  143 +++++++++++++++++++++++++-
 7 files changed, 221 insertions(+), 66 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 26ba519..c42daea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
 2010-12-09 Pierre Wieser <pwieser trychlos org>
 
+	Document NAIFactoryProvider interface.
+
+	* docs/reference/nautilus-actions-docs.xml:
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-ifactory-provider-provider.h:
+	* src/api/na-ifactory-provider.h:
+	* src/core/na-factory-provider.h:
+	* src/core/na-ifactory-provider.c: Updated accordingly.
+
 	Fix NAIExporter reference manual.
 
 	* docs/reference/nautilus-actions-sections.txt:
diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml
index 7ef4029..6a96b33 100644
--- a/docs/reference/nautilus-actions-docs.xml
+++ b/docs/reference/nautilus-actions-docs.xml
@@ -50,8 +50,6 @@
     <xi:include href="xml/iio-provider.xml" />
     <xi:include href="xml/iimporter.xml" />
     <xi:include href="xml/iexporter.xml" />
-    <xi:include href="xml/ifactory-provider.xml" />
-    <xi:include href="xml/ifactory-object.xml" />
   </chapter>
 
   <chapter>
@@ -60,6 +58,12 @@
   </chapter>
 
   <chapter>
+    <title>Data factory management system</title>
+    <xi:include href="xml/ifactory-provider.xml" />
+    <xi:include href="xml/ifactory-object.xml" />
+  </chapter>
+
+  <chapter>
     <title>Others (nautilus-actions-api.xml title)</title>
     <xi:include href="xml/na-object-id.xml"/>
     <xi:include href="xml/na-object-action.xml"/>
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index 43588d5..849bf70 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -70,6 +70,24 @@ NAIExporterInterfacePrivate
 </SECTION>
 
 <SECTION>
+<FILE>ifactory-provider</FILE>
+NA_IFACTORY_PROVIDER_TYPE
+NA_IFACTORY_PROVIDER
+NA_IS_IFACTORY_PROVIDER
+NA_IFACTORY_PROVIDER_GET_INTERFACE
+NAIFactoryProvider
+NAIFactoryProviderInterface
+na_ifactory_provider_read_item
+na_ifactory_provider_write_item
+
+<SUBSECTION Standard>
+na_ifactory_provider_get_type
+
+<SUBSECTION Private>
+NAIFactoryProviderInterfacePrivate
+</SECTION>
+
+<SECTION>
 <FILE>ifactory-object</FILE>
 NA_IFACTORY_OBJECT_TYPE
 NA_IFACTORY_OBJECT_GET_INTERFACE
@@ -88,21 +106,6 @@ na_ifactory_object_get_type
 </SECTION>
 
 <SECTION>
-<FILE>ifactory-provider</FILE>
-NA_IFACTORY_PROVIDER_TYPE
-NA_IFACTORY_PROVIDER_GET_INTERFACE
-NAIFactoryProviderInterfacePrivate
-NAIFactoryProviderInterface
-na_ifactory_provider_read_item
-na_ifactory_provider_write_item
-
-<SUBSECTION Standard>
-NA_IFACTORY_PROVIDER
-NA_IS_IFACTORY_PROVIDER
-na_ifactory_provider_get_type
-</SECTION>
-
-<SECTION>
 <FILE>dbus</FILE>
 <TITLE>DBus (nautilus-actions-sections title)</TITLE>
 NAUTILUS_ACTIONS_DBUS_SERVICE
@@ -437,11 +440,6 @@ na_gconf_utils_slist_to_string
 </SECTION>
 
 <SECTION>
-<FILE>na-ifactory-provider-provider</FILE>
-NAIFactoryProvider
-</SECTION>
-
-<SECTION>
 <FILE>core-utils</FILE>
 na_core_utils_boolean_from_string
 na_core_utils_str_add_prefix
diff --git a/src/api/na-ifactory-provider-provider.h b/src/api/na-ifactory-provider-provider.h
index b4b1a13..6b0f82c 100644
--- a/src/api/na-ifactory-provider-provider.h
+++ b/src/api/na-ifactory-provider-provider.h
@@ -31,19 +31,11 @@
 #ifndef __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_PROVIDER_H__
 #define __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_PROVIDER_H__
 
-/**
- * SECTION: ifactory-provider
- * @section_id: ifactory-provider
- * @title: NAIFactoryProvider (na-ifactory-provider-provider.h title)
- * @short_description: #NAIFactoryProvider interface definition (na-ifactory-provider-provider.h short description)
- * @include: nautilus-actions/na-ifactory_provider-provider.h
- */
-
 #include <glib.h>
 
 G_BEGIN_DECLS
 
-typedef struct NAIFactoryProvider NAIFactoryProvider;
+typedef struct _NAIFactoryProvider NAIFactoryProvider;
 
 G_END_DECLS
 
diff --git a/src/api/na-ifactory-provider.h b/src/api/na-ifactory-provider.h
index dbfce2d..c8442a1 100644
--- a/src/api/na-ifactory-provider.h
+++ b/src/api/na-ifactory-provider.h
@@ -31,86 +31,96 @@
 #ifndef __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__
 #define __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__
 
-/**
- * SECTION: ifactory-provider
- * @section_id: ifactory-provider
- * @title: NAIFactoryProvider (na-ifactory-provider.h title)
- * @short_description: #NAIFactoryProvider interface definition (na-ifactory-provider.h short description)
- * @include: nautilus-actions/na-ifactory_provider.h
- *
- * This is the interface used by data factory management system for
- * having serialization/unserialization services. This interface should
- * be implemented by I/O providers which would take advantage of this
- * system.
- *
- * Nautilus-Actions v 2.30 - API version:  1
- */
-
 #include "na-data-boxed.h"
 #include "na-ifactory-object.h"
 #include "na-ifactory-provider-provider.h"
 
 G_BEGIN_DECLS
 
-#define NA_IFACTORY_PROVIDER_TYPE						( na_ifactory_provider_get_type())
-#define NA_IFACTORY_PROVIDER( instance )				( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IFACTORY_PROVIDER_TYPE, NAIFactoryProvider ))
-#define NA_IS_IFACTORY_PROVIDER( instance )				( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IFACTORY_PROVIDER_TYPE ))
-#define NA_IFACTORY_PROVIDER_GET_INTERFACE( instance )	( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IFACTORY_PROVIDER_TYPE, NAIFactoryProviderInterface ))
+#define NA_IFACTORY_PROVIDER_TYPE                       ( na_ifactory_provider_get_type())
+#define NA_IFACTORY_PROVIDER( instance )                ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IFACTORY_PROVIDER_TYPE, NAIFactoryProvider ))
+#define NA_IS_IFACTORY_PROVIDER( instance )             ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IFACTORY_PROVIDER_TYPE ))
+#define NA_IFACTORY_PROVIDER_GET_INTERFACE( instance )  ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IFACTORY_PROVIDER_TYPE, NAIFactoryProviderInterface ))
 
-typedef struct NAIFactoryProviderInterfacePrivate NAIFactoryProviderInterfacePrivate;
+typedef struct _NAIFactoryProviderInterfacePrivate NAIFactoryProviderInterfacePrivate;
 
+/**
+ * NAIFactoryProviderInterface:
+ * @get_version: returns the version of this interface the plugin implements.
+ * @read_start:  triggered just before reading an item.
+ * @read_data:   reads an item.
+ * @read_done:   triggered at the end of item reading.
+ * @write_start: triggered just before writing an item.
+ * @write_data:  writes an item.
+ * @write_done:  triggered at the end of item writing.
+ *
+ * This defines the interface that a #NAIFactoryProvider may implement.
+ */
 typedef struct {
+	/*< private >*/
 	GTypeInterface                      parent;
 	NAIFactoryProviderInterfacePrivate *private;
 
+	/*< public >*/
 	/**
 	 * get_version:
 	 * @instance: this #NAIFactoryProvider instance.
 	 *
+	 * Defaults to 1.
+	 *
 	 * Returns: the version of this interface supported by @instance implementation.
 	 *
-	 * Defaults to 1.
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
 	 */
 	guint         ( *get_version )( const NAIFactoryProvider *instance );
 
 	/**
 	 * read_start:
 	 * @reader: this #NAIFactoryProvider instance.
-	 * @reader_data: the data associated to this instance.
+	 * @reader_data: the data associated to this instance, as provided
+	 *  when na_ifactory_provider_read_item() was called.
 	 * @object: the #NAIFactoryObject object which comes to be readen.
 	 * @messages: a pointer to a #GSList list of strings; the provider
 	 *  may append messages to this list, but shouldn't reinitialize it.
 	 *
 	 * API called by #NAIFactoryObject just before starting with reading data.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
 	 */
 	void          ( *read_start ) ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, GSList **messages  );
 
 	/**
 	 * read_data:
 	 * @reader: this #NAIFactoryProvider instance.
-	 * @reader_data: the data associated to this instance.
+	 * @reader_data: the data associated to this instance, as provided
+	 *  when na_ifactory_provider_read_item() was called.
 	 * @object: the #NAIFactoryobject being unserialized.
 	 * @def: a #NADataDef structure which identifies the data to be unserialized.
 	 * @messages: a pointer to a #GSList list of strings; the provider
 	 *  may append messages to this list, but shouldn't reinitialize it.
 	 *
+	 * This method must be implemented in order any data be read.
+	 *
 	 * Returns: a newly allocated NADataBoxed which contains the readen value.
 	 * Should return %NULL if data is not found.
 	 *
-	 * This method must be implemented in order any data be read.
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
 	 */
 	NADataBoxed * ( *read_data )  ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, const NADataDef *def, GSList **messages );
 
 	/**
 	 * read_done:
 	 * @reader: this #NAIFactoryProvider instance.
-	 * @reader_data: the data associated to this instance.
+	 * @reader_data: the data associated to this instance, as provided
+	 *  when na_ifactory_provider_read_item() was called.
 	 * @object: the #NAIFactoryObject object which comes to be readen.
 	 * @messages: a pointer to a #GSList list of strings; the provider
 	 *  may append messages to this list, but shouldn't reinitialize it.
 	 *
 	 * API called by #NAIFactoryObject when all data have been readen.
 	 * Implementor may take advantage of this to do some cleanup.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
 	 */
 	void          ( *read_done )  ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, GSList **messages  );
 
@@ -122,9 +132,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.
 	 *
+	 * API called by #NAIFactoryObject just before starting with writing data.
+	 *
 	 * Returns: a NAIIOProvider operation return code.
 	 *
-	 * API called by #NAIFactoryObject just before starting with writing data.
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
 	 */
 	guint         ( *write_start )( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages  );
 
@@ -140,9 +152,11 @@ typedef struct {
 	 *
 	 * Write the data embedded in @value down to @instance.
 	 *
+	 * This method must be implemented in order any data be written.
+	 *
 	 * Returns: a NAIIOProvider operation return code.
 	 *
-	 * This method must be implemented in order any data be written.
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
 	 */
 	guint         ( *write_data ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, const NADataBoxed *boxed, GSList **messages );
 
@@ -154,10 +168,12 @@ typedef struct {
 	 * @messages: a pointer to a #GSList list of strings; the provider
 	 *  may append messages to this list, but shouldn't reinitialize it.
 	 *
-	 * Returns: a NAIIOProvider operation return code.
-	 *
 	 * API called by #NAIFactoryObject when all data have been written.
 	 * Implementor may take advantage of this to do some cleanup.
+	 *
+	 * Returns: a NAIIOProvider operation return code.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
 	 */
 	guint         ( *write_done ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages  );
 }
diff --git a/src/core/na-factory-provider.h b/src/core/na-factory-provider.h
index 7ebbe72..3b984c3 100644
--- a/src/core/na-factory-provider.h
+++ b/src/core/na-factory-provider.h
@@ -31,9 +31,8 @@
 #ifndef __CORE_NA_FACTORY_PROVIDER_H__
 #define __CORE_NA_FACTORY_PROVIDER_H__
 
-/**
- * SECTION: na_ifactory_provider
- * @short_description: #NAIFactoryProvider interface definition.
+/*
+ * SECTION: ifactory_provider
  * @include: core/na-factory-provider.h
  *
  * Declare the function only accessed from core library (not published as API).
diff --git a/src/core/na-ifactory-provider.c b/src/core/na-ifactory-provider.c
index 2558829..b8f925c 100644
--- a/src/core/na-ifactory-provider.c
+++ b/src/core/na-ifactory-provider.c
@@ -38,9 +38,113 @@
 #include "na-factory-object.h"
 #include "na-factory-provider.h"
 
+/**
+ * SECTION: ifactory-provider
+ * @title: NAIFactoryProvider
+ * @short_description: The Data Factory Management System
+ * @include: nautilus-actions/na-ifactory_provider.h
+ *
+ * &prodname; has to deal with a relatively great number of elementary datas,
+ * reading them from different supports, storing and displaying them,
+ * then re-writing these same datas, with several output formats, and so on.
+ *
+ * This has rapidly become a pain, if not just a bug generator.
+ * Each new data must be described, have a schema to be stored in
+ * (historical storage subsystem) GConf; import and export assistants
+ * must be carefully updated to export the new data...
+ *
+ * The #NAIFactoryProvider aims to simplify and organize all the work
+ * which must be done around each and every elementary data. It is based
+ * on three main things:
+ *
+ * <orderedlist>
+ *   <listitem>
+ *     <formalpara>
+ *       <title>Elementary datas are banalized.</title>
+ *       <para>
+ *         whether they are a string, an integer, a boolean, a simple
+ *         or double-linked list, each elementary data is encapsuled
+ *         into a #NADataBox, small sort of structure (incidentally,
+ *         which acts almost as the new GLib #GVariant, but too late,
+ *         guys :)).
+ *       </para>
+ *     </formalpara>
+ *   </listitem>
+ *   <listitem>
+ *     <formalpara>
+ *       <title>Our objects are de-structured.</title>
+ *       <para>
+ *         Instead of organizing our elementary datas into structures,
+ *         our objects are just flat lists of #NADataBox.
+ *       </para>
+ *     </formalpara>
+ *   </listitem>
+ *   <listitem>
+ *     <formalpara>
+ *       <title>A full, centralized, data dictionary is defined.</title>
+ *       <para>
+ *         Now that our elementary datas are banalized and de-structured,
+ *         it is simple enough to describe each of these datas with all
+ *         iss properties in one single, centralized, place.
+ *       </para>
+ *     </formalpara>
+ *   </listitem>
+ * </orderedlist>
+ *
+ * Of course, I/O providers are good candidates to be users of this
+ * #NAIFactoryProvider interface.
+ *
+ * Without this interface, each and every I/O provider must,
+ * for example when reading an item, have the list of data to be
+ * readen for each item, then read each individual data, then
+ * organize them in a I/O structure..
+ * Each time a new data is added to an object, as e.g. a new condition,
+ * then all available I/O providers must be updated: read the data,
+ * write the data, then display the data, and so on..
+ *
+ * With this #NAIFactoryProvider interface, the I/O provider has just to
+ * deal with reading/writing elementary types. It does need to know that
+ * it will have to read, name, tooltip, description. It just needs to know
+ * how to read a string.
+ * And while we do not introduce another data type, the I/O provider
+ * does not need any maintenance even if we add lot of new data, conditions
+ * labels, and so on.
+ *
+ * So, this is the interface used by data factory management system for
+ * providing serialization/unserialization services. This interface may
+ * be implemented by I/O providers which would take advantage of this
+ * system.
+ *
+ * <refsect2>
+ *  <title>Versions historic</title>
+ *  <table>
+ *    <title>Historic of the versions of the #NAIFactoryProvider 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>#NAIFactoryProvider 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
  */
-struct NAIFactoryProviderInterfacePrivate {
+struct _NAIFactoryProviderInterfacePrivate {
 	void *empty;						/* so that gcc -pedantic is happy */
 };
 
@@ -151,10 +255,40 @@ ifactory_provider_get_version( const NAIFactoryProvider *instance )
 /**
  * na_ifactory_provider_read_item:
  * @reader: the instance which implements this #NAIFactoryProvider interface.
- * @reader_data: instance data.
+ * @reader_data: instance data which will be provided back to the interface
+ *  methods
  * @object: the #NAIFactoryObject object to be unserialilzed.
  * @messages: a pointer to a #GSList list of strings; the implementation
  *  may append messages to this list, but shouldn't reinitialize it.
+ *
+ * This function is to be called by a #NAIIOProvider which would wish read
+ * its items. The function takes care of collecting and structuring data,
+ * while the callback interface methods #NAIFactoryProviderInterface.read_start(),
+ * #NAIFactoryProviderInterface.read_data() and #NAIFactoryProviderInterface.read_done()
+ * just have to fill a given #NADataBox with the ad-hoc data type.
+ *
+ * <example>
+ *   <programlisting>
+ *     &lcomment;
+ *      * allocate the object to be readen
+ *      &rcomment;
+ *     NAObjectItem *item = NA_OBJECT_ITEM( na_object_action_new());
+ *     &lcomment;
+ *      * some data we may need to have access to in callback methods
+ *      &rcomment;
+ *     void *data;
+ *     &lcomment;
+ *      * now call interface function
+ *      &rcomment;
+ *     na_ifactory_provider_read_item(
+ *         NA_IFACTORY_PROVIDER( provider ),
+ *         data,
+ *         NA_IFACTORY_OBJECT( item ),
+ *         messages );
+ *   </programlisting>
+ * </example>
+ *
+ * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
  */
 void
 na_ifactory_provider_read_item( const NAIFactoryProvider *reader, void *reader_data, NAIFactoryObject *object, GSList **messages )
@@ -178,9 +312,12 @@ na_ifactory_provider_read_item( const NAIFactoryProvider *reader, void *reader_d
  * @messages: a pointer to a #GSList list of strings; the implementation
  *  may append messages to this list, but shouldn't reinitialize it.
  *
- * Writes the data down to the FactoryProvider.
+ * This function is to be called by a #NAIIOProvider which would wish write
+ * an item. The function takes care of collecting and writing elementary data.
  *
  * Returns: a NAIIOProvider operation return code.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIFactoryProvider interface v 1.
  */
 guint
 na_ifactory_provider_write_item( const NAIFactoryProvider *writer, void *writer_data, NAIFactoryObject *object, GSList **messages )
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]