NAIImporter

NAIImporter — The Import Interface

Synopsis

#include <nautilus-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 Nautilus-Actions™ repository (see NAIIOProvider interface for how these items will be later managed to be store somewhere).

In version 1 of the NAIImporter interface, Nautilus-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 Nautilus-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

Nautilus-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.
	 *
	 * Nautilus-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,
	 * Nautilus-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 Nautilus-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