src/api/na-iio-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_IIO_PROVIDER_H__
  32 #define __NAUTILUS_ACTIONS_API_NA_IIO_PROVIDER_H__
  33
  34 /**
  35  * SECTION: iio-provider
  36  * @title: NAIIOProvider
  37  * @short_description: The I/O Provider Interface v 1
  38  * @include: nautilus-actions/na-iio-provider.h
  39  *
  40  * The #NAIIOProvider interface is defined in order to let internal
  41  * and external plugins provide read and write accesses
  42  * to an alternate storage subsystem.
  43  *
  44  * The #NAIIOProvider interface provides three types of services:
  45  * <itemizedlist>
  46  *  <listitem>
  47  *   <para>
  48  *    load items;
  49  *   </para>
  50  *  </listitem>
  51  *  <listitem>
  52  *   <para>
  53  *    create, update or delete items;
  54  *   </para>
  55  *  </listitem>
  56  *  <listitem>
  57  *   <para>
  58  *    inform &prodname; when an item has been modified on the
  59  *    underlying storage subsystem.
  60  *   </para>
  61  *   <para>
  62  *    The #NAIIOProvider interface does not define specific monitoring
  63  *    methods. Instead, it is waited that the I/O provider module
  64  *    automatically takes care of starting/stopping its own monitoring
  65  *    services at load/unload time, calling the na_iio_provider_item_changed()
  66  *    function when appropriate.
  67  *   </para>
  68  *  </listitem>
  69  * </itemizedlist>
  70  *
  71  * These services may be fully implemented by the I/O provider itself.
  72  * Or, the I/O provider may also prefer to take advantage of the data
  73  * factory management (see #NAIFactoryObject and #NAIFactoryProvider
  74  * interfaces).
  75  *
  76  * <refsect2>
  77  *  <title>Versions historic</title>
  78  *  <table>
  79  *    <title>Historic of the versions of the #NAIIOProvider interface</title>
  80  *    <tgroup rowsep="1" colsep="1" align="center" cols="3">
  81  *      <colspec colname="na-version" />
  82  *      <colspec colname="api-version" />
  83  *      <colspec colname="current" />
  84  *      <thead>
  85  *        <row>
  86  *          <entry>&prodname; version</entry>
  87  *          <entry>#NAIIOProvider interface version</entry>
  88  *          <entry></entry>
  89  *        </row>
  90  *      </thead>
  91  *      <tbody>
  92  *        <row>
  93  *          <entry>since 2.30</entry>
  94  *          <entry>1</entry>
  95  *          <entry>current version</entry>
  96  *        </row>
  97  *      </tbody>
  98  *    </tgroup>
  99  *  </table>
 100  * </refsect2>
 101  */
 102
 103 #include "na-object-item.h"
 104
 105 G_BEGIN_DECLS
 106
 107 #define NA_IIO_PROVIDER_TYPE                      ( na_iio_provider_get_type())
 108 #define NA_IIO_PROVIDER( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IIO_PROVIDER_TYPE, NAIIOProvider ))
 109 #define NA_IS_IIO_PROVIDER( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IIO_PROVIDER_TYPE ))
 110 #define NA_IIO_PROVIDER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IIO_PROVIDER_TYPE, NAIIOProviderInterface ))
 111
 112 typedef struct _NAIIOProvider                     NAIIOProvider;
 113 typedef struct _NAIIOProviderInterfacePrivate     NAIIOProviderInterfacePrivate;
 114
 115 /**
 116  * NAIIOProviderInterface:
 117  * @get_version:         returns the version of this interface that the
 118  *                       plugin implements.
 119  * @get_id:              returns the internal id of the plugin.
 120  * @get_name:            returns the public name of the plugin.
 121  * @read_items:          reads items.
 122  * @is_willing_to_write: asks if the plugin is willing to write.
 123  * @is_able_to_write:    asks if the plugin is able to write.
 124  * @write_item:          writes an item.
 125  * @delete_item:         deletes an item.
 126  * @duplicate_data:      duplicates the provider-specific data.
 127  *
 128  * This defines the interface that a #NAIIOProvider should implement.
 129  */
 130 typedef struct {
 131         /*< private >*/
 132         GTypeInterface                 parent;
 133         NAIIOProviderInterfacePrivate *private;
 134
 135         /*< public >*/
 136         /**
 137          * get_version:
 138          * @instance: the #NAIIOProvider provider.
 139          *
 140          * This method is called by the &prodname; program each time
 141          * it needs to know which version of this interface the plugin
 142          * implements.
 143          *
 144          * If this method is not implemented by the plugin,
 145          * the &prodname; program considers that the plugin only implements
 146          * the version 1 of the #NAIIOProvider interface.
 147          *
 148          * Returns: the version of this interface supported by the I/O provider.
 149          *
 150          * Since: 2.30
 151          */
 152         guint    ( *get_version )        ( const NAIIOProvider *instance );
 153
 154         /**
 155          * get_id:
 156          * @instance: the #NAIIOProvider provider.
 157          *
 158          * To avoid any collision, the I/O provider id is allocated by the
 159          * Nautilus-Actions maintainer team. If you wish develop a new I/O
 160          * provider, and so need a new provider id, please contact the
 161          * maintainers (see nautilus-actions.doap).
 162          *
 163          * The I/O provider must implement this method.
 164          *
 165          * Returns: the id of the I/O provider, as a newly allocated string
 166          * which should be g_free() by the caller.
 167          *
 168          * Since: 2.30
 169          */
 170         gchar *  ( *get_id )             ( const NAIIOProvider *instance );
 171
 172         /**
 173          * get_name:
 174          * @instance: the #NAIIOProvider provider.
 175          *
 176          * Defaults to an empty string.
 177          *
 178          * Returns: the name to be displayed for this I/O provider, as a
 179          * newly allocated string which should be g_free() by the caller.
 180          *
 181          * Since: 2.30
 182          */
 183         gchar *  ( *get_name )           ( const NAIIOProvider *instance );
 184
 185         /**
 186          * read_items:
 187          * @instance: the #NAIIOProvider provider.
 188          * @messages: a pointer to a #GSList list of strings; the provider
 189          *  may append messages to this list, but shouldn't reinitialize it.
 190          *
 191          * Reads the whole items list from the specified I/O provider.
 192          *
 193          * The I/O provider must implement this method.
 194          *
 195          * Returns: a unordered flat #GList of #NAObjectItem -derived objects
 196          * (menus or actions); the actions embed their own profiles.
 197          *
 198          * Since: 2.30
 199          */
 200         GList *  ( *read_items )         ( const NAIIOProvider *instance, GSList **messages );
 201
 202         /**
 203          * is_willing_to_write:
 204          * @instance: the #NAIIOProvider provider.
 205          *
 206          * The 'willing_to_write' property is intrinsic to the I/O provider.
 207          * It is not supposed to make any assumption on the environment it is
 208          * currently running on.
 209          * This property just says that the developer/maintainer has released
 210          * the needed code in order to update/create/delete #NAObjectItem
 211          * -derived objects.
 212          *
 213          * Note that even if this property is %TRUE, there is yet many
 214          * reasons for not being able to update/delete existing items or
 215          * create new ones (see e.g. #is_able_to_write() below).
 216          *
 217          * Defaults to %FALSE.
 218          *
 219          * Returns: %TRUE if this I/O provider is willing to write,
 220          *  %FALSE else.
 221          *
 222          * Since: 2.30
 223          */
 224         gboolean ( *is_willing_to_write )( const NAIIOProvider *instance );
 225
 226         /**
 227          * is_able_to_write:
 228          * @instance: the #NAIIOProvider provider.
 229          *
 230          * The 'able_to_write' property is a runtime one.
 231          * When returning %TRUE, the I/O provider insures that it has
 232          * successfully checked that it was able to write some things
 233          * down to its storage subsystems.
 234          *
 235          * The 'able_to_write' property is independent of the
 236          * 'willing_to_write' above, though it is only checked if the
 237          * I/O provider is actually willing to write.
 238          *
 239          * This condition is only relevant when trying to define new items,
 240          * to see if a willing_to provider is actually able to do write
 241          * operations. It it not relevant for updating/deleting already
 242          * existing items as they have already checked their own runtime
 243          * writability status when read from the storage subsystems.
 244          *
 245          * Note that even if this property is %TRUE, there is yet many
 246          * reasons for not being able to update/delete existing items or
 247          * create new ones (see e.g. 'locked' preference key).
 248          *
 249          * Defaults to %FALSE.
 250          *
 251          * Returns: %TRUE if this I/O provider is able to do write
 252          * operations at runtime, %FALSE else.
 253          *
 254          * Since: 2.30
 255          */
 256         gboolean ( *is_able_to_write )   ( const NAIIOProvider *instance );
 257
 258         /**
 259          * write_item:
 260          * @instance: the #NAIIOProvider provider.
 261          * @item: a #NAObjectItem -derived item, menu or action.
 262          * @messages: a pointer to a #GSList list of strings; the provider
 263          *  may append messages to this list, but shouldn't reinitialize it.
 264          *
 265          * Writes a new @item.
 266          *
 267          * There is no update_item function ; it is the responsibility
 268          * of the provider to delete the previous version of an item before
 269          * actually writing the new one.
 270          *
 271          * The I/O provider should implement this method, or return
 272          * %FALSE in is_willing_to_write() method above.
 273          *
 274          * Returns: %NA_IIO_PROVIDER_CODE_OK if the write operation
 275          * was successful, or another code depending of the detected error.
 276          *
 277          * Since: 2.30
 278          */
 279         guint    ( *write_item )         ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages );
 280
 281         /**
 282          * delete_item:
 283          * @instance: the #NAIIOProvider provider.
 284          * @item: a #NAObjectItem -derived item, menu or action.
 285          * @messages: a pointer to a #GSList list of strings; the provider
 286          *  may append messages to this list, but shouldn't reinitialize it.
 287          *
 288          * Deletes an existing @item from the I/O subsystem.
 289          *
 290          * The I/O provider should implement this method, or return
 291          * %FALSE in is_willing_to_write() method above.
 292          *
 293          * Returns: %NA_IIO_PROVIDER_CODE_OK if the delete operation was
 294          * successful, or another code depending of the detected error.
 295          *
 296          * Since: 2.30
 297          */
 298         guint    ( *delete_item )        ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages );
 299
 300         /**
 301          * duplicate_data:
 302          * @instance: the #NAIIOProvider provider.
 303          * @dest: a #NAObjectItem -derived item, menu or action.
 304          * @source: a #NAObjectItem -derived item, menu or action.
 305          * @messages: a pointer to a #GSList list of strings; the provider
 306          *  may append messages to this list, but shouldn't reinitialize it.
 307          *
 308          * Duplicates provider-specific data (if any) from @source to @dest.
 309          *
 310          * Note that this does not duplicate in any way any #NAObjectItem
 311          * -derived object. We are just dealing here with the provider-specific
 312          * data which may have been attached to a #NAObjectItem -derived object.
 313          *
 314          * Returns: %NA_IIO_PROVIDER_CODE_OK if the duplicate operation was
 315          * successful, or another code depending of the detected error.
 316          *
 317          * Since: 2.30
 318          */
 319         guint    ( *duplicate_data )     ( const NAIIOProvider *instance, NAObjectItem *dest, const NAObjectItem *source, GSList **messages );
 320 }
 321         NAIIOProviderInterface;
 322
 323 GType na_iio_provider_get_type( void );
 324
 325 /* This function is to be called by the I/O provider when it detects
 326  * that an object has been modified in its underlying storage
 327  * subsystem. It eventually ends up by sending a messages to its
 328  * registered consumers.
 329  */
 330 void  na_iio_provider_item_changed ( const NAIIOProvider *instance );
 331
 332 /* Adding a new status here should imply also adding a new tooltip
 333  * in #na_io_provider_get_readonly_tooltip().
 334  */
 335 /**
 336  * NAIIOProviderWritabilityStatus:
 337  * @NA_IIO_PROVIDER_STATUS_WRITABLE:          item and i/o provider are writable.
 338  * @NA_IIO_PROVIDER_STATUS_UNAVAILABLE:       unavailable i/o provider.
 339  * @NA_IIO_PROVIDER_STATUS_INCOMPLETE_API:    i/o provider has an incomplete write api.
 340  * @NA_IIO_PROVIDER_STATUS_NOT_WILLING_TO:    i/o provider is not willing to write.
 341  * @NA_IIO_PROVIDER_STATUS_NOT_ABLE_TO:       i/o provider is not able to write.
 342  * @NA_IIO_PROVIDER_STATUS_LOCKED_BY_ADMIN:   i/o provider has been locked by the administrator.
 343  * @NA_IIO_PROVIDER_STATUS_LOCKED_BY_USER:    i/o provider has been locked by the user.
 344  * @NA_IIO_PROVIDER_STATUS_ITEM_READONLY:     item is read-only.
 345  * @NA_IIO_PROVIDER_STATUS_NO_PROVIDER_FOUND: no writable i/o provider found.
 346  * @NA_IIO_PROVIDER_STATUS_LEVEL_ZERO:        level zero is not writable.
 347  * @NA_IIO_PROVIDER_STATUS_UNDETERMINED:      unknwon reason (and probably a bug).
 348  *
 349  * The reasons for which an item may not be writable.
 350  */
 351 typedef enum {
 352         NA_IIO_PROVIDER_STATUS_WRITABLE = 0,
 353         NA_IIO_PROVIDER_STATUS_UNAVAILABLE,
 354         NA_IIO_PROVIDER_STATUS_INCOMPLETE_API,
 355         NA_IIO_PROVIDER_STATUS_NOT_WILLING_TO,
 356         NA_IIO_PROVIDER_STATUS_NOT_ABLE_TO,
 357         NA_IIO_PROVIDER_STATUS_LOCKED_BY_ADMIN,
 358         NA_IIO_PROVIDER_STATUS_LOCKED_BY_USER,
 359         NA_IIO_PROVIDER_STATUS_ITEM_READONLY,
 360         NA_IIO_PROVIDER_STATUS_NO_PROVIDER_FOUND,
 361         NA_IIO_PROVIDER_STATUS_LEVEL_ZERO,
 362         NA_IIO_PROVIDER_STATUS_UNDETERMINED,
 363         /*< private >*/
 364         NA_IIO_PROVIDER_STATUS_LAST,
 365 }
 366         NAIIOProviderWritabilityStatus;
 367
 368 /* adding a new code here should imply also adding a new label
 369  * in #na_io_provider_get_return_code_label().
 370  */
 371 /**
 372  * NAIIOProviderOperationStatus:
 373  * @NA_IIO_PROVIDER_CODE_OK:            the requested operation has been successful.
 374  * @NA_IIO_PROVIDER_CODE_PROGRAM_ERROR: a program error has been detected.
 375  *                                      You should open a bug in
 376  *                                      <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions">Bugzilla</ulink>.
 377  * @NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN:   the provider is not willing
 378  *                                             to do the requested action.
 379  * @NA_IIO_PROVIDER_CODE_WRITE_ERROR:          a write error has been detected.
 380  * @NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR: the schemas could not be deleted.
 381  * @NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR:  the configuration could not be deleted.
 382  *
 383  * The return code of operations.
 384  */
 385 typedef enum {
 386         NA_IIO_PROVIDER_CODE_OK = 0,
 387         NA_IIO_PROVIDER_CODE_PROGRAM_ERROR = 1 + NA_IIO_PROVIDER_STATUS_LAST,
 388         NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN,
 389         NA_IIO_PROVIDER_CODE_WRITE_ERROR,
 390         NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR,
 391         NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR,
 392 }
 393         NAIIOProviderOperationStatus;
 394
 395 G_END_DECLS
 396
 397 #endif /* __NAUTILUS_ACTIONS_API_NA_IIO_PROVIDER_H__ */