src/api/na-iexporter.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_IEXPORTER_H__
  32 #define __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__
  33
  34 /**
  35  * SECTION: iexporter
  36  * @title: NAIExporter
  37  * @short_description: The Export Interface v 1
  38  * @include: nautilus-actions/na-iexporter.h
  39  *
  40  * The #NAIExporter interface exports items to the outside world.
  41  *
  42  * <refsect2>
  43  *  <title>Versions historic</title>
  44  *  <table>
  45  *    <title>Historic of the versions of the #NAIExporter interface</title>
  46  *    <tgroup rowsep="1" colsep="1" align="center" cols="3">
  47  *      <colspec colname="na-version" />
  48  *      <colspec colname="api-version" />
  49  *      <colspec colname="current" />
  50  *      <thead>
  51  *        <row>
  52  *          <entry>&prodname; version</entry>
  53  *          <entry>#NAIExporter interface version</entry>
  54  *          <entry></entry>
  55  *        </row>
  56  *      </thead>
  57  *      <tbody>
  58  *        <row>
  59  *          <entry>since 2.30</entry>
  60  *          <entry>1</entry>
  61  *          <entry>current version</entry>
  62  *        </row>
  63  *      </tbody>
  64  *    </tgroup>
  65  *  </table>
  66  * </refsect2>
  67  */
  68
  69 #include "na-object-item.h"
  70
  71 G_BEGIN_DECLS
  72
  73 #define NA_IEXPORTER_TYPE                      ( na_iexporter_get_type())
  74 #define NA_IEXPORTER( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IEXPORTER_TYPE, NAIExporter ))
  75 #define NA_IS_IEXPORTER( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IEXPORTER_TYPE ))
  76 #define NA_IEXPORTER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IEXPORTER_TYPE, NAIExporterInterface ))
  77
  78 typedef struct _NAIExporter                    NAIExporter;
  79 typedef struct _NAIExporterInterfacePrivate    NAIExporterInterfacePrivate;
  80 typedef struct _NAIExporterFileParms           NAIExporterFileParms;
  81 typedef struct _NAIExporterBufferParms         NAIExporterBufferParms;
  82
  83 /**
  84  * NAIExporterFormat:
  85  * @format:      format identifier (ascii).
  86  * @label:       short label to be displayed in dialog (UTF-8 localized)
  87  * @description: full description of the format (UTF-8 localized);
  88  *               mainly used in the export assistant.
  89  *
  90  * This structure describes a supported output format.
  91  * It must be provided by each #NAIExporter implementation
  92  * (see e.g. <filename>src/io-xml/naxml-formats.c</filename>).
  93  *
  94  * When listing available export formats, the instance returns a #GList
  95  * of these structures.
  96  */
  97 typedef struct {
  98         gchar *format;
  99         gchar *label;
 100         gchar *description;
 101 }
 102         NAIExporterFormat;
 103
 104 /**
 105  * NAIExporterInterface:
 106  * @get_version: returns the version of this interface the plugin implements.
 107  * @get_name:    returns the public plugin name.
 108  * @get_formats: returns the list of supported formats.
 109  * @to_file:     exports an item to a file.
 110  * @to_buffer:   exports an item to a buffer.
 111  *
 112  * This defines the interface that a #NAIExporter should implement.
 113  */
 114 typedef struct {
 115         /*< private >*/
 116         GTypeInterface               parent;
 117         NAIExporterInterfacePrivate *private;
 118
 119         /*< public >*/
 120         /**
 121          * get_version:
 122          * @instance: this #NAIExporter instance.
 123          *
 124          * Returns: the version of this interface supported by the I/O provider.
 125          *
 126          * Defaults to 1.
 127          *
 128          * Since: 2.30
 129          */
 130         guint                     ( *get_version )( const NAIExporter *instance );
 131
 132         /**
 133          * get_name:
 134          * @instance: this #NAIExporter instance.
 135          *
 136          * Returns: the name to be displayed for this instance, as a
 137          * newly allocated string which should be g_free() by the caller.
 138          *
 139          * Since: 2.30
 140          */
 141         gchar *                   ( *get_name )   ( const NAIExporter *instance );
 142
 143         /**
 144          * get_formats:
 145          * @instance: this #NAIExporter instance.
 146          *
 147          * The returned list is owned by the @instance. It must not be
 148          * released by the caller.
 149          *
 150          * To avoid any collision, the format id is allocated by the
 151          * Nautilus-Actions maintainer team. If you wish develop a new
 152          * export format, and so need a new format id, please contact the
 153          * maintainers (see #nautilus-actions.doap).
 154          *
 155          * Returns: a list of #NAIExporterFormat structures which describe the
 156          * formats supported by @instance.
 157          *
 158          * Defaults to %NULL (no format at all).
 159          *
 160          * Since: 2.30
 161          */
 162         const NAIExporterFormat * ( *get_formats )( const NAIExporter *instance );
 163
 164         /**
 165          * to_file:
 166          * @instance: this #NAIExporter instance.
 167          * @parms: a #NAIExporterFileParms structure.
 168          *
 169          * Exports the specified 'exported' to the target 'folder' in the required
 170          * 'format'.
 171          *
 172          * Returns: the #NAIExporterExportStatus status of the operation.
 173          *
 174          * Since: 2.30
 175          */
 176         guint                     ( *to_file )    ( const NAIExporter *instance, NAIExporterFileParms *parms );
 177
 178         /**
 179          * to_buffer:
 180          * @instance: this #NAIExporter instance.
 181          * @parms: a #NAIExporterFileParms structure.
 182          *
 183          * Exports the specified 'exported' to a newly allocated 'buffer' in
 184          * the required 'format'. The allocated 'buffer' should be g_free()
 185          * by the caller.
 186          *
 187          * Returns: the #NAIExporterExportStatus status of the operation.
 188          *
 189          * Since: 2.30
 190          */
 191         guint                     ( *to_buffer )  ( const NAIExporter *instance, NAIExporterBufferParms *parms );
 192 }
 193         NAIExporterInterface;
 194
 195 /**
 196  * NAIExporterExportStatus:
 197  * @NA_IEXPORTER_CODE_OK:              export OK.
 198  * @NA_IEXPORTER_CODE_INVALID_ITEM:    exported item was found invalid.
 199  * @NA_IEXPORTER_CODE_INVALID_TARGET:  selected target was found invalid.
 200  * @NA_IEXPORTER_CODE_INVALID_FORMAT:  asked format was found invalid.
 201  * @NA_IEXPORTER_CODE_UNABLE_TO_WRITE: unable to write the item.
 202  * @NA_IEXPORTER_CODE_ERROR:           other undetermined error.
 203  *
 204  * The reasons for which an item may not have been exported
 205  */
 206 typedef enum {
 207         NA_IEXPORTER_CODE_OK = 0,
 208         NA_IEXPORTER_CODE_INVALID_ITEM,
 209         NA_IEXPORTER_CODE_INVALID_TARGET,
 210         NA_IEXPORTER_CODE_INVALID_FORMAT,
 211         NA_IEXPORTER_CODE_UNABLE_TO_WRITE,
 212         NA_IEXPORTER_CODE_ERROR,
 213 }
 214         NAIExporterExportStatus;
 215
 216 /**
 217  * NAIExporterFileParms:
 218  * @version:  version of this structure (input, since v 1)
 219  * @exported: exported NAObjectItem-derived object (input, since v 1)
 220  * @folder:   URI of the target folder (input, since v 1)
 221  * @format:   export format as a GQuark (input, since v 1)
 222  * @basename: basename of the exported file (output, since v 1)
 223  * @messages: a #GSList list of localized strings;
 224  *            the provider may append messages to this list,
 225  *            but shouldn't reinitialize it
 226  *            (input/output, since v 1).
 227  *
 228  * The structure that the plugin receives as a parameter of
 229  * #NAIExporterInterface.to_file () interface method.
 230  */
 231 struct _NAIExporterFileParms {
 232         guint         version;
 233         NAObjectItem *exported;
 234         gchar        *folder;
 235         GQuark        format;
 236         gchar        *basename;
 237         GSList       *messages;
 238 };
 239
 240 /**
 241  * NAIExporterBufferParms:
 242  * @version:  version of this structure (input, since v 1)
 243  * @exported: exported NAObjectItem-derived object (input, since v 1)
 244  * @format:   export format as a GQuark (input, since v 1)
 245  * @buffer:   buffer which contains the exported object (output, since v 1)
 246  * @messages: a #GSList list of localized strings;
 247  *            the provider may append messages to this list,
 248  *            but shouldn't reinitialize it
 249  *            (input/output, since v 1).
 250  *
 251  * The structure that the plugin receives as a parameter of
 252  * #NAIExporterInterface.to_buffer () interface method.
 253  */
 254 struct _NAIExporterBufferParms {
 255         guint         version;
 256         NAObjectItem *exported;
 257         GQuark        format;
 258         gchar        *buffer;
 259         GSList       *messages;
 260 };
 261
 262 GType na_iexporter_get_type( void );
 263
 264 G_END_DECLS
 265
 266 #endif /* __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__ */