src/lib/dbus/E_DBus.h

   1 #ifndef E_DBUS_H
   2 #define E_DBUS_H
   3
   4 #define DBUS_API_SUBJECT_TO_CHANGE
   5
   6 #ifdef _WIN32
   7 # ifdef interface
   8 #  undef interface
   9 # endif
  10 #endif
  11
  12 #ifdef _WIN32
  13 # ifdef interface
  14 #  undef interface
  15 # endif
  16 # define DBUS_API_SUBJECT_TO_CHANGE
  17 #endif
  18
  19 #include <dbus/dbus.h>
  20 #include <Eina.h>
  21
  22 #ifdef EAPI
  23 # undef EAPI
  24 #endif
  25
  26 #ifdef _WIN32
  27 # ifdef EFL_EDBUS_BUILD
  28 #  ifdef DLL_EXPORT
  29 #   define EAPI __declspec(dllexport)
  30 #  else
  31 #   define EAPI
  32 #  endif /* ! DLL_EXPORT */
  33 # else
  34 #  define EAPI __declspec(dllimport)
  35 # endif /* ! EFL_EDBUS_BUILD */
  36 #else
  37 # ifdef __GNUC__
  38 #  if __GNUC__ >= 4
  39 #   define EAPI __attribute__ ((visibility("default")))
  40 #  else
  41 #   define EAPI
  42 #  endif
  43 # else
  44 #  define EAPI
  45 # endif
  46 #endif
  47
  48 /**
  49  * @mainpage EDbus
  50  *
  51  * @section edbus_intro_sec Introduction
  52  *
  53  * EDbus is a wrapper around the
  54  * <a href="http://www.freedesktop.org/wiki/Software/dbus">dbus</a>
  55  * library, which is a message bus system. It also implements a set of
  56  * specifications using dbus as interprocess communication.
  57  *
  58  * @section edbus_modules_sec Modules
  59  *
  60  * @li @ref EDbus_Group Wrapper around the dbus library, which
  61  * implementent an inter-process communication (IPC) system for
  62  * software applications to communicate with one another.
  63  * @li @ref EBluez_Group Implementation of the <a
  64  * href="http://www.bluez.org/">BlueZ</a> specifications, for wireless
  65  * communications with Bleutooth devices.
  66  * @li @ref EConnman_Group Implementation of the <a
  67  * href="http://connman.net/">connman</a> specifications, which
  68  * manages internet connections running the Linux operating system.
  69  * @li @ref EHal_Group Implementation of the <a
  70  * href="http://www.freedesktop.org/wiki/Software/hal">HAL</a>
  71  * specifications, which is a (software) layer between the hardware
  72  * devices of a computer and the softwares that run on that
  73  * computer (Hardware Abstraction Layer). HAL is deprecated, in favor
  74  * of DeviceKit.
  75  * @li @ref ENotify_Group To de described.
  76  * @li @ref EOfono_Group Implementation of the <a
  77  * href="http://ofono.org/">ofono</a> specifications, which is an
  78  * interface for mobile telephony applications.
  79  * @li @ref EUkit_Group Implementation of the <a
  80  * href="http://freedesktop.org/wiki/Software/DeviceKit">DeviceKit</a>
  81  * specifications, which is, like HAL, an Hardware Abstraction
  82  * Layer. DeviceKit is a replacement of the deprecated HAL system. It
  83  * has two submodules: UDisks, which manipulate storage devices, and
  84  * UPower, which manage power devices.
  85  */
  86
  87 /**
  88  * @defgroup EDbus_Group EDbus
  89  *
  90  * @{
  91  */
  92
  93 #define E_DBUS_FDO_BUS "org.freedesktop.DBus"
  94 #define E_DBUS_FDO_PATH "/org/freedesktop/DBus"
  95 #define E_DBUS_FDO_INTERFACE E_DBUS_FDO_BUS
  96 #define E_DBUS_FDO_INTERFACE_PROPERTIES "org.freedesktop.DBus.Properties"
  97
  98 #ifdef __cplusplus
  99 extern "C" {
 100 #endif
 101
 102 #define E_DBUS_VERSION_MAJOR 1
 103 #define E_DBUS_VERSION_MINOR 7
 104
 105    typedef struct _E_DBus_Version
 106      {
 107         int major;
 108         int minor;
 109         int micro;
 110         int revision;
 111      } E_DBus_Version;
 112
 113    EAPI extern E_DBus_Version *e_dbus_version;
 114
 115    EAPI extern int E_DBUS_DOMAIN_GLOBAL;
 116    EAPI extern int E_DBUS_EVENT_SIGNAL;
 117
 118    typedef struct E_DBus_Connection E_DBus_Connection;
 119    typedef struct E_DBus_Object E_DBus_Object;
 120    typedef struct E_DBus_Interface E_DBus_Interface;
 121    typedef struct E_DBus_Signal_Handler E_DBus_Signal_Handler;
 122
 123    typedef DBusMessage *(* E_DBus_Method_Cb)(E_DBus_Object *obj, DBusMessage *message);
 124    typedef void (*E_DBus_Method_Return_Cb) (void *data, DBusMessage *msg, DBusError *error);
 125    typedef void (*E_DBus_Signal_Cb) (void *data, DBusMessage *msg);
 126
 127    typedef void (*E_DBus_Object_Property_Get_Cb) (E_DBus_Object *obj, const char *property, int *type, void **value);
 128    typedef int  (*E_DBus_Object_Property_Set_Cb) (E_DBus_Object *obj, const char *property, int type, void *value);
 129
 130 /**
 131  * A callback function for a DBus call
 132  * @param user_data the data passed in to the method call
 133  * @param event_data a struct containing the return data.
 134  */
 135    typedef void (*E_DBus_Callback_Func) (void *user_data, void *method_return, DBusError *error);
 136    typedef void *(*E_DBus_Unmarshal_Func) (DBusMessage *msg, DBusError *err);
 137    typedef void (*E_DBus_Free_Func) (void *data);
 138
 139    typedef struct E_DBus_Callback E_DBus_Callback;
 140
 141
 142 /**
 143  * @brief Initialize e_dbus
 144  */
 145 EAPI int e_dbus_init(void);
 146
 147 /**
 148  * Shutdown e_dbus.
 149  */
 150 EAPI int e_dbus_shutdown(void);
 151
 152 /* setting up the connection */
 153
 154 /**
 155  * Retrieve a connection to the bus and integrate it with the ecore main loop.
 156  * @param type the type of bus to connect to, e.g. DBUS_BUS_SYSTEM or DBUS_BUS_SESSION
 157  */
 158 EAPI E_DBus_Connection *e_dbus_bus_get(DBusBusType type);
 159
 160    EAPI void e_dbus_connection_ref(E_DBus_Connection *conn);
 161
 162 /**
 163  * Integrate a DBus connection with the ecore main loop
 164  *
 165  * @param conn - a dbus connection
 166  */
 167 EAPI E_DBus_Connection *e_dbus_connection_setup(DBusConnection *conn);
 168
 169 /**
 170  * Close out a connection retrieved with e_dbus_bus_get()
 171  * @param conn the connection to close
 172  */
 173 EAPI void e_dbus_connection_close(E_DBus_Connection *conn);
 174
 175 /* receiving method calls */
 176    EAPI E_DBus_Interface *e_dbus_interface_new(const char *interface);
 177    EAPI void e_dbus_interface_ref(E_DBus_Interface *iface);
 178    EAPI void e_dbus_interface_unref(E_DBus_Interface *iface);
 179    EAPI void e_dbus_object_interface_attach(E_DBus_Object *obj, E_DBus_Interface *iface);
 180    EAPI void e_dbus_object_interface_detach(E_DBus_Object *obj, E_DBus_Interface *iface);
 181
 182 /**
 183  * Add a method to an object
 184  *
 185  * @param iface the E_DBus_Interface to which this method belongs
 186  * @param member the name of the method
 187  * @param signature  an optional message signature. if provided, then messages
 188  *                   with invalid signatures will be automatically rejected
 189  *                   (an Error response will be sent) and introspection data
 190  *                   will be available.
 191  *
 192  * @return 1 if successful, 0 if failed (e.g. no memory)
 193  */
 194 EAPI int e_dbus_interface_method_add(E_DBus_Interface *iface, const char *member, const char *signature, const char *reply_signature, E_DBus_Method_Cb func);
 195
 196 /**
 197  * Add a signal to an object
 198  *
 199  * @param iface the E_DBus_Interface to which this signal belongs
 200  * @param name  the name of the signal
 201  * @param signature  an optional message signature.
 202  *
 203  * @return 1 if successful, 0 if failed (e.g. no memory)
 204  */
 205 EAPI int e_dbus_interface_signal_add(E_DBus_Interface *iface, const char *name, const char *signature);
 206
 207 /**
 208  * Add a dbus object.
 209  *
 210  * @param conn the connection on with the object should listen
 211  * @param object_path a unique string identifying an object (e.g. org/enlightenment/WindowManager
 212  * @param data custom data to set on the object (retrievable via
 213  *             e_dbus_object_data_get())
 214  */
 215 EAPI E_DBus_Object *e_dbus_object_add(E_DBus_Connection *conn, const char *object_path, void *data);
 216
 217 /**
 218  * Free a dbus object
 219  *
 220  * @param obj the object to free
 221  */
 222 EAPI void e_dbus_object_free(E_DBus_Object *obj);
 223
 224 /**
 225  * @brief Fetch the data pointer for a dbus object
 226  * @param obj the dbus object
 227  */
 228 EAPI void *e_dbus_object_data_get(E_DBus_Object *obj);
 229
 230 /**
 231  * @brief Get the dbus connection of a dbus object
 232  * @param obj the dbus object
 233  */
 234 EAPI E_DBus_Connection *e_dbus_object_conn_get(E_DBus_Object *obj);
 235
 236 /**
 237  * @brief Get the path of a dbus object
 238  * @param obj the dbus object
 239  */
 240 EAPI const char *e_dbus_object_path_get(E_DBus_Object *obj);
 241
 242 /**
 243  * @brief Get the interfaces of a dbus object
 244  * @param obj the dbus object
 245  */
 246 EAPI const Eina_List *e_dbus_object_interfaces_get(E_DBus_Object *obj);
 247
 248 /**
 249  * @brief Sets the callback to fetch properties from an object
 250  * @param obj the object
 251  * @param func the callback
 252  */
 253 EAPI void e_dbus_object_property_get_cb_set(E_DBus_Object *obj, E_DBus_Object_Property_Get_Cb func);
 254
 255 /**
 256  * @brief Sets the callback to set properties on an object
 257  * @param obj the object
 258  * @param func the callback
 259  */
 260 EAPI void e_dbus_object_property_set_cb_set(E_DBus_Object *obj, E_DBus_Object_Property_Set_Cb func);
 261
 262
 263 /* sending method calls */
 264
 265 /**
 266  * @brief Send a DBus message with callbacks
 267  * @param conn The DBus connection
 268  * @param msg  The message to send
 269  * @param cb_return A callback function for returns (only used if @a msg is a method-call)
 270  * @param timeout   A timeout in milliseconds, after which a synthetic error will be generated
 271  * @param data custom data to pass in to the callback
 272  * @return a DBusPendingCall that can be used to cancel the current call
 273  */
 274 EAPI DBusPendingCall *e_dbus_message_send(E_DBus_Connection *conn, DBusMessage *msg, E_DBus_Method_Return_Cb cb_return, int timeout, void *data);
 275
 276    EAPI DBusPendingCall *e_dbus_method_call_send(E_DBus_Connection *conn, DBusMessage *msg, E_DBus_Unmarshal_Func unmarshal_func, E_DBus_Callback_Func cb_func, E_DBus_Free_Func free_func, int timeout, void *data);
 277
 278
 279 /* signal receiving */
 280
 281 /**
 282  * Add a signal handler
 283  *
 284  * @param conn the dbus connection
 285  * @param sender name of the signal's sender
 286  * @param path the object path of the signal's sender
 287  * @param interface the signal's interface
 288  * @param member the signal's name
 289  * @param cb_signal a callback to call when the signal is received
 290  * @param data custom data to pass in to the callback
 291  */
 292 EAPI E_DBus_Signal_Handler *e_dbus_signal_handler_add(E_DBus_Connection *conn, const char *sender, const char *path, const char *interface, const char *member, E_DBus_Signal_Cb cb_signal, void *data);
 293
 294 /**
 295  * Delete a signal handler
 296  *
 297  * @param conn the dbus connection
 298  * @param sh the handler to delete
 299  */
 300 EAPI void e_dbus_signal_handler_del(E_DBus_Connection *conn, E_DBus_Signal_Handler *sh);
 301
 302 /* standard dbus method calls */
 303
 304    EAPI DBusPendingCall *e_dbus_request_name(E_DBus_Connection *conn, const char *name,
 305                                              unsigned int flags,
 306                                              E_DBus_Method_Return_Cb cb_return,
 307                                              const void *data);
 308    EAPI DBusPendingCall *e_dbus_release_name(E_DBus_Connection *conn, const char *name,
 309                                              E_DBus_Method_Return_Cb cb_return,
 310                                              const void *data);
 311
 312    EAPI DBusPendingCall *e_dbus_get_name_owner(E_DBus_Connection *conn, const char *name,
 313                                                E_DBus_Method_Return_Cb cb_return,
 314                                                const void *data);
 315    EAPI DBusPendingCall *e_dbus_list_names(E_DBus_Connection *conn,
 316                                            E_DBus_Method_Return_Cb cb_return,
 317                                            const void *data);
 318    EAPI DBusPendingCall *e_dbus_list_activatable_names(E_DBus_Connection *conn,
 319                                                        E_DBus_Method_Return_Cb cb_return,
 320                                                        const void *data);
 321    EAPI DBusPendingCall *e_dbus_name_has_owner(E_DBus_Connection *conn, const char *name,
 322                                                E_DBus_Method_Return_Cb cb_return,
 323                                                const void *data);
 324    EAPI DBusPendingCall *e_dbus_start_service_by_name(E_DBus_Connection *conn, const char *name, unsigned int flags,
 325                                                       E_DBus_Method_Return_Cb cb_return,
 326                                                       const void *data);
 327
 328 /* standard methods calls on objects */
 329
 330 /**
 331  * Calls the Introspect method on a given bus and object path.
 332  * @param conn The dbus connection to use
 333  * @param bus The bus to call the method on
 334  * @param object_path The path of the bus to call on
 335  * @param cb_return The callback to call on reply from dbus
 336  * @param data The data to associate with the callback
 337  * @return A pending dbus call
 338  */
 339 EAPI DBusPendingCall *e_dbus_introspect(E_DBus_Connection *conn, const char *bus,
 340        const char *object_path, E_DBus_Method_Return_Cb cb_return, const void *data);
 341
 342 /**
 343  * Ping the dbus peer
 344  *
 345  * @param conn the dbus connection
 346  * @param destination the bus name that the object is on
 347  * @param path the object path
 348  * @param cb_return a callback for a successful return
 349  * @param data data to pass to the callbacks
 350  */
 351 EAPI DBusPendingCall *e_dbus_peer_ping(E_DBus_Connection *conn, const char *destination,
 352                                           const char *path, E_DBus_Method_Return_Cb cb_return,
 353                                           const void *data);
 354
 355 /**
 356  * Get the UUID of the peer
 357  *
 358  * @param conn the dbus connection
 359  * @param destination the bus name that the object is on
 360  * @param path the object path
 361  * @param cb_return a callback for a successful return
 362  * @param data data to pass to the callbacks
 363  */
 364 EAPI DBusPendingCall *e_dbus_peer_get_machine_id(E_DBus_Connection *conn,
 365                                                     const char *destination, const char *path,
 366                                                     E_DBus_Method_Return_Cb cb_return,
 367                                                     const void *data);
 368    EAPI DBusPendingCall *e_dbus_properties_get_all(E_DBus_Connection *conn, const char *destination,
 369                                                    const char *path, const char *interface,
 370                                                    E_DBus_Method_Return_Cb cb_return,
 371                                                    const void *data);
 372
 373 /**
 374  * Get the value of a property on an object
 375  *
 376  * @param conn the dbus connection
 377  * @param destination the bus name that the object is on
 378  * @param path the object path
 379  * @param interface the interface name of the property
 380  * @param property the name of the property
 381  * @param cb_return a callback for a successful return
 382  * @param data data to pass to the callbacks
 383  */
 384 EAPI DBusPendingCall *e_dbus_properties_get(E_DBus_Connection *conn, const char *destination,
 385                                                const char *path, const char *interface,
 386                                                const char *property,
 387                                                E_DBus_Method_Return_Cb cb_return,
 388                                                const void *data);
 389
 390 /**
 391  * Set the value of a property on an object
 392  *
 393  * @param conn the dbus connection
 394  * @param destination the bus name that the object is on
 395  * @param path the object path
 396  * @param interface the interface name of the property
 397  * @param property the name of the property
 398  * @param value_type the type of the property's value
 399  * @param value a pointer to the value
 400  * @param cb_return a callback for a successful return
 401  * @param data data to pass to the callbacks
 402  */
 403 EAPI DBusPendingCall *e_dbus_properties_set(E_DBus_Connection *conn, const char *destination,
 404                                                const char *path, const char *interface,
 405                                                const char *property, int value_type,
 406                                                const void *value, E_DBus_Method_Return_Cb cb_return,
 407                                                const void *data);
 408
 409
 410 /**
 411  * @brief Create a callback structure
 412  * @param cb_func the callback function
 413  * @param user_data data to pass to the callback
 414  */
 415 EAPI E_DBus_Callback *e_dbus_callback_new(E_DBus_Callback_Func cb_func, E_DBus_Unmarshal_Func unmarshal_func, E_DBus_Free_Func free_func, void *user_data);
 416
 417 /**
 418  * @brief Free a callback structure
 419  * @param callback the callback to free
 420  */
 421 EAPI void e_dbus_callback_free(E_DBus_Callback *callback);
 422    EAPI void e_dbus_callback_call(E_DBus_Callback *cb, void *data, DBusError *error);
 423    EAPI void *e_dbus_callback_unmarshal(E_DBus_Callback *cb, DBusMessage *msg, DBusError *err);
 424    EAPI void e_dbus_callback_return_free(E_DBus_Callback *callback, void *data);
 425
 426 #ifdef __cplusplus
 427 }
 428 #endif
 429
 430 /**
 431  * @}
 432  */
 433
 434 #endif