NAIImporter

## NAIImporter NAIImporter — The Import Interface |

## Synopsis

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

    #define             NA_TYPE_IIMPORTER
    #define             NA_IIMPORTER                        (instance)
    #define             NA_IS_IIMPORTER                     (instance)
    #define             NA_IIMPORTER_GET_INTERFACE          (instance)
                        NAIImporter;
                        NAIImporterInterface;
    enum                NAIImporterImportMode;
    enum                NAIImporterImportStatus;
    guint               NAIImporterAskUserFn                (const NAObjectItem *imported,
                                                             const NAObjectItem *existing,
                                                             void *fn_data);
    NAObjectItem *      NAIImporterCheckFn                  (const NAObjectItem *imported,
                                                             void *fn_data);
                        NAIImporterImportFromUriParms;
                        NAIImporterImportFromUriParmsv2;
                        NAIImporterManageImportModeParms;
    guint               na_iimporter_import_from_uri        (const NAIImporter *importer,
                                                             NAIImporterImportFromUriParmsv2 *parms);
    guint               na_iimporter_manage_import_mode     (NAIImporterManageImportModeParms *parms);

## Object Hierarchy

      GInterface
       +----NAIImporter

## Prerequisites

NAIImporter requires GObject.

## Description

The NAIImporter interface imports items from the outside world into Caja-Actions™ repository (see NAIIOProvider interface for how these items will be later managed to be store somewhere).

In version 1 of the NAIImporter interface, Caja-Actions™ used to provide the implementation with all was needed to be able to manage the import process up to be ready for insertion, including the deduplication if required.

This used to put on the implementation the responsability to check for the unicity of the imported identifier, maybe asking the caller (via provided callback functions) what to do with it, maybe reallocating a new identifier, and so on...

Starting with Caja-Actions™ version 3.2, this interface is bumped to a version 2 which greatly simplifies it.

The I/O provider which implements the NAIImporter interface is no more required to check for existence of the imported items, but this check is pushed back to the caller responsability.

Rationale is that only the caller is able to check against a valid repository in its current import context, while the NAIImporter provider should only be responsible to import an item in memory.

### Versions historic

Table 4. Historic of the versions of the NAIImporter interface

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

## Details

### NA_TYPE_IIMPORTER

    #define NA_TYPE_IIMPORTER                      ( na_iimporter_get_type())

### NA_IIMPORTER()

    #define NA_IIMPORTER( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IIMPORTER, NAIImporter ))

### NA_IS_IIMPORTER()

    #define NA_IS_IIMPORTER( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IIMPORTER ))

### NA_IIMPORTER_GET_INTERFACE()

    #define NA_IIMPORTER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IIMPORTER, NAIImporterInterface ))

### NAIImporter

    typedef struct _NAIImporter NAIImporter;

### NAIImporterInterface

    typedef struct {
    	/**
    	 * get_version:
    	 * @instance: the NAIImporter provider.
    	 *
    	 * 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 NAIImporter *instance );

    	/**
    	 * import_from_uri:
    	 * @instance: the NAIImporter provider.
    	 * @parms: a NAIImporterImportFromUriParms structure.
    	 *
    	 * Imports an item.
    	 *
    	 * If the provider implements the version 1 of this interface, then
    	 * @parms is supposed to map to NAIImporterImportFromUriParms structure.
    	 *
    	 * Contrarily, if the provider implements the version 2 of the interface,
    	 * then @parms is supposed to map to a NAIImporterImportFromUriParmsv2
    	 * structure.
    	 *
    	 * Return value: the return code of the operation.
    	 *
    	 * Since: 2.30
    	 */
    	guint ( *import_from_uri )( const NAIImporter *instance, void *parms );
    } NAIImporterInterface;

This defines the interface that a NAIImporter should implement.

`get_version` () | [should] returns the version of this interface that the plugin implements.
`import_from_uri` () | [should] imports an item.

### enum NAIImporterImportMode

    typedef enum {
    	IMPORTER_MODE_NO_IMPORT = 1,
    	IMPORTER_MODE_RENUMBER,
    	IMPORTER_MODE_OVERRIDE,
    	IMPORTER_MODE_ASK
    } NAIImporterImportMode;

### Warning

`NAIImporterImportMode` is deprecated and should not be used in newly-written code. 3.2

Define the mode of an import operation.

