src/api/na-ifactory-provider.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_PROVIDER_H__
  32 #define __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__
  33
  34 /**
  35  * SECTION: ifactory-provider
  36  * @title: NAIFactoryProvider
  37  * @short_description: The Data Factory Provider Interface v 1
  38  * @include: nautilus-actions/na-ifactory_provider.h
  39  *
  40  * &prodname; has to deal with a relatively great number of elementary datas,
  41  * reading them from different supports, storing and displaying them,
  42  * then re-writing these same datas, with several output formats, and so on.
  43  *
  44  * This has rapidly become a pain, if not just a bug generator.
  45  * Each new data must be described, have a schema to be stored in
  46  * (historical storage subsystem) GConf; import and export assistants
  47  * must be carefully updated to export the new data...
  48  *
  49  * The #NAIFactoryProvider aims to simplify and organize all the work
  50  * which must be done around each and every elementary data. It is based
  51  * on three main things:
  52  *
  53  * <orderedlist>
  54  *   <listitem>
  55  *     <formalpara>
  56  *       <title>Elementary datas are banalized.</title>
  57  *       <para>
  58  *         whether they are a string, an integer, a boolean, a simple
  59  *         or double-linked list, each elementary data is encapsuled
  60  *         into a #NADataBoxed, small sort of structure (incidentally,
  61  *         which acts almost as the new GLib #GVariant, but too late,
  62  *         guys :)).
  63  *       </para>
  64  *     </formalpara>
  65  *   </listitem>
  66  *   <listitem>
  67  *     <formalpara>
  68  *       <title>Our objects are de-structured.</title>
  69  *       <para>
  70  *         Instead of organizing our elementary datas into structures,
  71  *         our objects are just flat lists of #NADataBoxed.
  72  *       </para>
  73  *     </formalpara>
  74  *   </listitem>
  75  *   <listitem>
  76  *     <formalpara>
  77  *       <title>A full, centralized, data dictionary is defined.</title>
  78  *       <para>
  79  *         Now that our elementary datas are banalized and de-structured,
  80  *         it is simple enough to describe each of these datas with all
  81  *         iss properties in one single, centralized, place.
  82  *       </para>
  83  *     </formalpara>
  84  *   </listitem>
  85  * </orderedlist>
  86  *
  87  * Of course, I/O providers are good candidates to be users of this
  88  * #NAIFactoryProvider interface.
  89  *
  90  * Without this interface, each and every I/O provider must,
  91  * for example when reading an item, have the list of data to be
  92  * read for each item, then read each individual data, then
  93  * organize them in a I/O structure..
  94  * Each time a new data is added to an object, as e.g. a new condition,
  95  * then all available I/O providers must be updated: read the data,
  96  * write the data, then display the data, and so on..
  97  *
  98  * With this #NAIFactoryProvider interface, the I/O provider has just to
  99  * deal with reading/writing elementary types. It does need to know that
 100  * it will have to read, name, tooltip, description. It just needs to know
 101  * how to read a string.
 102  * And while we do not introduce another data type, the I/O provider
 103  * does not need any maintenance even if we add lot of new data, conditions
 104  * labels, and so on.
 105  *
 106  * So, this is the interface used by data factory management system for
 107  * providing serialization/unserialization services. This interface may
 108  * be implemented by I/O providers which would take advantage of this
 109  * system.
 110  *
 111  * <refsect2>
 112  *  <title>Versions historic</title>
 113  *  <table>
 114  *    <title>Historic of the versions of the #NAIFactoryProvider interface</title>
 115  *    <tgroup rowsep="1" colsep="1" align="center" cols="3">
 116  *      <colspec colname="na-version" />
 117  *      <colspec colname="api-version" />
 118  *      <colspec colname="current" />
 119  *      <thead>
 120  *        <row>
 121  *          <entry>&prodname; version</entry>
 122  *          <entry>#NAIFactoryProvider interface version</entry>
 123  *          <entry></entry>
 124  *        </row>
 125  *      </thead>
 126  *      <tbody>
 127  *        <row>
 128  *          <entry>since 2.30</entry>
 129  *          <entry>1</entry>
 130  *          <entry>current version</entry>
 131  *        </row>
 132  *      </tbody>
 133  *    </tgroup>
 134  *  </table>
 135  * </refsect2>
 136  */
 137
 138 #include "na-data-boxed.h"
 139 #include "na-ifactory-object.h"
 140 #include "na-ifactory-provider-provider.h"
 141
 142 G_BEGIN_DECLS
 143
 144 #define NA_IFACTORY_PROVIDER_TYPE                      ( na_ifactory_provider_get_type())
 145 #define NA_IFACTORY_PROVIDER( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IFACTORY_PROVIDER_TYPE, NAIFactoryProvider ))
 146 #define NA_IS_IFACTORY_PROVIDER( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IFACTORY_PROVIDER_TYPE ))
 147 #define NA_IFACTORY_PROVIDER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IFACTORY_PROVIDER_TYPE, NAIFactoryProviderInterface ))
 148
 149 typedef struct _NAIFactoryProviderInterfacePrivate     NAIFactoryProviderInterfacePrivate;
 150
 151 /**
 152  * NAIFactoryProviderInterface:
 153  * @get_version: returns the version of this interface the plugin implements.
 154  * @read_start:  triggered just before reading an item.
 155  * @read_data:   reads an item.
 156  * @read_done:   triggered at the end of item reading.
 157  * @write_start: triggered just before writing an item.
 158  * @write_data:  writes an item.
 159  * @write_done:  triggered at the end of item writing.
 160  *
 161  * This defines the interface that a #NAIFactoryProvider may implement.
 162  */
 163 typedef struct {
 164         /*< private >*/
 165         GTypeInterface                      parent;
 166         NAIFactoryProviderInterfacePrivate *private;
 167
 168         /*< public >*/
 169         /**
 170          * get_version:
 171          * @instance: this #NAIFactoryProvider instance.
 172          *
 173          * Defaults to 1.
 174          *
 175          * Returns: the version of this interface supported by @instance implementation.
 176          *
 177          * Since: 2.30
 178          */
 179         guint         ( *get_version )( const NAIFactoryProvider *instance );
 180
 181         /**
 182          * read_start:
 183          * @reader: this #NAIFactoryProvider instance.
 184          * @reader_data: the data associated to this instance, as provided
 185          *  when na_ifactory_provider_read_item() was called.
 186          * @object: the #NAIFactoryObject object which comes to be read.
 187          * @messages: a pointer to a #GSList list of strings; the provider
 188          *  may append messages to this list, but shouldn't reinitialize it.
 189          *
 190          * API called by #NAIFactoryObject just before starting with reading data.
 191          *
 192          * Since: 2.30
 193          */
 194         void          ( *read_start ) ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, GSList **messages  );
 195
 196         /**
 197          * read_data:
 198          * @reader: this #NAIFactoryProvider instance.
 199          * @reader_data: the data associated to this instance, as provided
 200          *  when na_ifactory_provider_read_item() was called.
 201          * @object: the #NAIFactoryobject being unserialized.
 202          * @def: a #NADataDef structure which identifies the data to be unserialized.
 203          * @messages: a pointer to a #GSList list of strings; the provider
 204          *  may append messages to this list, but shouldn't reinitialize it.
 205          *
 206          * This method must be implemented in order any data be read.
 207          *
 208          * Returns: a newly allocated NADataBoxed which contains the read value.
 209          * Should return %NULL if data is not found.
 210          *
 211          * Since: 2.30
 212          */
 213         NADataBoxed * ( *read_data )  ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, const NADataDef *def, GSList **messages );
 214
 215         /**
 216          * read_done:
 217          * @reader: this #NAIFactoryProvider instance.
 218          * @reader_data: the data associated to this instance, as provided
 219          *  when na_ifactory_provider_read_item() was called.
 220          * @object: the #NAIFactoryObject object which comes to be read.
 221          * @messages: a pointer to a #GSList list of strings; the provider
 222          *  may append messages to this list, but shouldn't reinitialize it.
 223          *
 224          * API called by #NAIFactoryObject when all data have been read.
 225          * Implementor may take advantage of this to do some cleanup.
 226          *
 227          * Since: 2.30
 228          */
 229         void          ( *read_done )  ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, GSList **messages  );
 230
 231         /**
 232          * write_start:
 233          * @writer: this #NAIFactoryProvider instance.
 234          * @writer_data: the data associated to this instance.
 235          * @object: the #NAIFactoryObject object which comes to be written.
 236          * @messages: a pointer to a #GSList list of strings; the provider
 237          *  may append messages to this list, but shouldn't reinitialize it.
 238          *
 239          * API called by #NAIFactoryObject just before starting with writing data.
 240          *
 241          * Returns: a NAIIOProvider operation return code.
 242          *
 243          * Since: 2.30
 244          */
 245         guint         ( *write_start )( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages  );
 246
 247         /**
 248          * write_data:
 249          * @writer: this #NAIFactoryProvider instance.
 250          * @writer_data: the data associated to this instance.
 251          * @object: the #NAIFactoryObject object being written.
 252          * @def: the description of the data to be written.
 253          * @value: the #NADataBoxed to be written down.
 254          * @messages: a pointer to a #GSList list of strings; the provider
 255          *  may append messages to this list, but shouldn't reinitialize it.
 256          *
 257          * Write the data embedded in @value down to @instance.
 258          *
 259          * This method must be implemented in order any data be written.
 260          *
 261          * Returns: a NAIIOProvider operation return code.
 262          *
 263          * Since: 2.30
 264          */
 265         guint         ( *write_data ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, const NADataBoxed *boxed, GSList **messages );
 266
 267         /**
 268          * write_done:
 269          * @writer: this #NAIFactoryProvider instance.
 270          * @writer_data: the data associated to this instance.
 271          * @object: the #NAIFactoryObject object which comes to be written.
 272          * @messages: a pointer to a #GSList list of strings; the provider
 273          *  may append messages to this list, but shouldn't reinitialize it.
 274          *
 275          * API called by #NAIFactoryObject when all data have been written.
 276          * Implementor may take advantage of this to do some cleanup.
 277          *
 278          * Returns: a NAIIOProvider operation return code.
 279          *
 280          * Since: 2.30
 281          */
 282         guint         ( *write_done ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages  );
 283 }
 284         NAIFactoryProviderInterface;
 285
 286 GType na_ifactory_provider_get_type( void );
 287
 288 void  na_ifactory_provider_read_item ( const NAIFactoryProvider *reader, void *reader_data, NAIFactoryObject *object, GSList **messages );
 289 guint na_ifactory_provider_write_item( const NAIFactoryProvider *writer, void *writer_data, NAIFactoryObject *object, GSList **messages );
 290
 291 G_END_DECLS
 292
 293 #endif /* __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__ */