|  |  |  | Nautilus-Actions™ Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Prerequisites | ||||
#include <nautilus-actions/na-iexporter.h> #define NA_TYPE_IEXPORTER #define NA_IEXPORTER (instance) #define NA_IS_IEXPORTER (instance) #define NA_IEXPORTER_GET_INTERFACE (instance) NAIExporter; NAIExporterInterface; enum NAIExporterExportStatus; NAIExporterFormat; NAIExporterFormatv2; NAIExporterFileParms; NAIExporterFileParmsv2; NAIExporterBufferParms; NAIExporterBufferParmsv2;
The NAIExporter interface exports items to the outside world. Each implementation may provide one or more formats.
For its own internal needs, Nautilus-Actions™ requires that each export format have its own identifier, as an ASCII string.
In order to avoid any collision, this export format identifier is allocated by the Nautilus-Actions™ maintainers team. If you wish provide yourself a new export format, and so need a new export format identifier, please contact the maintainers (see nautilus-actions.doap at the root of the source tree).
Below is a list of currently allocated export format identifiers. This list has been last updated on 2010, July 28th.
Table 5. Currently allocated export format identifiers
| Identifier | Name | Holder | Allocated on | 
|---|---|---|---|
| Ask | Reserved for Nautilus-Actions™ internal needs | Nautilus-Actions™ | 2010-02-15 | 
| Desktop1 | NA Desktop module | Nautilus-Actions™ | 2010-07-28 | 
| GConfSchemaV1 | NA XML module | Nautilus-Actions™ | 2010-02-15 | 
| GConfSchemaV2 | NA XML module | Nautilus-Actions™ | 2010-02-15 | 
| GConfEntry | NA XML module | Nautilus-Actions™ | 2010-02-15 | 
Table 6. Historic of the versions of the NAIExporter interface
| Nautilus-Actions™ version | NAIExporter interface version | ||
|---|---|---|---|
| from 2.30 to 3.1.5 | 1 | deprecated | |
| since 3.2 | 2 | current version | 
#define NA_IEXPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IEXPORTER, NAIExporter ))
#define NA_IS_IEXPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IEXPORTER ))
#define NA_IEXPORTER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IEXPORTER, NAIExporterInterface ))
typedef struct {
	/**
	 * get_version:
	 * @instance: this NAIExporter instance.
	 *
	 * Nautilus-Actions calls this method each time it needs to know
	 * which version of this interface the plugin implements.
	 *
	 * If this method is not implemented by the plugin,
	 * Nautilus-Actions considers that the plugin only implements
	 * the version 1 of the NAIImporter interface.
	 *
	 * Return value: if implemented, this method must return the version
	 * number of this interface the I/O provider is supporting.
	 *
	 * Defaults to 1.
	 *
	 * Since: 2.30
	 */
	guint   ( *get_version )( const NAIExporter *instance );
	/**
	 * get_name:
	 * @instance: this NAIExporter instance.
	 *
	 * Return value: if implemented, the method should return the name to be
	 * displayed, as a newly allocated string which will be g_free() by the
	 * caller.
	 *
	 * This may be the name of the module itself, but this also may be a
	 * special name the modules gives to this interface.
	 *
	 * Defaults to a NULL string.
	 *
	 * Since: 2.30
	 */
	gchar * ( *get_name )   ( const NAIExporter *instance );
	/**
	 * get_formats:
	 * @instance: this NAIExporter instance.
	 *
	 * For its own internal needs, Nautilus-Actions requires each export
	 * format has its own unique identifier (in fact, just a small ASCII
	 * string).
	 *
	 * To avoid any collision, the format identifier is allocated by the
	 * Nautilus-Actions maintainers team. If you wish develop a new export
	 * format, and so need a new format identifier, please contact the
	 * maintainers (see nautilus-actions.doap).
	 *
	 * Return value:
	 * - Interface v1:
	 *   a null-terminated list of NAIExporterFormat structures
	 *   which describes the formats supported by this NAIExporter
	 *   provider.
	 *   The returned list is owned by the NAIExporter provider,
	 *   and should not be freed nor released by the caller.
	 *
	 * - Interface v2:
	 *   a GList of NAIExporterFormatv2 structures
	 *   which describes the formats supported by this NAIExporter
	 *   provider.
	 *   The caller should then invoke the free_formats() method
	 *   in order the provider be able to release the resources
	 *   allocated to the list.
	 *
	 * Defaults to NULL (no format at all).
	 *
	 * Since: 2.30
	 */
	void *  ( *get_formats )( const NAIExporter *instance );
	/**
	 * free_formats:
	 * @instance: this NAIExporter instance.
	 * @formats: a null-terminated list of NAIExporterFormatv2 structures,
	 *  as returned by get_formats() method above.
	 *
	 * Free the resources allocated to the @formats list.
	 *
	 * Since: 3.2
	 */
	void    ( *free_formats )( const NAIExporter *instance, GList *formats );
	/**
	 * to_file:
	 * @instance: this NAIExporter instance.
	 * @parms: a NAIExporterFileParmsv2 structure.
	 *
	 * Exports the specified 'exported' to the target 'folder' in the required
	 * 'format'.
	 *
	 * Return value: the NAIExporterExportStatus status of the operation.
	 *
	 * Since: 2.30
	 */
	guint   ( *to_file )    ( const NAIExporter *instance, NAIExporterFileParmsv2 *parms );
	/**
	 * to_buffer:
	 * @instance: this NAIExporter instance.
	 * @parms: a NAIExporterFileParmsv2 structure.
	 *
	 * Exports the specified 'exported' to a newly allocated 'buffer' in
	 * the required 'format'. The allocated 'buffer' will be g_free()
	 * by the caller.
	 *
	 * Return value: the NAIExporterExportStatus status of the operation.
	 *
	 * Since: 2.30
	 */
	guint   ( *to_buffer )  ( const NAIExporter *instance, NAIExporterBufferParmsv2 *parms );
} NAIExporterInterface;
This defines the interface that a NAIExporter should implement.
| [should] returns the version of this interface the plugin implements. | |
| [should] returns the public plugin name. | |
| [should] returns the list of supported formats. | |
| [should] free a list of formats | |
| [should] exports an item to a file. | |
| [should] exports an item to a buffer. | 
typedef enum {
	NA_IEXPORTER_CODE_OK = 0,
	NA_IEXPORTER_CODE_INVALID_ITEM,
	NA_IEXPORTER_CODE_INVALID_TARGET,
	NA_IEXPORTER_CODE_INVALID_FORMAT,
	NA_IEXPORTER_CODE_UNABLE_TO_WRITE,
	NA_IEXPORTER_CODE_ERROR,
} NAIExporterExportStatus;
The reasons for which an item may not have been exported
| export OK. | |
| exported item was found invalid. | |
| selected target was found invalid. | |
| asked format was found invalid. | |
| unable to write the item. | |
| other undetermined error. | 
typedef struct {
	gchar     *format;
	gchar     *label;
	gchar     *description;
} NAIExporterFormat;
NAIExporterFormat is deprecated and should not be used in newly-written code. 3.2
This structure describes a supported output format.
It must be provided by each NAIExporter implementation
(see e.g. src/io-xml/naxml-formats.c).
When listing available export formats, the instance returns a GList of these structures.
typedef struct {
	guint        version;
	NAIExporter *provider;
	gchar       *format;
	gchar       *label;
	gchar       *description;
	GdkPixbuf   *pixbuf;
} NAIExporterFormatv2;
This structure describes a supported output format.
It must be provided by each NAIExporter implementation
(see e.g. src/io-xml/naxml-formats.c).
When listing available export formats, the provider must return a GList
of these structures.
Table 7. Historic of the versions of the NAIExporterFormatv2 structure
| Nautilus-Actions™ version | NAIExporterFormatv2 structure version | |
|---|---|---|
| since 2.30 | 1 | |
| since 3.2 | 2 | current version | 
| guint  | the version of this NAIExporterFormatv2 structure; equals to 2; since structure version 1. | 
| NAIExporter * | the NAIExporter provider for this format; since structure version 2. | 
| gchar * | format identifier (ascii, allocated by the Nautilus-Actions team); since structure version 2. | 
| gchar * | short label to be displayed in dialog (UTF-8 localized); since structure version 2. | 
| gchar * | full description of the format (UTF-8 localized); mainly used as a tooltip; since structure version 2. | 
| GdkPixbuf * | an image to be associated with this export format; this pixbuf is supposed to be rendered with GTK_ICON_SIZE_DIALOG size; since structure version 2. | 
Since 3.2
typedef struct {
	guint         version;
	NAObjectItem *exported;
	gchar        *folder;
	GQuark        format;
	gchar        *basename;
	GSList       *messages;
} NAIExporterFileParms;
NAIExporterFileParms is deprecated and should not be used in newly-written code. 3.2
The structure that the implementation receives as a parameter of
NAIExporterInterface.to_file() interface method.
| guint  | [in] version of this structure; since structure version 1. | 
| NAObjectItem * | [in] exported NAObjectItem-derived object; since structure version 1. | 
| gchar * | [in] URI of the target folder; since structure version 1. | 
| GQuark  | [in] export format as a GQuark; since structure version 1. | 
| gchar * | [out] basename of the exported file; since structure version 1. | 
| GSList * | [in/out] a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it; since structure version 1. | 
typedef struct {
	guint         version;
	guint         content;
	NAObjectItem *exported;
	gchar        *folder;
	gchar        *format;
	gchar        *basename;
	GSList       *messages;
} NAIExporterFileParmsv2;
The structure that the plugin receives as a parameter of
NAIExporterInterface.to_file() interface method.
| guint  | [in] version of this structure; equals to 2; since structure version 1. | 
| guint  | [in] version of the content of this structure; equals to 1; since structure version 2. | 
| NAObjectItem * | [in] exported NAObjectItem-derived object; since structure version 1. | 
| gchar * | [in] URI of the target folder; since structure version 1. | 
| gchar * | [in] export format string identifier; since structure version 1. | 
| gchar * | [out] basename of the exported file; since structure version 1. | 
| GSList * | [in/out] a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it; since structure version 1. | 
Since 3.2
typedef struct {
	guint         version;
	NAObjectItem *exported;
	GQuark        format;
	gchar        *buffer;
	GSList       *messages;
} NAIExporterBufferParms;
NAIExporterBufferParms is deprecated and should not be used in newly-written code. 3.2
The structure that the plugin receives as a parameter of
NAIExporterInterface.to_buffer() interface method.
| guint  | [in] version of this structure; since structure version 1. | 
| NAObjectItem * | [in] exported NAObjectItem-derived object; since structure version 1. | 
| GQuark  | [in] export format as a GQuark; since structure version 1. | 
| gchar * | [out] buffer which contains the exported object; since structure version 1. | 
| GSList * | [in/out] a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it; since structure version 1. | 
typedef struct {
	guint         version;
	guint         content;
	NAObjectItem *exported;
	gchar        *format;
	gchar        *buffer;
	GSList       *messages;
} NAIExporterBufferParmsv2;
The structure that the plugin receives as a parameter of
NAIExporterInterface.to_buffer() interface method.
| guint  | [in] version of this structure; equals to 2; since structure version 1. | 
| guint  | [in] version of the content of this structure; equals to 1; since structure version 2. | 
| NAObjectItem * | [in] exported NAObjectItem-derived object; since structure version 1. | 
| gchar * | [in] export format string identifier; since structure version 2. | 
| gchar * | [out] buffer which contains the exported object; since structure version 1. | 
| GSList * | [in/out] a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it; since structure version 1. | 
Since 3.2