X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=src%2Flib%2Fdbus%2FE_DBus.h;h=d11a1b83753c54bc139d2ead642e0bf9d327485e;hb=1136d51952eda69d81f748d2fa1c1c8972285022;hp=1534512ca86ea6d0b3e748a2c2388694cbd25aad;hpb=7ff03e95453af6283a20c2e385b338d879245790;p=framework%2Fuifw%2Fedbus.git diff --git a/src/lib/dbus/E_DBus.h b/src/lib/dbus/E_DBus.h index 1534512..d11a1b8 100644 --- a/src/lib/dbus/E_DBus.h +++ b/src/lib/dbus/E_DBus.h @@ -3,23 +3,36 @@ #define DBUS_API_SUBJECT_TO_CHANGE -#include -#include -#include +#ifdef _WIN32 +# ifdef interface +# undef interface +# endif +#endif + +#ifdef _WIN32 +# ifdef interface +# undef interface +# endif +# define DBUS_API_SUBJECT_TO_CHANGE +#endif #include -#include #include #ifdef EAPI -#undef EAPI +# undef EAPI #endif -#ifdef _MSC_VER -# ifdef BUILDING_DLL -# define EAPI __declspec(dllexport) + +#ifdef _WIN32 +# ifdef EFL_EDBUS_BUILD +# ifdef DLL_EXPORT +# define EAPI __declspec(dllexport) +# else +# define EAPI +# endif /* ! DLL_EXPORT */ # else # define EAPI __declspec(dllimport) -# endif +# endif /* ! EFL_EDBUS_BUILD */ #else # ifdef __GNUC__ # if __GNUC__ >= 4 @@ -32,10 +45,75 @@ # endif #endif +/** + * @mainpage EDbus + * + * @section edbus_intro_sec Introduction + * + * EDbus is a wrapper around the + * dbus + * library, which is a message bus system. It also implement a set of + * specifications using dbus as interprocess comunication. + * + * @section edbus_modules_sec Modules + * + * @li @ref EDbus_Group Wrapper around the dbus library, which + * implementent an inter-process communication (IPC) system for + * software applications to communicate with one another. + * @li @ref EBluez_Group Implementation of the BlueZ specifications, for wireless + * communications with Bleutooth devices. + * @li @ref EConnman_Group Implementation of the connman specifications, which + * manages internet connections within embedded devices running the + * Linux operating system. + * @li @ref EHal_Group Implementation of the HAL + * specifications, which is a (software) layer between the hardware + * devices of a computer and the softwares that run on that + * computer (Hardware Abstraction Layer). HAL is deprecated, in favor + * of DeviceKit. + * @li @ref ENotify_Group To de described. + * @li @ref EOfono_Group Implementation of the ofono specifications, which is an + * interface for mobile telephony applications. + * @li @ref EUkit_Group Implementation of the DeviceKit + * specifications, which is, like HAL, an Hardware Abstraction + * Layer. DeviceKit is a replacement of the deprecated HAL system. It + * has two submodules: UDisks, which manipulate storage devices, and + * UPower, which manage power devices. + */ + +/** + * @defgroup EDbus_Group EDbus + * + * @{ + */ + +#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_Connection E_DBus_Connection; @@ -62,17 +140,41 @@ extern "C" { 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); @@ -80,33 +182,132 @@ extern "C" { 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 */ @@ -130,15 +331,47 @@ extern "C" { EAPI DBusPendingCall *e_dbus_name_has_owner(E_DBus_Connection *conn, const char *name, E_DBus_Method_Return_Cb cb_return, const void *data); - EAPI DBusPendingCall *e_dbus_start_service_by_name(E_DBus_Connection *conn, const char *name, + EAPI DBusPendingCall *e_dbus_start_service_by_name(E_DBus_Connection *conn, const char *name, unsigned int flags, E_DBus_Method_Return_Cb cb_return, 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); @@ -146,27 +379,75 @@ extern "C" { 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 +/** + * @} + */ + #endif