`IMPORTER_MODE_NO_IMPORT` | a "do not import" mode.
`IMPORTER_MODE_RENUMBER` | reallocate a new id when the imported one already exists.
`IMPORTER_MODE_OVERRIDE` | override the existing id with the imported one.
`IMPORTER_MODE_ASK` | ask the user for what to do with this particular item.

### enum NAIImporterImportStatus

    typedef enum {
    	IMPORTER_CODE_OK = 0,
    	IMPORTER_CODE_PROGRAM_ERROR,
    	IMPORTER_CODE_NOT_WILLING_TO,
    	IMPORTER_CODE_NO_ITEM_ID,
    	IMPORTER_CODE_NO_ITEM_TYPE,
    	IMPORTER_CODE_UNKNOWN_ITEM_TYPE,
    	IMPORTER_CODE_CANCELLED,
    	IMPORTER_CODE_NOT_LOADABLE
    } NAIImporterImportStatus;

Define the return status of an import operation.

`IMPORTER_CODE_OK` | import ok.
`IMPORTER_CODE_PROGRAM_ERROR` | a program error has been detected. You should open a bug in Bugzilla.
`IMPORTER_CODE_NOT_WILLING_TO` | the plugin is not willing to import the uri.
`IMPORTER_CODE_NO_ITEM_ID` | item id not found.
`IMPORTER_CODE_NO_ITEM_TYPE` | item type not found.
`IMPORTER_CODE_UNKNOWN_ITEM_TYPE` | unknown item type.
`IMPORTER_CODE_CANCELLED` | operation cancelled by the user.
`IMPORTER_CODE_NOT_LOADABLE` | the file is considered as not loadable at all. This is not a matter of which I/O provider has been tried, but the file is empty, or too big, or eventually not a regular file.

### NAIImporterAskUserFn ()

    guint               NAIImporterAskUserFn                (const NAObjectItem *imported,
                                                             const NAObjectItem *existing,
                                                             void *fn_data);

### Warning

`NAIImporterAskUserFn` is deprecated and should not be used in newly-written code. 3.2

In version 1 of the interface, this function may be provided by the caller as a convenience way for the NAIImporter to ask the user to know what to do in the case of a duplicate id.

If this function is not provided, and the NAIImporter does not have any other way to ask the user, then a 'no import' policy should be preferred when managing duplicate identifiers.

`imported` : | the currently imported NAObjectItem.
`existing` : | an already existing NAObjectItem with same id.
`fn_data` : | some data to be passed to the function.
Returns : | the import mode chosen by the user, which must not be `IMPORTER_MODE_ASK`.

Since 2.30

### NAIImporterCheckFn ()

    NAObjectItem *      NAIImporterCheckFn                  (const NAObjectItem *imported,
                                                             void *fn_data);

### Warning

`NAIImporterCheckFn` is deprecated and should not be used in newly-written code. 3.2

In version 1 of the interface, this function may be provided by the caller in order the NAIImporter provider be able to check for pre-existence of the imported item. This function should return the already existing item which has the same id than the currently being imported one, or `NULL` if the imported id will be unique.

If this function is not provided, then the NAIImporter provider will not be able to check for duplicates. In this case, the id of the imported item should be systematically regenerated as a unique id, regardless of the asked import mode.

Standard N-A callers provide a function which checks for the existance of the newly imported item :

- first among the current list of just imported items

- and then amon the items currently visible in the main window.

Items which may have been loaded by NAPivot at the start of the application, and deleted meanwhile, are just ignored.

`imported` : | the currently imported NAObjectItem -derived object.
`fn_data` : | some data to be passed to the function.
Returns : | the already existing NAObjectItem with same id, or `NULL`.

Since 2.30

### NAIImporterImportFromUriParms

    typedef struct {
    	guint                version;
    	gchar               *uri;
    	guint                asked_mode;
    	gboolean             exist;
    	guint                import_mode;
    	NAObjectItem        *imported;
    	NAIImporterCheckFn   check_fn;
    	void                *check_fn_data;
    	NAIImporterAskUserFn ask_fn;
    	void                *ask_fn_data;
    	GSList              *messages;
    } NAIImporterImportFromUriParms;

### Warning

`NAIImporterImportFromUriParms` is deprecated and should not be used in newly-written code. 3.2

This structure allows all used parameters when importing from an URI to be passed and received through a single structure.

