1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-watch.c DBusWatch implementation
4 * Copyright (C) 2002, 2003 Red Hat Inc.
6 * Licensed under the Academic Free License version 2.1
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.
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.
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
24 #include "dbus-internals.h"
25 #include "dbus-watch.h"
26 #include "dbus-list.h"
29 * @defgroup DBusWatchInternals DBusWatch implementation details
30 * @ingroup DBusInternals
31 * @brief implementation details for DBusWatch
37 * Implementation of DBusWatch
41 int refcount; /**< Reference count */
42 int fd; /**< File descriptor. */
43 unsigned int flags; /**< Conditions to watch. */
45 DBusWatchHandler handler; /**< Watch handler. */
46 void *handler_data; /**< Watch handler data. */
47 DBusFreeFunction free_handler_data_function; /**< Free the watch handler data. */
49 void *data; /**< Application data. */
50 DBusFreeFunction free_data_function; /**< Free the application data. */
51 unsigned int enabled : 1; /**< Whether it's enabled. */
55 * Creates a new DBusWatch. Used to add a file descriptor to be polled
58 * @param fd the file descriptor to be watched.
59 * @param flags the conditions to watch for on the descriptor.
60 * @param enabled the initial enabled state
61 * @param handler the handler function
62 * @param data data for handler function
63 * @param free_data_function function to free the data
64 * @returns the new DBusWatch object.
67 _dbus_watch_new (int fd,
70 DBusWatchHandler handler,
72 DBusFreeFunction free_data_function)
76 #define VALID_WATCH_FLAGS (DBUS_WATCH_WRITABLE | DBUS_WATCH_READABLE)
78 _dbus_assert ((flags & VALID_WATCH_FLAGS) == flags);
80 watch = dbus_new0 (DBusWatch, 1);
87 watch->enabled = enabled;
89 watch->handler = handler;
90 watch->handler_data = data;
91 watch->free_handler_data_function = free_data_function;
97 * Increments the reference count of a DBusWatch object.
99 * @param watch the watch object.
100 * @returns the watch object.
103 _dbus_watch_ref (DBusWatch *watch)
105 watch->refcount += 1;
111 * Decrements the reference count of a DBusWatch object
112 * and finalizes the object if the count reaches zero.
114 * @param watch the watch object.
117 _dbus_watch_unref (DBusWatch *watch)
119 _dbus_assert (watch != NULL);
120 _dbus_assert (watch->refcount > 0);
122 watch->refcount -= 1;
123 if (watch->refcount == 0)
125 dbus_watch_set_data (watch, NULL, NULL); /* call free_data_function */
127 if (watch->free_handler_data_function)
128 (* watch->free_handler_data_function) (watch->handler_data);
135 * Clears the file descriptor from a now-invalid watch object so that
136 * no one tries to use it. This is because a watch may stay alive due
137 * to reference counts after the file descriptor is closed.
138 * Invalidation makes it easier to catch bugs. It also
139 * keeps people from doing dorky things like assuming file descriptors
140 * are unique (never recycled).
142 * @param watch the watch object.
145 _dbus_watch_invalidate (DBusWatch *watch)
152 * Sanitizes the given condition so that it only contains
153 * flags that the DBusWatch requested. e.g. if the
154 * watch is a DBUS_WATCH_READABLE watch then
155 * DBUS_WATCH_WRITABLE will be stripped from the condition.
157 * @param watch the watch object.
158 * @param condition address of the condition to sanitize.
161 _dbus_watch_sanitize_condition (DBusWatch *watch,
162 unsigned int *condition)
164 if (!(watch->flags & DBUS_WATCH_READABLE))
165 *condition &= ~DBUS_WATCH_READABLE;
166 if (!(watch->flags & DBUS_WATCH_WRITABLE))
167 *condition &= ~DBUS_WATCH_WRITABLE;
172 * @typedef DBusWatchList
174 * Opaque data type representing a list of watches
175 * and a set of DBusAddWatchFunction/DBusRemoveWatchFunction.
176 * Automatically handles removing/re-adding watches
177 * when the DBusAddWatchFunction is updated or changed.
178 * Holds a reference count to each watch.
180 * Used in the implementation of both DBusServer and
186 * DBusWatchList implementation details. All fields
192 DBusList *watches; /**< Watch objects. */
194 DBusAddWatchFunction add_watch_function; /**< Callback for adding a watch. */
195 DBusRemoveWatchFunction remove_watch_function; /**< Callback for removing a watch. */
196 DBusWatchToggledFunction watch_toggled_function; /**< Callback on toggling enablement */
197 void *watch_data; /**< Data for watch callbacks */
198 DBusFreeFunction watch_free_data_function; /**< Free function for watch callback data */
202 * Creates a new watch list. Returns #NULL if insufficient
205 * @returns the new watch list, or #NULL on failure.
208 _dbus_watch_list_new (void)
210 DBusWatchList *watch_list;
212 watch_list = dbus_new0 (DBusWatchList, 1);
213 if (watch_list == NULL)
220 * Frees a DBusWatchList.
222 * @param watch_list the watch list.
225 _dbus_watch_list_free (DBusWatchList *watch_list)
227 /* free watch_data and removes watches as a side effect */
228 _dbus_watch_list_set_functions (watch_list,
229 NULL, NULL, NULL, NULL, NULL);
230 _dbus_list_foreach (&watch_list->watches,
231 (DBusForeachFunction) _dbus_watch_unref,
233 _dbus_list_clear (&watch_list->watches);
235 dbus_free (watch_list);
239 * Sets the watch functions. This function is the "backend"
240 * for dbus_connection_set_watch_functions() and
241 * dbus_server_set_watch_functions().
243 * @param watch_list the watch list.
244 * @param add_function the add watch function.
245 * @param remove_function the remove watch function.
246 * @param toggled_function function on toggling enabled flag, or #NULL
247 * @param data the data for those functions.
248 * @param free_data_function the function to free the data.
249 * @returns #FALSE if not enough memory
253 _dbus_watch_list_set_functions (DBusWatchList *watch_list,
254 DBusAddWatchFunction add_function,
255 DBusRemoveWatchFunction remove_function,
256 DBusWatchToggledFunction toggled_function,
258 DBusFreeFunction free_data_function)
260 /* Add watches with the new watch function, failing on OOM */
261 if (add_function != NULL)
265 link = _dbus_list_get_first_link (&watch_list->watches);
268 DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
271 #ifdef DBUS_ENABLE_VERBOSE_MODE
273 const char *watch_type;
276 flags = dbus_watch_get_flags (link->data);
277 if ((flags & DBUS_WATCH_READABLE) &&
278 (flags & DBUS_WATCH_WRITABLE))
279 watch_type = "readwrite";
280 else if (flags & DBUS_WATCH_READABLE)
282 else if (flags & DBUS_WATCH_WRITABLE)
283 watch_type = "write";
285 watch_type = "not read or write";
287 _dbus_verbose ("Adding a %s watch on fd %d using newly-set add watch function\n",
289 dbus_watch_get_fd (link->data));
291 #endif /* DBUS_ENABLE_VERBOSE_MODE */
293 if (!(* add_function) (link->data, data))
295 /* remove it all again and return FALSE */
298 link2 = _dbus_list_get_first_link (&watch_list->watches);
299 while (link2 != link)
301 DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
304 _dbus_verbose ("Removing watch on fd %d using newly-set remove function because initial add failed\n",
305 dbus_watch_get_fd (link2->data));
307 (* remove_function) (link2->data, data);
319 /* Remove all current watches from previous watch handlers */
321 if (watch_list->remove_watch_function != NULL)
323 _dbus_verbose ("Removing all pre-existing watches\n");
325 _dbus_list_foreach (&watch_list->watches,
326 (DBusForeachFunction) watch_list->remove_watch_function,
327 watch_list->watch_data);
330 if (watch_list->watch_free_data_function != NULL)
331 (* watch_list->watch_free_data_function) (watch_list->watch_data);
333 watch_list->add_watch_function = add_function;
334 watch_list->remove_watch_function = remove_function;
335 watch_list->watch_toggled_function = toggled_function;
336 watch_list->watch_data = data;
337 watch_list->watch_free_data_function = free_data_function;
343 * Adds a new watch to the watch list, invoking the
344 * application DBusAddWatchFunction if appropriate.
346 * @param watch_list the watch list.
347 * @param watch the watch to add.
348 * @returns #TRUE on success, #FALSE if no memory.
351 _dbus_watch_list_add_watch (DBusWatchList *watch_list,
354 if (!_dbus_list_append (&watch_list->watches, watch))
357 _dbus_watch_ref (watch);
359 if (watch_list->add_watch_function != NULL)
361 _dbus_verbose ("Adding watch on fd %d\n",
362 dbus_watch_get_fd (watch));
364 if (!(* watch_list->add_watch_function) (watch,
365 watch_list->watch_data))
367 _dbus_list_remove_last (&watch_list->watches, watch);
368 _dbus_watch_unref (watch);
377 * Removes a watch from the watch list, invoking the
378 * application's DBusRemoveWatchFunction if appropriate.
380 * @param watch_list the watch list.
381 * @param watch the watch to remove.
384 _dbus_watch_list_remove_watch (DBusWatchList *watch_list,
387 if (!_dbus_list_remove (&watch_list->watches, watch))
388 _dbus_assert_not_reached ("Nonexistent watch was removed");
390 if (watch_list->remove_watch_function != NULL)
392 _dbus_verbose ("Removing watch on fd %d\n",
393 dbus_watch_get_fd (watch));
395 (* watch_list->remove_watch_function) (watch,
396 watch_list->watch_data);
399 _dbus_watch_unref (watch);
403 * Sets a watch to the given enabled state, invoking the
404 * application's DBusWatchToggledFunction if appropriate.
406 * @param watch_list the watch list.
407 * @param watch the watch to toggle.
408 * @param enabled #TRUE to enable
411 _dbus_watch_list_toggle_watch (DBusWatchList *watch_list,
417 if (enabled == watch->enabled)
420 watch->enabled = enabled;
422 if (watch_list->watch_toggled_function != NULL)
424 _dbus_verbose ("Toggling watch %p on fd %d to %d\n",
425 watch, dbus_watch_get_fd (watch), watch->enabled);
427 (* watch_list->watch_toggled_function) (watch,
428 watch_list->watch_data);
433 * Sets the handler for the watch.
435 * @todo this function only exists because of the weird
436 * way connection watches are done, see the note
437 * in docs for _dbus_connection_handle_watch().
439 * @param watch the watch
440 * @param handler the new handler
441 * @param data the data
442 * @param free_data_function free data with this
445 _dbus_watch_set_handler (DBusWatch *watch,
446 DBusWatchHandler handler,
448 DBusFreeFunction free_data_function)
450 if (watch->free_handler_data_function)
451 (* watch->free_handler_data_function) (watch->handler_data);
453 watch->handler = handler;
454 watch->handler_data = data;
455 watch->free_handler_data_function = free_data_function;
461 * @defgroup DBusWatch DBusWatch
463 * @brief Object representing a file descriptor to be watched.
465 * Types and functions related to DBusWatch. A watch represents
466 * a file descriptor that the main loop needs to monitor,
467 * as in Qt's QSocketNotifier or GLib's g_io_add_watch().
475 * Opaque object representing a file descriptor
476 * to be watched for changes in readability,
477 * writability, or hangup.
481 * Gets the file descriptor that should be watched.
483 * @param watch the DBusWatch object.
484 * @returns the file descriptor to watch.
487 dbus_watch_get_fd (DBusWatch *watch)
493 * Gets flags from DBusWatchFlags indicating
494 * what conditions should be monitored on the
497 * The flags returned will only contain DBUS_WATCH_READABLE
498 * and DBUS_WATCH_WRITABLE, never DBUS_WATCH_HANGUP or
499 * DBUS_WATCH_ERROR; all watches implicitly include a watch
500 * for hangups, errors, and other exceptional conditions.
502 * @param watch the DBusWatch object.
503 * @returns the conditions to watch.
506 dbus_watch_get_flags (DBusWatch *watch)
508 _dbus_assert ((watch->flags & VALID_WATCH_FLAGS) == watch->flags);
514 * Gets data previously set with dbus_watch_set_data()
517 * @param watch the DBusWatch object.
518 * @returns previously-set data.
521 dbus_watch_get_data (DBusWatch *watch)
527 * Sets data which can be retrieved with dbus_watch_get_data().
528 * Intended for use by the DBusAddWatchFunction and
529 * DBusRemoveWatchFunction to store their own data. For example with
530 * Qt you might store the QSocketNotifier for this watch and with GLib
531 * you might store a GSource.
533 * @param watch the DBusWatch object.
534 * @param data the data.
535 * @param free_data_function function to be called to free the data.
538 dbus_watch_set_data (DBusWatch *watch,
540 DBusFreeFunction free_data_function)
542 _dbus_verbose ("Setting watch fd %d data to data = %p function = %p from data = %p function = %p\n",
543 dbus_watch_get_fd (watch),
544 data, free_data_function, watch->data, watch->free_data_function);
546 if (watch->free_data_function != NULL)
547 (* watch->free_data_function) (watch->data);
550 watch->free_data_function = free_data_function;
554 * Returns whether a watch is enabled or not. If not
555 * enabled, it should not be polled by the main loop.
557 * @param watch the DBusWatch object
558 * @returns #TRUE if the watch is enabled
561 dbus_watch_get_enabled (DBusWatch *watch)
563 _dbus_assert (watch != NULL);
564 return watch->enabled;
569 * Called to notify the D-BUS library when a previously-added watch is
570 * ready for reading or writing, or has an exception such as a hangup.
572 * If this function returns #FALSE, then the file descriptor may still
573 * be ready for reading or writing, but more memory is needed in order
574 * to do the reading or writing. If you ignore the #FALSE return, your
575 * application may spin in a busy loop on the file descriptor until
576 * memory becomes available, but nothing more catastrophic should
579 * dbus_watch_handle() cannot be called during the
580 * DBusAddWatchFunction, as the connection will not be ready to handle
583 * It is not allowed to reference a DBusWatch after it has been passed
584 * to remove_function.
586 * @param watch the DBusWatch object.
587 * @param flags the poll condition using #DBusWatchFlags values
588 * @returns #FALSE if there wasn't enough memory
591 dbus_watch_handle (DBusWatch *watch,
594 #ifndef DBUS_DISABLE_CHECKS
595 if (watch->fd < 0 || watch->flags == 0)
597 _dbus_warn ("%s: Watch is invalid, it should have been removed\n",
598 _DBUS_FUNCTION_NAME);
603 _dbus_return_val_if_fail (watch->fd >= 0 /* fails if watch was removed */, TRUE);
605 _dbus_watch_sanitize_condition (watch, &flags);
609 _dbus_verbose ("After sanitization, watch flags on fd %d were 0\n",
614 return (* watch->handler) (watch, flags,
615 watch->handler_data);