NAIExporter

NAIExporter — The Export Interface v 1

Synopsis

#include <nautilus-actions/na-iexporter.h>

#define             NA_IEXPORTER_TYPE
#define             NA_IEXPORTER                        (instance)
#define             NA_IS_IEXPORTER                     (instance)
#define             NA_IEXPORTER_GET_INTERFACE          (instance)
                    NAIExporter;
                    NAIExporterInterface;
enum                NAIExporterExportStatus;
                    NAIExporterFormat;
struct              NAIExporterFileParms;
struct              NAIExporterBufferParms;

Object Hierarchy

  GInterface
   +----NAIExporter

Prerequisites

NAIExporter requires GObject.

Description

The NAIExporter interface exports items to the outside world.

Versions historic

Table 4. Historic of the versions of the NAIExporter interface

Nautilus-Actions™ version NAIExporter interface version  
since 2.30 1 current version

Details

NA_IEXPORTER_TYPE

#define NA_IEXPORTER_TYPE                       ( na_iexporter_get_type())

NA_IEXPORTER()

#define NA_IEXPORTER( instance )                ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IEXPORTER_TYPE, NAIExporter ))

NA_IS_IEXPORTER()

#define NA_IS_IEXPORTER( instance )             ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IEXPORTER_TYPE ))

NA_IEXPORTER_GET_INTERFACE()

#define NA_IEXPORTER_GET_INTERFACE( instance )  ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IEXPORTER_TYPE, NAIExporterInterface ))

NAIExporter

typedef struct _NAIExporter NAIExporter;

NAIExporterInterface

typedef struct {
	/**
	 * get_version:
	 * @instance: this #NAIExporter instance.
	 *
	 * Returns: the version of this interface supported by the I/O provider.
	 *
	 * Defaults to 1.
	 *
	 * Since: 2.30
	 */
	guint                     ( *get_version )( const NAIExporter *instance );

	/**
	 * get_name:
	 * @instance: this #NAIExporter instance.
	 *
	 * Returns: the name to be displayed for this instance, as a
	 * newly allocated string which should be g_free() by the caller.
	 *
	 * Since: 2.30
	 */
	gchar *                   ( *get_name )   ( const NAIExporter *instance );

	/**
	 * get_formats:
	 * @instance: this #NAIExporter instance.
	 *
	 * The returned list is owned by the @instance. It must not be
	 * released by the caller.
	 *
	 * To avoid any collision, the format id is allocated by the
	 * Nautilus-Actions maintainer team. If you wish develop a new
	 * export format, and so need a new format id, please contact the
	 * maintainers (see #nautilus-actions.doap).
	 *
	 * Returns: a list of #NAIExporterFormat structures which describe the
	 * formats supported by @instance.
	 *
	 * Defaults to %NULL (no format at all).
	 *
	 * Since: 2.30
	 */
	const NAIExporterFormat * ( *get_formats )( const NAIExporter *instance );

	/**
	 * to_file:
	 * @instance: this #NAIExporter instance.
	 * @parms: a #NAIExporterFileParms structure.
	 *
	 * Exports the specified 'exported' to the target 'folder' in the required
	 * 'format'.
	 *
	 * Returns: the #NAIExporterExportStatus status of the operation.
	 *
	 * Since: 2.30
	 */
	guint                     ( *to_file )    ( const NAIExporter *instance, NAIExporterFileParms *parms );

	/**
	 * to_buffer:
	 * @instance: this #NAIExporter instance.
	 * @parms: a #NAIExporterFileParms structure.
	 *
	 * Exports the specified 'exported' to a newly allocated 'buffer' in
	 * the required 'format'. The allocated 'buffer' should be g_free()
	 * by the caller.
	 *
	 * Returns: the #NAIExporterExportStatus status of the operation.
	 *
	 * Since: 2.30
	 */
	guint                     ( *to_buffer )  ( const NAIExporter *instance, NAIExporterBufferParms *parms );
} NAIExporterInterface;

This defines the interface that a NAIExporter should implement.

get_version ()

returns the version of this interface the plugin implements.

get_name ()

returns the public plugin name.

get_formats ()

returns the list of supported formats.

to_file ()

exports an item to a file.

to_buffer ()

exports an item to a buffer.

enum NAIExporterExportStatus

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

NA_IEXPORTER_CODE_OK

export OK.

NA_IEXPORTER_CODE_INVALID_ITEM

exported item was found invalid.

NA_IEXPORTER_CODE_INVALID_TARGET

selected target was found invalid.

NA_IEXPORTER_CODE_INVALID_FORMAT

asked format was found invalid.

NA_IEXPORTER_CODE_UNABLE_TO_WRITE

unable to write the item.

NA_IEXPORTER_CODE_ERROR

other undetermined error.

NAIExporterFormat

typedef struct {
	gchar *format;
	gchar *label;
	gchar *description;
} NAIExporterFormat;

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.

gchar *format;

format identifier (ascii).

gchar *label;

short label to be displayed in dialog (UTF-8 localized)

gchar *description;

full description of the format (UTF-8 localized); mainly used in the export assistant.

struct NAIExporterFileParms

struct NAIExporterFileParms {
	guint         version;
	NAObjectItem *exported;
	gchar        *folder;
	GQuark        format;
	gchar        *basename;
	GSList       *messages;
};

The structure that the plugin receives as a parameter of NAIExporterInterface.to_file() interface method.

guint version;

version of this structure (input, since v 1)

NAObjectItem *exported;

exported NAObjectItem-derived object (input, since v 1)

gchar *folder;

URI of the target folder (input, since v 1)

GQuark format;

export format as a GQuark (input, since v 1)

gchar *basename;

basename of the exported file (output, since v 1)

GSList *messages;

a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it (input/output, since v 1).

struct NAIExporterBufferParms

struct NAIExporterBufferParms {
	guint         version;
	NAObjectItem *exported;
	GQuark        format;
	gchar        *buffer;
	GSList       *messages;
};

The structure that the plugin receives as a parameter of NAIExporterInterface.to_buffer() interface method.

guint version;

version of this structure (input, since v 1)

NAObjectItem *exported;

exported NAObjectItem-derived object (input, since v 1)

GQuark format;

export format as a GQuark (input, since v 1)

gchar *buffer;

buffer which contains the exported object (output, since v 1)

GSList *messages;

a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it (input/output, since v 1).