NAIImporter

NAIImporter — The Import Interface v 1

Synopsis

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

#define             NA_IIMPORTER_TYPE
#define             NA_IIMPORTER                        (instance)
#define             NA_IS_IIMPORTER                     (instance)
#define             NA_IIMPORTER_GET_INTERFACE          (instance)
                    NAIImporter;
                    NAIImporterInterface;
enum                NAIImporterImportMode;
enum                NAIImporterImportStatus;
NAObjectItem *      NAIImporterCheckFn                  (const NAObjectItem *imported,
                                                         void *fn_data);
guint               NAIImporterAskUserFn                (const NAObjectItem *imported,
                                                         const NAObjectItem *existing,
                                                         void *fn_data);
struct              NAIImporterImportFromUriParms;
struct              NAIImporterManageImportModeParms;
guint               na_iimporter_import_from_uri        (const NAIImporter *importer,
                                                         NAIImporterImportFromUriParms *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.

Versions historic

Table 3. Historic of the versions of the NAIImporter interface

Nautilus-Actions™ version NAIImporter interface version  
since 2.30 1 current version

Details

NA_IIMPORTER_TYPE

#define NA_IIMPORTER_TYPE                       ( na_iimporter_get_type())

NA_IIMPORTER()

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

NA_IS_IIMPORTER()

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

NA_IIMPORTER_GET_INTERFACE()

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

NAIImporter

typedef struct _NAIImporter NAIImporter;

NAIImporterInterface

typedef struct {
	/**
	 * get_version:
	 * @instance: the #NAIImporter provider.
	 *
	 * This method is called by the &prodname; program each time
	 * it needs to know which version of this interface the plugin
	 * implements.
	 *
	 * If this method is not implemented by the plugin,
	 * the &prodname; program considers that the plugin only implements
	 * the version 1 of the #NAIImporter interface.
	 *
	 * Returns: the version of this interface supported by the plugin.
	 *
	 * Since: 2.30
	 */
	guint ( *get_version )    ( const NAIImporter *instance );

	/**
	 * import_from_uri:
	 * @instance: the #NAIImporter provider.
	 * @parms: a #NAIImporterImportFromUriParms structure.
	 *
	 * Imports an item.
	 *
	 * Returns: the return code of the operation.
	 *
	 * Since: 2.30
	 */
	guint ( *import_from_uri )( const NAIImporter *instance, NAIImporterImportFromUriParms *parms );
} NAIImporterInterface;

This defines the interface that a NAIImporter should implement.

get_version ()

returns the version of this interface that the plugin implements.

import_from_uri ()

imports an item.

enum NAIImporterImportMode

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

Define the mode of an import operation.

IMPORTER_MODE_NO_IMPORT

a "do not import anything" 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
} 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 anything.

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.

NAIImporterCheckFn ()

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

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.

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


NAIImporterAskUserFn ()

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

This function may be provided by the caller in order the NAIImporter provider be able to ask the user to know what to do in the case of a duplicate id.

If this function is not provided, then the NAIImporter provider will not be able to ask the user. In this case, the duplicated id should be systematically regenerated as a unique id.

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 choosen by the user, which must not be IMPORTER_MODE_ASK.

Since 2.30


struct NAIImporterImportFromUriParms

struct NAIImporterImportFromUriParms {
	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;
};

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

guint version;

the version of this structure, currently equals to 1. input; since version 1 of the structure.

gchar *uri;

uri of the file to be imported. input; since version 1 of the structure.

guint asked_mode;

asked import mode. input; since version 1 of the structure.

gboolean exist;

whether the imported Id already existed. output; since version 1 of the structure.

guint import_mode;

actually used import mode. output; since version 1 of the structure.

NAObjectItem *imported;

the imported NAObjectItem -derived object, or NULL. output; since version 1 of the structure.

NAIImporterCheckFn check_fn;

a NAIImporterCheckFn() function to check the existence of the imported id. input; since version 1 of the structure.

void *check_fn_data;

check_fn data input; since version 1 of the structure.

NAIImporterAskUserFn ask_fn;

a NAIImporterAskUserFn() function to ask the user what to do in case of a duplicate id input; since version 1 of the structure.

void *ask_fn_data;

ask_fn data input; since version 1 of the structure.

GSList *messages;

a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it input/output; since version 1 of the structure.

Since 2.30


struct NAIImporterManageImportModeParms

struct NAIImporterManageImportModeParms {
	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;
};

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

guint version;

the version of this structure, currently equals to 1. input; since version 1 of the structure.

NAObjectItem *imported;

the imported NAObjectItem -derived object

guint asked_mode;

asked import mode

NAIImporterCheckFn check_fn;

a NAIImporterCheckFn function to check the existence of the imported id. input; since version 1 of the structure.

void *check_fn_data;

check_fn data input; since version 1 of the structure.

NAIImporterAskUserFn ask_fn;

a NAIImporterAskUserFn function to ask the user what to do in case of a duplicate id input; since version 1 of the structure.

void *ask_fn_data;

ask_fn data input; since version 1 of the structure.

gboolean exist;

whether the imported Id already existed output; since version 1 of the structure.

guint import_mode;

actually used import mode output; since version 1 of the structure.

GSList *messages;

a GSList list of localized strings; the provider may append messages to this list, but shouldn't reinitialize it input/output; since version 1 of the structure.

Since 2.30


na_iimporter_import_from_uri ()

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

na_iimporter_manage_import_mode ()

guint               na_iimporter_manage_import_mode     (NAIImporterManageImportModeParms *parms);