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