1 #ifndef ELDBUS_OBJECT_H 2 #define ELDBUS_OBJECT_H 1 3 4 /** 5 * @defgroup Eldbus_Object_Mapper Object Mapper 6 * @ingroup Eldbus 7 * 8 * @{ 9 */ 10 11 /** 12 * @brief Get an object of the given bus and path. 13 * 14 * @param conn connection where object belongs 15 * @param bus name of bus or unique-id of who listens for calls of this object 16 * @param path object path of this object 17 * @return The corresponding Eldbus_Object. 18 */ 19 EAPI Eldbus_Object *eldbus_object_get(Eldbus_Connection *conn, const char *bus, const char *path) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; 20 21 /** 22 * @brief Increase object reference. 23 * 24 * @param obj An Eldbus_Object. 25 * @return The same Eldbus_Object with an increased refcount. 26 */ 27 EAPI Eldbus_Object *eldbus_object_ref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); 28 29 /** 30 * @brief Decrease object reference. 31 * If reference == 0 object will be freed and all its children. 32 * 33 * @param obj An Eldbus_Object. 34 */ 35 EAPI void eldbus_object_unref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); 36 37 /** 38 * @brief Add a callback function to be called when object will be freed. 39 * 40 * @param obj object that you want to monitor 41 * @param cb callback that will be executed 42 * @param data passed to callback 43 */ 44 EAPI void eldbus_object_free_cb_add(Eldbus_Object *obj, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); 45 46 /** 47 * @brief Remove callback registered in eldbus_object_free_cb_add(). 48 * 49 * @param obj Object monitored. 50 * @param cb Callback that was registered. 51 * @param data Data that was passed to callback. 52 */ 53 EAPI void eldbus_object_free_cb_del(Eldbus_Object *obj, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); 54 55 /** 56 * @typedef Eldbus_Object_Event_Type 57 * 58 * An enumeration containing several Eldbus_Object event types. 59 */ 60 typedef enum 61 { 62 ELDBUS_OBJECT_EVENT_IFACE_ADDED = 0, /**< a parent path must have a ObjectManager interface */ 63 ELDBUS_OBJECT_EVENT_IFACE_REMOVED, /**< a parent path must have a ObjectManager interface */ 64 ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, /**< a property has changes */ 65 ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, /**< a property was removed */ 66 ELDBUS_OBJECT_EVENT_DEL, 67 ELDBUS_OBJECT_EVENT_LAST /**< sentinel, not a real event type */ 68 } Eldbus_Object_Event_Type; 69 70 /** 71 * @typedef Eldbus_Object_Event_Interface_Added 72 * 73 * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_ADDED event. 74 */ 75 typedef struct _Eldbus_Object_Event_Interface_Added 76 { 77 const char *interface; /**< The interface name */ 78 Eldbus_Proxy *proxy; /**< The proxy object */ 79 } Eldbus_Object_Event_Interface_Added; 80 81 /** 82 * @typedef Eldbus_Object_Event_Interface_Removed 83 * 84 * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_REMOVED event. 85 */ 86 typedef struct _Eldbus_Object_Event_Interface_Removed 87 { 88 const char *interface; /**< The interface name */ 89 } Eldbus_Object_Event_Interface_Removed; 90 91 /** 92 * @typedef Eldbus_Object_Event_Property_Changed 93 * 94 * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED event. 95 */ 96 typedef struct _Eldbus_Object_Event_Property_Changed 97 { 98 const char *interface; /**< The interface name */ 99 Eldbus_Proxy *proxy; /**< The proxy object */ 100 const char *name; /**< The name of the property */ 101 const Eina_Value *value; /**< The value of the property */ 102 } Eldbus_Object_Event_Property_Changed; 103 104 /** 105 * @typedef Eldbus_Object_Event_Property_Removed 106 * 107 * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED event. 108 */ 109 typedef struct _Eldbus_Object_Event_Property_Removed 110 { 111 const char *interface; /**< The interface name */ 112 Eldbus_Proxy *proxy; /**< The proxy object */ 113 const char *name; /**< The name of the property */ 114 } Eldbus_Object_Event_Property_Removed; 115 116 /** 117 * @typedef Eldbus_Object_Event_Cb 118 * 119 * Callback that will be called when an Eldbus_Object event happens. 120 * 121 * @param data Context data. 122 * @param obj The Eldbus_Object. 123 * @param event_info Information about the event that triggered the callback. 124 */ 125 typedef void (*Eldbus_Object_Event_Cb)(void *data, Eldbus_Object *obj, void *event_info); 126 127 /** 128 * @brief Add a callback function to be called when an event of the specified 129 * type occurs. 130 * 131 * @param obj The Eldbus_Object on which to register a callback. 132 * @param type The type of the event. 133 * @param cb The callback to call. 134 * @param cb_data The data to pass to the callback. 135 */ 136 EAPI void eldbus_object_event_callback_add(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); 137 138 /** 139 * @brief Remove callback registered in eldbus_object_event_callback_add(). 140 * 141 * @param obj The Eldbus_Object. 142 * @param type The type of the event. 143 * @param cb The callback to call. 144 * @param cb_data The data to pass to the callback. 145 */ 146 EAPI void eldbus_object_event_callback_del(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); 147 148 /** 149 * Get the Eldbus_Connection object associated with a Eldbus_Object. 150 * 151 * @param obj The Eldbus_Object. 152 * @return The corresponding Eldbus_Connection object. 153 */ 154 EAPI Eldbus_Connection *eldbus_object_connection_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 155 156 /** 157 * Get the name associated with a Eldbus_Object. 158 * 159 * @param obj The Eldbus_Object. 160 * @return A string corresponding to the Eldbus_Object name. 161 */ 162 EAPI const char *eldbus_object_bus_name_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 163 164 /** 165 * Get the path associated with a Eldbus_Object. 166 * 167 * @param obj The Eldbus_Object. 168 * @return A string corresponding to the Eldbus_Object path. 169 */ 170 EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 171 172 /** 173 * @brief Send a message. 174 * 175 * @param obj the msg will be sent in connection to this object 176 * @param msg message that will be sent 177 * @param cb if msg is a method call a callback should be passed 178 * to be executed when a response arrives 179 * @param cb_data data passed to callback 180 * @param timeout timeout in milliseconds, -1 to default internal value or 181 * ELDBUS_TIMEOUT_INFINITE for no timeout 182 * @return A Eldbus_Pending object. 183 */ 184 EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); 185 186 /** 187 * @brief Add a signal handler. 188 * 189 * @param obj where the signal is emitted 190 * @param interface of the signal 191 * @param member name of the signal 192 * @param cb callback that will be called when this signal is received 193 * @param cb_data data that will be passed to callback 194 * @return A listener to the desired signal. 195 */ 196 EAPI Eldbus_Signal_Handler *eldbus_object_signal_handler_add(Eldbus_Object *obj, const char *interface, const char *member, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 4); 197 198 /** 199 * @brief Call a dbus method on the Eldbus_Object. 200 * 201 * @param obj The Eldbus_Object on which to call the method. 202 * @param interface Interface name. 203 * @param member Name of the method to be called. 204 * 205 * @return a new Eldbus_Message, free with eldbus_message_unref() 206 */ 207 EAPI Eldbus_Message *eldbus_object_method_call_new(Eldbus_Object *obj, const char *interface, const char *member) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; 208 209 /** 210 * @} 211 */ 212 #endif 213