git.maemo.org Git - mdictionary/blob - include/ws_dbus.h

   1 /*
   2 This library is free software; you can redistribute it and/or
   3 modify it under the terms of the GNU Lesser General Public
   4 License as published by the Free Software Foundation;
   5 version 2.1 of the License.
   6
   7 This library is distributed in the hope that it will be useful,
   8 but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  10 Lesser General Public License for more details.
  11
  12 You should have received a copy of the GNU Lesser General Public
  13 License along with this library; if not, write to the Free Software
  14 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  15
  16 Copyright 2006 ComArch S.A.
  17 */
  18
  19 #ifndef _WS_DBUS
  20 #define _WS_DBUS
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 #include <libosso.h>
  27 #include <string.h>
  28 #include <dbus-1.0/dbus/dbus-protocol.h>
  29 #include <stdio.h>
  30 #include <stdlib.h>
  31 #include <glib-2.0/glib.h>
  32
  33 /** \brief Callback function definition
  34 *
  35 *@param error - pointer to a GError structure. Currently not used
  36 *@param words - GArray of osso_rpc_t structures containing sent data
  37 *@param user_data - data passed by user while setting the callback
  38 function with ::ws_dbus_set_cb
  39 *\sa ws_dbus_set_cb
  40 */
  41 typedef void (* ws_dbus_cb) (GError *error, GArray *words, gpointer user_data);
  42
  43 /** \brief This structure contains data vital for DBUS communication.
  44 *
  45 * These are for example both the local and remote addresses of the applications
  46 which are supposed to communicate. In this case they are the <I>GUI</I> and the
  47 <I>MANAGER</I>
  48 * The fields shouldn't be modified directly. It should be done by ws_dbus_config
  49  function
  50 *\sa ws_dbus_config
  51 */
  52 struct _WSDBusData
  53 {
  54         osso_context_t * context; ///<a pointer needed by osso_initiallize
  55
  56         gchar *service; ///<owner service path
  57         gchar *object; ///<owner object path
  58         gchar *iface; ///<owner interface path
  59
  60         gchar *remote_service; ///<remote service path
  61         gchar *remote_object; ///<remote object path
  62         gchar *remote_iface; ///<remote interface path
  63
  64         gchar *name; ///<Program name
  65         gchar *version; ///<Program version
  66
  67         GArray *cb_data;
  68 };
  69
  70 /**
  71 *\brief Informs whether the transmission succeeded or not
  72 */
  73 typedef enum
  74 {
  75         WS_DBUS_STATUS_OK = 0, ///<Transmission succeeded
  76         WS_DBUS_STATUS_ERROR ///<Transmission error
  77 } WSDBusStatus;
  78
  79 /**\brief Specifies the possible kinds of event notifications that can be sent via DBus
  80 */
  81 typedef enum
  82 {
  83         WS_DBUS_INFO_TERMINATE = 1, ///<GUI signal - terminate the application
  84         WS_DBUS_INFO_STOP_SEARCH, ///<GUI signal - stop the current search
  85         WS_DBUS_INFO_SEARCH_FINISHED, ///<Manager signal - informs the GUI, that there will be no more results returned
  86         WS_DBUS_INFO_CACHING, ///<Manager signal - informs the GUI, that caching has started
  87         WS_DBUS_INFO_CACHING_FINISHED, ///<Manager signal - informs the GUI, that caching has finished
  88         WS_DBUS_INFO_CONFIG_CHANGED, ///<GUI signal - informs the Manager about changes in the GConf configuration
  89         WS_DBUS_ERROR_INVALID_FILE_FORMAT, ///<Parser error - dictionary file has invalid format
  90         WS_DBUS_ERROR_FILE_NOT_FOUND, ///<Parser error - dictionary file not found
  91         WS_DBUS_ERROR_NO_PERMISSION, ///<Parser error - no permission to read the dictionary file
  92         WS_DBUS_ERROR_UNKNOWN, ///<Parser error - unknown error
  93         WS_DBUS_ERROR_OUT_OF_MEMORY, ///<Either the UI or the manager is out of memory
  94         WS_DBUS_ERROR_ENGINE_NOT_FOUND, ///<Manager error - dictionary engine module, couldn't be located
  95         //added by me
  96         WS_DBUS_ERROR_DICTIONARY_NOT_LOAD, ///<Manager sigal - informs the GUI,that history record can not be found because dictionary is not activate
  97         WS_DBUS_BOOKMARKS_ADDED_OK, ///<GUI signal - send if bookmark has been added succesfully
  98         WS_DBUS_BOOKMARKS_REMOVED_OK, ///<GUI signal - send if bookmark has been removed succesfully
  99         WS_DBUS_BOOKMARKS_ADDED_FAIL, ///<GUI signal - send if bookmark has not been added succesfully
 100         WS_DBUS_BOOKMARKS_REMOVED_FAIL, ///<GUI signal - send if bookmark has not been removed succesfully
 101         WS_DBUS_LOAD_BOOKMARK_FAILED, ///<GUI signal - blocks bookmarks
 102         WS_DBUS_BOOKMARK_MODE_ON,
 103         WS_DBUS_BOOKMARK_MODE_OFF,
 104         WS_DBUS_EXTRACT_FILE,
 105         WS_DBUS_EXTRACT_FILE_FINISHED
 106
 107 } WSDBusNotify;
 108
 109
 110 /**
 111 *\brief This structure is used for specifying the field of WSDBusData structure one would like to modify.
 112 *
 113 *It is used in the ws_dbus_config function. Its main purpose is to clarify D-BUS
 114  configuration.
 115 */
 116 typedef enum
 117 {
 118         WS_DBUS_CONFIG_SERVICE = 1,
 119         WS_DBUS_CONFIG_OBJECT,
 120         WS_DBUS_CONFIG_IFACE,
 121         WS_DBUS_CONFIG_REMOTE_SERVICE,
 122         WS_DBUS_CONFIG_REMOTE_OBJECT,
 123         WS_DBUS_CONFIG_REMOTE_IFACE
 124 } WSDBusConfig;
 125
 126 typedef struct _WSDBusData WSDBusData;
 127
 128
 129 /**\brief First function to be called in every program using this wrapper library
 130 *
 131 *This function is used for allocating memory for the WSDBusData structure and
 132 setting some basic parameters.
 133 *@param name - name of the application
 134 *@param version - app's version
 135 *@return pointer to WSDBusData structure\n
 136 *\sa ::WSDBusData
 137 */
 138 WSDBusData * ws_dbus_create (gchar *name, gchar *version);
 139
 140 /**\brief This function is used for setting dbus service/client parameters.
 141 *
 142 *These include the addresses of both remote and local apps communicating
 143 *@param ws_dbus_data - pointer to a structure uniquely identifying
 144 the application for DBus. The possible values of
 145 *this parameter are listed here: ::WSDBusConfig
 146 *@param field - the name of the variable, this function is supposed to set.
 147 *@param value - the value of the variable
 148 *@return WS_STATUS_OK - on success \n
 149 *WS_STATUS_ERROR - on error
 150 *\sa ::WSDBusConfig
 151 */
 152 WSDBusStatus ws_dbus_config (WSDBusData * ws_dbus_data,
 153                              WSDBusConfig field,
 154                              gchar *value);
 155
 156 /**
 157 *\brief Initialize D-BUS communication.
 158 *
 159 *It should be the called after <B>ws_dbus_create</B> and after setting all D-BUS
 160  parameters with the <B>ws_dbus_config</B> function.
 161 *The structure it returns is necessary to call out every function implemented in
 162  this wrapper library.
 163 *@param ws_dbus_data - it's a structure containing the unique paths to objects
 164 and interfaces to be registered in the DBus session daemon
 165 *@return WS_STATUS_OK - on success \n
 166 *WS_STATUS_ERROR - on error
 167 *\sa ::WSDBusConfig, ws_dbus_create, ws_dbus_config
 168 */
 169 WSDBusStatus ws_dbus_connect (WSDBusData * ws_dbus_data);
 170
 171 /**\brief Function deinitializing D-BUS wrapper library
 172 *
 173 *Before the program exits, all memory allocated by D-BUS should be freed.
 174 @param ws_dbus_data - pointer to a structure uniquely identifying the
 175 application for DBus
 176 *@return WS_STATUS_OK - on success \n
 177 *WS_STATUS_ERROR - on error
 178 */
 179
 180 void ws_dbus_destroy (WSDBusData * ws_dbus_data);
 181
 182 /**\brief This function is used for setting a callback function for some predefined signals.
 183 *
 184 *Some of the signals should be used only by the <I>GUI</I>, others by the
 185 <I>MANAGER</I>.
 186 *
 187 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 188 application for D-BUS
 189 *@param detailed_signal - string containing the signal name which will trigger
 190 the function passed in
 191 *the c_func parameter.
 192 *@param c_func - is a pointer to the signal handling function.
 193 *@param user_data - is the data passed directly to the signal handling function
 194 *
 195 *The predefined signal values for the GUI part are:
 196 *
 197 *       - <I>"return_words"</I> - used for receiving a list of words found by
 198 the <I>MANAGER</I>
 199 *       - <I>"return_translations"</I> - used for receiving a list of
 200 translations found by the <I>MANAGER</I>
 201 *       - <I>"signal"</I> - used for handling signals from the <I>MANAGER</I>.
 202 In this case they are mainly error signals.
 203 *
 204 *The predefined signal values for the MANAGER part are:
 205 *
 206 *       - <I>"find_word"</I> - used for receiving the word a user is looking for
 207 *       - <I>"find_translation"</I> - used for receiving the word a user needs
 208 to translate
 209 *       - <I>"signal"</I> - used for handling signals from the <I>GUI</I>.
 210 In this case they are termination and stop search signals.
 211 *
 212 *@return WS_STATUS_OK - on success \n
 213 *WS_STATUS_ERROR - on error
 214 *\sa ::WSDBusConfig \n
 215 *#ws_dbus_cb
 216 */
 217
 218 WSDBusStatus ws_dbus_set_cb (WSDBusData * ws_dbus_data,
 219                              gchar * detailed_signal,
 220                              gpointer c_func,
 221                              gpointer user_data);
 222
 223 /**\brief Send signal to the remote application
 224 *
 225 *A purpose of this function is to send signals between both ends.
 226 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 227 application for D-BUS
 228 *@param ws_dbus_info - the command or information to send to the other side.
 229 *\sa #WSDBusNotify
 230 */
 231
 232 WSDBusStatus ws_dbus_notify (WSDBusData * ws_dbus_data,
 233                              WSDBusNotify ws_dbus_info);
 234
 235 /**\brief Find a word in the dictionary
 236 *
 237 *This is run by <I>GUI</I>. This function is used for finding a word, the user
 238 is searching for. It should be
 239 *called after the user enters a word in the text field and presses the search
 240 button.
 241 *
 242 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 243 application for DBus
 244 *@param word - the word, user is looking for
 245 *@return WS_STATUS_OK - on success \n
 246 *WS_STATUS_ERROR - on error
 247 */
 248
 249 WSDBusStatus ws_dbus_client_find_word (WSDBusData * ws_dbus_data, gchar * word);
 250
 251 /**\brief Find translation of a word
 252 *
 253 *This is run by <I>GUI</I>. When a user selects a word from the words list,
 254 this function is called in order
 255 *to find the translation of the selected word.
 256 *
 257 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 258 application for DBus
 259 *@param word - a word, for which the user wishes to find the translation
 260 *@return WS_STATUS_OK - on success \n
 261 *WS_STATUS_ERROR - on error
 262 */
 263
 264 WSDBusStatus ws_dbus_client_find_translation (WSDBusData * ws_dbus_data,
 265                                               gchar * word);
 266
 267 /**\brief Return a list of words
 268 *
 269 *Transmits a list of words found by the parsing engine/engines
 270 *
 271 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 272 application for DBus
 273 *@param words - a GArray of words, the engine thread returned
 274 *@return WS_STATUS_OK - on success \n
 275 *WS_STATUS_ERROR - on error
 276 */
 277
 278 WSDBusStatus ws_dbus_server_return_words  (WSDBusData * ws_dbus_data,
 279                                            GArray * words);
 280
 281 /**
 282 *This function is used for returning the list of words the parsing thread has
 283 *found. It should be run after the last thread finishes the search, because it
 284 also
 285 *signalizes the GUI that the search has finished.
 286 *
 287 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 288 application for DBus
 289 *@param words - a GArray of words, the engine thread returned
 290 *@return WS_STATUS_OK - on success \n
 291 *WS_STATUS_ERROR - on error
 292 */
 293
 294 /**\brief Return a translation of a given word
 295 *
 296 *This is run by the <I>MANAGER</I>. It returns a translation of a
 297 previously sent word
 298 *
 299 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 300 application for DBus
 301 *@param translation - a string containing the word's translation
 302 *@return WS_STATUS_OK - on success \n
 303 *WS_STATUS_ERROR - on error
 304 */
 305
 306 WSDBusStatus ws_dbus_server_return_translations (WSDBusData * ws_dbus_data,
 307                                                  gchar * translation);
 308
 309 /**
 310 *This function is used for returning the list of translations the parsing thread
 311 *finds. It should be ran after the *last thread finishes the search, because it
 312 also
 313 *signalizes the GUI that the search has finished.
 314 *
 315 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 316 application for DBus
 317 *@param translation - a string containing the word's translation
 318 *@return WS_STATUS_OK - on success \n
 319 *WS_STATUS_ERROR - on error
 320 */
 321
 322 /** \brief Sends an address of data to transmit
 323 *
 324 *Function used in order to increase the speed of data transmission.
 325 For now it's been added just for testing purposes.
 326 *The goal is to use the main advantage of threads, that is memory sharing.
 327 If <I>GUI</I> and <I>MANAGER</I> are in the
 328 *same memory area, the data pointers also stay in the same memory area.
 329 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 330 application for DBus
 331 *@param method - name of the method of the remote object to call
 332 *@param data_address - address of the data
 333 *@return WS_STATUS_OK - on success \n
 334 *WS_STATUS_ERROR - on error
 335 */
 336
 337 WSDBusStatus ws_dbus_send_ptrtodata (WSDBusData * ws_dbus_data,
 338                                      gchar *method,
 339                                      gulong data_address);
 340
 341 /**\brief Splits the data from buffer generated by ::ws_dbus_concat_data
 342 *
 343 *Function used in order to increase the speed of data transmission.
 344 For now it's been added just for testing purposes.
 345 *It ommits the limit of D-BUS message fields in one message.
 346 *@param buffer - pointer to strings concatenated by ws_dbus_concat_data
 347 *@return GArray of strings
 348 */
 349
 350 GArray * ws_dbus_split_data (gpointer buffer);
 351
 352 /**\brief Concatenates data from a GArray to one long buffer ::ws_dbus_split_data
 353 *
 354 *Function used in order to increase the speed of data transmission.
 355 For now it's been added just for testing purposes.
 356 *It ommits the limit of D-BUS message fields in one message.
 357 *@param garray - a GArray to be concatenated
 358 *@return pointer to a buffer
 359 */
 360
 361 gpointer ws_dbus_concat_data (GArray *garray);
 362
 363 WSDBusStatus ws_dbus_update_progressbar (WSDBusData * ws_dbus_data,
 364                                          double progress);
 365
 366 WSDBusStatus ws_dbus_client_search_in_history (WSDBusData * ws_dbus_data,
 367                                                gchar * word);
 368
 369 /**\brief Add bookmark
 370 *
 371 *This is run by <I>GUI</I>. When a user selects a word from the words list,
 372 this function is called in order
 373 *to find the translation of the selected word.
 374 *
 375 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 376 application for DBus
 377 *@param word - a word, for which the user wishes to find the translation
 378 *@return WS_STATUS_OK - on success \n
 379 *WS_STATUS_ERROR - on error
 380 */
 381
 382 WSDBusStatus ws_dbus_add_bookmark (WSDBusData * ws_dbus_data, gchar * word, gchar *translation);
 383
 384 /**\brief Remove a bookmark
 385 *
 386 *This is run by <I>GUI</I>. When a user selects a word from the words list,
 387 this function is called in order
 388 *to find the translation of the selected word.
 389 *
 390 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 391 application for DBus
 392 *@param word - a word, for which the user wishes to find the translation
 393 *@return WS_STATUS_OK - on success \n
 394 *WS_STATUS_ERROR - on error
 395 */
 396
 397 WSDBusStatus ws_dbus_remove_bookmark (WSDBusData * ws_dbus_data, gchar * word);
 398
 399 /**\brief Send a message for GUI to display it
 400 *
 401 *This is run by <I>MANAGER</I>. When a user selects a word from the words list,
 402 this function is called in order
 403 *to find the translation of the selected word.
 404 *
 405 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 406 application for DBus
 407 *@param word - a word, for which the user wishes to find the translation
 408 *@return WS_STATUS_OK - on success \n
 409 *WS_STATUS_ERROR - on error
 410 */
 411
 412 WSDBusStatus ws_dbus_send_message (WSDBusData* ws_dbus_data, gchar * word);
 413
 414 WSDBusStatus ws_dbus_extract_dictionary(WSDBusData* ws_dbus_data,
 415                                         gchar* path);
 416
 417 WSDBusStatus ws_dbus_server_return_extracted_dict(WSDBusData* ws_dbus_data,
 418                                         gchar* path);
 419
 420 #ifdef __cplusplus
 421 }
 422 #endif
 423
 424 #endif