## FMAIImporter FMAIImporter — The Import Interface |

## Functions

#define | FMA_IIMPORTER()
#define | FMA_IS_IIMPORTER()
#define | FMA_IIMPORTER_GET_INTERFACE()
guint | FMAIImporterAskUserFn ()
FMAObjectItem * | FMAIImporterCheckFn ()
guint | fma_iimporter_import_from_uri ()
guint | fma_iimporter_manage_import_mode ()

## Types and Values

#define | FMA_TYPE_IIMPORTER
| FMAIImporter
| FMAIImporterInterface
enum | FMAIImporterImportMode
enum | FMAIImporterImportStatus
| FMAIImporterImportFromUriParms
| FMAIImporterImportFromUriParmsv2
| FMAIImporterManageImportModeParms

## Includes

    #include <filemanager-actions/fma-iimporter.h>

## Description

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

In version 1 of the FMAIImporter interface, FileManager-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 FileManager-Actions™ version 3.2, this interface is bumped to a version 2 which greatly simplifies it.

The I/O provider which implements the FMAIImporter 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 FMAIImporter provider should only be responsible to import an item in memory.

### Versions historic

Table 4. Historic of the versions of the FMAIImporter interface

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

## Functions

### FMA_IIMPORTER()

    #define FMA_IIMPORTER( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, FMA_TYPE_IIMPORTER, FMAIImporter ))

### FMA_IS_IIMPORTER()

    #define FMA_IS_IIMPORTER( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, FMA_TYPE_IIMPORTER ))

### FMA_IIMPORTER_GET_INTERFACE()

    #define FMA_IIMPORTER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), FMA_TYPE_IIMPORTER, FMAIImporterInterface ))

### FMAIImporterAskUserFn ()

    guint
    FMAIImporterAskUserFn (const FMAObjectItem *imported,
                           const FMAObjectItem *existing,
                           void *fn_data);

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

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

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

#### Parameters

imported | the currently imported FMAObjectItem. |
existing | an already existing FMAObjectItem 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

### FMAIImporterCheckFn ()

    FMAObjectItem *
    FMAIImporterCheckFn (const FMAObjectItem *imported,
                         void *fn_data);

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

In version 1 of the interface, this function may be provided by the caller in order the FMAIImporter 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 FMAIImporter 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 FMA 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 FMAPivot at the start of the application, and deleted meanwhile, are just ignored.

#### Parameters

imported | the currently imported FMAObjectItem -derived object. |
fn_data | some data to be passed to the function. |

#### Returns

the already existing FMAObjectItem with same id, or `NULL`.

Since: 2.30

### fma_iimporter_import_from_uri ()

    guint
    fma_iimporter_import_from_uri (const FMAIImporter *importer,
                                   FMAIImporterImportFromUriParmsv2 *parms);

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

Note that, starting with FileManager-Actions™ 3.2, the `parms` argument is no more a FMAIImporterImportFromUriParms pointer, but a FMAIImporterImportFromUriParmsv2 one.

#### Parameters

importer | this FMAIImporter instance. |
parms | a FMAIImporterImportFromUriParmsv2 structure. |

#### Returns

the return code of the operation.

Since: 2.30

### fma_iimporter_manage_import_mode ()

    guint
    fma_iimporter_manage_import_mode (FMAIImporterManageImportModeParms *parms);

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

#### Parameters

parms | a FMAIImporterManageImportModeParms struct. |

#### Returns

the FMAIImporterImportStatus 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

## Types and Values

### FMA_TYPE_IIMPORTER

    #define FMA_TYPE_IIMPORTER                      ( fma_iimporter_get_type())

### FMAIImporter

    typedef struct _FMAIImporter FMAIImporter;

### FMAIImporterInterface

    typedef struct {
    	/**
    	 * get_version:
    	 * @instance: the FMAIImporter provider.
    	 *
    	 * FileManager-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,
    	 * FileManager-Actions considers that the plugin only implements
    	 * the version 1 of the FMAIImporter 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 FMAIImporter *instance );

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

This defines the interface that a FMAIImporter should implement.

#### Members

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

### enum FMAIImporterImportMode

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

Define the mode of an import operation.

#### Members

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 FMAIImporterImportStatus

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

Define the return status of an import operation.

#### Members

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

### FMAIImporterImportFromUriParms

    typedef struct {
    	guint                 version;
    	gchar                *uri;
    	guint                 asked_mode;
    	gboolean              exist;
    	guint                 import_mode;
    	FMAObjectItem        *imported;
    	FMAIImporterCheckFn   check_fn;
    	void                 *check_fn_data;
    	FMAIImporterAskUserFn ask_fn;
    	void                 *ask_fn_data;
    	GSList               *messages;
    } FMAIImporterImportFromUriParms;

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

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

#### Members

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. |
FMAObjectItem *`imported`; | [out] the imported FMAObjectItem -derived object, or `NULL`; since structure version 1. |
FMAIImporterCheckFn `check_fn`; | [in] a `FMAIImporterCheckFn()` 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. |
FMAIImporterAskUserFn `ask_fn`; | [in] a `FMAIImporterAskUserFn()` 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

### FMAIImporterImportFromUriParmsv2

    typedef struct {
    	guint          version;
    	guint          content;
    	const gchar   *uri;
    	FMAObjectItem *imported;
    	GSList        *messages;
    } FMAIImporterImportFromUriParmsv2;

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

#### Members

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. |
FMAObjectItem *`imported`; | [out] the imported FMAObjectItem -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

### FMAIImporterManageImportModeParms

    typedef struct {
    	guint                 version;
    	FMAObjectItem        *imported;
    	guint                 asked_mode;
    	FMAIImporterCheckFn   check_fn;
    	void                 *check_fn_data;
    	FMAIImporterAskUserFn ask_fn;
    	void                 *ask_fn_data;
    	gboolean              exist;
    	guint                 import_mode;
    	GSList               *messages;
    } FMAIImporterManageImportModeParms;

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

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

#### Members

guint `version`; | [in] the version of the structure content, equals to 1; since structure version 1. |
FMAObjectItem *`imported`; | [in] the imported FMAObjectItem -derived object; since structure version 1. |
guint `asked_mode`; | [in] asked import mode; since structure version 1. |
FMAIImporterCheckFn `check_fn`; | [in] a FMAIImporterCheckFn 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. |
FMAIImporterAskUserFn `ask_fn`; | [in] a FMAIImporterAskUserFn 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