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