dbus/dbus-watch.c

   1 /* -*- mode: C; c-file-style: "gnu" -*- */
   2 /* dbus-watch.c DBusWatch implementation
   3  *
   4  * Copyright (C) 2002, 2003  Red Hat Inc.
   5  *
   6  * Licensed under the Academic Free License version 1.2
   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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  *
  22  */
  23
  24 #include "dbus-internals.h"
  25 #include "dbus-watch.h"
  26 #include "dbus-list.h"
  27
  28 /**
  29  * @defgroup DBusWatchInternals DBusWatch implementation details
  30  * @ingroup  DBusInternals
  31  * @brief implementation details for DBusWatch
  32  *
  33  * @{
  34  */
  35
  36 struct DBusWatch
  37 {
  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. */
  44 };
  45
  46 /**
  47  * Creates a new DBusWatch. Normally used by a DBusTransport
  48  * implementation.
  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.
  53  */
  54 DBusWatch*
  55 _dbus_watch_new (int          fd,
  56                  unsigned int flags,
  57                  dbus_bool_t  enabled)
  58 {
  59   DBusWatch *watch;
  60
  61 #define VALID_WATCH_FLAGS (DBUS_WATCH_WRITABLE | DBUS_WATCH_READABLE)
  62
  63   _dbus_assert ((flags & VALID_WATCH_FLAGS) == flags);
  64
  65   watch = dbus_new0 (DBusWatch, 1);
  66   watch->refcount = 1;
  67   watch->fd = fd;
  68   watch->flags = flags;
  69   watch->enabled = enabled;
  70
  71   return watch;
  72 }
  73
  74 /**
  75  * Increments the reference count of a DBusWatch object.
  76  *
  77  * @param watch the watch object.
  78  */
  79 void
  80 _dbus_watch_ref (DBusWatch *watch)
  81 {
  82   watch->refcount += 1;
  83 }
  84
  85 /**
  86  * Decrements the reference count of a DBusWatch object
  87  * and finalizes the object if the count reaches zero.
  88  *
  89  * @param watch the watch object.
  90  */
  91 void
  92 _dbus_watch_unref (DBusWatch *watch)
  93 {
  94   _dbus_assert (watch != NULL);
  95   _dbus_assert (watch->refcount > 0);
  96
  97   watch->refcount -= 1;
  98   if (watch->refcount == 0)
  99     {
 100       dbus_watch_set_data (watch, NULL, NULL); /* call free_data_function */
 101       dbus_free (watch);
 102     }
 103 }
 104
 105 /**
 106  * Clears the file descriptor from a now-invalid watch object so that
 107  * no one tries to use it.  This is because a watch may stay alive due
 108  * to reference counts after the file descriptor is closed.
 109  * Invalidation makes it easier to catch bugs. It also
 110  * keeps people from doing dorky things like assuming file descriptors
 111  * are unique (never recycled).
 112  *
 113  * @param watch the watch object.
 114  */
 115 void
 116 _dbus_watch_invalidate (DBusWatch *watch)
 117 {
 118   watch->fd = -1;
 119   watch->flags = 0;
 120 }
 121
 122 /**
 123  * Sanitizes the given condition so that it only contains
 124  * flags that the DBusWatch requested. e.g. if the
 125  * watch is a DBUS_WATCH_READABLE watch then
 126  * DBUS_WATCH_WRITABLE will be stripped from the condition.
 127  *
 128  * @param watch the watch object.
 129  * @param condition address of the condition to sanitize.
 130  */
 131 void
 132 _dbus_watch_sanitize_condition (DBusWatch    *watch,
 133                                 unsigned int *condition)
 134 {
 135   if (!(watch->flags & DBUS_WATCH_READABLE))
 136     *condition &= ~DBUS_WATCH_READABLE;
 137   if (!(watch->flags & DBUS_WATCH_WRITABLE))
 138     *condition &= ~DBUS_WATCH_WRITABLE;
 139 }
 140
 141
 142 /**
 143  * @typedef DBusWatchList
 144  *
 145  * Opaque data type representing a list of watches
 146  * and a set of DBusAddWatchFunction/DBusRemoveWatchFunction.
 147  * Automatically handles removing/re-adding watches
 148  * when the DBusAddWatchFunction is updated or changed.
 149  * Holds a reference count to each watch.
 150  *
 151  * Used in the implementation of both DBusServer and
 152  * DBusClient.
 153  *
 154  */
 155
 156 /**
 157  * DBusWatchList implementation details. All fields
 158  * are private.
 159  *
 160  */
 161 struct DBusWatchList
 162 {
 163   DBusList *watches;           /**< Watch objects. */
 164
 165   DBusAddWatchFunction add_watch_function;    /**< Callback for adding a watch. */
 166   DBusRemoveWatchFunction remove_watch_function; /**< Callback for removing a watch. */
 167   DBusWatchToggledFunction watch_toggled_function; /**< Callback on toggling enablement */
 168   void *watch_data;                           /**< Data for watch callbacks */
 169   DBusFreeFunction watch_free_data_function;  /**< Free function for watch callback data */
 170 };
 171
 172 /**
 173  * Creates a new watch list. Returns #NULL if insufficient
 174  * memory exists.
 175  *
 176  * @returns the new watch list, or #NULL on failure.
 177  */
 178 DBusWatchList*
 179 _dbus_watch_list_new (void)
 180 {
 181   DBusWatchList *watch_list;
 182
 183   watch_list = dbus_new0 (DBusWatchList, 1);
 184   if (watch_list == NULL)
 185     return NULL;
 186
 187   return watch_list;
 188 }
 189
 190 /**
 191  * Frees a DBusWatchList.
 192  *
 193  * @param watch_list the watch list.
 194  */
 195 void
 196 _dbus_watch_list_free (DBusWatchList *watch_list)
 197 {
 198   /* free watch_data and removes watches as a side effect */
 199   _dbus_watch_list_set_functions (watch_list,
 200                                   NULL, NULL, NULL, NULL, NULL);
 201
 202   _dbus_list_foreach (&watch_list->watches,
 203                       (DBusForeachFunction) _dbus_watch_unref,
 204                       NULL);
 205   _dbus_list_clear (&watch_list->watches);
 206
 207   dbus_free (watch_list);
 208 }
 209
 210 /**
 211  * Sets the watch functions. This function is the "backend"
 212  * for dbus_connection_set_watch_functions() and
 213  * dbus_server_set_watch_functions().
 214  *
 215  * @param watch_list the watch list.
 216  * @param add_function the add watch function.
 217  * @param remove_function the remove watch function.
 218  * @param toggled_function function on toggling enabled flag, or #NULL
 219  * @param data the data for those functions.
 220  * @param free_data_function the function to free the data.
 221  * @returns #FALSE if not enough memory
 222  *
 223  */
 224 dbus_bool_t
 225 _dbus_watch_list_set_functions (DBusWatchList           *watch_list,
 226                                 DBusAddWatchFunction     add_function,
 227                                 DBusRemoveWatchFunction  remove_function,
 228                                 DBusWatchToggledFunction toggled_function,
 229                                 void                    *data,
 230                                 DBusFreeFunction         free_data_function)
 231 {
 232   /* Add watches with the new watch function, failing on OOM */
 233   if (add_function != NULL)
 234     {
 235       DBusList *link;
 236
 237       link = _dbus_list_get_first_link (&watch_list->watches);
 238       while (link != NULL)
 239         {
 240           DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
 241                                                      link);
 242
 243           if (!(* add_function) (link->data, data))
 244             {
 245               /* remove it all again and return FALSE */
 246               DBusList *link2;
 247
 248               link2 = _dbus_list_get_first_link (&watch_list->watches);
 249               while (link2 != link)
 250                 {
 251                   DBusList *next = _dbus_list_get_next_link (&watch_list->watches,
 252                                                              link2);
 253
 254                   (* remove_function) (link2->data, data);
 255
 256                   link2 = next;
 257                 }
 258
 259               return FALSE;
 260             }
 261
 262           link = next;
 263         }
 264     }
 265
 266   /* Remove all current watches from previous watch handlers */
 267
 268   if (watch_list->remove_watch_function != NULL)
 269     {
 270       _dbus_list_foreach (&watch_list->watches,
 271                           (DBusForeachFunction) watch_list->remove_watch_function,
 272                           watch_list->watch_data);
 273     }
 274
 275   if (watch_list->watch_free_data_function != NULL)
 276     (* watch_list->watch_free_data_function) (watch_list->watch_data);
 277
 278   watch_list->add_watch_function = add_function;
 279   watch_list->remove_watch_function = remove_function;
 280   watch_list->watch_toggled_function = toggled_function;
 281   watch_list->watch_data = data;
 282   watch_list->watch_free_data_function = free_data_function;
 283
 284   return TRUE;
 285 }
 286
 287 /**
 288  * Adds a new watch to the watch list, invoking the
 289  * application DBusAddWatchFunction if appropriate.
 290  *
 291  * @param watch_list the watch list.
 292  * @param watch the watch to add.
 293  * @returns #TRUE on success, #FALSE if no memory.
 294  */
 295 dbus_bool_t
 296 _dbus_watch_list_add_watch (DBusWatchList *watch_list,
 297                             DBusWatch     *watch)
 298 {
 299   if (!_dbus_list_append (&watch_list->watches, watch))
 300     return FALSE;
 301
 302   _dbus_watch_ref (watch);
 303
 304   if (watch_list->add_watch_function != NULL)
 305     {
 306       if (!(* watch_list->add_watch_function) (watch,
 307                                                watch_list->watch_data))
 308         {
 309           _dbus_list_remove_last (&watch_list->watches, watch);
 310           _dbus_watch_unref (watch);
 311           return FALSE;
 312         }
 313     }
 314
 315   return TRUE;
 316 }
 317
 318 /**
 319  * Removes a watch from the watch list, invoking the
 320  * application's DBusRemoveWatchFunction if appropriate.
 321  *
 322  * @param watch_list the watch list.
 323  * @param watch the watch to remove.
 324  */
 325 void
 326 _dbus_watch_list_remove_watch  (DBusWatchList *watch_list,
 327                                 DBusWatch     *watch)
 328 {
 329   if (!_dbus_list_remove (&watch_list->watches, watch))
 330     _dbus_assert_not_reached ("Nonexistent watch was removed");
 331
 332   if (watch_list->remove_watch_function != NULL)
 333     (* watch_list->remove_watch_function) (watch,
 334                                            watch_list->watch_data);
 335
 336   _dbus_watch_unref (watch);
 337 }
 338
 339 /**
 340  * Sets a watch to the given enabled state, invoking the
 341  * application's DBusWatchToggledFunction if appropriate.
 342  *
 343  * @param watch_list the watch list.
 344  * @param watch the watch to toggle.
 345  * @param enabled #TRUE to enable
 346  */
 347 void
 348 _dbus_watch_list_toggle_watch (DBusWatchList           *watch_list,
 349                                DBusWatch               *watch,
 350                                dbus_bool_t              enabled)
 351 {
 352   enabled = !!enabled;
 353
 354   if (enabled == watch->enabled)
 355     return;
 356
 357   watch->enabled = enabled;
 358
 359   if (watch_list->watch_toggled_function != NULL)
 360     (* watch_list->watch_toggled_function) (watch,
 361                                             watch_list->watch_data);
 362 }
 363
 364 /** @} */
 365
 366 /**
 367  * @defgroup DBusWatch DBusWatch
 368  * @ingroup  DBus
 369  * @brief Object representing a file descriptor to be watched.
 370  *
 371  * Types and functions related to DBusWatch. A watch represents
 372  * a file descriptor that the main loop needs to monitor,
 373  * as in Qt's QSocketNotifier or GLib's g_io_add_watch().
 374  *
 375  * @{
 376  */
 377
 378 /**
 379  * @typedef DBusWatch
 380  *
 381  * Opaque object representing a file descriptor
 382  * to be watched for changes in readability,
 383  * writability, or hangup.
 384  */
 385
 386 /**
 387  * Gets the file descriptor that should be watched.
 388  *
 389  * @param watch the DBusWatch object.
 390  * @returns the file descriptor to watch.
 391  */
 392 int
 393 dbus_watch_get_fd (DBusWatch *watch)
 394 {
 395   return watch->fd;
 396 }
 397
 398 /**
 399  * Gets flags from DBusWatchFlags indicating
 400  * what conditions should be monitored on the
 401  * file descriptor.
 402  *
 403  * The flags returned will only contain DBUS_WATCH_READABLE
 404  * and DBUS_WATCH_WRITABLE, never DBUS_WATCH_HANGUP or
 405  * DBUS_WATCH_ERROR; all watches implicitly include a watch
 406  * for hangups, errors, and other exceptional conditions.
 407  *
 408  * @param watch the DBusWatch object.
 409  * @returns the conditions to watch.
 410  */
 411 unsigned int
 412 dbus_watch_get_flags (DBusWatch *watch)
 413 {
 414   _dbus_assert ((watch->flags & VALID_WATCH_FLAGS) == watch->flags);
 415
 416   return watch->flags;
 417 }
 418
 419 /**
 420  * Gets data previously set with dbus_watch_set_data()
 421  * or #NULL if none.
 422  *
 423  * @param watch the DBusWatch object.
 424  * @returns previously-set data.
 425  */
 426 void*
 427 dbus_watch_get_data (DBusWatch *watch)
 428 {
 429   return watch->data;
 430 }
 431
 432 /**
 433  * Sets data which can be retrieved with dbus_watch_get_data().
 434  * Intended for use by the DBusAddWatchFunction and
 435  * DBusRemoveWatchFunction to store their own data.  For example with
 436  * Qt you might store the QSocketNotifier for this watch and with GLib
 437  * you might store a GSource.
 438  *
 439  * @param watch the DBusWatch object.
 440  * @param data the data.
 441  * @param free_data_function function to be called to free the data.
 442  */
 443 void
 444 dbus_watch_set_data (DBusWatch        *watch,
 445                      void             *data,
 446                      DBusFreeFunction  free_data_function)
 447 {
 448   if (watch->free_data_function != NULL)
 449     (* watch->free_data_function) (watch->data);
 450
 451   watch->data = data;
 452   watch->free_data_function = free_data_function;
 453 }
 454
 455 /**
 456  * Returns whether a watch is enabled or not. If not
 457  * enabled, it should not be polled by the main loop.
 458  *
 459  * @param watch the DBusWatch object
 460  * @returns #TRUE if the watch is enabled
 461  */
 462 dbus_bool_t
 463 dbus_watch_get_enabled (DBusWatch *watch)
 464 {
 465   return watch->enabled;
 466 }
 467
 468 /** @} */