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_IEXPORTER_H__ 31 #define __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__ 32 33 /** 34 * SECTION: iexporter 35 * @title: NAIExporter 36 * @short_description: The Export Interface 37 * @include: nautilus-actions/na-iexporter.h 38 * 39 * The #NAIExporter interface exports items to the outside world. Each 40 * implementation may provide one or more formats. 41 * 42 * <refsect2> 43 * <title>Export format identifier</title> 44 * <para> 45 * For its own internal needs, &prodname; requires that each export 46 * format have its own identifier, as an ASCII string. 47 * </para> 48 * <para> 49 * In order to avoid any collision, this export format identifier is 50 * allocated by the &prodname; maintainers team. If you wish provide 51 * yourself a new export format, and so need a new export format identifier, 52 * please contact the maintainers (see nautilus-actions.doap at the 53 * root of the source tree). 54 * </para> 55 * <para> 56 * Below is a list of currently allocated export format identifiers. 57 * This list has been last updated on 2010, July 28th. 58 * </para> 59 * <table> 60 * <title>Currently allocated export format identifiers</title> 61 * <tgroup rowsep="1" colsep="1" cols="4"> 62 * <colspec colname="id" /> 63 * <colspec colname="label" /> 64 * <colspec colname="holder" /> 65 * <colspec colname="allocated" align="center" /> 66 * <thead> 67 * <row> 68 * <entry>Identifier</entry> 69 * <entry>Name</entry> 70 * <entry>Holder</entry> 71 * <entry>Allocated on</entry> 72 * </row> 73 * </thead> 74 * <tbody> 75 * <row> 76 * <entry><literal>Ask</literal></entry> 77 * <entry>Reserved for &prodname; internal needs</entry> 78 * <entry>&prodname;</entry> 79 * <entry>2010-02-15</entry> 80 * </row> 81 * <row> 82 * <entry><literal>Desktop1</literal></entry> 83 * <entry>NA Desktop module</entry> 84 * <entry>&prodname;</entry> 85 * <entry>2010-07-28</entry> 86 * </row> 87 * <row> 88 * <entry><literal>GConfSchemaV1</literal></entry> 89 * <entry>NA XML module</entry> 90 * <entry>&prodname;</entry> 91 * <entry>2010-02-15</entry> 92 * </row> 93 * <row> 94 * <entry><literal>GConfSchemaV2</literal></entry> 95 * <entry>NA XML module</entry> 96 * <entry>&prodname;</entry> 97 * <entry>2010-02-15</entry> 98 * </row> 99 * <row> 100 * <entry><literal>GConfEntry</literal></entry> 101 * <entry>NA XML module</entry> 102 * <entry>&prodname;</entry> 103 * <entry>2010-02-15</entry> 104 * </row> 105 * </tbody> 106 * </tgroup> 107 * </table> 108 * </refsect2> 109 * 110 * <refsect2> 111 * <title>Versions historic</title> 112 * <table> 113 * <title>Historic of the versions of the #NAIExporter interface</title> 114 * <tgroup rowsep="1" colsep="1" align="center" cols="3"> 115 * <colspec colname="na-version" /> 116 * <colspec colname="api-version" /> 117 * <colspec colname="current" /> 118 * <colspec colname="deprecated" /> 119 * <thead> 120 * <row> 121 * <entry>&prodname; version</entry> 122 * <entry>#NAIExporter interface version</entry> 123 * <entry></entry> 124 * <entry></entry> 125 * </row> 126 * </thead> 127 * <tbody> 128 * <row> 129 * <entry>from 2.30 to 3.1.5</entry> 130 * <entry>1</entry> 131 * <entry></entry> 132 * <entry>deprecated</entry> 133 * </row> 134 * <row> 135 * <entry>since 3.2</entry> 136 * <entry>2</entry> 137 * <entry>current version</entry> 138 * <entry></entry> 139 * </row> 140 * </tbody> 141 * </tgroup> 142 * </table> 143 * </refsect2> 144 */ 145 146 #include <gdk-pixbuf/gdk-pixbuf.h> 147 #include "na-object-item.h" 148 149 G_BEGIN_DECLS 150 151 #define NA_TYPE_IEXPORTER ( na_iexporter_get_type()) 152 #define NA_IEXPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IEXPORTER, NAIExporter )) 153 #define NA_IS_IEXPORTER( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IEXPORTER )) 154 #define NA_IEXPORTER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IEXPORTER, NAIExporterInterface )) 155 156 typedef struct _NAIExporter NAIExporter; 157 typedef struct _NAIExporterInterfacePrivate NAIExporterInterfacePrivate; 158 159 #ifdef NA_ENABLE_DEPRECATED 160 /** 161 * NAIExporterFormat: 162 * @format: format identifier (ascii). 163 * @label: short label to be displayed in dialog (UTF-8 localized) 164 * @description: full description of the format (UTF-8 localized); 165 * mainly used in the export assistant. 166 * 167 * This structure describes a supported output format. 168 * It must be provided by each #NAIExporter implementation 169 * (see e.g. <filename>src/io-xml/naxml-formats.c</filename>). 170 * 171 * When listing available export formats, the instance returns a #GList 172 * of these structures. 173 * 174 * Deprecated: 3.2 175 */ 176 typedef struct { 177 gchar *format; 178 gchar *label; 179 gchar *description; 180 } 181 NAIExporterFormat; 182 183 /** 184 * NAIExporterFileParms: 185 * @version: [in] version of this structure; 186 * since structure version 1. 187 * @exported: [in] exported NAObjectItem-derived object; 188 * since structure version 1. 189 * @folder: [in] URI of the target folder; 190 * since structure version 1. 191 * @format: [in] export format as a GQuark; 192 * since structure version 1. 193 * @basename: [out] basename of the exported file; 194 * since structure version 1. 195 * @messages: [in/out] a #GSList list of localized strings; 196 * the provider may append messages to this list, 197 * but shouldn't reinitialize it; 198 * since structure version 1. 199 * 200 * The structure that the implementation receives as a parameter of 201 * #NAIExporterInterface.to_file () interface method. 202 * 203 * Deprecated: 3.2 204 */ 205 typedef struct { 206 guint version; 207 NAObjectItem *exported; 208 gchar *folder; 209 GQuark format; 210 gchar *basename; 211 GSList *messages; 212 } 213 NAIExporterFileParms; 214 215 /** 216 * NAIExporterBufferParms: 217 * @version: [in] version of this structure; 218 * since structure version 1. 219 * @exported: [in] exported NAObjectItem-derived object; 220 * since structure version 1. 221 * @format: [in] export format as a GQuark; 222 * since structure version 1. 223 * @buffer: [out] buffer which contains the exported object; 224 * since structure version 1. 225 * @messages: [in/out] a #GSList list of localized strings; 226 * the provider may append messages to this list, 227 * but shouldn't reinitialize it; 228 * since structure version 1. 229 * 230 * The structure that the plugin receives as a parameter of 231 * #NAIExporterInterface.to_buffer () interface method. 232 * 233 * Deprecated: 3.2 234 */ 235 typedef struct { 236 guint version; 237 NAObjectItem *exported; 238 GQuark format; 239 gchar *buffer; 240 GSList *messages; 241 } 242 NAIExporterBufferParms; 243 244 #endif /* NA_ENABLE_DEPRECATED */ 245 246 /** 247 * NAIExporterFormatv2: 248 * @version: the version of this #NAIExporterFormatv2 structure; 249 * equals to 2; 250 * since structure version 1. 251 * @provider: the #NAIExporter provider for this format; 252 * since structure version 2. 253 * @format: format identifier (ascii, allocated by the Nautilus-Actions team); 254 * since structure version 2. 255 * @label: short label to be displayed in dialog (UTF-8 localized); 256 * since structure version 2. 257 * @description: full description of the format (UTF-8 localized); 258 * mainly used as a tooltip; 259 * since structure version 2. 260 * @pixbuf: an image to be associated with this export format; 261 * this pixbuf is supposed to be rendered with GTK_ICON_SIZE_DIALOG size; 262 * since structure version 2. 263 * 264 * This structure describes a supported output format. 265 * It must be provided by each #NAIExporter implementation 266 * (see e.g. <filename>src/io-xml/naxml-formats.c</filename>). 267 * 268 * When listing available export formats, the @provider must return a #GList 269 * of these structures. 270 * 271 * <refsect2> 272 * <title>Versions historic</title> 273 * <table> 274 * <title>Historic of the versions of the #NAIExporterFormatv2 structure</title> 275 * <tgroup rowsep="1" colsep="1" align="center" cols="3"> 276 * <colspec colname="na-version" /> 277 * <colspec colname="api-version" /> 278 * <colspec colname="current" /> 279 * <thead> 280 * <row> 281 * <entry>&prodname; version</entry> 282 * <entry>#NAIExporterFormatv2 structure version</entry> 283 * <entry></entry> 284 * </row> 285 * </thead> 286 * <tbody> 287 * <row> 288 * <entry>since 2.30</entry> 289 * <entry>1</entry> 290 * <entry></entry> 291 * </row> 292 * <row> 293 * <entry>since 3.2</entry> 294 * <entry>2</entry> 295 * <entry>current version</entry> 296 * </row> 297 * </tbody> 298 * </tgroup> 299 * </table> 300 * </refsect2> 301 * 302 * Since: 3.2 303 */ 304 typedef struct { 305 guint version; 306 NAIExporter *provider; 307 gchar *format; 308 gchar *label; 309 gchar *description; 310 GdkPixbuf *pixbuf; 311 } 312 NAIExporterFormatv2; 313 314 /** 315 * NAIExporterFileParmsv2: 316 * @version: [in] version of this structure; 317 * equals to 2; 318 * since structure version 1. 319 * @content: [in] version of the content of this structure; 320 * equals to 1; 321 * since structure version 2. 322 * @exported: [in] exported NAObjectItem-derived object; 323 * since structure version 1. 324 * @folder: [in] URI of the target folder; 325 * since structure version 1. 326 * @format: [in] export format string identifier; 327 * since structure version 1. 328 * @basename: [out] basename of the exported file; 329 * since structure version 1. 330 * @messages: [in/out] a #GSList list of localized strings; 331 * the provider may append messages to this list, 332 * but shouldn't reinitialize it; 333 * since structure version 1. 334 * 335 * The structure that the plugin receives as a parameter of 336 * #NAIExporterInterface.to_file () interface method. 337 * 338 * Since: 3.2 339 */ 340 typedef struct { 341 guint version; 342 guint content; 343 NAObjectItem *exported; 344 gchar *folder; 345 gchar *format; 346 gchar *basename; 347 GSList *messages; 348 } 349 NAIExporterFileParmsv2; 350 351 /** 352 * NAIExporterBufferParmsv2: 353 * @version: [in] version of this structure; 354 * equals to 2; 355 * since structure version 1. 356 * @content: [in] version of the content of this structure; 357 * equals to 1; 358 * since structure version 2. 359 * @exported: [in] exported NAObjectItem-derived object; 360 * since structure version 1. 361 * @format: [in] export format string identifier; 362 * since structure version 2. 363 * @buffer: [out] buffer which contains the exported object; 364 * since structure version 1. 365 * @messages: [in/out] a #GSList list of localized strings; 366 * the provider may append messages to this list, 367 * but shouldn't reinitialize it; 368 * since structure version 1. 369 * 370 * The structure that the plugin receives as a parameter of 371 * #NAIExporterInterface.to_buffer () interface method. 372 * 373 * Since: 3.2 374 */ 375 typedef struct { 376 guint version; 377 guint content; 378 NAObjectItem *exported; 379 gchar *format; 380 gchar *buffer; 381 GSList *messages; 382 } 383 NAIExporterBufferParmsv2; 384 385 /** 386 * NAIExporterInterface: 387 * @get_version: [should] returns the version of this interface the plugin implements. 388 * @get_name: [should] returns the public plugin name. 389 * @get_formats: [should] returns the list of supported formats. 390 * @free_formats: [should] free a list of formats 391 * @to_file: [should] exports an item to a file. 392 * @to_buffer: [should] exports an item to a buffer. 393 * 394 * This defines the interface that a #NAIExporter should implement. 395 */ 396 typedef struct { 397 /*< private >*/ 398 GTypeInterface parent; 399 NAIExporterInterfacePrivate *private; 400 401 /*< public >*/ 402 /** 403 * get_version: 404 * @instance: this NAIExporter instance. 405 * 406 * Nautilus-Actions calls this method each time it needs to know 407 * which version of this interface the plugin implements. 408 * 409 * If this method is not implemented by the plugin, 410 * Nautilus-Actions considers that the plugin only implements 411 * the version 1 of the NAIImporter interface. 412 * 413 * Return value: if implemented, this method must return the version 414 * number of this interface the I/O provider is supporting. 415 * 416 * Defaults to 1. 417 * 418 * Since: 2.30 419 */ 420 guint ( *get_version )( const NAIExporter *instance ); 421 422 /** 423 * get_name: 424 * @instance: this NAIExporter instance. 425 * 426 * Return value: if implemented, the method should return the name to be 427 * displayed, as a newly allocated string which will be g_free() by the 428 * caller. 429 * 430 * This may be the name of the module itself, but this also may be a 431 * special name the modules gives to this interface. 432 * 433 * Defaults to a NULL string. 434 * 435 * Since: 2.30 436 */ 437 gchar * ( *get_name ) ( const NAIExporter *instance ); 438 439 /** 440 * get_formats: 441 * @instance: this NAIExporter instance. 442 * 443 * For its own internal needs, Nautilus-Actions requires each export 444 * format has its own unique identifier (in fact, just a small ASCII 445 * string). 446 * 447 * To avoid any collision, the format identifier is allocated by the 448 * Nautilus-Actions maintainers team. If you wish develop a new export 449 * format, and so need a new format identifier, please contact the 450 * maintainers (see nautilus-actions.doap). 451 * 452 * Return value: 453 * - Interface v1: 454 * a null-terminated list of NAIExporterFormat structures 455 * which describes the formats supported by this NAIExporter 456 * provider. 457 * The returned list is owned by the NAIExporter provider, 458 * and should not be freed nor released by the caller. 459 * 460 * - Interface v2: 461 * a GList of NAIExporterFormatv2 structures 462 * which describes the formats supported by this NAIExporter 463 * provider. 464 * The caller should then invoke the free_formats() method 465 * in order the provider be able to release the resources 466 * allocated to the list. 467 * 468 * Defaults to NULL (no format at all). 469 * 470 * Since: 2.30 471 */ 472 void * ( *get_formats )( const NAIExporter *instance ); 473 474 /** 475 * free_formats: 476 * @instance: this NAIExporter instance. 477 * @formats: a null-terminated list of NAIExporterFormatv2 structures, 478 * as returned by get_formats() method above. 479 * 480 * Free the resources allocated to the @formats list. 481 * 482 * Since: 3.2 483 */ 484 void ( *free_formats )( const NAIExporter *instance, GList *formats ); 485 486 /** 487 * to_file: 488 * @instance: this NAIExporter instance. 489 * @parms: a NAIExporterFileParmsv2 structure. 490 * 491 * Exports the specified 'exported' to the target 'folder' in the required 492 * 'format'. 493 * 494 * Return value: the NAIExporterExportStatus status of the operation. 495 * 496 * Since: 2.30 497 */ 498 guint ( *to_file ) ( const NAIExporter *instance, NAIExporterFileParmsv2 *parms ); 499 500 /** 501 * to_buffer: 502 * @instance: this NAIExporter instance. 503 * @parms: a NAIExporterFileParmsv2 structure. 504 * 505 * Exports the specified 'exported' to a newly allocated 'buffer' in 506 * the required 'format'. The allocated 'buffer' will be g_free() 507 * by the caller. 508 * 509 * Return value: the NAIExporterExportStatus status of the operation. 510 * 511 * Since: 2.30 512 */ 513 guint ( *to_buffer ) ( const NAIExporter *instance, NAIExporterBufferParmsv2 *parms ); 514 } 515 NAIExporterInterface; 516 517 /** 518 * NAIExporterExportStatus: 519 * @NA_IEXPORTER_CODE_OK: export OK. 520 * @NA_IEXPORTER_CODE_INVALID_ITEM: exported item was found invalid. 521 * @NA_IEXPORTER_CODE_INVALID_TARGET: selected target was found invalid. 522 * @NA_IEXPORTER_CODE_INVALID_FORMAT: asked format was found invalid. 523 * @NA_IEXPORTER_CODE_UNABLE_TO_WRITE: unable to write the item. 524 * @NA_IEXPORTER_CODE_ERROR: other undetermined error. 525 * 526 * The reasons for which an item may not have been exported 527 */ 528 typedef enum { 529 NA_IEXPORTER_CODE_OK = 0, 530 NA_IEXPORTER_CODE_INVALID_ITEM, 531 NA_IEXPORTER_CODE_INVALID_TARGET, 532 NA_IEXPORTER_CODE_INVALID_FORMAT, 533 NA_IEXPORTER_CODE_UNABLE_TO_WRITE, 534 NA_IEXPORTER_CODE_ERROR, 535 } 536 NAIExporterExportStatus; 537 538 GType na_iexporter_get_type( void ); 539 540 G_END_DECLS 541 542 #endif /* __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__ */ 543