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