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   DBusAddWatchFunction 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 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  *
 216  */
 217 void
 218 _dbus_watch_list_set_functions (DBusWatchList           *watch_list,
 219                                 DBusAddWatchFunction     add_function,
 220                                 DBusRemoveWatchFunction  remove_function,
 221                                 void                    *data,
 222                                 DBusFreeFunction         free_data_function)
 223 {
 224   /* Remove all current watches from previous watch handlers */
 225
 226   if (watch_list->remove_watch_function != NULL)
 227     {
 228       _dbus_list_foreach (&watch_list->watches,
 229                           (DBusForeachFunction) watch_list->remove_watch_function,
 230                           watch_list->watch_data);
 231     }
 232
 233   if (watch_list->watch_free_data_function != NULL)
 234     (* watch_list->watch_free_data_function) (watch_list->watch_data);
 235
 236   watch_list->add_watch_function = add_function;
 237   watch_list->remove_watch_function = remove_function;
 238   watch_list->watch_data = data;
 239   watch_list->watch_free_data_function = free_data_function;
 240
 241   /* Re-add all pending watches */
 242   if (watch_list->add_watch_function != NULL)
 243     {
 244       _dbus_list_foreach (&watch_list->watches,
 245                           (DBusForeachFunction) watch_list->add_watch_function,
 246                           watch_list->watch_data);
 247     }
 248 }
 249
 250 /**
 251  * Adds a new watch to the watch list, invoking the
 252  * application DBusAddWatchFunction if appropriate.
 253  *
 254  * @param watch_list the watch list.
 255  * @param watch the watch to add.
 256  * @returns #TRUE on success, #FALSE if no memory.
 257  */
 258 dbus_bool_t
 259 _dbus_watch_list_add_watch (DBusWatchList *watch_list,
 260                             DBusWatch     *watch)
 261 {
 262   if (!_dbus_list_append (&watch_list->watches, watch))
 263     return FALSE;
 264
 265   _dbus_watch_ref (watch);
 266
 267   if (watch_list->add_watch_function != NULL)
 268     (* watch_list->add_watch_function) (watch,
 269                                         watch_list->watch_data);
 270
 271   return TRUE;
 272 }
 273
 274 /**
 275  * Removes a watch from the watch list, invoking the
 276  * application's DBusRemoveWatchFunction if appropriate.
 277  *
 278  * @param watch_list the watch list.
 279  * @param watch the watch to remove.
 280  */
 281 void
 282 _dbus_watch_list_remove_watch  (DBusWatchList *watch_list,
 283                                 DBusWatch     *watch)
 284 {
 285   if (!_dbus_list_remove (&watch_list->watches, watch))
 286     _dbus_assert_not_reached ("Nonexistent watch was removed");
 287
 288   if (watch_list->remove_watch_function != NULL)
 289     (* watch_list->remove_watch_function) (watch,
 290                                            watch_list->watch_data);
 291
 292   _dbus_watch_unref (watch);
 293 }
 294
 295 /** @} */
 296
 297 /**
 298  * @defgroup DBusWatch DBusWatch
 299  * @ingroup  DBus
 300  * @brief Object representing a file descriptor to be watched.
 301  *
 302  * Types and functions related to DBusWatch. A watch represents
 303  * a file descriptor that the main loop needs to monitor,
 304  * as in Qt's QSocketNotifier or GLib's g_io_add_watch().
 305  *
 306  * @{
 307  */
 308
 309 /**
 310  * @typedef DBusWatch
 311  *
 312  * Opaque object representing a file descriptor
 313  * to be watched for changes in readability,
 314  * writability, or hangup.
 315  */
 316
 317 /**
 318  * Gets the file descriptor that should be watched.
 319  *
 320  * @param watch the DBusWatch object.
 321  * @returns the file descriptor to watch.
 322  */
 323 int
 324 dbus_watch_get_fd (DBusWatch *watch)
 325 {
 326   return watch->fd;
 327 }
 328
 329 /**
 330  * Gets flags from DBusWatchFlags indicating
 331  * what conditions should be monitored on the
 332  * file descriptor.
 333  *
 334  * @param watch the DBusWatch object.
 335  * @returns the conditions to watch.
 336  */
 337 unsigned int
 338 dbus_watch_get_flags (DBusWatch *watch)
 339 {
 340   _dbus_assert ((watch->flags & VALID_WATCH_FLAGS) == watch->flags);
 341
 342   return watch->flags;
 343 }
 344
 345 /**
 346  * Gets data previously set with dbus_watch_set_data()
 347  * or #NULL if none.
 348  *
 349  * @param watch the DBusWatch object.
 350  * @returns previously-set data.
 351  */
 352 void*
 353 dbus_watch_get_data (DBusWatch *watch)
 354 {
 355   return watch->data;
 356 }
 357
 358 /**
 359  * Sets data which can be retrieved with dbus_watch_get_data().
 360  * Intended for use by the DBusAddWatchFunction and
 361  * DBusRemoveWatchFunction to store their own data.  For example with
 362  * Qt you might store the QSocketNotifier for this watch and with GLib
 363  * you might store a GSource.
 364  *
 365  * @param watch the DBusWatch object.
 366  * @param data the data.
 367  * @param free_data_function function to be called to free the data.
 368  */
 369 void
 370 dbus_watch_set_data (DBusWatch        *watch,
 371                      void             *data,
 372                      DBusFreeFunction  free_data_function)
 373 {
 374   if (watch->free_data_function != NULL)
 375     (* watch->free_data_function) (watch->data);
 376
 377   watch->data = data;
 378   watch->free_data_function = free_data_function;
 379 }
 380
 381 /** @} */