![]() |
![]() |
![]() |
Caja-Actions™ Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Prerequisites |
#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
);
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.
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 |
#define NA_IIMPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IIMPORTER, NAIImporter ))
#define NA_IS_IIMPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IIMPORTER ))
#define NA_IIMPORTER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IIMPORTER, 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.
typedef enum { IMPORTER_MODE_NO_IMPORT = 1, IMPORTER_MODE_RENUMBER, IMPORTER_MODE_OVERRIDE, IMPORTER_MODE_ASK } NAIImporterImportMode;
NAIImporterImportMode
is deprecated and should not be used in newly-written code. 3.2
Define the mode of an import operation.
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.
import ok. | |
a program error has been detected. You should open a bug in Bugzilla. | |
the plugin is not willing to import the uri. | |
item id not found. | |
item type not found. | |
unknown item type. | |
operation cancelled by the user. | |
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. |
guint NAIImporterAskUserFn (const NAObjectItem *imported
,const NAObjectItem *existing
,void *fn_data
);
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.
|
the currently imported NAObjectItem. |
|
an already existing NAObjectItem with same id. |
|
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
NAObjectItem * NAIImporterCheckFn (const NAObjectItem *imported
,void *fn_data
);
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.
|
the currently imported NAObjectItem -derived object. |
|
some data to be passed to the function. |
Returns : |
the already existing NAObjectItem with same id, or NULL . |
Since 2.30
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;
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 |
[in] the version of this structure; since structure version 1. |
gchar * |
[in] uri of the file to be imported; since structure version 1. |
guint |
[in] asked import mode; since structure version 1. |
gboolean |
[out] whether the imported Id already existed; since structure version 1. |
guint |
[out] actually used import mode; since structure version 1. |
NAObjectItem * |
[out] the imported NAObjectItem -derived object, or NULL ;
since structure version 1. |
NAIImporterCheckFn |
[in] a NAIImporterCheckFn() function to check the existence
of the imported id;
since structure version 1. |
[in] check_fn data;
since structure version 1. |
|
NAIImporterAskUserFn |
[in] a NAIImporterAskUserFn() function to ask the user what to
do in case of a duplicate id;
since structure version 1. |
[in] ask_fn data;
since structure version 1. |
|
GSList * |
[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
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 |
[in] the version of the structure, equals to 2; since structure version 1. |
guint |
[in] the version of the description content, equals to 1; since structure version 2. |
const gchar * |
[in] uri of the file to be imported; since structure version 1. |
NAObjectItem * |
[out] the imported NAObjectItem -derived object, or NULL ;
since structure version 1. |
GSList * |
[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
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;
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 |
[in] the version of the structure content, equals to 1; since structure version 1. |
NAObjectItem * |
[in] the imported NAObjectItem -derived object; since structure version 1. |
guint |
[in] asked import mode; since structure version 1. |
NAIImporterCheckFn |
[in] a NAIImporterCheckFn function to check the existence of the imported id; since structure version 1. |
[in] check_fn data;
since structure version 1. |
|
NAIImporterAskUserFn |
[in] a NAIImporterAskUserFn function to ask the user what to do in case of a duplicate id; since structure version 1. |
[in] ask_fn data;
since structure version 1. |
|
gboolean |
[out] whether the imported Id already existed; since structure version 1. |
guint |
[out] actually used import mode; since structure version 1. |
GSList * |
[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
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.
|
this NAIImporter instance. |
|
a NAIImporterImportFromUriParmsv2 structure. |
Returns : |
the return code of the operation. |
Since 2.30
guint na_iimporter_manage_import_mode (NAIImporterManageImportModeParms *parms
);
na_iimporter_manage_import_mode
is deprecated and should not be used in newly-written code. 3.2
|
a NAIImporterManageImportModeParms struct. |
Returns : |
the NAIImporterImportStatus status of the operation:
|
Since 2.30