NAIExporter

## NAIExporter NAIExporter — The Export Interface |

## Synopsis

    #include <caja-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;

## Object Hierarchy

      GInterface
       +----NAIExporter

## Prerequisites

NAIExporter requires GObject.

## 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 |

## Details

### NA_TYPE_IEXPORTER

    #define NA_TYPE_IEXPORTER                      ( na_iexporter_get_type())

### 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 ))

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

`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

    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;

### Warning

`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/caxml-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.

### NAIExporterFormatv2

    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/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

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;

### Warning

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

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;

### Warning

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

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