NAIFactoryProvider

## NAIFactoryProvider NAIFactoryProvider — The Data Factory Provider Interface v 1 |

## Synopsis

    #include <nautilus-actions/na-ifactory_provider.h>

    #define             NA_TYPE_IFACTORY_PROVIDER
    #define             NA_IFACTORY_PROVIDER                (instance)
    #define             NA_IS_IFACTORY_PROVIDER             (instance)
    #define             NA_IFACTORY_PROVIDER_GET_INTERFACE  (instance)
                        NAIFactoryProvider;
                        NAIFactoryProviderInterface;
    void                na_ifactory_provider_read_item      (const NAIFactoryProvider *reader,
                                                             void *reader_data,
                                                             NAIFactoryObject *object,
                                                             GSList **messages);
    guint               na_ifactory_provider_write_item     (const NAIFactoryProvider *writer,
                                                             void *writer_data,
                                                             NAIFactoryObject *object,
                                                             GSList **messages);

## Object Hierarchy

      GInterface
       +----NAIFactoryProvider

## Prerequisites

NAIFactoryProvider requires GObject.

## Description

Nautilus-Actions™ 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:

1. Elementary datas are banalized. whether they are a string, an integer, a boolean, a simple or double-linked list, each elementary data is encapsuled into a NADataBoxed, small sort of structure (incidentally, which acts almost as the new GLib GVariant, but too late, guys :)).

2. Our objects are de-structured. Instead of organizing our elementary datas into structures, our objects are just flat lists of NADataBoxed.

3. A full, centralized, data dictionary is defined. 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.

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 read 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.

### Versions historic

Table 8. Historic of the versions of the NAIFactoryProvider interface

Nautilus-Actions™ version | NAIFactoryProvider interface version |
--- | --- | ---
since 2.30 | 1 | current version

## Details

### NA_TYPE_IFACTORY_PROVIDER

    #define NA_TYPE_IFACTORY_PROVIDER                      ( na_ifactory_provider_get_type())

### NA_IFACTORY_PROVIDER()

    #define NA_IFACTORY_PROVIDER( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IFACTORY_PROVIDER, NAIFactoryProvider ))

### NA_IS_IFACTORY_PROVIDER()

    #define NA_IS_IFACTORY_PROVIDER( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IFACTORY_PROVIDER ))

### NA_IFACTORY_PROVIDER_GET_INTERFACE()

    #define NA_IFACTORY_PROVIDER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IFACTORY_PROVIDER, NAIFactoryProviderInterface ))

### NAIFactoryProvider

    typedef struct _NAIFactoryProvider NAIFactoryProvider;

### NAIFactoryProviderInterface

    typedef struct {
    	/**
    	 * get_version:
    	 * @instance: this #NAIFactoryProvider instance.
    	 *
    	 * Defaults to 1.
    	 *
    	 * Returns: the version of this interface supported by @instance implementation.
    	 *
    	 * Since: 2.30
    	 */
    	guint         ( *get_version )( const NAIFactoryProvider *instance );

    	/**
    	 * read_start:
    	 * @reader: this #NAIFactoryProvider 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 read.
    	 * @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: 2.30
    	 */
    	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, 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 read value.
    	 * Should return %NULL if data is not found.
    	 *
    	 * Since: 2.30
    	 */
    	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, as provided
    	 *  when na_ifactory_provider_read_item() was called.
    	 * @object: the #NAIFactoryObject object which comes to be read.
    	 * @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 read.
    	 * Implementor may take advantage of this to do some cleanup.
    	 *
    	 * Since: 2.30
    	 */
    	void          ( *read_done )  ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, GSList **messages  );

    	/**
    	 * write_start:
    	 * @writer: this #NAIFactoryProvider instance.
    	 * @writer_data: the data associated to this instance.
    	 * @object: the #NAIFactoryObject object which comes to be written.
    	 * @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.
    	 *
    	 * Since: 2.30
    	 */
    	guint         ( *write_start )( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages  );

    	/**
    	 * write_data:
    	 * @writer: this #NAIFactoryProvider instance.
    	 * @writer_data: the data associated to this instance.
    	 * @object: the #NAIFactoryObject object being written.
    	 * @def: the description of the data to be written.
    	 * @value: the #NADataBoxed to be written down.
    	 * @messages: a pointer to a #GSList list of strings; the provider
    	 *  may append messages to this list, but shouldn't reinitialize it.
    	 *
    	 * 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.
    	 *
    	 * Since: 2.30
    	 */
    	guint         ( *write_data ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, const NADataBoxed *boxed, GSList **messages );

    	/**
    	 * write_done:
    	 * @writer: this #NAIFactoryProvider instance.
    	 * @writer_data: the data associated to this instance.
    	 * @object: the #NAIFactoryObject object which comes to be written.
    	 * @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 written.
    	 * Implementor may take advantage of this to do some cleanup.
    	 *
    	 * Returns: a NAIIOProvider operation return code.
    	 *
    	 * Since: 2.30
    	 */
    	guint         ( *write_done ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages  );
    } NAIFactoryProviderInterface;

This defines the interface that a NAIFactoryProvider may implement.

`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.

### na_ifactory_provider_read_item ()

    void                na_ifactory_provider_read_item      (const NAIFactoryProvider *reader,
                                                             void *reader_data,
                                                             NAIFactoryObject *object,
                                                             GSList **messages);

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 NADataBoxed with the ad-hoc data type.

Example 3.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    /*
     * allocate the object to be read
     */
    NAObjectItem *item = NA_OBJECT_ITEM( na_object_action_new());
    /*
     * some data we may need to have access to in callback methods
     */
    void *data;
    /*
     * now call interface function
     */
    na_ifactory_provider_read_item(
        NA_IFACTORY_PROVIDER( provider ),
        data,
        NA_IFACTORY_OBJECT( item ),
        messages );

`reader` : | the instance which implements this NAIFactoryProvider interface.
`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.

Since 2.30

### na_ifactory_provider_write_item ()

    guint               na_ifactory_provider_write_item     (const NAIFactoryProvider *writer,
                                                             void *writer_data,
                                                             NAIFactoryObject *object,
                                                             GSList **messages);

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.

`writer` : | the instance which implements this NAIFactoryProvider interface.
`writer_data` : | instance data.
`object` : | the NAIFactoryObject derived object to be serialized.
`messages` : | a pointer to a GSList list of strings; the implementation may append messages to this list, but shouldn't reinitialize it.
Returns : | a NAIIOProvider operation return code.

Since 2.30