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_IFACTORY_PROVIDER_H__ 31 #define __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__ 32 33 /** 34 * SECTION: ifactory-provider 35 * @title: NAIFactoryProvider 36 * @short_description: The Data Factory Provider Interface v 1 37 * @include: nautilus-actions/na-ifactory_provider.h 38 * 39 * &prodname; has to deal with a relatively great number of elementary datas, 40 * reading them from different supports, storing and displaying them, 41 * then re-writing these same datas, with several output formats, and so on. 42 * 43 * This has rapidly become a pain, if not just a bug generator. 44 * Each new data must be described, have a schema to be stored in 45 * (historical storage subsystem) GConf; import and export assistants 46 * must be carefully updated to export the new data... 47 * 48 * The #NAIFactoryProvider aims to simplify and organize all the work 49 * which must be done around each and every elementary data. It is based 50 * on three main things: 51 * 52 * <orderedlist> 53 * <listitem> 54 * <formalpara> 55 * <title>Elementary datas are banalized.</title> 56 * <para> 57 * whether they are a string, an integer, a boolean, a simple 58 * or double-linked list, each elementary data is encapsuled 59 * into a #NADataBoxed, small sort of structure (incidentally, 60 * which acts almost as the new GLib #GVariant, but too late, 61 * guys :)). 62 * </para> 63 * </formalpara> 64 * </listitem> 65 * <listitem> 66 * <formalpara> 67 * <title>Our objects are de-structured.</title> 68 * <para> 69 * Instead of organizing our elementary datas into structures, 70 * our objects are just flat lists of #NADataBoxed. 71 * </para> 72 * </formalpara> 73 * </listitem> 74 * <listitem> 75 * <formalpara> 76 * <title>A full, centralized, data dictionary is defined.</title> 77 * <para> 78 * Now that our elementary datas are banalized and de-structured, 79 * it is simple enough to describe each of these datas with all 80 * iss properties in one single, centralized, place. 81 * </para> 82 * </formalpara> 83 * </listitem> 84 * </orderedlist> 85 * 86 * Of course, I/O providers are good candidates to be users of this 87 * #NAIFactoryProvider interface. 88 * 89 * Without this interface, each and every I/O provider must, 90 * for example when reading an item, have the list of data to be 91 * read for each item, then read each individual data, then 92 * organize them in a I/O structure.. 93 * Each time a new data is added to an object, as e.g. a new condition, 94 * then all available I/O providers must be updated: read the data, 95 * write the data, then display the data, and so on.. 96 * 97 * With this #NAIFactoryProvider interface, the I/O provider has just to 98 * deal with reading/writing elementary types. It does need to know that 99 * it will have to read, name, tooltip, description. It just needs to know 100 * how to read a string. 101 * And while we do not introduce another data type, the I/O provider 102 * does not need any maintenance even if we add lot of new data, conditions 103 * labels, and so on. 104 * 105 * So, this is the interface used by data factory management system for 106 * providing serialization/unserialization services. This interface may 107 * be implemented by I/O providers which would take advantage of this 108 * system. 109 * 110 * <refsect2> 111 * <title>Versions historic</title> 112 * <table> 113 * <title>Historic of the versions of the #NAIFactoryProvider 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 * <thead> 119 * <row> 120 * <entry>&prodname; version</entry> 121 * <entry>#NAIFactoryProvider interface version</entry> 122 * <entry></entry> 123 * </row> 124 * </thead> 125 * <tbody> 126 * <row> 127 * <entry>since 2.30</entry> 128 * <entry>1</entry> 129 * <entry>current version</entry> 130 * </row> 131 * </tbody> 132 * </tgroup> 133 * </table> 134 * </refsect2> 135 */ 136 137 #include "na-data-boxed.h" 138 #include "na-ifactory-object.h" 139 #include "na-ifactory-provider-provider.h" 140 141 G_BEGIN_DECLS 142 143 #define NA_TYPE_IFACTORY_PROVIDER ( na_ifactory_provider_get_type()) 144 #define NA_IFACTORY_PROVIDER( instance ) ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IFACTORY_PROVIDER, NAIFactoryProvider )) 145 #define NA_IS_IFACTORY_PROVIDER( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IFACTORY_PROVIDER )) 146 #define NA_IFACTORY_PROVIDER_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IFACTORY_PROVIDER, NAIFactoryProviderInterface )) 147 148 typedef struct _NAIFactoryProviderInterfacePrivate NAIFactoryProviderInterfacePrivate; 149 150 /** 151 * NAIFactoryProviderInterface: 152 * @get_version: returns the version of this interface the plugin implements. 153 * @read_start: triggered just before reading an item. 154 * @read_data: reads an item. 155 * @read_done: triggered at the end of item reading. 156 * @write_start: triggered just before writing an item. 157 * @write_data: writes an item. 158 * @write_done: triggered at the end of item writing. 159 * 160 * This defines the interface that a #NAIFactoryProvider may implement. 161 */ 162 typedef struct { 163 /*< private >*/ 164 GTypeInterface parent; 165 NAIFactoryProviderInterfacePrivate *private; 166 167 /*< public >*/ 168 /** 169 * get_version: 170 * @instance: this #NAIFactoryProvider instance. 171 * 172 * Defaults to 1. 173 * 174 * Returns: the version of this interface supported by @instance implementation. 175 * 176 * Since: 2.30 177 */ 178 guint ( *get_version )( const NAIFactoryProvider *instance ); 179 180 /** 181 * read_start: 182 * @reader: this #NAIFactoryProvider instance. 183 * @reader_data: the data associated to this instance, as provided 184 * when na_ifactory_provider_read_item() was called. 185 * @object: the #NAIFactoryObject object which comes to be read. 186 * @messages: a pointer to a #GSList list of strings; the provider 187 * may append messages to this list, but shouldn't reinitialize it. 188 * 189 * API called by #NAIFactoryObject just before starting with reading data. 190 * 191 * Since: 2.30 192 */ 193 void ( *read_start ) ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, GSList **messages ); 194 195 /** 196 * read_data: 197 * @reader: this #NAIFactoryProvider instance. 198 * @reader_data: the data associated to this instance, as provided 199 * when na_ifactory_provider_read_item() was called. 200 * @object: the #NAIFactoryobject being unserialized. 201 * @def: a #NADataDef structure which identifies the data to be unserialized. 202 * @messages: a pointer to a #GSList list of strings; the provider 203 * may append messages to this list, but shouldn't reinitialize it. 204 * 205 * This method must be implemented in order any data be read. 206 * 207 * Returns: a newly allocated NADataBoxed which contains the read value. 208 * Should return %NULL if data is not found. 209 * 210 * Since: 2.30 211 */ 212 NADataBoxed * ( *read_data ) ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, const NADataDef *def, GSList **messages ); 213 214 /** 215 * read_done: 216 * @reader: this #NAIFactoryProvider instance. 217 * @reader_data: the data associated to this instance, as provided 218 * when na_ifactory_provider_read_item() was called. 219 * @object: the #NAIFactoryObject object which comes to be read. 220 * @messages: a pointer to a #GSList list of strings; the provider 221 * may append messages to this list, but shouldn't reinitialize it. 222 * 223 * API called by #NAIFactoryObject when all data have been read. 224 * Implementor may take advantage of this to do some cleanup. 225 * 226 * Since: 2.30 227 */ 228 void ( *read_done ) ( const NAIFactoryProvider *reader, void *reader_data, const NAIFactoryObject *object, GSList **messages ); 229 230 /** 231 * write_start: 232 * @writer: this #NAIFactoryProvider instance. 233 * @writer_data: the data associated to this instance. 234 * @object: the #NAIFactoryObject object which comes to be written. 235 * @messages: a pointer to a #GSList list of strings; the provider 236 * may append messages to this list, but shouldn't reinitialize it. 237 * 238 * API called by #NAIFactoryObject just before starting with writing data. 239 * 240 * Returns: a NAIIOProvider operation return code. 241 * 242 * Since: 2.30 243 */ 244 guint ( *write_start )( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages ); 245 246 /** 247 * write_data: 248 * @writer: this #NAIFactoryProvider instance. 249 * @writer_data: the data associated to this instance. 250 * @object: the #NAIFactoryObject object being written. 251 * @def: the description of the data to be written. 252 * @value: the #NADataBoxed to be written down. 253 * @messages: a pointer to a #GSList list of strings; the provider 254 * may append messages to this list, but shouldn't reinitialize it. 255 * 256 * Write the data embedded in @value down to @instance. 257 * 258 * This method must be implemented in order any data be written. 259 * 260 * Returns: a NAIIOProvider operation return code. 261 * 262 * Since: 2.30 263 */ 264 guint ( *write_data ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, const NADataBoxed *boxed, GSList **messages ); 265 266 /** 267 * write_done: 268 * @writer: this #NAIFactoryProvider instance. 269 * @writer_data: the data associated to this instance. 270 * @object: the #NAIFactoryObject object which comes to be written. 271 * @messages: a pointer to a #GSList list of strings; the provider 272 * may append messages to this list, but shouldn't reinitialize it. 273 * 274 * API called by #NAIFactoryObject when all data have been written. 275 * Implementor may take advantage of this to do some cleanup. 276 * 277 * Returns: a NAIIOProvider operation return code. 278 * 279 * Since: 2.30 280 */ 281 guint ( *write_done ) ( const NAIFactoryProvider *writer, void *writer_data, const NAIFactoryObject *object, GSList **messages ); 282 } 283 NAIFactoryProviderInterface; 284 285 GType na_ifactory_provider_get_type( void ); 286 287 void na_ifactory_provider_read_item ( const NAIFactoryProvider *reader, void *reader_data, NAIFactoryObject *object, GSList **messages ); 288 guint na_ifactory_provider_write_item( const NAIFactoryProvider *writer, void *writer_data, NAIFactoryObject *object, GSList **messages ); 289 290 G_END_DECLS 291 292 #endif /* __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__ */ 293