1 /* 2 * Nautilus-Actions 3 * A Nautilus extension which offers configurable context menu actions. 4 * 5 * Copyright (C) 2005 The GNOME Foundation 6 * Copyright (C) 2006-2008 Frederic Ruaudel and others (see AUTHORS) 7 * Copyright (C) 2009-2014 Pierre Wieser and others (see AUTHORS) 8 * 9 * Nautilus-Actions is free software; you can redistribute it and/or 10 * modify it under the terms of the GNU General Public License as 11 * published by the Free Software Foundation; either version 2 of 12 * the License, or (at your option) any later version. 13 * 14 * Nautilus-Actions is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License 20 * along with Nautilus-Actions; see the file COPYING. If not, see 21 * <http://www.gnu.org/licenses/>. 22 * 23 * Authors: 24 * Frederic Ruaudel <grumz@grumz.net> 25 * Rodrigo Moya <rodrigo@gnome-db.org> 26 * Pierre Wieser <pwieser@trychlos.org> 27 * ... and many others (see AUTHORS) 28 */ 29 30 #ifndef __NAUTILUS_ACTIONS_API_NA_IIMPORTER_H__ 31 #define __NAUTILUS_ACTIONS_API_NA_IIMPORTER_H__ 32 33 /** 34 * SECTION: iimporter 35 * @title: NAIImporter 36 * @short_description: The Import Interface 37 * @include: nautilus-actions/na-iimporter.h 38 * 39 * The #NAIImporter interface imports items from the outside world 40 * into &prodname; repository (see #NAIIOProvider interface for how 41 * these items will be later managed to be store somewhere). 42 * 43 * In version 1 of the #NAIImporter interface, &prodname; used to 44 * provide the implementation with all was needed to be able to manage 45 * the import process up to be ready for insertion, including the 46 * deduplication if required. 47 * 48 * This used to put on the implementation the responsability to check 49 * for the unicity of the imported identifier, maybe asking the caller 50 * (via provided callback functions) what to do with it, maybe 51 * reallocating a new identifier, and so on... 52 * 53 * Starting with &prodname; version 3.2, this interface is bumped to 54 * a version 2 which greatly simplifies it. 55 * 56 * The I/O provider which implements the #NAIImporter interface is no 57 * more required to check for existence of the imported items, but this 58 * check is pushed back to the caller responsability. 59 * 60 * Rationale is that only the caller is able to check against a valid 61 * repository in its current import context, while the #NAIImporter 62 * provider should only be responsible to import an item in memory. 63 * 64 * <refsect2> 65 * <title>Versions historic</title> 66 * <table> 67 * <title>Historic of the versions of the #NAIImporter interface</title> 68 * <tgroup rowsep="1" colsep="1" align="center" cols="3"> 69 * <colspec colname="na-version" /> 70 * <colspec colname="api-version" /> 71 * <colspec colname="current" /> 72 * <colspec colname="deprecated" /> 73 * <thead> 74 * <row> 75 * <entry>&prodname; version</entry> 76 * <entry>#NAIImporter interface version</entry> 77 * <entry></entry> 78 * <entry></entry> 79 * </row> 80 * </thead> 81 * <tbody> 82 * <row> 83 * <entry>from 2.30 up to 3.1.5</entry> 84 * <entry>1</entry> 85 * <entry></entry> 86 * <entry>deprecated</entry> 87 * </row> 88 * <row> 89 * <entry>since 3.2</entry> 90 * <entry>2</entry> 91 * <entry>current version</entry> 92 * <entry></entry> 93 * </row> 94 * </tbody> 95 * </tgroup> 96 * </table> 97 * </refsect2> 98 */ 99 100 #include "na-object-item.h" 101 102 G_BEGIN_DECLS 103 104 #define NA_TYPE_IIMPORTER ( na_iimporter_get_type()) 105 #define NA_IIMPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IIMPORTER, NAIImporter )) 106 #define NA_IS_IIMPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IIMPORTER )) 107 #define NA_IIMPORTER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IIMPORTER, NAIImporterInterface )) 108 109 typedef struct _NAIImporter NAIImporter; 110 typedef struct _NAIImporterInterfacePrivate NAIImporterInterfacePrivate; 111 112 /** 113 * NAIImporterInterface: 114 * @get_version: [should] returns the version of this interface that the 115 * plugin implements. 116 * @import_from_uri: [should] imports an item. 117 * 118 * This defines the interface that a #NAIImporter should implement. 119 */ 120 typedef struct { 121 /*< private >*/ 122 GTypeInterface parent; 123 NAIImporterInterfacePrivate *private; 124 125 /*< public >*/ 126 /** 127 * get_version: 128 * @instance: the NAIImporter provider. 129 * 130 * Nautilus-Actions calls this method each time it needs to know 131 * which version of this interface the plugin implements. 132 * 133 * If this method is not implemented by the plugin, 134 * Nautilus-Actions considers that the plugin only implements 135 * the version 1 of the NAIImporter interface. 136 * 137 * Return value: if implemented, this method must return the version 138 * number of this interface the I/O provider is supporting. 139 * 140 * Defaults to 1. 141 * 142 * Since: 2.30 143 */ 144 guint ( *get_version ) ( const NAIImporter *instance ); 145 146 /** 147 * import_from_uri: 148 * @instance: the NAIImporter provider. 149 * @parms: a NAIImporterImportFromUriParms structure. 150 * 151 * Imports an item. 152 * 153 * If the provider implements the version 1 of this interface, then 154 * @parms is supposed to map to NAIImporterImportFromUriParms structure. 155 * 156 * Contrarily, if the provider implements the version 2 of the interface, 157 * then @parms is supposed to map to a NAIImporterImportFromUriParmsv2 158 * structure. 159 * 160 * Return value: the return code of the operation. 161 * 162 * Since: 2.30 163 */ 164 guint ( *import_from_uri )( const NAIImporter *instance, void *parms ); 165 } 166 NAIImporterInterface; 167 168 #ifdef NA_ENABLE_DEPRECATED 169 /** 170 * NAIImporterCheckFn: 171 * @imported: the currently imported #NAObjectItem -derived object. 172 * @fn_data: some data to be passed to the function. 173 * 174 * In version 1 of the interface, this function may be provided by 175 * the caller in order the #NAIImporter provider be able to check for 176 * pre-existence of the imported item. 177 * This function should return the already existing item which has the 178 * same id than the currently being imported one, or %NULL if the 179 * imported id will be unique. 180 * 181 * If this function is not provided, then the #NAIImporter provider will not 182 * be able to check for duplicates. In this case, the id of the imported item 183 * should be systematically regenerated as a unique id, regardless of the 184 * asked import mode. 185 * 186 * Standard N-A callers provide a function which checks for the existance 187 * of the newly imported item : 188 * <itemizedlist> 189 * <listitem> 190 * <para> 191 * first among the current list of just imported items 192 * </para> 193 * </listitem> 194 * <listitem> 195 * <para> 196 * and then amon the items currently visible in the main window. 197 * </para> 198 * </listitem> 199 * </itemizedlist> 200 * Items which may have been loaded by NAPivot at the start of the 201 * application, and deleted meanwhile, are just ignored. 202 * 203 * Returns: the already existing #NAObjectItem with same id, or %NULL. 204 * 205 * Since: 2.30 206 * Deprecated: 3.2 207 */ 208 typedef NAObjectItem * ( *NAIImporterCheckFn )( const NAObjectItem *, void * ); 209 210 /** 211 * NAIImporterAskUserFn: 212 * @imported: the currently imported #NAObjectItem. 213 * @existing: an already existing #NAObjectItem with same id. 214 * @fn_data: some data to be passed to the function. 215 * 216 * In version 1 of the interface, this function may be provided by the 217 * caller as a convenience way for the #NAIImporter to ask the user to 218 * know what to do in the case of a duplicate id. 219 * 220 * If this function is not provided, and the #NAIImporter does not have 221 * any other way to ask the user, then a 'no import' policy should be 222 * preferred when managing duplicate identifiers. 223 * 224 * Returns: the import mode chosen by the user, which must not be 225 * %IMPORTER_MODE_ASK. 226 * 227 * Since: 2.30 228 * Deprecated: 3.2 229 */ 230 typedef guint ( *NAIImporterAskUserFn )( const NAObjectItem *, const NAObjectItem *, void * ); 231 232 /** 233 * NAIImporterManageImportModeParms: 234 * @version: [in] the version of the structure content, equals to 1; 235 * since structure version 1. 236 * @imported: [in] the imported #NAObjectItem -derived object; 237 * since structure version 1. 238 * @asked_mode: [in] asked import mode; 239 * since structure version 1. 240 * @check_fn: [in] a #NAIImporterCheckFn function to check the existence of the imported id; 241 * since structure version 1. 242 * @check_fn_data: [in] @check_fn data; 243 * since structure version 1. 244 * @ask_fn: [in] a #NAIImporterAskUserFn function to ask the user what to do in case of a duplicate id; 245 * since structure version 1. 246 * @ask_fn_data: [in] @ask_fn data; 247 * since structure version 1. 248 * @exist: [out] whether the imported Id already existed; 249 * since structure version 1. 250 * @import_mode: [out] actually used import mode; 251 * since structure version 1. 252 * @messages: [in/out] a #GSList list of localized strings; 253 * the provider may append messages to this list, but shouldn't reinitialize it; 254 * since structure version 1. 255 * 256 * This structure allows all used parameters when managing the import mode 257 * to be passed and received through a single structure. 258 * 259 * Since: 2.30 260 * Deprecated: 3.2 261 */ 262 typedef struct { 263 guint version; 264 NAObjectItem *imported; 265 guint asked_mode; 266 NAIImporterCheckFn check_fn; 267 void *check_fn_data; 268 NAIImporterAskUserFn ask_fn; 269 void *ask_fn_data; 270 gboolean exist; 271 guint import_mode; 272 GSList *messages; 273 } 274 NAIImporterManageImportModeParms; 275 276 /** 277 * NAIImporterImportMode: 278 * @IMPORTER_MODE_NO_IMPORT: a "do not import" mode. 279 * @IMPORTER_MODE_RENUMBER: reallocate a new id when the imported one already exists. 280 * @IMPORTER_MODE_OVERRIDE: override the existing id with the imported one. 281 * @IMPORTER_MODE_ASK: ask the user for what to do with this particular item. 282 * 283 * Define the mode of an import operation. 284 * 285 * Deprecated: 3.2 286 */ 287 typedef enum { 288 IMPORTER_MODE_NO_IMPORT = 1, 289 IMPORTER_MODE_RENUMBER, 290 IMPORTER_MODE_OVERRIDE, 291 IMPORTER_MODE_ASK 292 } 293 NAIImporterImportMode; 294 295 guint na_iimporter_manage_import_mode( NAIImporterManageImportModeParms *parms ); 296 297 /** 298 * NAIImporterImportFromUriParms: 299 * @version: [in] the version of this structure; 300 * since structure version 1. 301 * @uri: [in] uri of the file to be imported; 302 * since structure version 1. 303 * @asked_mode: [in] asked import mode; 304 * since structure version 1. 305 * @exist: [out] whether the imported Id already existed; 306 * since structure version 1. 307 * @import_mode: [out] actually used import mode; 308 * since structure version 1. 309 * @imported: [out] the imported #NAObjectItem -derived object, or %NULL; 310 * since structure version 1. 311 * @check_fn: [in] a NAIImporterCheckFn() function to check the existence 312 * of the imported id; 313 * since structure version 1. 314 * @check_fn_data: [in] @check_fn data; 315 * since structure version 1. 316 * @ask_fn: [in] a NAIImporterAskUserFn() function to ask the user what to 317 * do in case of a duplicate id; 318 * since structure version 1. 319 * @ask_fn_data: [in] @ask_fn data; 320 * since structure version 1. 321 * @messages: [in/out] a #GSList list of localized strings; 322 * the provider may append messages to this list, but 323 * shouldn't reinitialize it; 324 * since structure version 1. 325 * 326 * This structure allows all used parameters when importing from an URI 327 * to be passed and received through a single structure. 328 * 329 * Since: 2.30 330 * Deprecated: 3.2 331 */ 332 typedef struct { 333 guint version; 334 gchar *uri; 335 guint asked_mode; 336 gboolean exist; 337 guint import_mode; 338 NAObjectItem *imported; 339 NAIImporterCheckFn check_fn; 340 void *check_fn_data; 341 NAIImporterAskUserFn ask_fn; 342 void *ask_fn_data; 343 GSList *messages; 344 } 345 NAIImporterImportFromUriParms; 346 347 #endif /* NA_ENABLE_DEPRECATED */ 348 349 /** 350 * NAIImporterImportStatus: 351 * @IMPORTER_CODE_OK: import ok. 352 * @IMPORTER_CODE_PROGRAM_ERROR: a program error has been detected. 353 * You should open a bug in 354 * <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions">Bugzilla</ulink>. 355 * @IMPORTER_CODE_NOT_WILLING_TO: the plugin is not willing to import the uri. 356 * @IMPORTER_CODE_NO_ITEM_ID: item id not found. 357 * @IMPORTER_CODE_NO_ITEM_TYPE: item type not found. 358 * @IMPORTER_CODE_UNKNOWN_ITEM_TYPE: unknown item type. 359 * @IMPORTER_CODE_CANCELLED: operation cancelled by the user. 360 * @IMPORTER_CODE_NOT_LOADABLE: the file is considered as not loadable at all. 361 * This is not a matter of which I/O provider has been tried, 362 * but the file is empty, or too big, or eventually not a 363 * regular file. 364 * 365 * Define the return status of an import operation. 366 */ 367 typedef enum { 368 IMPORTER_CODE_OK = 0, 369 IMPORTER_CODE_PROGRAM_ERROR, 370 IMPORTER_CODE_NOT_WILLING_TO, 371 IMPORTER_CODE_NO_ITEM_ID, 372 IMPORTER_CODE_NO_ITEM_TYPE, 373 IMPORTER_CODE_UNKNOWN_ITEM_TYPE, 374 IMPORTER_CODE_CANCELLED, 375 IMPORTER_CODE_NOT_LOADABLE 376 } 377 NAIImporterImportStatus; 378 379 /** 380 * NAIImporterImportFromUriParmsv2: 381 * @version: [in] the version of the structure, equals to 2; 382 * since structure version 1. 383 * @content: [in] the version of the description content, equals to 1; 384 * since structure version 2. 385 * @uri: [in] uri of the file to be imported; 386 * since structure version 1. 387 * @imported: [out] the imported #NAObjectItem -derived object, or %NULL; 388 * since structure version 1. 389 * @messages: [in/out] a #GSList list of localized strings; 390 * the provider may append messages to this list, but 391 * shouldn't reinitialize it; 392 * since structure version 1. 393 * 394 * This structure allows all used parameters when importing from an URI 395 * to be passed and received through a single structure. 396 * 397 * Since: 3.2 398 */ 399 typedef struct { 400 guint version; 401 guint content; 402 const gchar *uri; 403 NAObjectItem *imported; 404 GSList *messages; 405 } 406 NAIImporterImportFromUriParmsv2; 407 408 GType na_iimporter_get_type ( void ); 409 410 guint na_iimporter_import_from_uri( const NAIImporter *importer, NAIImporterImportFromUriParmsv2 *parms ); 411 412 G_END_DECLS 413 414 #endif /* __NAUTILUS_ACTIONS_API_NA_IIMPORTER_H__ */ 415