32920fa44b0c2db42b1698f174338f66011be117
[framework/uifw/edbus.git] / 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