3 * A Nautilus extension which offers configurable context menu actions.
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)
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.
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.
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.
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)
31 #ifndef __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__
32 #define __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__
37 * @short_description: The Export Interface v 1
38 * @include: nautilus-actions/na-iexporter.h
40 * The #NAIExporter interface exports items to the outside world.
43 * <title>Versions historic</title>
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" />
52 * <entry>&prodname; version</entry>
53 * <entry>#NAIExporter interface version</entry>
59 * <entry>since 2.30</entry>
61 * <entry>current version</entry>
69 #include "na-object-item.h"
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 ))
78 typedef struct _NAIExporter NAIExporter
;
79 typedef struct _NAIExporterInterfacePrivate NAIExporterInterfacePrivate
;
80 typedef struct _NAIExporterFileParms NAIExporterFileParms
;
81 typedef struct _NAIExporterBufferParms NAIExporterBufferParms
;
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.
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>).
94 * When listing available export formats, the instance returns a #GList
95 * of these structures.
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.
112 * This defines the interface that a #NAIExporter should implement.
116 GTypeInterface parent
;
117 NAIExporterInterfacePrivate
*private;
122 * @instance: this #NAIExporter instance.
124 * Returns: the version of this interface supported by the I/O provider.
130 guint ( *get_version
)( const NAIExporter
*instance
);
134 * @instance: this #NAIExporter instance.
136 * Returns: the name to be displayed for this instance, as a
137 * newly allocated string which should be g_free() by the caller.
141 gchar
* ( *get_name
) ( const NAIExporter
*instance
);
145 * @instance: this #NAIExporter instance.
147 * The returned list is owned by the @instance. It must not be
148 * released by the caller.
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).
155 * Returns: a list of #NAIExporterFormat structures which describe the
156 * formats supported by @instance.
158 * Defaults to %NULL (no format at all).
162 const NAIExporterFormat
* ( *get_formats
)( const NAIExporter
*instance
);
166 * @instance: this #NAIExporter instance.
167 * @parms: a #NAIExporterFileParms structure.
169 * Exports the specified 'exported' to the target 'folder' in the required
172 * Returns: the #NAIExporterExportStatus status of the operation.
176 guint ( *to_file
) ( const NAIExporter
*instance
, NAIExporterFileParms
*parms
);
180 * @instance: this #NAIExporter instance.
181 * @parms: a #NAIExporterFileParms structure.
183 * Exports the specified 'exported' to a newly allocated 'buffer' in
184 * the required 'format'. The allocated 'buffer' should be g_free()
187 * Returns: the #NAIExporterExportStatus status of the operation.
191 guint ( *to_buffer
) ( const NAIExporter
*instance
, NAIExporterBufferParms
*parms
);
193 NAIExporterInterface
;
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.
204 * The reasons for which an item may not have been exported
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
,
214 NAIExporterExportStatus
;
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).
228 * The structure that the plugin receives as a parameter of
229 * #NAIExporterInterface.to_file () interface method.
231 struct _NAIExporterFileParms
{
233 NAObjectItem
*exported
;
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).
251 * The structure that the plugin receives as a parameter of
252 * #NAIExporterInterface.to_buffer () interface method.
254 struct _NAIExporterBufferParms
{
256 NAObjectItem
*exported
;
262 GType
na_iexporter_get_type( void );
266 #endif /* __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__ */