* @{
*/
+#define E_DBUS_FDO_BUS "org.freedesktop.DBus"
+#define E_DBUS_FDO_PATH "/org/freedesktop/DBus"
+#define E_DBUS_FDO_INTERFACE E_DBUS_FDO_BUS
+#define E_DBUS_FDO_INTERFACE_PROPERTIES "org.freedesktop.DBus.Properties"
+
#ifdef __cplusplus
extern "C" {
#endif
+
+#define E_DBUS_VERSION_MAJOR 1
+#define E_DBUS_VERSION_MINOR 0
+
+ typedef struct _E_DBus_Version
+ {
+ int major;
+ int minor;
+ int micro;
+ int revision;
+ } E_DBus_Version;
+
+ EAPI extern E_DBus_Version *e_dbus_version;
+
EAPI extern int E_DBUS_DOMAIN_GLOBAL;
EAPI extern int E_DBUS_EVENT_SIGNAL;
typedef struct E_DBus_Callback E_DBus_Callback;
- EAPI int e_dbus_init(void);
- EAPI int e_dbus_shutdown(void);
+
+/**
+ * @brief Initialize e_dbus
+ */
+EAPI int e_dbus_init(void);
+
+/**
+ * Shutdown e_dbus.
+ */
+EAPI int e_dbus_shutdown(void);
/* setting up the connection */
- EAPI E_DBus_Connection *e_dbus_bus_get(DBusBusType type);
+
+/**
+ * Retrieve a connection to the bus and integrate it with the ecore main loop.
+ * @param type the type of bus to connect to, e.g. DBUS_BUS_SYSTEM or DBUS_BUS_SESSION
+ */
+EAPI E_DBus_Connection *e_dbus_bus_get(DBusBusType type);
EAPI void e_dbus_connection_ref(E_DBus_Connection *conn);
- EAPI E_DBus_Connection *e_dbus_connection_setup(DBusConnection *conn);
- EAPI void e_dbus_connection_close(E_DBus_Connection *conn);
+
+/**
+ * Integrate a DBus connection with the ecore main loop
+ *
+ * @param conn - a dbus connection
+ */
+EAPI E_DBus_Connection *e_dbus_connection_setup(DBusConnection *conn);
+
+/**
+ * Close out a connection retrieved with e_dbus_bus_get()
+ * @param conn the connection to close
+ */
+EAPI void e_dbus_connection_close(E_DBus_Connection *conn);
/* receiving method calls */
EAPI E_DBus_Interface *e_dbus_interface_new(const char *interface);
EAPI void e_dbus_interface_unref(E_DBus_Interface *iface);
EAPI void e_dbus_object_interface_attach(E_DBus_Object *obj, E_DBus_Interface *iface);
EAPI void e_dbus_object_interface_detach(E_DBus_Object *obj, E_DBus_Interface *iface);
- 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);
+
+/**
+ * Add a method to an object
+ *
+ * @param iface the E_DBus_Interface to which this method belongs
+ * @param member the name of the method
+ * @param signature an optional message signature. if provided, then messages
+ * with invalid signatures will be automatically rejected
+ * (an Error response will be sent) and introspection data
+ * will be available.
+ *
+ * @return 1 if successful, 0 if failed (e.g. no memory)
+ */
+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);
- EAPI int e_dbus_interface_signal_add(E_DBus_Interface *iface, const char *name, const char *signature);
+
+/**
+ * Add a signal to an object
+ *
+ * @param iface the E_DBus_Interface to which this signal belongs
+ * @param name the name of the signal
+ * @param signature an optional message signature.
+ *
+ * @return 1 if successful, 0 if failed (e.g. no memory)
+ */
+EAPI int e_dbus_interface_signal_add(E_DBus_Interface *iface, const char *name, const char *signature);
- EAPI E_DBus_Object *e_dbus_object_add(E_DBus_Connection *conn, const char *object_path, void *data);
- EAPI void e_dbus_object_free(E_DBus_Object *obj);
- EAPI void *e_dbus_object_data_get(E_DBus_Object *obj);
- EAPI E_DBus_Connection *e_dbus_object_conn_get(E_DBus_Object *obj);
- EAPI const char *e_dbus_object_path_get(E_DBus_Object *obj);
- EAPI const Eina_List *e_dbus_object_interfaces_get(E_DBus_Object *obj);
+
+/**
+ * Add a dbus object.
+ *
+ * @param conn the connection on with the object should listen
+ * @param object_path a unique string identifying an object (e.g. org/enlightenment/WindowManager
+ * @param data custom data to set on the object (retrievable via
+ * e_dbus_object_data_get())
+ */
+EAPI E_DBus_Object *e_dbus_object_add(E_DBus_Connection *conn, const char *object_path, void *data);
+
+/**
+ * Free a dbus object
+ *
+ * @param obj the object to free
+ */
+EAPI void e_dbus_object_free(E_DBus_Object *obj);
+
+/**
+ * @brief Fetch the data pointer for a dbus object
+ * @param obj the dbus object
+ */
+EAPI void *e_dbus_object_data_get(E_DBus_Object *obj);
+
+/**
+ * @brief Get the dbus connection of a dbus object
+ * @param obj the dbus object
+ */
+EAPI E_DBus_Connection *e_dbus_object_conn_get(E_DBus_Object *obj);
+
+/**
+ * @brief Get the path of a dbus object
+ * @param obj the dbus object
+ */
+EAPI const char *e_dbus_object_path_get(E_DBus_Object *obj);
+
+/**
+ * @brief Get the interfaces of a dbus object
+ * @param obj the dbus object
+ */
+EAPI const Eina_List *e_dbus_object_interfaces_get(E_DBus_Object *obj);
- EAPI void e_dbus_object_property_get_cb_set(E_DBus_Object *obj, E_DBus_Object_Property_Get_Cb func);
- EAPI void e_dbus_object_property_set_cb_set(E_DBus_Object *obj, E_DBus_Object_Property_Set_Cb func);
+
+/**
+ * @brief Sets the callback to fetch properties from an object
+ * @param obj the object
+ * @param func the callback
+ */
+EAPI void e_dbus_object_property_get_cb_set(E_DBus_Object *obj, E_DBus_Object_Property_Get_Cb func);
+
+/**
+ * @brief Sets the callback to set properties on an object
+ * @param obj the object
+ * @param func the callback
+ */
+EAPI void e_dbus_object_property_set_cb_set(E_DBus_Object *obj, E_DBus_Object_Property_Set_Cb func);
/* sending method calls */
- EAPI DBusPendingCall *e_dbus_message_send(E_DBus_Connection *conn, DBusMessage *msg, E_DBus_Method_Return_Cb cb_return, int timeout, void *data);
+
+/**
+ * @brief Send a DBus message with callbacks
+ * @param conn The DBus connection
+ * @param msg The message to send
+ * @param cb_return A callback function for returns (only used if @a msg is a method-call)
+ * @param timeout A timeout in milliseconds, after which a synthetic error will be generated
+ * @param data custom data to pass in to the callback
+ * @return a DBusPendingCall that can be used to cancel the current call
+ */
+EAPI DBusPendingCall *e_dbus_message_send(E_DBus_Connection *conn, DBusMessage *msg, E_DBus_Method_Return_Cb cb_return, int timeout, void *data);
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);
/* signal receiving */
- 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);
- EAPI void e_dbus_signal_handler_del(E_DBus_Connection *conn, E_DBus_Signal_Handler *sh);
+
+/**
+ * Add a signal handler
+ *
+ * @param conn the dbus connection
+ * @param sender name of the signal's sender
+ * @param path the object path of the signal's sender
+ * @param interface the signal's interface
+ * @param member the signal's name
+ * @param cb_signal a callback to call when the signal is received
+ * @param data custom data to pass in to the callback
+ */
+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);
+
+/**
+ * Delete a signal handler
+ *
+ * @param conn the dbus connection
+ * @param sh the handler to delete
+ */
+EAPI void e_dbus_signal_handler_del(E_DBus_Connection *conn, E_DBus_Signal_Handler *sh);
/* standard dbus method calls */
const void *data);
/* standard methods calls on objects */
- EAPI DBusPendingCall *e_dbus_peer_ping(E_DBus_Connection *conn, const char *destination,
+
+/**
+ * Calls the Introspect method on a given bus and object path.
+ * @param conn The dbus connection to use
+ * @param bus The bus to call the method on
+ * @param object_path The path of the bus to call on
+ * @param cb_return The callback to call on reply from dbus
+ * @param data The data to associate with the callback
+ * @return A pending dbus call
+ */
+EAPI DBusPendingCall *e_dbus_introspect(E_DBus_Connection *conn, const char *bus,
+ const char *object_path, E_DBus_Method_Return_Cb cb_return, const void *data);
+
+/**
+ * Ping the dbus peer
+ *
+ * @param conn the dbus connection
+ * @param destination the bus name that the object is on
+ * @param path the object path
+ * @param cb_return a callback for a successful return
+ * @param data data to pass to the callbacks
+ */
+EAPI DBusPendingCall *e_dbus_peer_ping(E_DBus_Connection *conn, const char *destination,
const char *path, E_DBus_Method_Return_Cb cb_return,
const void *data);
- EAPI DBusPendingCall *e_dbus_peer_get_machine_id(E_DBus_Connection *conn,
+
+/**
+ * Get the UUID of the peer
+ *
+ * @param conn the dbus connection
+ * @param destination the bus name that the object is on
+ * @param path the object path
+ * @param cb_return a callback for a successful return
+ * @param data data to pass to the callbacks
+ */
+EAPI DBusPendingCall *e_dbus_peer_get_machine_id(E_DBus_Connection *conn,
const char *destination, const char *path,
E_DBus_Method_Return_Cb cb_return,
const void *data);
const char *path, const char *interface,
E_DBus_Method_Return_Cb cb_return,
const void *data);
- EAPI DBusPendingCall *e_dbus_properties_get(E_DBus_Connection *conn, const char *destination,
+
+/**
+ * Get the value of a property on an object
+ *
+ * @param conn the dbus connection
+ * @param destination the bus name that the object is on
+ * @param path the object path
+ * @param interface the interface name of the property
+ * @param property the name of the property
+ * @param cb_return a callback for a successful return
+ * @param data data to pass to the callbacks
+ */
+EAPI DBusPendingCall *e_dbus_properties_get(E_DBus_Connection *conn, const char *destination,
const char *path, const char *interface,
const char *property,
E_DBus_Method_Return_Cb cb_return,
const void *data);
- EAPI DBusPendingCall *e_dbus_properties_set(E_DBus_Connection *conn, const char *destination,
+
+/**
+ * Set the value of a property on an object
+ *
+ * @param conn the dbus connection
+ * @param destination the bus name that the object is on
+ * @param path the object path
+ * @param interface the interface name of the property
+ * @param property the name of the property
+ * @param value_type the type of the property's value
+ * @param value a pointer to the value
+ * @param cb_return a callback for a successful return
+ * @param data data to pass to the callbacks
+ */
+EAPI DBusPendingCall *e_dbus_properties_set(E_DBus_Connection *conn, const char *destination,
const char *path, const char *interface,
const char *property, int value_type,
const void *value, E_DBus_Method_Return_Cb cb_return,
const void *data);
- 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);
+
+/**
+ * @brief Create a callback structure
+ * @param cb_func the callback function
+ * @param user_data data to pass to the callback
+ */
+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);
- EAPI void e_dbus_callback_free(E_DBus_Callback *callback);
+
+/**
+ * @brief Free a callback structure
+ * @param callback the callback to free
+ */
+EAPI void e_dbus_callback_free(E_DBus_Callback *callback);
EAPI void e_dbus_callback_call(E_DBus_Callback *cb, void *data, DBusError *error);
EAPI void *e_dbus_callback_unmarshal(E_DBus_Callback *cb, DBusMessage *msg, DBusError *err);
EAPI void e_dbus_callback_return_free(E_DBus_Callback *callback, void *data);
+/**
+ * @brief Retrieve the DBusConnection pointer.
+ * @param conn pointer to the opaque E_DBus_Connection struct
+ * @since 1.1
+ */
+EAPI DBusConnection *e_dbus_connection_dbus_connection_get(E_DBus_Connection *conn);
+
#ifdef __cplusplus
}
#endif