NAIFactoryObject

## NAIFactoryObject NAIFactoryObject — The NAObjectItem Interface v 1 |

## Synopsis

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

    #define             NA_TYPE_IFACTORY_OBJECT
    #define             NA_IFACTORY_OBJECT                  (instance)
    #define             NA_IS_IFACTORY_OBJECT               (instance)
    #define             NA_IFACTORY_OBJECT_GET_INTERFACE    (instance)
                        NAIFactoryObject;
                        NAIFactoryObjectInterface;
    NADataBoxed *       na_ifactory_object_get_data_boxed   (const NAIFactoryObject *object,
                                                             const gchar *name);
    NADataGroup *       na_ifactory_object_get_data_groups  (const NAIFactoryObject *object);
    void *              na_ifactory_object_get_as_void      (const NAIFactoryObject *object,
                                                             const gchar *name);
    void                na_ifactory_object_set_from_void    (NAIFactoryObject *object,
                                                             const gchar *name,
                                                             const void *data);

## Object Hierarchy

      GInterface
       +----NAIFactoryObject

## Prerequisites

NAIFactoryObject requires GObject.

## Known Implementations

NAIFactoryObject is implemented by NAObjectAction, NAObjectMenu and NAObjectProfile.

## Description

This interface is implemented by NAObjectItem derived objects so that they can take advantage of our data factory management system.

A NAObjectItem derived object which would implement this NAIFactoryObject interface must meet following conditions:

- accept an empty constructor

### Versions historic

Table 9. Historic of the versions of the NAIFactoryObject interface

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

## Details

### NA_TYPE_IFACTORY_OBJECT

    #define NA_TYPE_IFACTORY_OBJECT                      ( na_ifactory_object_get_type())

### NA_IFACTORY_OBJECT()

    #define NA_IFACTORY_OBJECT( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IFACTORY_OBJECT, NAIFactoryObject ))

### NA_IS_IFACTORY_OBJECT()

    #define NA_IS_IFACTORY_OBJECT( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IFACTORY_OBJECT ))

### NA_IFACTORY_OBJECT_GET_INTERFACE()

    #define NA_IFACTORY_OBJECT_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IFACTORY_OBJECT, NAIFactoryObjectInterface ))

### NAIFactoryObject

    typedef struct _NAIFactoryObject NAIFactoryObject;

### NAIFactoryObjectInterface

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

    	/**
    	 * get_groups:
    	 * @instance: this #NAIFactoryObject instance.
    	 *
    	 * Returns: a pointer to the NADataGroup which defines this object.
    	 *
    	 * Since: 2.30
    	 */
    	NADataGroup * ( *get_groups ) ( const NAIFactoryObject *instance );

    	/**
    	 * copy:
    	 * @instance: the target #NAIFactoryObject instance.
    	 * @source: the source #NAIFactoryObject instance.
    	 *
    	 * This function is triggered after having copied @source to
    	 * @instance target. This later may take advantage of this call
    	 * to do some particular copy tasks.
    	 *
    	 * Since: 2.30
    	 */
    	void          ( *copy )       ( NAIFactoryObject *instance, const NAIFactoryObject *source );

    	/**
    	 * are_equal:
    	 * @a: the first #NAIFactoryObject instance.
    	 * @b: the second #NAIFactoryObject instance.
    	 *
    	 * This function is triggered after all elementary data comparisons
    	 * have been sucessfully made.
    	 *
    	 * Returns: %TRUE if @a is equal to @b.
    	 *
    	 * Since: 2.30
    	 */
    	gboolean      ( *are_equal )  ( const NAIFactoryObject *a, const NAIFactoryObject *b );

    	/**
    	 * is_valid:
    	 * @object: the #NAIFactoryObject instance whose validity is to be checked.
    	 *
    	 * This function is triggered after all elementary data comparisons
    	 * have been sucessfully made.
    	 *
    	 * Returns: %TRUE if @object is valid.
    	 *
    	 * Since: 2.30
    	 */
    	gboolean      ( *is_valid )   ( const NAIFactoryObject *object );

    	/**
    	 * read_start:
    	 * @instance: this #NAIFactoryObject instance.
    	 * @reader: the instance which has provided read services.
    	 * @reader_data: the data associated to @reader.
    	 * @messages: a pointer to a #GSList list of strings; the instance
    	 *  may append messages to this list, but shouldn't reinitialize it.
    	 *
    	 * Called just before the object is unserialized.
    	 *
    	 * Since: 2.30
    	 */
    	void          ( *read_start ) ( NAIFactoryObject *instance, const NAIFactoryProvider *reader, void *reader_data, GSList **messages );

    	/**
    	 * read_done:
    	 * @instance: this #NAIFactoryObject instance.
    	 * @reader: the instance which has provided read services.
    	 * @reader_data: the data associated to @reader.
    	 * @messages: a pointer to a #GSList list of strings; the instance
    	 *  may append messages to this list, but shouldn't reinitialize it.
    	 *
    	 * Called when the object has been unserialized.
    	 *
    	 * Since: 2.30
    	 */
    	void          ( *read_done )  ( NAIFactoryObject *instance, const NAIFactoryProvider *reader, void *reader_data, GSList **messages );

    	/**
    	 * write_start:
    	 * @instance: this #NAIFactoryObject instance.
    	 * @writer: the instance which has provided writing services.
    	 * @writer_data: the data associated to @writer.
    	 * @messages: a pointer to a #GSList list of strings; the instance
    	 *  may append messages to this list, but shouldn't reinitialize it.
    	 *
    	 * Called just before the object is serialized.
    	 *
    	 * Returns: a NAIIOProvider operation return code.
    	 *
    	 * Since: 2.30
    	 */
    	guint         ( *write_start )( NAIFactoryObject *instance, const NAIFactoryProvider *writer, void *writer_data, GSList **messages );

    	/**
    	 * write_done:
    	 * @instance: this #NAIFactoryObject instance.
    	 * @writer: the instance which has provided writing services.
    	 * @writer_data: the data associated to @writer.
    	 * @messages: a pointer to a #GSList list of strings; the instance
    	 *  may append messages to this list, but shouldn't reinitialize it.
    	 *
    	 * Called when the object has been serialized.
    	 *
    	 * Returns: a NAIIOProvider operation return code.
    	 *
    	 * Since: 2.30
    	 */
    	guint         ( *write_done ) ( NAIFactoryObject *instance, const NAIFactoryProvider *writer, void *writer_data, GSList **messages );
    } NAIFactoryObjectInterface;

