NAIExporter

NAIExporter — The Export Interface

Functions

Types and Values

Includes

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

Description

The NAIExporter interface exports items to the outside world. Each implementation may provide one or more formats.

Export format identifier

For its own internal needs, Caja-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 Caja-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 caja-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 Caja-Actions™ internal needs Caja-Actions 2010-02-15
Desktop1 NA Desktop module Caja-Actions 2010-07-28
MateConfSchemaV1 NA XML module Caja-Actions 2010-02-15
MateConfSchemaV2 NA XML module Caja-Actions 2010-02-15
MateConfEntry NA XML module Caja-Actions 2010-02-15


Versions historic

Table 6. Historic of the versions of the NAIExporter interface

Caja-Actions™ version NAIExporter interface version    
from 2.30 to 3.1.5 1   deprecated
since 3.2 2 current version  

Functions

NA_IEXPORTER()

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

NA_IS_IEXPORTER()

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

NA_IEXPORTER_GET_INTERFACE()

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

Types and Values

NA_TYPE_IEXPORTER

#define NA_TYPE_IEXPORTER                      ( na_iexporter_get_type())

NAIExporter

typedef struct _NAIExporter NAIExporter;

NAIExporterInterface

typedef struct {
	/**
	 * get_version:
	 * @instance: this NAIExporter instance.
	 *
	 * Caja-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,
	 * Caja-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, Caja-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
	 * Caja-Actions maintainers team. If you wish develop a new export
	 * format, and so need a new format identifier, please contact the
	 * maintainers (see caja-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.

Members

get_version ()

[should] returns the version of this interface the plugin implements.

 

get_name ()

[should] returns the public plugin name.

 

get_formats ()

[should] returns the list of supported formats.

 

free_formats ()

[should] free a list of formats

 

to_file ()

[should] exports an item to a file.

 

to_buffer ()

[should] exports an item to a buffer.

 

enum NAIExporterExportStatus

The reasons for which an item may not have been exported

Members

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;

NAIExporterFormat has been deprecated since version 3.2 and should not be used in newly-written code.

This structure describes a supported output format. It must be provided by each NAIExporter implementation (see e.g. src/io-xml/caxml-formats.c).

When listing available export formats, the instance returns a GList of these structures.

Members

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.

 

NAIExporterFormatv2

typedef struct {
	guint        version;
	NAIExporter *provider;
	gchar       *format;
	gchar       *label;
	gchar       *description;
	GdkPixbuf   *pixbuf;
} NAIExporterFormatv2;

NAIExporterFormatv2 is deprecated and should not be used in newly-written code.

This structure describes a supported output format. It must be provided by each NAIExporter implementation (see e.g. src/io-xml/caxml-formats.c).

When listing available export formats, the provider must return a GList of these structures.

Versions historic

Table 7. Historic of the versions of the NAIExporterFormatv2 structure

Caja-Actions™ version NAIExporterFormatv2 structure version  
since 2.30 1  
since 3.2 2 current version

Members

guint version;

the version of this NAIExporterFormatv2 structure; equals to 2; since structure version 1.

 

NAIExporter *provider;

the NAIExporter provider for this format; since structure version 2.

 

gchar *format;

format identifier (ascii, allocated by the Caja-Actions team); since structure version 2.

 

gchar *label;

short label to be displayed in dialog (UTF-8 localized); since structure version 2.

 

gchar *description;

full description of the format (UTF-8 localized); mainly used as a tooltip; since structure version 2.

 

GdkPixbuf *pixbuf;

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


NAIExporterFileParms

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

NAIExporterFileParms has been deprecated since version 3.2 and should not be used in newly-written code.

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

Members

guint version;

[in] version of this structure; since structure version 1.

 

NAObjectItem *exported;

[in] exported NAObjectItem-derived object; since structure version 1.

 

gchar *folder;

[in] URI of the target folder; since structure version 1.

 

GQuark format;

[in] export format as a GQuark; since structure version 1.

 

gchar *basename;

[out] basename of the exported file; since structure version 1.

 

GSList *messages;

[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.

 

NAIExporterFileParmsv2

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.

Members

guint version;

[in] version of this structure; equals to 2; since structure version 1.

 

guint content;

[in] version of the content of this structure; equals to 1; since structure version 2.

 

NAObjectItem *exported;

[in] exported NAObjectItem-derived object; since structure version 1.

 

gchar *folder;

[in] URI of the target folder; since structure version 1.

 

gchar *format;

[in] export format string identifier; since structure version 1.

 

gchar *basename;

[out] basename of the exported file; since structure version 1.

 

GSList *messages;

[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


NAIExporterBufferParms

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

NAIExporterBufferParms has been deprecated since version 3.2 and should not be used in newly-written code.

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

Members

guint version;

[in] version of this structure; since structure version 1.

 

NAObjectItem *exported;

[in] exported NAObjectItem-derived object; since structure version 1.

 

GQuark format;

[in] export format as a GQuark; since structure version 1.

 

gchar *buffer;

[out] buffer which contains the exported object; since structure version 1.

 

GSList *messages;

[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.

 

NAIExporterBufferParmsv2

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.

Members

guint version;

[in] version of this structure; equals to 2; since structure version 1.

 

guint content;

[in] version of the content of this structure; equals to 1; since structure version 2.

 

NAObjectItem *exported;

[in] exported NAObjectItem-derived object; since structure version 1.

 

gchar *format;

[in] export format string identifier; since structure version 2.

 

gchar *buffer;

[out] buffer which contains the exported object; since structure version 1.

 

GSList *messages;

[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