vcs.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 <dbus/dbus-protocol.h>
  28 #include <string.h>
  29 #include <dbus-1.0/dbus/dbus-protocol.h>
  30 #include <stdio.h>
  31 #include <stdlib.h>
  32 #include <glib-2.0/glib.h>
  33
  34 /**\brief Callback function definition
  35 *
  36 *@param error - pointer to a GError structure. Currently not used
  37 *@param words - GArray of osso_rpc_t structures containing sent data
  38 *@param user_data - data passed by user while setting the callback
  39 function with ::ws_dbus_set_cb
  40 *\sa ws_dbus_set_cb
  41 */
  42 typedef void (* ws_dbus_cb) (GError *error, gpointer data, gpointer user_data);
  43
  44 /**\brief This structure contains data vital for DBUS communication.
  45 *
  46 * These are for example both the local and remote addresses of the applications
  47 which are supposed to communicate. In this case they are the <I>GUI</I> and the
  48 <I>MANAGER</I>
  49 * The fields shouldn't be modified directly. It should be done by ws_dbus_config
  50  function
  51 *\sa ws_dbus_config
  52 */
  53
  54 typedef enum
  55 {
  56         WS_DBUS_TYPE_STRING = DBUS_TYPE_STRING,
  57         WS_DBUS_TYPE_INT = DBUS_TYPE_INT32,
  58         WS_DBUS_TYPE_UINT  = DBUS_TYPE_UINT32,
  59         WS_DBUS_TYPE_BOOLEAN  = DBUS_TYPE_BOOLEAN,
  60         WS_DBUS_TYPE_DOUBLE  = DBUS_TYPE_DOUBLE,
  61         WS_DBUS_TYPE_INVALID  = DBUS_TYPE_INVALID,
  62         WS_DBUS_TYPE_GARRAY = ((int) 'a'),
  63         WS_DBUS_TYPE_SIGNAL = DBUS_TYPE_INT32
  64 } WSDBusDataType;
  65
  66 struct _WSDBusData
  67 {
  68         osso_context_t * context; ///<a pointer needed by osso_initiallize
  69
  70         gchar *service; ///<owner service path
  71         gchar *object; ///<owner object path
  72         gchar *iface; ///<owner interface path
  73
  74         gchar *remote_service; ///<remote service path
  75         gchar *remote_object; ///<remote object path
  76         gchar *remote_iface; ///<remote interface path
  77
  78         gchar *name; ///<Program name
  79         gchar *version; ///<Program version
  80
  81         GArray *method_data;
  82         GArray *remote_method_data;
  83 };
  84
  85 /**
  86 *\brief Informs whether the transmission succeeded or not
  87 */
  88 typedef enum
  89 {
  90         WS_DBUS_STATUS_OK = 0, ///<Transmission succeeded
  91         WS_DBUS_STATUS_ERROR ///<Transmission error
  92 } WSDBusStatus;
  93
  94 /**\brief Specifies the possible kinds of event notifications that can be sent via DBus
  95 */
  96 typedef enum
  97 {
  98         WS_DBUS_INFO_TERMINATE = 1, ///<GUI signal - terminate the application
  99         WS_DBUS_INFO_STOP_SEARCH, ///<GUI signal - stop the current search
 100         WS_DBUS_INFO_SEARCH_FINISHED, ///<Manager signal - informs the GUI, that there will be no more results returned
 101         WS_DBUS_INFO_CACHING, ///<Manager signal - informs the GUI, that caching has started
 102         WS_DBUS_INFO_CACHING_FINISHED, ///<Manager signal - informs the GUI, that caching has finished
 103         WS_DBUS_INFO_CONFIG_CHANGED, ///<GUI signal - informs the Manager about changes in the GConf configuration
 104         WS_DBUS_ERROR_INVALID_FILE_FORMAT, ///<Parser error - dictionary file has invalid format
 105         WS_DBUS_ERROR_FILE_NOT_FOUND, ///<Parser error - dictionary file not found
 106         WS_DBUS_ERROR_NO_PERMISSION, ///<Parser error - no permission to read the dictionary file
 107         WS_DBUS_ERROR_UNKNOWN, ///<Parser error - unknown error
 108         WS_DBUS_ERROR_OUT_OF_MEMORY, ///<Either the UI or the manager is out of memory
 109         WS_DBUS_ERROR_ENGINE_NOT_FOUND, ///<Manager error - dictionary engine module, couldn't be located
 110         //added by me
 111         WS_DBUS_ERROR_DICTIONARY_NOT_LOAD, ///<Manager sigal - informs the GUI,that history record can not be found because dictionary is not activate
 112         WS_DBUS_BOOKMARKS_ADDED_OK, ///<GUI signal - send if bookmark has been added succesfully
 113         WS_DBUS_BOOKMARKS_REMOVED_OK, ///<GUI signal - send if bookmark has been removed succesfully
 114         WS_DBUS_BOOKMARKS_ADDED_FAIL, ///<GUI signal - send if bookmark has not been added succesfully
 115         WS_DBUS_BOOKMARKS_REMOVED_FAIL, ///<GUI signal - send if bookmark has not been removed succesfully
 116         WS_DBUS_LOAD_BOOKMARK_FAILED, ///<GUI signal - blocks bookmarks
 117         WS_DBUS_BOOKMARK_MODE_ON,
 118         WS_DBUS_BOOKMARK_MODE_OFF,
 119         WS_DBUS_EXTRACT_FILE,
 120         WS_DBUS_EXTRACT_FILE_FINISHED,
 121         WS_DBUS_WORDS_LIST_STARTED,
 122         WS_DBUS_TRANSLATION_STARTED,
 123         WS_DBUS_WORDS_LIST_FINISHED,
 124         WS_DBUS_TRANSLATION_FINISHED,
 125         WS_DBUS_WORDS_LIST_FULL,
 126         WS_DBUS_WORDS_LIST_FILLED_NOT_FULL
 127
 128 } WSDBusNotify;
 129
 130
 131 /**
 132 *\brief This structure is used for specifying the field of WSDBusData structure one would like to modify.
 133 *
 134 *It is used in the ws_dbus_config function. Its main purpose is to clarify D-BUS
 135  configuration.
 136 */
 137 typedef enum
 138 {
 139         WS_DBUS_CONFIG_SERVICE = 1,
 140         WS_DBUS_CONFIG_OBJECT,
 141         WS_DBUS_CONFIG_IFACE,
 142         WS_DBUS_CONFIG_REMOTE_SERVICE,
 143         WS_DBUS_CONFIG_REMOTE_OBJECT,
 144         WS_DBUS_CONFIG_REMOTE_IFACE
 145 } WSDBusConfig;
 146
 147 typedef struct _WSDBusData WSDBusData;
 148
 149
 150 /**\brief First function to be called in every program using this wrapper library
 151 *
 152 *This function is used for allocating memory for the WSDBusData structure and
 153 setting some basic parameters.
 154 *@param name - name of the application
 155 *@param version - app's version
 156 *@return pointer to WSDBusData structure\n
 157 *\sa ::WSDBusData
 158 */
 159 WSDBusData * ws_dbus_create (gchar *name, gchar *version);
 160
 161 /**\brief This function is used for setting dbus service/client parameters.
 162 *
 163 *These include the addresses of both remote and local apps communicating
 164 *@param ws_dbus_data - pointer to a structure uniquely identifying
 165 the application for DBus. The possible values of
 166 *this parameter are listed here: ::WSDBusConfig
 167 *@param field - the name of the variable, this function is supposed to set.
 168 *@param value - the value of the variable
 169 *@return WS_STATUS_OK - on success \n
 170 *WS_STATUS_ERROR - on error
 171 *\sa ::WSDBusConfig
 172 */
 173 WSDBusStatus ws_dbus_config (WSDBusData * ws_dbus_data,
 174                              WSDBusConfig field,
 175                              gchar *value);
 176
 177 /**
 178 *\brief Initialize D-BUS communication.
 179 *
 180 *It should be the called after <B>ws_dbus_create</B> and after setting all D-BUS
 181  parameters with the <B>ws_dbus_config</B> function.
 182 *The structure it returns is necessary to call out every function implemented in
 183  this wrapper library.
 184 *@param ws_dbus_data - it's a structure containing the unique paths to objects
 185 and interfaces to be registered in the DBus session daemon
 186 *@return WS_STATUS_OK - on success \n
 187 *WS_STATUS_ERROR - on error
 188 *\sa ::WSDBusConfig, ws_dbus_create, ws_dbus_config
 189 */
 190 WSDBusStatus ws_dbus_connect (WSDBusData * ws_dbus_data);
 191
 192 /**\brief Function deinitializing D-BUS wrapper library
 193 *
 194 *Before the program exits, all memory allocated by D-BUS should be freed.
 195 @param ws_dbus_data - pointer to a structure uniquely identifying the
 196 application for DBus
 197 *@return WS_STATUS_OK - on success \n
 198 *WS_STATUS_ERROR - on error
 199 */
 200
 201 void ws_dbus_destroy (WSDBusData * ws_dbus_data);
 202
 203 /**\brief This function is used for setting a callback function for some predefined signals.
 204 *
 205 *Some of the signals should be used only by the <I>GUI</I>, others by the
 206 <I>MANAGER</I>.
 207 *
 208 *@param ws_dbus_data - pointer to a structure uniquely identifying the
 209 application for D-BUS
 210 *@param detailed_signal - string containing the signal name which will trigger
 211 the function passed in
 212 *the c_func parameter.
 213 *@param c_func - is a pointer to the signal handling function.
 214 *@param user_data - is the data passed directly to the signal handling function
 215 *
 216 *The predefined signal values for the GUI part are:
 217 *
 218 *       - <I>"return_words"</I> - used for receiving a list of words found by
 219 the <I>MANAGER</I>
 220 *       - <I>"return_translations"</I> - used for receiving a list of
 221 translations found by the <I>MANAGER</I>
 222 *       - <I>"signal"</I> - used for handling signals from the <I>MANAGER</I>.
 223 In this case they are mainly error signals.
 224 *
 225 *The predefined signal values for the MANAGER part are:
 226 *
 227 *       - <I>"find_word"</I> - used for receiving the word a user is looking for
 228 *       - <I>"find_translation"</I> - used for receiving the word a user needs
 229 to translate
 230 *       - <I>"signal"</I> - used for handling signals from the <I>GUI</I>.
 231 In this case they are termination and stop search signals.
 232 *
 233 *@return WS_STATUS_OK - on success \n
 234 *WS_STATUS_ERROR - on error
 235 *\sa ::WSDBusConfig \n
 236 *#ws_dbus_cb
 237 */
 238
 239 WSDBusStatus ws_dbus_set_cb (WSDBusData * ws_dbus_data,
 240                              gchar * detailed_signal,
 241                              gpointer c_func,
 242                              gpointer user_data);
 243
 244 WSDBusStatus ws_dbus_add_method (WSDBusData * ws_dbus_data, gchar *method, ...);
 245
 246
 247 WSDBusStatus ws_dbus_call_method (WSDBusData * ws_dbus_data, gchar *method,
 248                                   ...);
 249
 250 void ws_dbus_multipleargs_test (WSDBusData * ws_dbus_data, gchar *method, ...);
 251
 252 #define ws_dbus_notify(structure,arg)   ws_dbus_call_method(structure,"signal",WS_DBUS_TYPE_SIGNAL,arg,WS_DBUS_TYPE_INVALID)
 253
 254 #define ws_dbus_client_find_word(structure,arg) ws_dbus_call_method(structure,"find_word",WS_DBUS_TYPE_STRING,arg,WS_DBUS_TYPE_INVALID)
 255
 256 #define ws_dbus_client_find_translation(structure,arg)  ws_dbus_call_method(structure,"find_translation",WS_DBUS_TYPE_STRING,arg,WS_DBUS_TYPE_INVALID)
 257
 258 #define ws_dbus_client_add_bookmark(structure,arg1,arg2)        ws_dbus_call_method(structure,"add_bookmark",WS_DBUS_TYPE_STRING,arg1,WS_DBUS_TYPE_STRING,arg2,WS_DBUS_TYPE_INVALID)
 259
 260 #define ws_dbus_client_remove_bookmark(structure,arg)   ws_dbus_call_method(structure,"remove_bookmark",WS_DBUS_TYPE_STRING,arg,WS_DBUS_TYPE_INVALID)
 261
 262 #define ws_dbus_client_extract_dictionary(structure,arg)                ws_dbus_call_method(structure,"extract_dictionary",WS_DBUS_TYPE_STRING,arg,WS_DBUS_TYPE_INVALID)
 263
 264 #define ws_dbus_server_return_extracted_dict(structure,arg)     ws_dbus_call_method(structure,"return_extracted_dict",WS_DBUS_TYPE_STRING,arg,WS_DBUS_TYPE_INVALID)
 265
 266 #define ws_dbus_server_return_words(structure,arg)      ws_dbus_call_method(structure,"return_words",WS_DBUS_TYPE_GARRAY,arg,WS_DBUS_TYPE_INVALID)
 267
 268 #define ws_dbus_server_return_translations(structure,arg)       ws_dbus_call_method(structure,"return_translations",WS_DBUS_TYPE_STRING,arg,WS_DBUS_TYPE_INVALID)
 269
 270 #define ws_dbus_server_update_progressbar(structure,arg)        ws_dbus_call_method(structure,"update_progressbar",WS_DBUS_TYPE_DOUBLE,arg,WS_DBUS_TYPE_INVALID)
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif