dbus/dbus-watch.c

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