1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-timeout.c DBusTimeout implementation
3 *
4 * Copyright (C) 2003 CodeFactory AB
5 *
6 * Licensed under the Academic Free License version 2.1
7 *
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 *
22 */
23
24 #include "dbus-internals.h"
25 #include "dbus-timeout.h"
26 #include "dbus-list.h"
27
28 /**
29 * @defgroup DBusTimeoutInternals DBusTimeout implementation details
30 * @ingroup DBusInternals
31 * @brief implementation details for DBusTimeout
32 *
33 * @{
34 */
35
36 /**
37 * Internals of DBusTimeout
38 */
39 struct DBusTimeout
40 {
41 int refcount; /**< Reference count */
42 int interval; /**< Timeout interval in milliseconds. */
43
44 DBusTimeoutHandler handler; /**< Timeout handler. */
45 void *handler_data; /**< Timeout handler data. */
46 DBusFreeFunction free_handler_data_function; /**< Free the timeout handler data. */
47
48 void *data; /**< Application data. */
49 DBusFreeFunction free_data_function; /**< Free the application data. */
50 unsigned int enabled : 1; /**< True if timeout is active. */
51 };
52
53 /**
54 * Creates a new DBusTimeout, enabled by default.
55 * @param interval the timeout interval in milliseconds.
56 * @param handler function to call when the timeout occurs.
57 * @param data data to pass to the handler
58 * @param free_data_function function to be called to free the data.
59 * @returns the new DBusTimeout object,
60 */
61 DBusTimeout*
_dbus_timeout_new(int interval,DBusTimeoutHandler handler,void * data,DBusFreeFunction free_data_function)62 _dbus_timeout_new (int interval,
63 DBusTimeoutHandler handler,
64 void *data,
65 DBusFreeFunction free_data_function)
66 {
67 DBusTimeout *timeout;
68
69 timeout = dbus_new0 (DBusTimeout, 1);
70 if (timeout == NULL)
71 return NULL;
72
73 timeout->refcount = 1;
74 timeout->interval = interval;
75
76 timeout->handler = handler;
77 timeout->handler_data = data;
78 timeout->free_handler_data_function = free_data_function;
79
80 timeout->enabled = TRUE;
81
82 return timeout;
83 }
84
85 /**
86 * Increments the reference count of a DBusTimeout object.
87 *
88 * @param timeout the timeout object.
89 * @returns the timeout object.
90 */
91 DBusTimeout *
_dbus_timeout_ref(DBusTimeout * timeout)92 _dbus_timeout_ref (DBusTimeout *timeout)
93 {
94 timeout->refcount += 1;
95
96 return timeout;
97 }
98
99 /**
100 * Decrements the reference count of a DBusTimeout object
101 * and finalizes the object if the count reaches zero.
102 *
103 * @param timeout the timeout object.
104 */
105 void
_dbus_timeout_unref(DBusTimeout * timeout)106 _dbus_timeout_unref (DBusTimeout *timeout)
107 {
108 _dbus_assert (timeout != NULL);
109 _dbus_assert (timeout->refcount > 0);
110
111 timeout->refcount -= 1;
112 if (timeout->refcount == 0)
113 {
114 dbus_timeout_set_data (timeout, NULL, NULL); /* call free_data_function */
115
116 if (timeout->free_handler_data_function)
117 (* timeout->free_handler_data_function) (timeout->handler_data);
118
119 dbus_free (timeout);
120 }
121 }
122
123 /**
124 * Changes the timeout interval. Note that you have to disable and
125 * re-enable the timeout using the timeout toggle function
126 * (_dbus_connection_toggle_timeout_unlocked() etc.) to notify the
127 * application of this change.
128 *
129 * @param timeout the timeout
130 * @param interval the new interval
131 */
132 void
_dbus_timeout_set_interval(DBusTimeout * timeout,int interval)133 _dbus_timeout_set_interval (DBusTimeout *timeout,
134 int interval)
135 {
136 _dbus_assert (interval >= 0);
137
138 timeout->interval = interval;
139 }
140
141 /**
142 * Changes the timeout's enabled-ness. Note that you should use
143 * _dbus_connection_toggle_timeout_unlocked() etc. instead, if
144 * the timeout is passed out to an application main loop.
145 * i.e. you can't use this function in the D-Bus library, it's
146 * only used in the message bus daemon implementation.
147 *
148 * @param timeout the timeout
149 * @param enabled #TRUE if timeout should be enabled.
150 */
151 void
_dbus_timeout_set_enabled(DBusTimeout * timeout,dbus_bool_t enabled)152 _dbus_timeout_set_enabled (DBusTimeout *timeout,
153 dbus_bool_t enabled)
154 {
155 timeout->enabled = enabled != FALSE;
156 }
157
158
159 /**
160 * @typedef DBusTimeoutList
161 *
162 * Opaque data type representing a list of timeouts
163 * and a set of DBusAddTimeoutFunction/DBusRemoveTimeoutFunction.
164 * Automatically handles removing/re-adding timeouts
165 * when the DBusAddTimeoutFunction is updated or changed.
166 * Holds a reference count to each timeout.
167 *
168 */
169
170 /**
171 * DBusTimeoutList implementation details. All fields
172 * are private.
173 *
174 */
175 struct DBusTimeoutList
176 {
177 DBusList *timeouts; /**< Timeout objects. */
178
179 DBusAddTimeoutFunction add_timeout_function; /**< Callback for adding a timeout. */
180 DBusRemoveTimeoutFunction remove_timeout_function; /**< Callback for removing a timeout. */
181 DBusTimeoutToggledFunction timeout_toggled_function; /**< Callback when timeout is enabled/disabled or changes interval */
182 void *timeout_data; /**< Data for timeout callbacks */
183 DBusFreeFunction timeout_free_data_function; /**< Free function for timeout callback data */
184 };
185
186 /**
187 * Creates a new timeout list. Returns #NULL if insufficient
188 * memory exists.
189 *
190 * @returns the new timeout list, or #NULL on failure.
191 */
192 DBusTimeoutList*
_dbus_timeout_list_new(void)193 _dbus_timeout_list_new (void)
194 {
195 DBusTimeoutList *timeout_list;
196
197 timeout_list = dbus_new0 (DBusTimeoutList, 1);
198 if (timeout_list == NULL)
199 return NULL;
200
201 return timeout_list;
202 }
203
204 /**
205 * Frees a DBusTimeoutList.
206 *
207 * @param timeout_list the timeout list.
208 */
209 void
_dbus_timeout_list_free(DBusTimeoutList * timeout_list)210 _dbus_timeout_list_free (DBusTimeoutList *timeout_list)
211 {
212 /* free timeout_data and remove timeouts as a side effect */
213 _dbus_timeout_list_set_functions (timeout_list,
214 NULL, NULL, NULL, NULL, NULL);
215
216 _dbus_list_foreach (&timeout_list->timeouts,
217 (DBusForeachFunction) _dbus_timeout_unref,
218 NULL);
219 _dbus_list_clear (&timeout_list->timeouts);
220
221 dbus_free (timeout_list);
222 }
223
224 /**
225 * Sets the timeout functions. This function is the "backend"
226 * for dbus_connection_set_timeout_functions().
227 *
228 * @param timeout_list the timeout list
229 * @param add_function the add timeout function.
230 * @param remove_function the remove timeout function.
231 * @param toggled_function toggle notify function, or #NULL
232 * @param data the data for those functions.
233 * @param free_data_function the function to free the data.
234 * @returns #FALSE if no memory
235 *
236 */
237 dbus_bool_t
_dbus_timeout_list_set_functions(DBusTimeoutList * timeout_list,DBusAddTimeoutFunction add_function,DBusRemoveTimeoutFunction remove_function,DBusTimeoutToggledFunction toggled_function,void * data,DBusFreeFunction free_data_function)238 _dbus_timeout_list_set_functions (DBusTimeoutList *timeout_list,
239 DBusAddTimeoutFunction add_function,
240 DBusRemoveTimeoutFunction remove_function,
241 DBusTimeoutToggledFunction toggled_function,
242 void *data,
243 DBusFreeFunction free_data_function)
244 {
245 /* Add timeouts with the new function, failing on OOM */
246 if (add_function != NULL)
247 {
248 DBusList *link;
249
250 link = _dbus_list_get_first_link (&timeout_list->timeouts);
251 while (link != NULL)
252 {
253 DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
254 link);
255
256 if (!(* add_function) (link->data, data))
257 {
258 /* remove it all again and return FALSE */
259 DBusList *link2;
260
261 link2 = _dbus_list_get_first_link (&timeout_list->timeouts);
262 while (link2 != link)
263 {
264 DBusList *next = _dbus_list_get_next_link (&timeout_list->timeouts,
265 link2);
266
267 (* remove_function) (link2->data, data);
268
269 link2 = next;
270 }
271
272 return FALSE;
273 }
274
275 link = next;
276 }
277 }
278
279 /* Remove all current timeouts from previous timeout handlers */
280
281 if (timeout_list->remove_timeout_function != NULL)
282 {
283 _dbus_list_foreach (&timeout_list->timeouts,
284 (DBusForeachFunction) timeout_list->remove_timeout_function,
285 timeout_list->timeout_data);
286 }
287
288 if (timeout_list->timeout_free_data_function != NULL)
289 (* timeout_list->timeout_free_data_function) (timeout_list->timeout_data);
290
291 timeout_list->add_timeout_function = add_function;
292 timeout_list->remove_timeout_function = remove_function;
293 timeout_list->timeout_toggled_function = toggled_function;
294 timeout_list->timeout_data = data;
295 timeout_list->timeout_free_data_function = free_data_function;
296
297 return TRUE;
298 }
299
300 /**
301 * Adds a new timeout to the timeout list, invoking the
302 * application DBusAddTimeoutFunction if appropriate.
303 *
304 * @param timeout_list the timeout list.
305 * @param timeout the timeout to add.
306 * @returns #TRUE on success, #FALSE If no memory.
307 */
308 dbus_bool_t
_dbus_timeout_list_add_timeout(DBusTimeoutList * timeout_list,DBusTimeout * timeout)309 _dbus_timeout_list_add_timeout (DBusTimeoutList *timeout_list,
310 DBusTimeout *timeout)
311 {
312 if (!_dbus_list_append (&timeout_list->timeouts, timeout))
313 return FALSE;
314
315 _dbus_timeout_ref (timeout);
316
317 if (timeout_list->add_timeout_function != NULL)
318 {
319 if (!(* timeout_list->add_timeout_function) (timeout,
320 timeout_list->timeout_data))
321 {
322 _dbus_list_remove_last (&timeout_list->timeouts, timeout);
323 _dbus_timeout_unref (timeout);
324 return FALSE;
325 }
326 }
327
328 return TRUE;
329 }
330
331 /**
332 * Removes a timeout from the timeout list, invoking the
333 * application's DBusRemoveTimeoutFunction if appropriate.
334 *
335 * @param timeout_list the timeout list.
336 * @param timeout the timeout to remove.
337 */
338 void
_dbus_timeout_list_remove_timeout(DBusTimeoutList * timeout_list,DBusTimeout * timeout)339 _dbus_timeout_list_remove_timeout (DBusTimeoutList *timeout_list,
340 DBusTimeout *timeout)
341 {
342 if (!_dbus_list_remove (&timeout_list->timeouts, timeout))
343 _dbus_assert_not_reached ("Nonexistent timeout was removed");
344
345 if (timeout_list->remove_timeout_function != NULL)
346 (* timeout_list->remove_timeout_function) (timeout,
347 timeout_list->timeout_data);
348
349 _dbus_timeout_unref (timeout);
350 }
351
352 /**
353 * Sets a timeout to the given enabled state, invoking the
354 * application's DBusTimeoutToggledFunction if appropriate.
355 *
356 * @param timeout_list the timeout list.
357 * @param timeout the timeout to toggle.
358 * @param enabled #TRUE to enable
359 */
360 void
_dbus_timeout_list_toggle_timeout(DBusTimeoutList * timeout_list,DBusTimeout * timeout,dbus_bool_t enabled)361 _dbus_timeout_list_toggle_timeout (DBusTimeoutList *timeout_list,
362 DBusTimeout *timeout,
363 dbus_bool_t enabled)
364 {
365 enabled = !!enabled;
366
367 if (enabled == timeout->enabled)
368 return;
369
370 timeout->enabled = enabled;
371
372 if (timeout_list->timeout_toggled_function != NULL)
373 (* timeout_list->timeout_toggled_function) (timeout,
374 timeout_list->timeout_data);
375 }
376
377 /** @} */
378
379 /**
380 * @defgroup DBusTimeout DBusTimeout
381 * @ingroup DBus
382 * @brief Object representing a timeout
383 *
384 * Types and functions related to DBusTimeout. A timeout
385 * represents a timeout that the main loop needs to monitor,
386 * as in Qt's QTimer or GLib's g_timeout_add().
387 *
388 * Use dbus_connection_set_timeout_functions() or dbus_server_set_timeout_functions()
389 * to be notified when libdbus needs to add or remove timeouts.
390 *
391 * @{
392 */
393
394
395 /**
396 * @typedef DBusTimeout
397 *
398 * Opaque object representing a timeout.
399 */
400
401 /**
402 * Gets the timeout interval. The dbus_timeout_handle()
403 * should be called each time this interval elapses,
404 * starting after it elapses once.
405 *
406 * The interval may change during the life of the
407 * timeout; if so, the timeout will be disabled and
408 * re-enabled (calling the "timeout toggled function")
409 * to notify you of the change.
410 *
411 * @param timeout the DBusTimeout object.
412 * @returns the interval in milliseconds.
413 */
414 int
dbus_timeout_get_interval(DBusTimeout * timeout)415 dbus_timeout_get_interval (DBusTimeout *timeout)
416 {
417 return timeout->interval;
418 }
419
420 /**
421 * Gets data previously set with dbus_timeout_set_data()
422 * or #NULL if none.
423 *
424 * @param timeout the DBusTimeout object.
425 * @returns previously-set data.
426 */
427 void*
dbus_timeout_get_data(DBusTimeout * timeout)428 dbus_timeout_get_data (DBusTimeout *timeout)
429 {
430 return timeout->data;
431 }
432
433 /**
434 * Sets data which can be retrieved with dbus_timeout_get_data().
435 * Intended for use by the DBusAddTimeoutFunction and
436 * DBusRemoveTimeoutFunction to store their own data. For example with
437 * Qt you might store the QTimer for this timeout and with GLib
438 * you might store a g_timeout_add result id.
439 *
440 * @param timeout the DBusTimeout object.
441 * @param data the data.
442 * @param free_data_function function to be called to free the data.
443 */
444 void
dbus_timeout_set_data(DBusTimeout * timeout,void * data,DBusFreeFunction free_data_function)445 dbus_timeout_set_data (DBusTimeout *timeout,
446 void *data,
447 DBusFreeFunction free_data_function)
448 {
449 if (timeout->free_data_function != NULL)
450 (* timeout->free_data_function) (timeout->data);
451
452 timeout->data = data;
453 timeout->free_data_function = free_data_function;
454 }
455
456 /**
457 * Calls the timeout handler for this timeout.
458 * This function should be called when the timeout
459 * occurs.
460 *
461 * If this function returns #FALSE, then there wasn't
462 * enough memory to handle the timeout. Typically just
463 * letting the timeout fire again next time it naturally
464 * times out is an adequate response to that problem,
465 * but you could try to do more if you wanted.
466 *
467 * @param timeout the DBusTimeout object.
468 * @returns #FALSE if there wasn't enough memory
469 */
470 dbus_bool_t
dbus_timeout_handle(DBusTimeout * timeout)471 dbus_timeout_handle (DBusTimeout *timeout)
472 {
473 return (* timeout->handler) (timeout->handler_data);
474 }
475
476
477 /**
478 * Returns whether a timeout is enabled or not. If not
479 * enabled, it should not be polled by the main loop.
480 *
481 * @param timeout the DBusTimeout object
482 * @returns #TRUE if the timeout is enabled
483 */
484 dbus_bool_t
dbus_timeout_get_enabled(DBusTimeout * timeout)485 dbus_timeout_get_enabled (DBusTimeout *timeout)
486 {
487 return timeout->enabled;
488 }
489
490 /** @} end public API docs */
491