guint `version`; | [in] the version of this structure; since structure version 1.
gchar *`uri`; | [in] uri of the file to be imported; since structure version 1.
guint `asked_mode`; | [in] asked import mode; since structure version 1.
gboolean `exist`; | [out] whether the imported Id already existed; since structure version 1.
guint `import_mode`; | [out] actually used import mode; since structure version 1.
NAObjectItem *`imported`; | [out] the imported NAObjectItem -derived object, or `NULL`; since structure version 1.
NAIImporterCheckFn `check_fn`; | [in] a `NAIImporterCheckFn()` function to check the existence of the imported id; since structure version 1.
void *`check_fn_data`; | [in] `check_fn` data; since structure version 1.
NAIImporterAskUserFn `ask_fn`; | [in] a `NAIImporterAskUserFn()` function to ask the user what to do in case of a duplicate id; since structure version 1.
void *`ask_fn_data`; | [in] `ask_fn` data; 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 2.30

### NAIImporterImportFromUriParmsv2

    typedef struct {
    	guint         version;
    	guint         content;
    	const gchar  *uri;
    	NAObjectItem *imported;
    	GSList       *messages;
    } NAIImporterImportFromUriParmsv2;

This structure allows all used parameters when importing from an URI to be passed and received through a single structure.

guint `version`; | [in] the version of the structure, equals to 2; since structure version 1.
guint `content`; | [in] the version of the description content, equals to 1; since structure version 2.
const gchar *`uri`; | [in] uri of the file to be imported; since structure version 1.
NAObjectItem *`imported`; | [out] the imported NAObjectItem -derived object, or `NULL`; 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

### NAIImporterManageImportModeParms

    typedef struct {
    	guint                version;
    	NAObjectItem        *imported;
    	guint                asked_mode;
    	NAIImporterCheckFn   check_fn;
    	void                *check_fn_data;
    	NAIImporterAskUserFn ask_fn;
    	void                *ask_fn_data;
    	gboolean             exist;
    	guint                import_mode;
    	GSList              *messages;
    } NAIImporterManageImportModeParms;

### Warning

`NAIImporterManageImportModeParms` is deprecated and should not be used in newly-written code. 3.2

This structure allows all used parameters when managing the import mode to be passed and received through a single structure.

guint `version`; | [in] the version of the structure content, equals to 1; since structure version 1.
NAObjectItem *`imported`; | [in] the imported NAObjectItem -derived object; since structure version 1.
guint `asked_mode`; | [in] asked import mode; since structure version 1.
NAIImporterCheckFn `check_fn`; | [in] a NAIImporterCheckFn function to check the existence of the imported id; since structure version 1.
void *`check_fn_data`; | [in] `check_fn` data; since structure version 1.
NAIImporterAskUserFn `ask_fn`; | [in] a NAIImporterAskUserFn function to ask the user what to do in case of a duplicate id; since structure version 1.
void *`ask_fn_data`; | [in] `ask_fn` data; since structure version 1.
gboolean `exist`; | [out] whether the imported Id already existed; since structure version 1.
guint `import_mode`; | [out] actually used import mode; 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 2.30

### na_iimporter_import_from_uri ()

    guint               na_iimporter_import_from_uri        (const NAIImporter *importer,
                                                             NAIImporterImportFromUriParmsv2 *parms);

Tries to import a NAObjectItem from the URI specified in `parms`, returning the result in ``parms->imported``.

Note that, starting with Caja-Actions™ 3.2, the `parms` argument is no more a NAIImporterImportFromUriParms pointer, but a NAIImporterImportFromUriParmsv2 one.

`importer` : | this NAIImporter instance.
`parms` : | a NAIImporterImportFromUriParmsv2 structure.
Returns : | the return code of the operation.

Since 2.30

### na_iimporter_manage_import_mode ()

    guint               na_iimporter_manage_import_mode     (NAIImporterManageImportModeParms *parms);

### Warning

`na_iimporter_manage_import_mode` is deprecated and should not be used in newly-written code. 3.2

`parms` : | a NAIImporterManageImportModeParms struct.
Returns : | the NAIImporterImportStatus status of the operation: IMPORTER_CODE_OK if we can safely insert the action: the id doesn't already exist or the id already exists, but import mode is renumber or the id already exists, but import mode is override IMPORTER_CODE_CANCELLED if user chooses to cancel the operation

Since 2.30