In order to take full advantage of our data managament system, NAObjectItem-derived objects all implement this NAIFactoryObject interface.

`get_version` () | returns the version of this interface the NAObjectItem implements.
`get_groups` () | returns a pointer to the NADataGroup which defines this object.
`copy` () | post copy callback.
`are_equal` () | tests if two NAObjectItem are equals.
`is_valid` () | tests if one NAObjectItem is valid.
`read_start` () | triggered before serializing a NAObjectItem.
`read_done` () | triggered after a NAObjectItem has been serialized.
`write_start` () | triggered before unserializing a NAObjectItem.
`write_done` () | triggered after a NAObjectItem has been unserialized.

### na_ifactory_object_get_data_boxed ()

    NADataBoxed *       na_ifactory_object_get_data_boxed   (const NAIFactoryObject *object,
                                                             const gchar *name);

The returned NADataBoxed is owned by NAIFactoryObject `object`, and should not be released by the caller.

`object` : | a NAIFactoryObject object.
`name` : | the name of the elementary data we are searching for.
Returns : | The NADataBoxed object which contains the specified data, or `NULL`.

Since 2.30

### na_ifactory_object_get_data_groups ()

    NADataGroup *       na_ifactory_object_get_data_groups  (const NAIFactoryObject *object);

The returned NADataGroup is owned by the NAIFactoryObject `object`, and should not be released by the caller.

`object` : | a NAIFactoryObject object.
Returns : | The NADataGroup groups definition, or `NULL`.

Since 2.30

### na_ifactory_object_get_as_void ()

    void *              na_ifactory_object_get_as_void      (const NAIFactoryObject *object,
                                                             const gchar *name);

If the type of the value is `NA_DATA_TYPE_STRING`, `NA_DATA_TYPE_LOCALE_STRING`, or `NA_DATA_TYPE_STRING_LIST`, then the returned value is a newly allocated one and should be `g_free()` (resp. `na_core_utils_slist_free()`) by the caller.

`object` : | this NAIFactoryObject instance.
`name` : | the elementary data whose value is to be got.
Returns : | the searched value.

Since 2.30

### na_ifactory_object_set_from_void ()

    void                na_ifactory_object_set_from_void    (NAIFactoryObject *object,
                                                             const gchar *name,
                                                             const void *data);

Set the elementary data with the given value.

`object` : | this NAIFactoryObject instance.
`name` : | the name of the elementary data whose value is to be set.
`data` : | the value to set.

Since 2.30