src/api/na-ifactory-object.h

   1 /*
   2  * Nautilus Actions
   3  * A Nautilus extension which offers configurable context menu actions.
   4  *
   5  * Copyright (C) 2005 The GNOME Foundation
   6  * Copyright (C) 2006, 2007, 2008 Frederic Ruaudel and others (see AUTHORS)
   7  * Copyright (C) 2009, 2010, 2011 Pierre Wieser and others (see AUTHORS)
   8  *
   9  * This Program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU General Public License as
  11  * published by the Free Software Foundation; either version 2 of
  12  * the License, or (at your option) any later version.
  13  *
  14  * This Program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public
  20  * License along with this Library; see the file COPYING.  If not,
  21  * write to the Free Software Foundation, Inc., 59 Temple Place,
  22  * Suite 330, Boston, MA 02111-1307, USA.
  23  *
  24  * Authors:
  25  *   Frederic Ruaudel <grumz@grumz.net>
  26  *   Rodrigo Moya <rodrigo@gnome-db.org>
  27  *   Pierre Wieser <pwieser@trychlos.org>
  28  *   ... and many others (see AUTHORS)
  29  */
  30
  31 #ifndef __NAUTILUS_ACTIONS_API_NA_IFACTORY_OBJECT_H__
  32 #define __NAUTILUS_ACTIONS_API_NA_IFACTORY_OBJECT_H__
  33
  34 /**
  35  * SECTION: ifactory-object
  36  * @title: NAIFactoryObject
  37  * @short_description: The #NAObjectItem Interface v 1
  38  * @include: nautilus-actions/na-ifactory_object.h
  39  *
  40  * This interface is implemented by #NAObjectItem derived objects so that they
  41  * can take advantage of our data factory management system.
  42  *
  43  * A #NAObjectItem derived object which would implement this #NAIFactoryObject
  44  * interface must meet following conditions:
  45  * <itemizedlist>
  46  *   <listitem>
  47  *     <para>
  48  *       accept an empty constructor
  49  *     </para>
  50  *   </listitem>
  51  * </itemizedlist>
  52  *
  53  * <refsect2>
  54  *  <title>Versions historic</title>
  55  *  <table>
  56  *    <title>Historic of the versions of the #NAIFactoryObject interface</title>
  57  *    <tgroup rowsep="1" colsep="1" align="center" cols="3">
  58  *      <colspec colname="na-version" />
  59  *      <colspec colname="api-version" />
  60  *      <colspec colname="current" />
  61  *      <thead>
  62  *        <row>
  63  *          <entry>&prodname; version</entry>
  64  *          <entry>#NAIFactoryObject interface version</entry>
  65  *          <entry></entry>
  66  *        </row>
  67  *      </thead>
  68  *      <tbody>
  69  *        <row>
  70  *          <entry>since 2.30</entry>
  71  *          <entry>1</entry>
  72  *          <entry>current version</entry>
  73  *        </row>
  74  *      </tbody>
  75  *    </tgroup>
  76  *  </table>
  77  * </refsect2>
  78  */
  79
  80 #include "na-data-def.h"
  81 #include "na-data-boxed.h"
  82 #include "na-ifactory-provider-provider.h"
  83
  84 G_BEGIN_DECLS
  85
  86 #define NA_IFACTORY_OBJECT_TYPE                                                 ( na_ifactory_object_get_type())
  87 #define NA_IFACTORY_OBJECT( instance )                                  ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IFACTORY_OBJECT_TYPE, NAIFactoryObject ))
  88 #define NA_IS_IFACTORY_OBJECT( instance )                               ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IFACTORY_OBJECT_TYPE ))
  89 #define NA_IFACTORY_OBJECT_GET_INTERFACE( instance )    ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IFACTORY_OBJECT_TYPE, NAIFactoryObjectInterface ))
  90
  91 typedef struct _NAIFactoryObject                 NAIFactoryObject;
  92
  93 typedef struct _NAIFactoryObjectInterfacePrivate NAIFactoryObjectInterfacePrivate;
  94
  95 /**
  96  * NAIFactoryObjectInterface:
  97  * @get_version: returns the version of this interface the NAObjectItem implements.
  98  * @get_groups:  returns a pointer to the NADataGroup which defines this object.
  99  * @copy:        post copy callback.
 100  * @are_equal:   tests if two NAObjectItem are equals.
 101  * @is_valid:    tests if one NAObjectItem is valid.
 102  * @read_start:  triggered before serializing a NAObjectItem.
 103  * @read_done:   triggered after a NAObjectItem has been serialized.
 104  * @write_start: triggered before unserializing a NAObjectItem.
 105  * @write_done:  triggered after a NAObjectItem has been unserialized.
 106  *
 107  * In order to take full advantage of our data managament system,
 108  * NAObjectItem-derived objects all implement this #NAIFactoryObject
 109  * interface.
 110  */
 111 typedef struct {
 112         /*< private >*/
 113         GTypeInterface                    parent;
 114         NAIFactoryObjectInterfacePrivate *private;
 115
 116         /*< public >*/
 117         /**
 118          * get_version:
 119          * @instance: this #NAIFactoryObject instance.
 120          *
 121          * Defaults to 1.
 122          *
 123          * Returns: the version of this interface supported by @instance implementation.
 124          *
 125          * Since: 2.30
 126          */
 127         guint         ( *get_version )( const NAIFactoryObject *instance );
 128
 129         /**
 130          * get_groups:
 131          * @instance: this #NAIFactoryObject instance.
 132          *
 133          * Returns: a pointer to the NADataGroup which defines this object.
 134          *
 135          * Since: 2.30
 136          */
 137         NADataGroup * ( *get_groups ) ( const NAIFactoryObject *instance );
 138
 139         /**
 140          * copy:
 141          * @instance: the target #NAIFactoryObject instance.
 142          * @source: the source #NAIFactoryObject instance.
 143          *
 144          * This function is triggered after having copied @source to
 145          * @instance target. This later may take advantage of this call
 146          * to do some particular copy tasks.
 147          *
 148          * Since: 2.30
 149          */
 150         void          ( *copy )       ( NAIFactoryObject *instance, const NAIFactoryObject *source );
 151
 152         /**
 153          * are_equal:
 154          * @a: the first #NAIFactoryObject instance.
 155          * @b: the second #NAIFactoryObject instance.
 156          *
 157          * This function is triggered after all elementary data comparisons
 158          * have been sucessfully made.
 159          *
 160          * Returns: %TRUE if @a is equal to @b.
 161          *
 162          * Since: 2.30
 163          */
 164         gboolean      ( *are_equal )  ( const NAIFactoryObject *a, const NAIFactoryObject *b );
 165
 166         /**
 167          * is_valid:
 168          * @object: the #NAIFactoryObject instance whose validity is to be checked.
 169          *
 170          * This function is triggered after all elementary data comparisons
 171          * have been sucessfully made.
 172          *
 173          * Returns: %TRUE if @object is valid.
 174          *
 175          * Since: 2.30
 176          */
 177         gboolean      ( *is_valid )   ( const NAIFactoryObject *object );
 178
 179         /**
 180          * read_start:
 181          * @instance: this #NAIFactoryObject instance.
 182          * @reader: the instance which has provided read services.
 183          * @reader_data: the data associated to @reader.
 184          * @messages: a pointer to a #GSList list of strings; the instance
 185          *  may append messages to this list, but shouldn't reinitialize it.
 186          *
 187          * Called just before the object is unserialized.
 188          *
 189          * Since: 2.30
 190          */
 191         void          ( *read_start ) ( NAIFactoryObject *instance, const NAIFactoryProvider *reader, void *reader_data, GSList **messages );
 192
 193         /**
 194          * read_done:
 195          * @instance: this #NAIFactoryObject instance.
 196          * @reader: the instance which has provided read services.
 197          * @reader_data: the data associated to @reader.
 198          * @messages: a pointer to a #GSList list of strings; the instance
 199          *  may append messages to this list, but shouldn't reinitialize it.
 200          *
 201          * Called when the object has been unserialized.
 202          *
 203          * Since: 2.30
 204          */
 205         void          ( *read_done )  ( NAIFactoryObject *instance, const NAIFactoryProvider *reader, void *reader_data, GSList **messages );
 206
 207         /**
 208          * write_start:
 209          * @instance: this #NAIFactoryObject instance.
 210          * @writer: the instance which has provided writing services.
 211          * @writer_data: the data associated to @writer.
 212          * @messages: a pointer to a #GSList list of strings; the instance
 213          *  may append messages to this list, but shouldn't reinitialize it.
 214          *
 215          * Called just before the object is serialized.
 216          *
 217          * Returns: a NAIIOProvider operation return code.
 218          *
 219          * Since: 2.30
 220          */
 221         guint         ( *write_start )( NAIFactoryObject *instance, const NAIFactoryProvider *writer, void *writer_data, GSList **messages );
 222
 223         /**
 224          * write_done:
 225          * @instance: this #NAIFactoryObject instance.
 226          * @writer: the instance which has provided writing services.
 227          * @writer_data: the data associated to @writer.
 228          * @messages: a pointer to a #GSList list of strings; the instance
 229          *  may append messages to this list, but shouldn't reinitialize it.
 230          *
 231          * Called when the object has been serialized.
 232          *
 233          * Returns: a NAIIOProvider operation return code.
 234          *
 235          * Since: 2.30
 236          */
 237         guint         ( *write_done ) ( NAIFactoryObject *instance, const NAIFactoryProvider *writer, void *writer_data, GSList **messages );
 238 }
 239         NAIFactoryObjectInterface;
 240
 241 GType        na_ifactory_object_get_type( void );
 242
 243 NADataBoxed *na_ifactory_object_get_data_boxed ( const NAIFactoryObject *object, const gchar *name );
 244
 245 NADataGroup *na_ifactory_object_get_data_groups( const NAIFactoryObject *object );
 246
 247 void        *na_ifactory_object_get_as_void    ( const NAIFactoryObject *object, const gchar *name );
 248
 249 void         na_ifactory_object_set_from_void  ( NAIFactoryObject *object, const gchar *name, const void *data );
 250
 251 G_END_DECLS
 252
 253 #endif /* __NAUTILUS_ACTIONS_API_NA_IFACTORY_OBJECT_H__ */