dbus/dbus-watch.c

   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
  57 _dbus_watch_get_enabled (DBusWatch *watch)
  58 {
  59   return watch->enabled;
  60 }
  61
  62 dbus_bool_t
  63 _dbus_watch_get_oom_last_time (DBusWatch *watch)
  64 {
  65   return watch->oom_last_time;
  66 }
  67
  68 void
  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*
  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 *
 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
 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
 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
 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*
 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
 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*
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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*
 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
 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
 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
 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 /** @} */