1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-watch.c DBusWatch implementation
3 *
4 * Copyright (C) 2002, 2003 Red Hat Inc.
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-watch.h"
27 #include "dbus-list.h"
28
29 /**
30 * @defgroup DBusWatchInternals DBusWatch implementation details
31 * @ingroup DBusInternals
32 * @brief implementation details for DBusWatch
33 *
34 * @{
35 */
36
37 /**
38 * Implementation of DBusWatch
39 */
40 struct DBusWatch
41 {
42 int refcount; /**< Reference count */
43 int fd; /**< File descriptor. */
44 unsigned int flags; /**< Conditions to watch. */
45
46 DBusWatchHandler handler; /**< Watch handler. */
47 void *handler_data; /**< Watch handler data. */
48 DBusFreeFunction free_handler_data_function; /**< Free the watch handler data. */
49
50 void *data; /**< Application data. */
51 DBusFreeFunction free_data_function; /**< Free the application data. */
52 unsigned int enabled : 1; /**< Whether it's enabled. */
53 };
54
55 dbus_bool_t
_dbus_watch_get_enabled(DBusWatch * watch)56 _dbus_watch_get_enabled (DBusWatch *watch)
57 {
58 return watch->enabled;
59 }
60
61 /**
62 * Creates a new DBusWatch. Used to add a file descriptor to be polled
63 * by a main loop.
64 *
65 * @param fd the file descriptor to be watched.
66 * @param flags the conditions to watch for on the descriptor.
67 * @param enabled the initial enabled state
68 * @param handler the handler function
69 * @param data data for handler function
70 * @param free_data_function function to free the data
71 * @returns the new DBusWatch object.
72 */
73 DBusWatch*
_dbus_watch_new(int fd,unsigned int flags,dbus_bool_t enabled,DBusWatchHandler handler,void * data,DBusFreeFunction free_data_function)74 _dbus_watch_new (int fd,
75 unsigned int flags,
76 dbus_bool_t enabled,
77 DBusWatchHandler handler,
78 void *data,
79 DBusFreeFunction free_data_function)
80 {
81 DBusWatch *watch;
82
83 #define VALID_WATCH_FLAGS (DBUS_WATCH_WRITABLE | DBUS_WATCH_READABLE)
84
85 _dbus_assert ((flags & VALID_WATCH_FLAGS) == flags);
86
87 watch = dbus_new0 (DBusWatch, 1);
88 if (watch == NULL)
89 return NULL;
90
91 watch->refcount = 1;
92 watch->fd = fd;
93 watch->flags = flags;
94 watch->enabled = enabled;
95
96 watch->handler = handler;
97 watch->handler_data = data;
98 watch->free_handler_data_function = free_data_function;
99
100 return watch;
101 }
102
103 /**
104 * Increments the reference count of a DBusWatch object.
105 *
106 * @param watch the watch object.
107 * @returns the watch object.
108 */
109 DBusWatch *
_dbus_watch_ref(DBusWatch * watch)110 _dbus_watch_ref (DBusWatch *watch)
111 {
112 watch->refcount += 1;
113
114 return watch;
115 }
116
117 /**
118 * Decrements the reference count of a DBusWatch object
119 * and finalizes the object if the count reaches zero.
120 *
121 * @param watch the watch object.
122 */
123 void
_dbus_watch_unref(DBusWatch * watch)124 _dbus_watch_unref (DBusWatch *watch)
125 {
126 _dbus_assert (watch != NULL);
127 _dbus_assert (watch->refcount > 0);
128
129 watch->refcount -= 1;
130 if (watch->refcount == 0)
131 {
132 dbus_watch_set_data (watch, NULL, NULL); /* call free_data_function */
133
134 if (watch->free_handler_data_function)
135 (* watch->free_handler_data_function) (watch->handler_data);
136
137 dbus_free (watch);
138 }
139 }
140
141 /**
142 * Clears the file descriptor from a now-invalid watch object so that
143 * no one tries to use it. This is because a watch may stay alive due
144 * to reference counts after the file descriptor is closed.
145 * Invalidation makes it easier to catch bugs. It also
146 * keeps people from doing dorky things like assuming file descriptors
147 * are unique (never recycled).
148 *
149 * @param watch the watch object.
150 */
151 void
_dbus_watch_invalidate(DBusWatch * watch)152 _dbus_watch_invalidate (DBusWatch *watch)
153 {
154 watch->fd = -1;
155 watch->flags = 0;
156 }
157
158 /**
159 * Sanitizes the given condition so that it only contains
160 * flags that the DBusWatch requested. e.g. if the
161 * watch is a DBUS_WATCH_READABLE watch then
162 * DBUS_WATCH_WRITABLE will be stripped from the condition.
163 *
164 * @param watch the watch object.
165 * @param condition address of the condition to sanitize.
166 */
167 void
_dbus_watch_sanitize_condition(DBusWatch * watch,unsigned int * condition)168 _dbus_watch_sanitize_condition (DBusWatch *watch,
169 unsigned int *condition)
170 {
171 if (!(watch->flags & DBUS_WATCH_READABLE))
172 *condition &= ~DBUS_WATCH_READABLE;
173 if (!(watch->flags & DBUS_WATCH_WRITABLE))
174 *condition &= ~DBUS_WATCH_WRITABLE;
175 }
176
177
178 /**
179 * @typedef DBusWatchList
180 *
181 * Opaque data type representing a list of watches
182 * and a set of DBusAddWatchFunction/DBusRemoveWatchFunction.
183 * Automatically handles removing/re-adding watches
184 * when the DBusAddWatchFunction is updated or changed.
185 * Holds a reference count to each watch.
186 *
187 * Used in the implementation of both DBusServer and
188 * DBusClient.
189 *
190 */
191
192 /**
193 * DBusWatchList implementation details. All fields
194 * are private.
195 *
196 */
197 struct DBusWatchList
198 {
199 DBusList *watches; /**< Watch objects. */
200
201 DBusAddWatchFunction add_watch_function; /**< Callback for adding a watch. */
202 DBusRemoveWatchFunction remove_watch_function; /**< Callback for removing a watch. */
203 DBusWatchToggledFunction watch_toggled_function; /**< Callback on toggling enablement */
204 void *watch_data; /**< Data for watch callbacks */
205 DBusFreeFunction watch_free_data_function; /**< Free function for watch callback data */
206 };
207
208 /**
209 * Creates a new watch list. Returns #NULL if insufficient
210 * memory exists.
211 *
212 * @returns the new watch list, or #NULL on failure.
213 */
214 DBusWatchList*
_dbus_watch_list_new(void)215 _dbus_watch_list_new (void)
216 {
217 DBusWatchList *watch_list;
218
219 watch_list = dbus_new0 (DBusWatchList, 1);
220 if (watch_list == NULL)
221 return NULL;
222
223 return watch_list;
224 }
225
226 /**
227 * Frees a DBusWatchList.
228 *
229 * @param watch_list the watch list.
230 */
231 void
_dbus_watch_list_free(DBusWatchList * watch_list)232 _dbus_watch_list_free (DBusWatchList *watch_list)
233 {
234 /* free watch_data and removes watches as a side effect */
235 _dbus_watch_list_set_functions (watch_list,
236 NULL, NULL, NULL, NULL, NULL);
237 _dbus_list_foreach (&watch_list->watches,
238 (DBusForeachFunction) _dbus_watch_unref,
239 NULL);
240 _dbus_list_clear (&watch_list->watches);
241
242 dbus_free (watch_list);
243 }
244
245 /**
246 * Sets the watch functions. This function is the "backend"
247 * for dbus_connection_set_watch_functions() and
248 * dbus_server_set_watch_functions().
249 *
250 * @param watch_list the watch list.
251 * @param add_function the add watch function.
252 * @param remove_function the remove watch function.
253 * @param toggled_function function on toggling enabled flag, or #NULL
254 * @param data the data for those functions.
255 * @param free_data_function the function to free the data.
256 * @returns #FALSE if not enough memory
257 *
258 */
259 dbus_bool_t
_dbus_watch_list_set_functions(DBusWatchList * watch_list,DBusAddWatchFunction add_function,DBusRemoveWatchFunction remove_function,DBusWatchToggledFunction toggled_function,void * data,DBusFreeFunction free_data_function)260 _dbus_watch_list_set_functions (DBusWatchList *watch_list,
261 DBusAddWatchFunction add_function,
262 DBusRemoveWatchFunction remove_function,
263 DBusWatchToggledFunction toggled_function,
264 void *data,
265 DBusFreeFunction free_data_function)
266 {
267 /* Add watches with the new watch function, failing on OOM */
268 if (add_function != NULL)
269 {
270 DBusList *link;
271
272 link = _dbus_list_get_first_link (&watch_list->watches);
273 while (link != NULL)
274 {
275 DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
276 link);
277
278 #ifdef DBUS_ENABLE_VERBOSE_MODE
279 {
280 const char *watch_type;
281 int flags;
282
283 flags = dbus_watch_get_flags (link->data);
284 if ((flags & DBUS_WATCH_READABLE) &&
285 (flags & DBUS_WATCH_WRITABLE))
286 watch_type = "readwrite";
287 else if (flags & DBUS_WATCH_READABLE)
288 watch_type = "read";
289 else if (flags & DBUS_WATCH_WRITABLE)
290 watch_type = "write";
291 else
292 watch_type = "not read or write";
293
294 _dbus_verbose ("Adding a %s watch on fd %d using newly-set add watch function\n",
295 watch_type,
296 dbus_watch_get_socket (link->data));
297 }
298 #endif /* DBUS_ENABLE_VERBOSE_MODE */
299
300 if (!(* add_function) (link->data, data))
301 {
302 /* remove it all again and return FALSE */
303 DBusList *link2;
304
305 link2 = _dbus_list_get_first_link (&watch_list->watches);
306 while (link2 != link)
307 {
308 DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
309 link2);
310
311 _dbus_verbose ("Removing watch on fd %d using newly-set remove function because initial add failed\n",
312 dbus_watch_get_socket (link2->data));
313
314 (* remove_function) (link2->data, data);
315
316 link2 = next;
317 }
318
319 return FALSE;
320 }
321
322 link = next;
323 }
324 }
325
326 /* Remove all current watches from previous watch handlers */
327
328 if (watch_list->remove_watch_function != NULL)
329 {
330 _dbus_verbose ("Removing all pre-existing watches\n");
331
332 _dbus_list_foreach (&watch_list->watches,
333 (DBusForeachFunction) watch_list->remove_watch_function,
334 watch_list->watch_data);
335 }
336
337 if (watch_list->watch_free_data_function != NULL)
338 (* watch_list->watch_free_data_function) (watch_list->watch_data);
339
340 watch_list->add_watch_function = add_function;
341 watch_list->remove_watch_function = remove_function;
342 watch_list->watch_toggled_function = toggled_function;
343 watch_list->watch_data = data;
344 watch_list->watch_free_data_function = free_data_function;
345
346 return TRUE;
347 }
348
349 /**
350 * Adds a new watch to the watch list, invoking the
351 * application DBusAddWatchFunction if appropriate.
352 *
353 * @param watch_list the watch list.
354 * @param watch the watch to add.
355 * @returns #TRUE on success, #FALSE if no memory.
356 */
357 dbus_bool_t
_dbus_watch_list_add_watch(DBusWatchList * watch_list,DBusWatch * watch)358 _dbus_watch_list_add_watch (DBusWatchList *watch_list,
359 DBusWatch *watch)
360 {
361 if (!_dbus_list_append (&watch_list->watches, watch))
362 return FALSE;
363
364 _dbus_watch_ref (watch);
365
366 if (watch_list->add_watch_function != NULL)
367 {
368 _dbus_verbose ("Adding watch on fd %d\n",
369 dbus_watch_get_socket (watch));
370
371 if (!(* watch_list->add_watch_function) (watch,
372 watch_list->watch_data))
373 {
374 _dbus_list_remove_last (&watch_list->watches, watch);
375 _dbus_watch_unref (watch);
376 return FALSE;
377 }
378 }
379
380 return TRUE;
381 }
382
383 /**
384 * Removes a watch from the watch list, invoking the
385 * application's DBusRemoveWatchFunction if appropriate.
386 *
387 * @param watch_list the watch list.
388 * @param watch the watch to remove.
389 */
390 void
_dbus_watch_list_remove_watch(DBusWatchList * watch_list,DBusWatch * watch)391 _dbus_watch_list_remove_watch (DBusWatchList *watch_list,
392 DBusWatch *watch)
393 {
394 if (!_dbus_list_remove (&watch_list->watches, watch))
395 _dbus_assert_not_reached ("Nonexistent watch was removed");
396
397 if (watch_list->remove_watch_function != NULL)
398 {
399 _dbus_verbose ("Removing watch on fd %d\n",
400 dbus_watch_get_socket (watch));
401
402 (* watch_list->remove_watch_function) (watch,
403 watch_list->watch_data);
404 }
405
406 _dbus_watch_unref (watch);
407 }
408
409 /**
410 * Sets a watch to the given enabled state, invoking the
411 * application's DBusWatchToggledFunction if appropriate.
412 *
413 * @param watch_list the watch list.
414 * @param watch the watch to toggle.
415 * @param enabled #TRUE to enable
416 */
417 void
_dbus_watch_list_toggle_watch(DBusWatchList * watch_list,DBusWatch * watch,dbus_bool_t enabled)418 _dbus_watch_list_toggle_watch (DBusWatchList *watch_list,
419 DBusWatch *watch,
420 dbus_bool_t enabled)
421 {
422 enabled = !!enabled;
423
424 if (enabled == watch->enabled)
425 return;
426
427 watch->enabled = enabled;
428
429 if (watch_list->watch_toggled_function != NULL)
430 {
431 _dbus_verbose ("Toggling watch %p on fd %d to %d\n",
432 watch, dbus_watch_get_socket (watch), watch->enabled);
433
434 (* watch_list->watch_toggled_function) (watch,
435 watch_list->watch_data);
436 }
437 }
438
439 /**
440 * Sets the handler for the watch.
441 *
442 * @todo this function only exists because of the weird
443 * way connection watches are done, see the note
444 * in docs for _dbus_connection_handle_watch().
445 *
446 * @param watch the watch
447 * @param handler the new handler
448 * @param data the data
449 * @param free_data_function free data with this
450 */
451 void
_dbus_watch_set_handler(DBusWatch * watch,DBusWatchHandler handler,void * data,DBusFreeFunction free_data_function)452 _dbus_watch_set_handler (DBusWatch *watch,
453 DBusWatchHandler handler,
454 void *data,
455 DBusFreeFunction free_data_function)
456 {
457 if (watch->free_handler_data_function)
458 (* watch->free_handler_data_function) (watch->handler_data);
459
460 watch->handler = handler;
461 watch->handler_data = data;
462 watch->free_handler_data_function = free_data_function;
463 }
464
465 /** @} */
466
467 /**
468 * @defgroup DBusWatch DBusWatch
469 * @ingroup DBus
470 * @brief Object representing a file descriptor to be watched.
471 *
472 * Types and functions related to DBusWatch. A watch represents
473 * a file descriptor that the main loop needs to monitor,
474 * as in Qt's QSocketNotifier or GLib's g_io_add_watch().
475 *
476 * Use dbus_connection_set_watch_functions() or dbus_server_set_watch_functions()
477 * to be notified when libdbus needs to add or remove watches.
478 *
479 * @{
480 */
481
482 /**
483 * @typedef DBusWatch
484 *
485 * Opaque object representing a file descriptor
486 * to be watched for changes in readability,
487 * writability, or hangup.
488 */
489
490 /**
491 * Deprecated former name of dbus_watch_get_unix_fd().
492 *
493 * @param watch the DBusWatch object.
494 * @returns the file descriptor to watch.
495 */
496 int
dbus_watch_get_fd(DBusWatch * watch)497 dbus_watch_get_fd (DBusWatch *watch)
498 {
499 return dbus_watch_get_unix_fd(watch);
500 }
501
502 /**
503 * Returns a UNIX file descriptor to be watched,
504 * which may be a pipe, socket, or other type of
505 * descriptor. On UNIX this is preferred to
506 * dbus_watch_get_socket() since it works with
507 * more kinds of #DBusWatch.
508 *
509 * Always returns -1 on Windows. On Windows you use
510 * dbus_watch_get_socket() to get a Winsock socket to watch.
511 *
512 * @param watch the DBusWatch object.
513 * @returns the file descriptor to watch.
514 */
515 int
dbus_watch_get_unix_fd(DBusWatch * watch)516 dbus_watch_get_unix_fd (DBusWatch *watch)
517 {
518 /* FIXME remove #ifdef and do this on a lower level
519 * (watch should have set_socket and set_unix_fd and track
520 * which it has, and the transport should provide the
521 * appropriate watch type)
522 */
523 #ifdef DBUS_UNIX
524 return watch->fd;
525 #else
526 return dbus_watch_get_socket( watch );
527 #endif
528 }
529
530 /**
531 * Returns a socket to be watched, on UNIX this will return -1 if our
532 * transport is not socket-based so dbus_watch_get_unix_fd() is
533 * preferred.
534 *
535 * On Windows, dbus_watch_get_unix_fd() returns -1 but this function
536 * returns a Winsock socket (assuming the transport is socket-based,
537 * as it always is for now).
538 *
539 * @param watch the DBusWatch object.
540 * @returns the socket to watch.
541 */
542 int
dbus_watch_get_socket(DBusWatch * watch)543 dbus_watch_get_socket (DBusWatch *watch)
544 {
545 return watch->fd;
546 }
547
548 /**
549 * Gets flags from DBusWatchFlags indicating
550 * what conditions should be monitored on the
551 * file descriptor.
552 *
553 * The flags returned will only contain DBUS_WATCH_READABLE
554 * and DBUS_WATCH_WRITABLE, never DBUS_WATCH_HANGUP or
555 * DBUS_WATCH_ERROR; all watches implicitly include a watch
556 * for hangups, errors, and other exceptional conditions.
557 *
558 * @param watch the DBusWatch object.
559 * @returns the conditions to watch.
560 */
561 unsigned int
dbus_watch_get_flags(DBusWatch * watch)562 dbus_watch_get_flags (DBusWatch *watch)
563 {
564 _dbus_assert ((watch->flags & VALID_WATCH_FLAGS) == watch->flags);
565
566 return watch->flags;
567 }
568
569 /**
570 * Gets data previously set with dbus_watch_set_data()
571 * or #NULL if none.
572 *
573 * @param watch the DBusWatch object.
574 * @returns previously-set data.
575 */
576 void*
dbus_watch_get_data(DBusWatch * watch)577 dbus_watch_get_data (DBusWatch *watch)
578 {
579 return watch->data;
580 }
581
582 /**
583 * Sets data which can be retrieved with dbus_watch_get_data().
584 * Intended for use by the DBusAddWatchFunction and
585 * DBusRemoveWatchFunction to store their own data. For example with
586 * Qt you might store the QSocketNotifier for this watch and with GLib
587 * you might store a GSource.
588 *
589 * @param watch the DBusWatch object.
590 * @param data the data.
591 * @param free_data_function function to be called to free the data.
592 */
593 void
dbus_watch_set_data(DBusWatch * watch,void * data,DBusFreeFunction free_data_function)594 dbus_watch_set_data (DBusWatch *watch,
595 void *data,
596 DBusFreeFunction free_data_function)
597 {
598 _dbus_verbose ("Setting watch fd %d data to data = %p function = %p from data = %p function = %p\n",
599 dbus_watch_get_socket (watch),
600 data, free_data_function, watch->data, watch->free_data_function);
601
602 if (watch->free_data_function != NULL)
603 (* watch->free_data_function) (watch->data);
604
605 watch->data = data;
606 watch->free_data_function = free_data_function;
607 }
608
609 /**
610 * Returns whether a watch is enabled or not. If not
611 * enabled, it should not be polled by the main loop.
612 *
613 * @param watch the DBusWatch object
614 * @returns #TRUE if the watch is enabled
615 */
616 dbus_bool_t
dbus_watch_get_enabled(DBusWatch * watch)617 dbus_watch_get_enabled (DBusWatch *watch)
618 {
619 _dbus_assert (watch != NULL);
620 return watch->enabled;
621 }
622
623
624 /**
625 * Called to notify the D-Bus library when a previously-added watch is
626 * ready for reading or writing, or has an exception such as a hangup.
627 *
628 * If this function returns #FALSE, then the file descriptor may still
629 * be ready for reading or writing, but more memory is needed in order
630 * to do the reading or writing. If you ignore the #FALSE return, your
631 * application may spin in a busy loop on the file descriptor until
632 * memory becomes available, but nothing more catastrophic should
633 * happen.
634 *
635 * dbus_watch_handle() cannot be called during the
636 * DBusAddWatchFunction, as the connection will not be ready to handle
637 * that watch yet.
638 *
639 * It is not allowed to reference a DBusWatch after it has been passed
640 * to remove_function.
641 *
642 * @param watch the DBusWatch object.
643 * @param flags the poll condition using #DBusWatchFlags values
644 * @returns #FALSE if there wasn't enough memory
645 */
646 dbus_bool_t
dbus_watch_handle(DBusWatch * watch,unsigned int flags)647 dbus_watch_handle (DBusWatch *watch,
648 unsigned int flags)
649 {
650 #ifndef DBUS_DISABLE_CHECKS
651 if (watch->fd < 0 || watch->flags == 0)
652 {
653 _dbus_warn_check_failed ("Watch is invalid, it should have been removed\n");
654 return TRUE;
655 }
656 #endif
657
658 _dbus_return_val_if_fail (watch->fd >= 0 /* fails if watch was removed */, TRUE);
659
660 _dbus_watch_sanitize_condition (watch, &flags);
661
662 if (flags == 0)
663 {
664 _dbus_verbose ("After sanitization, watch flags on fd %d were 0\n",
665 watch->fd);
666 return TRUE;
667 }
668 else
669 return (* watch->handler) (watch, flags,
670 watch->handler_data);
671 }
672
673
674 /** @} */
675