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 1.2
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
38 int refcount; /**< Reference count */
39 int fd; /**< File descriptor. */
40 unsigned int flags; /**< Conditions to watch. */
41 void *data; /**< Application data. */
42 DBusFreeFunction free_data_function; /**< Free the application data. */
43 unsigned int enabled : 1; /**< Whether it's enabled. */
47 * Creates a new DBusWatch. Normally used by a DBusTransport
49 * @param fd the file descriptor to be watched.
50 * @param flags the conditions to watch for on the descriptor.
51 * @param enabled the initial enabled state
52 * @returns the new DBusWatch object.
55 _dbus_watch_new (int fd,
61 #define VALID_WATCH_FLAGS (DBUS_WATCH_WRITABLE | DBUS_WATCH_READABLE)
63 _dbus_assert ((flags & VALID_WATCH_FLAGS) == flags);
65 watch = dbus_new0 (DBusWatch, 1);
72 watch->enabled = enabled;
78 * Increments the reference count of a DBusWatch object.
80 * @param watch the watch object.
83 _dbus_watch_ref (DBusWatch *watch)
89 * Decrements the reference count of a DBusWatch object
90 * and finalizes the object if the count reaches zero.
92 * @param watch the watch object.
95 _dbus_watch_unref (DBusWatch *watch)
97 _dbus_assert (watch != NULL);
98 _dbus_assert (watch->refcount > 0);
100 watch->refcount -= 1;
101 if (watch->refcount == 0)
103 dbus_watch_set_data (watch, NULL, NULL); /* call free_data_function */
109 * Clears the file descriptor from a now-invalid watch object so that
110 * no one tries to use it. This is because a watch may stay alive due
111 * to reference counts after the file descriptor is closed.
112 * Invalidation makes it easier to catch bugs. It also
113 * keeps people from doing dorky things like assuming file descriptors
114 * are unique (never recycled).
116 * @param watch the watch object.
119 _dbus_watch_invalidate (DBusWatch *watch)
126 * Sanitizes the given condition so that it only contains
127 * flags that the DBusWatch requested. e.g. if the
128 * watch is a DBUS_WATCH_READABLE watch then
129 * DBUS_WATCH_WRITABLE will be stripped from the condition.
131 * @param watch the watch object.
132 * @param condition address of the condition to sanitize.
135 _dbus_watch_sanitize_condition (DBusWatch *watch,
136 unsigned int *condition)
138 if (!(watch->flags & DBUS_WATCH_READABLE))
139 *condition &= ~DBUS_WATCH_READABLE;
140 if (!(watch->flags & DBUS_WATCH_WRITABLE))
141 *condition &= ~DBUS_WATCH_WRITABLE;
146 * @typedef DBusWatchList
148 * Opaque data type representing a list of watches
149 * and a set of DBusAddWatchFunction/DBusRemoveWatchFunction.
150 * Automatically handles removing/re-adding watches
151 * when the DBusAddWatchFunction is updated or changed.
152 * Holds a reference count to each watch.
154 * Used in the implementation of both DBusServer and
160 * DBusWatchList implementation details. All fields
166 DBusList *watches; /**< Watch objects. */
168 DBusAddWatchFunction add_watch_function; /**< Callback for adding a watch. */
169 DBusRemoveWatchFunction remove_watch_function; /**< Callback for removing a watch. */
170 DBusWatchToggledFunction watch_toggled_function; /**< Callback on toggling enablement */
171 void *watch_data; /**< Data for watch callbacks */
172 DBusFreeFunction watch_free_data_function; /**< Free function for watch callback data */
176 * Creates a new watch list. Returns #NULL if insufficient
179 * @returns the new watch list, or #NULL on failure.
182 _dbus_watch_list_new (void)
184 DBusWatchList *watch_list;
186 watch_list = dbus_new0 (DBusWatchList, 1);
187 if (watch_list == NULL)
194 * Frees a DBusWatchList.
196 * @param watch_list the watch list.
199 _dbus_watch_list_free (DBusWatchList *watch_list)
201 /* free watch_data and removes watches as a side effect */
202 _dbus_watch_list_set_functions (watch_list,
203 NULL, NULL, NULL, NULL, NULL);
204 _dbus_list_foreach (&watch_list->watches,
205 (DBusForeachFunction) _dbus_watch_unref,
207 _dbus_list_clear (&watch_list->watches);
209 dbus_free (watch_list);
213 * Sets the watch functions. This function is the "backend"
214 * for dbus_connection_set_watch_functions() and
215 * dbus_server_set_watch_functions().
217 * @param watch_list the watch list.
218 * @param add_function the add watch function.
219 * @param remove_function the remove watch function.
220 * @param toggled_function function on toggling enabled flag, or #NULL
221 * @param data the data for those functions.
222 * @param free_data_function the function to free the data.
223 * @returns #FALSE if not enough memory
227 _dbus_watch_list_set_functions (DBusWatchList *watch_list,
228 DBusAddWatchFunction add_function,
229 DBusRemoveWatchFunction remove_function,
230 DBusWatchToggledFunction toggled_function,
232 DBusFreeFunction free_data_function)
234 /* Add watches with the new watch function, failing on OOM */
235 if (add_function != NULL)
239 link = _dbus_list_get_first_link (&watch_list->watches);
242 DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
245 if (!(* add_function) (link->data, data))
247 /* remove it all again and return FALSE */
250 link2 = _dbus_list_get_first_link (&watch_list->watches);
251 while (link2 != link)
253 DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
256 (* remove_function) (link2->data, data);
268 /* Remove all current watches from previous watch handlers */
270 if (watch_list->remove_watch_function != NULL)
272 _dbus_list_foreach (&watch_list->watches,
273 (DBusForeachFunction) watch_list->remove_watch_function,
274 watch_list->watch_data);
277 if (watch_list->watch_free_data_function != NULL)
278 (* watch_list->watch_free_data_function) (watch_list->watch_data);
280 watch_list->add_watch_function = add_function;
281 watch_list->remove_watch_function = remove_function;
282 watch_list->watch_toggled_function = toggled_function;
283 watch_list->watch_data = data;
284 watch_list->watch_free_data_function = free_data_function;
290 * Adds a new watch to the watch list, invoking the
291 * application DBusAddWatchFunction if appropriate.
293 * @param watch_list the watch list.
294 * @param watch the watch to add.
295 * @returns #TRUE on success, #FALSE if no memory.
298 _dbus_watch_list_add_watch (DBusWatchList *watch_list,
301 if (!_dbus_list_append (&watch_list->watches, watch))
304 _dbus_watch_ref (watch);
306 if (watch_list->add_watch_function != NULL)
308 if (!(* watch_list->add_watch_function) (watch,
309 watch_list->watch_data))
311 _dbus_list_remove_last (&watch_list->watches, watch);
312 _dbus_watch_unref (watch);
321 * Removes a watch from the watch list, invoking the
322 * application's DBusRemoveWatchFunction if appropriate.
324 * @param watch_list the watch list.
325 * @param watch the watch to remove.
328 _dbus_watch_list_remove_watch (DBusWatchList *watch_list,
331 if (!_dbus_list_remove (&watch_list->watches, watch))
332 _dbus_assert_not_reached ("Nonexistent watch was removed");
334 if (watch_list->remove_watch_function != NULL)
335 (* watch_list->remove_watch_function) (watch,
336 watch_list->watch_data);
338 _dbus_watch_unref (watch);
342 * Sets a watch to the given enabled state, invoking the
343 * application's DBusWatchToggledFunction if appropriate.
345 * @param watch_list the watch list.
346 * @param watch the watch to toggle.
347 * @param enabled #TRUE to enable
350 _dbus_watch_list_toggle_watch (DBusWatchList *watch_list,
356 if (enabled == watch->enabled)
359 watch->enabled = enabled;
361 if (watch_list->watch_toggled_function != NULL)
362 (* watch_list->watch_toggled_function) (watch,
363 watch_list->watch_data);
369 * @defgroup DBusWatch DBusWatch
371 * @brief Object representing a file descriptor to be watched.
373 * Types and functions related to DBusWatch. A watch represents
374 * a file descriptor that the main loop needs to monitor,
375 * as in Qt's QSocketNotifier or GLib's g_io_add_watch().
383 * Opaque object representing a file descriptor
384 * to be watched for changes in readability,
385 * writability, or hangup.
389 * Gets the file descriptor that should be watched.
391 * @param watch the DBusWatch object.
392 * @returns the file descriptor to watch.
395 dbus_watch_get_fd (DBusWatch *watch)
401 * Gets flags from DBusWatchFlags indicating
402 * what conditions should be monitored on the
405 * The flags returned will only contain DBUS_WATCH_READABLE
406 * and DBUS_WATCH_WRITABLE, never DBUS_WATCH_HANGUP or
407 * DBUS_WATCH_ERROR; all watches implicitly include a watch
408 * for hangups, errors, and other exceptional conditions.
410 * @param watch the DBusWatch object.
411 * @returns the conditions to watch.
414 dbus_watch_get_flags (DBusWatch *watch)
416 _dbus_assert ((watch->flags & VALID_WATCH_FLAGS) == watch->flags);
422 * Gets data previously set with dbus_watch_set_data()
425 * @param watch the DBusWatch object.
426 * @returns previously-set data.
429 dbus_watch_get_data (DBusWatch *watch)
435 * Sets data which can be retrieved with dbus_watch_get_data().
436 * Intended for use by the DBusAddWatchFunction and
437 * DBusRemoveWatchFunction to store their own data. For example with
438 * Qt you might store the QSocketNotifier for this watch and with GLib
439 * you might store a GSource.
441 * @param watch the DBusWatch object.
442 * @param data the data.
443 * @param free_data_function function to be called to free the data.
446 dbus_watch_set_data (DBusWatch *watch,
448 DBusFreeFunction free_data_function)
450 if (watch->free_data_function != NULL)
451 (* watch->free_data_function) (watch->data);
454 watch->free_data_function = free_data_function;
458 * Returns whether a watch is enabled or not. If not
459 * enabled, it should not be polled by the main loop.
461 * @param watch the DBusWatch object
462 * @returns #TRUE if the watch is enabled
465 dbus_watch_get_enabled (DBusWatch *watch)
467 return watch->enabled;