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_IIO_PROVIDER_H__ 31 #define __NAUTILUS_ACTIONS_API_NA_IIO_PROVIDER_H__ 32 33 /** 34 * SECTION: iio-provider 35 * @title: NAIIOProvider 36 * @short_description: The I/O Provider Interface 37 * @include: nautilus-actions/na-iio-provider.h 38 * 39 * The #NAIIOProvider interface is defined in order to let both &prodname; 40 * internal and user-provided external plugins provide read and write accesses 41 * to their own private storage subsystem. 42 * 43 * &prodname; core does not provide by itself input/output code. Instead, 44 * we entirely relies on input/output facilities provided by implementations 45 * of this interface. 46 * 47 * &prodname; is bundled with several I/O providers. 48 * Since version 3, the <literal>na-desktop</literal> I/O provider, which 49 * implements the 50 * <ulink role="online-location" url="http://www.nautilus-actions.org/?q=node/377/">DES-EMA</ulink> 51 * specification, is the preferred way of storing (and sharing) items. 52 * 53 * The #NAIIOProvider interface provides three types of services: 54 * <itemizedlist> 55 * <listitem> 56 * <formalpara> 57 * <title> 58 * loading items 59 * </title> 60 * <para> 61 * Loading items is used both by the &nautilus; plugin, by the 62 * &nact; program, and by the command-line utilities. 63 * </para> 64 * </formalpara> 65 * </listitem> 66 * <listitem> 67 * <formalpara> 68 * <title> 69 * creating, updating or deleting items 70 * </title> 71 * <para> 72 * Updating items is a feature only used by the &nact; program and 73 * by some command-line utilities. 74 * </para> 75 * </formalpara> 76 * </listitem> 77 * <listitem> 78 * <formalpara> 79 * <title> 80 * informing &prodname; of extern modifications 81 * </title> 82 * <para> 83 * The I/O provider should inform &prodname; when an item happens to 84 * have been modified in the underlying storage subsystem. 85 * </para> 86 * </formalpara> 87 * <para> 88 * This feature is only used by the &nautilus; plugin and by the 89 * &nact; program. 90 * </para> 91 * <para> 92 * The #NAIIOProvider interface does not define specific monitoring 93 * methods (but you can also take a glance at #NATimeout object). 94 * Instead, it is waited that the I/O provider module takes care 95 * itself of managing its own monitoring services at 96 * load/unload time, calling the na_iio_provider_item_changed() 97 * function when appropriate. 98 * </para> 99 * </listitem> 100 * </itemizedlist> 101 * 102 * These services may be fully implemented by the I/O provider itself. 103 * Or, the I/O provider may also prefer to take advantage of the data 104 * factory management (see #NAIFactoryObject and #NAIFactoryProvider 105 * interfaces) services. 106 * 107 * <refsect2> 108 * <title>I/O provider identifier</title> 109 * <para> 110 * For its own internal needs, &prodname; requires that each I/O provider 111 * have its own identifier, as an ASCII string. 112 * </para> 113 * <para> 114 * In order to avoid any collision, this I/O provider identifier is 115 * allocated by the &prodname; maintainers team. If you wish develop 116 * yourself a new I/O provider, and so need a new provider identifier, 117 * please contact the maintainers (see nautilus-actions.doap at the 118 * root of the source tree). 119 * </para> 120 * <para> 121 * Below is a list of currently allocated I/O provider identifiers. 122 * This list has been last updated on 2010, Feb. 14th. 123 * </para> 124 * <table> 125 * <title>Currently allocated I/O provider identifiers</title> 126 * <tgroup rowsep="1" colsep="1" cols="4"> 127 * <colspec colname="id" /> 128 * <colspec colname="label" /> 129 * <colspec colname="holder" /> 130 * <colspec colname="allocated" align="center" /> 131 * <thead> 132 * <row> 133 * <entry>Identifier</entry> 134 * <entry>Name</entry> 135 * <entry>Holder</entry> 136 * <entry>Allocated on</entry> 137 * </row> 138 * </thead> 139 * <tbody> 140 * <row> 141 * <entry><literal>all</literal></entry> 142 * <entry>Reserved for &prodname; internal needs</entry> 143 * <entry>&prodname;</entry> 144 * <entry>2010-01-28</entry> 145 * </row> 146 * <row> 147 * <entry><literal>na-desktop</literal></entry> 148 * <entry>NA Desktop I/O Provider</entry> 149 * <entry>&prodname;</entry> 150 * <entry>2009-12-16</entry> 151 * </row> 152 * <row> 153 * <entry><literal>na-gconf</literal></entry> 154 * <entry>NA GConf I/O Provider</entry> 155 * <entry>&prodname;</entry> 156 * <entry>2009-12-16</entry> 157 * </row> 158 * <row> 159 * <entry><literal>na-xml</literal></entry> 160 * <entry>NA XML module</entry> 161 * <entry>&prodname;</entry> 162 * <entry>2010-02-14</entry> 163 * </row> 164 * </tbody> 165 * </tgroup> 166 * </table> 167 * </refsect2> 168 * 169 * <refsect2> 170 * <title>Versions historic</title> 171 * <table> 172 * <title>Historic of the versions of the #NAIIOProvider interface</title> 173 * <tgroup rowsep="1" colsep="1" align="center" cols="3"> 174 * <colspec colname="na-version" /> 175 * <colspec colname="api-version" /> 176 * <colspec colname="current" /> 177 * <thead> 178 * <row> 179 * <entry>&prodname; version</entry> 180 * <entry>#NAIIOProvider interface version</entry> 181 * <entry></entry> 182 * </row> 183 * </thead> 184 * <tbody> 185 * <row> 186 * <entry>since 2.30</entry> 187 * <entry>1</entry> 188 * <entry>current version</entry> 189 * </row> 190 * </tbody> 191 * </tgroup> 192 * </table> 193 * </refsect2> 194 */ 195 196 #include "na-object-item.h" 197 198 G_BEGIN_DECLS 199 200 #define NA_TYPE_IIO_PROVIDER ( na_iio_provider_get_type()) 201 #define NA_IIO_PROVIDER( instance ) ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IIO_PROVIDER, NAIIOProvider )) 202 #define NA_IS_IIO_PROVIDER( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IIO_PROVIDER )) 203 #define NA_IIO_PROVIDER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IIO_PROVIDER, NAIIOProviderInterface )) 204 205 typedef struct _NAIIOProvider NAIIOProvider; 206 typedef struct _NAIIOProviderInterfacePrivate NAIIOProviderInterfacePrivate; 207 208 /** 209 * NAIIOProviderInterface: 210 * @get_version: [should] returns the version of this interface that the 211 * plugin implements. 212 * @get_id: [must] returns the internal id of the plugin. 213 * @get_name: [should] returns the public name of the plugin. 214 * @read_items: [should] reads items. 215 * @is_willing_to_write: [should] asks the plugin whether it is willing to write. 216 * @is_able_to_write: [should] asks the plugin whether it is able to write. 217 * @write_item: [should] writes an item. 218 * @delete_item: [should] deletes an item. 219 * @duplicate_data: [may] let the I/O provider duplicates its specific data. 220 * 221 * This defines the methods that a #NAIIOProvider may, should, or must 222 * implement. 223 */ 224 typedef struct { 225 /*< private >*/ 226 GTypeInterface parent; 227 NAIIOProviderInterfacePrivate *private; 228 229 /*< public >*/ 230 /** 231 * get_version: 232 * @instance: the NAIIOProvider provider. 233 * 234 * Nautilus-Actions calls this method each time it needs to know 235 * which version of this interface the plugin implements. 236 * 237 * If this method is not implemented by the plugin, 238 * Nautilus-Actions considers that the plugin only implements 239 * the version 1 of the NAIIOProvider interface. 240 * 241 * Return value: if implemented, this method must return the version 242 * number of this interface the I/O provider is supporting. 243 * 244 * Defaults to 1. 245 * 246 * Since: 2.30 247 */ 248 guint ( *get_version ) ( const NAIIOProvider *instance ); 249 250 /** 251 * get_id: 252 * @instance: the NAIIOProvider provider. 253 * 254 * The I/O provider must implement this method. 255 * 256 * Return value: the implementation must return the internal identifier 257 * of the I/O provider, as a newly allocated string which will be g_free() 258 * by the caller. 259 * 260 * Since: 2.30 261 */ 262 gchar * ( *get_id ) ( const NAIIOProvider *instance ); 263 264 /** 265 * get_name: 266 * @instance: the NAIIOProvider provider. 267 * 268 * Return value: if implemented, this method must return the display 269 * name of the I/O provider, as a newly allocated string which will be 270 * g_free() by the caller. 271 * 272 * This may be the name of the module itself, but this also may be a 273 * special name the modules gives to this interface. 274 * 275 * Defaults to an empty string. 276 * 277 * Since: 2.30 278 */ 279 gchar * ( *get_name ) ( const NAIIOProvider *instance ); 280 281 /** 282 * read_items: 283 * @instance: the NAIIOProvider provider. 284 * @messages: a pointer to a GSList list of strings; the provider 285 * may append messages to this list, but shouldn't reinitialize it. 286 * 287 * Reads the whole items list from the specified I/O provider. 288 * 289 * The I/O provider should implement this method, but if it doesn't, 290 * then this greatly lowerize the interest of this I/O provider (!). 291 * 292 * Return value: if implemented, this method must return a unordered 293 * flat GList of NAObjectItem-derived objects (menus or actions); 294 * the actions embed their own profiles. 295 * 296 * Defaults to NULL list. 297 * 298 * Since: 2.30 299 */ 300 GList * ( *read_items ) ( const NAIIOProvider *instance, GSList **messages ); 301 302 /** 303 * is_willing_to_write: 304 * @instance: the NAIIOProvider provider. 305 * 306 * The 'willing_to_write' property is intrinsic to the I/O provider. 307 * It is not supposed to make any assumption on the environment it is 308 * currently running on. 309 * This property just says that the developer/maintainer has released 310 * the needed code in order to update/create/delete NAObjectItem-derived 311 * objects. 312 * 313 * Note that even if this property is TRUE, there is yet many 314 * reasons for not being able to update/delete existing items or 315 * create new ones (see e.g. is_able_to_write() method below). 316 * 317 * Return value: if implemented, this method must return a boolean 318 * value, whose purpose is to let know to Nautilus-Actions whether 319 * this I/O provider is, or not, willing to write. 320 * 321 * Defaults to FALSE. 322 * 323 * Since: 2.30 324 */ 325 gboolean ( *is_willing_to_write )( const NAIIOProvider *instance ); 326 327 /** 328 * is_able_to_write: 329 * @instance: the NAIIOProvider provider. 330 * 331 * The 'able_to_write' property is a runtime one. 332 * When returning TRUE, the I/O provider insures that it has 333 * successfully checked that it was able to write some things 334 * down to its storage subsystem(s). 335 * 336 * The 'able_to_write' property is independent of the 337 * 'willing_to_write' above, though it is only checked if the 338 * I/O provider is actually willing to write. 339 * 340 * This condition is only relevant when trying to define new items, 341 * to see if a willing_to provider is actually able to do write 342 * operations. It it not relevant for updating/deleting already 343 * existing items as they have already checked their own runtime 344 * writability status when read from the storage subsystems. 345 * 346 * Note that even if this property is TRUE, there is yet many 347 * reasons for not being able to update/delete existing items or 348 * create new ones (see e.g. 'locked' user preference key). 349 * 350 * Return value: if implemented, this method must return a boolean 351 * value, whose purpose is to let know to Nautilus-Actions whether 352 * this I/O provider is eventually able to write. 353 * 354 * Defaults to FALSE. 355 * 356 * Since: 2.30 357 */ 358 gboolean ( *is_able_to_write ) ( const NAIIOProvider *instance ); 359 360 /** 361 * write_item: 362 * @instance: the NAIIOProvider provider. 363 * @item: a NAObjectItem-derived item, menu or action. 364 * @messages: a pointer to a GSList list of strings; the provider 365 * may append messages to this list, but shouldn't reinitialize it. 366 * 367 * Writes a new @item down to the privat underlying storage subsystem 368 * which happens to be managed by the I/O provider. 369 * 370 * There is no update_item function; it is the responsibility 371 * of the provider to delete the previous version of an item before 372 * actually writing the new one. 373 * 374 * The I/O provider should implement this method, or return 375 * FALSE in is_willing_to_write() method above. 376 * 377 * Return value: NA_IIO_PROVIDER_CODE_OK if the write operation 378 * was successful, or another code depending of the detected error. 379 * 380 * Since: 2.30 381 */ 382 guint ( *write_item ) ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages ); 383 384 /** 385 * delete_item: 386 * @instance: the NAIIOProvider provider. 387 * @item: a NAObjectItem-derived item, menu or action. 388 * @messages: a pointer to a GSList list of strings; the provider 389 * may append messages to this list, but shouldn't reinitialize it. 390 * 391 * Deletes an existing @item from the I/O subsystem. 392 * 393 * The I/O provider should implement this method, or return 394 * FALSE in is_willing_to_write() method above. 395 * 396 * Return value: NA_IIO_PROVIDER_CODE_OK if the delete operation was 397 * successful, or another code depending of the detected error. 398 * 399 * Since: 2.30 400 */ 401 guint ( *delete_item ) ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages ); 402 403 /** 404 * duplicate_data: 405 * @instance: the NAIIOProvider provider. 406 * @dest: a NAObjectItem-derived item, menu or action. 407 * @source: a NAObjectItem-derived item, menu or action. 408 * @messages: a pointer to a GSList list of strings; the provider 409 * may append messages to this list, but shouldn't reinitialize it. 410 * 411 * Nautilus-Actions typically calls this method while duplicating 412 * a NAObjectItem-derived object, in order to let the I/O provider 413 * duplicates itself specific data (if any) it may have set on 414 * @source object. 415 * 416 * Note that this does not duplicate in any way any 417 * NAObjectItem-derived object. We are just dealing here with 418 * the provider-specific data which may have been attached to 419 * the NAObjectItem-derived object. 420 * 421 * Return value: NA_IIO_PROVIDER_CODE_OK if the duplicate operation 422 * was successful, or another code depending of the detected error. 423 * 424 * Since: 2.30 425 */ 426 guint ( *duplicate_data ) ( const NAIIOProvider *instance, NAObjectItem *dest, const NAObjectItem *source, GSList **messages ); 427 } 428 NAIIOProviderInterface; 429 430 /* -- adding a new status here should imply also adding a new tooltip 431 * -- in na_io_provider_get_readonly_tooltip(). 432 */ 433 /** 434 * NAIIOProviderWritabilityStatus: 435 * @NA_IIO_PROVIDER_STATUS_WRITABLE: item and i/o provider are writable. 436 * @NA_IIO_PROVIDER_STATUS_UNAVAILABLE: unavailable i/o provider. 437 * @NA_IIO_PROVIDER_STATUS_INCOMPLETE_API: i/o provider has an incomplete write api. 438 * @NA_IIO_PROVIDER_STATUS_NOT_WILLING_TO: i/o provider is not willing to write. 439 * @NA_IIO_PROVIDER_STATUS_NOT_ABLE_TO: i/o provider is not able to write. 440 * @NA_IIO_PROVIDER_STATUS_LOCKED_BY_ADMIN: i/o provider has been locked by the administrator. 441 * @NA_IIO_PROVIDER_STATUS_LOCKED_BY_USER: i/o provider has been locked by the user. 442 * @NA_IIO_PROVIDER_STATUS_ITEM_READONLY: item is read-only. 443 * @NA_IIO_PROVIDER_STATUS_NO_PROVIDER_FOUND: no writable i/o provider found. 444 * @NA_IIO_PROVIDER_STATUS_LEVEL_ZERO: level zero is not writable. 445 * @NA_IIO_PROVIDER_STATUS_UNDETERMINED: unknwon reason (and probably a bug). 446 * 447 * The reasons for which an item may not be writable. 448 * 449 * Not all reasons are to be managed at the I/O provider level. 450 * Some are to be used only internally from &prodname; programs. 451 */ 452 typedef enum { 453 NA_IIO_PROVIDER_STATUS_WRITABLE = 0, 454 NA_IIO_PROVIDER_STATUS_UNAVAILABLE, 455 NA_IIO_PROVIDER_STATUS_INCOMPLETE_API, 456 NA_IIO_PROVIDER_STATUS_NOT_WILLING_TO, 457 NA_IIO_PROVIDER_STATUS_NOT_ABLE_TO, 458 NA_IIO_PROVIDER_STATUS_LOCKED_BY_ADMIN, 459 NA_IIO_PROVIDER_STATUS_LOCKED_BY_USER, 460 NA_IIO_PROVIDER_STATUS_ITEM_READONLY, 461 NA_IIO_PROVIDER_STATUS_NO_PROVIDER_FOUND, 462 NA_IIO_PROVIDER_STATUS_LEVEL_ZERO, 463 NA_IIO_PROVIDER_STATUS_UNDETERMINED, 464 /*< private >*/ 465 NA_IIO_PROVIDER_STATUS_LAST, 466 } 467 NAIIOProviderWritabilityStatus; 468 469 /* -- adding a new code here should imply also adding a new label 470 * -- in #na_io_provider_get_return_code_label(). 471 */ 472 /** 473 * NAIIOProviderOperationStatus: 474 * @NA_IIO_PROVIDER_CODE_OK: the requested operation has been successful. 475 * @NA_IIO_PROVIDER_CODE_PROGRAM_ERROR: a program error has been detected; 476 * you should open a bug in 477 * <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions">Bugzilla</ulink>. 478 * @NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN: the provider is not willing 479 * to do the requested action. 480 * @NA_IIO_PROVIDER_CODE_WRITE_ERROR: a write error has been detected. 481 * @NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR: the schemas could not be deleted. 482 * @NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR: the configuration could not be deleted. 483 * 484 * The return code of operations. 485 */ 486 typedef enum { 487 NA_IIO_PROVIDER_CODE_OK = 0, 488 NA_IIO_PROVIDER_CODE_PROGRAM_ERROR = 1 + NA_IIO_PROVIDER_STATUS_LAST, 489 NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN, 490 NA_IIO_PROVIDER_CODE_WRITE_ERROR, 491 NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR, 492 NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR, 493 } 494 NAIIOProviderOperationStatus; 495 496 GType na_iio_provider_get_type ( void ); 497 498 /* -- to be called by the I/O provider when an item has changed 499 */ 500 void na_iio_provider_item_changed( const NAIIOProvider *instance ); 501 502 G_END_DECLS 503 504 #endif /* __NAUTILUS_ACTIONS_API_NA_IIO_PROVIDER_H__ */ 505