gio/gfilemonitor.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2006-2007 Red Hat, Inc.
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Author: Alexander Larsson <alexl@redhat.com>
  21  */
  22
  23 #include "config.h"
  24 #include <string.h>
  25
  26 #include "gfilemonitor.h"
  27 #include "gioenumtypes.h"
  28 #include "gmarshal-internal.h"
  29 #include "gfile.h"
  30 #include "gvfs.h"
  31 #include "glibintl.h"
  32
  33 /**
  34  * SECTION:gfilemonitor
  35  * @short_description: File Monitor
  36  * @include: gio/gio.h
  37  *
  38  * Monitors a file or directory for changes.
  39  *
  40  * To obtain a #GFileMonitor for a file or directory, use
  41  * g_file_monitor(), g_file_monitor_file(), or
  42  * g_file_monitor_directory().
  43  *
  44  * To get informed about changes to the file or directory you are
  45  * monitoring, connect to the #GFileMonitor::changed signal. The
  46  * signal will be emitted in the
  47  * [thread-default main context][g-main-context-push-thread-default]
  48  * of the thread that the monitor was created in
  49  * (though if the global default main context is blocked, this may
  50  * cause notifications to be blocked even if the thread-default
  51  * context is still running).
  52  **/
  53
  54 #define DEFAULT_RATE_LIMIT_MSECS 800
  55
  56 struct _GFileMonitorPrivate
  57 {
  58   gboolean cancelled;
  59 };
  60
  61 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GFileMonitor, g_file_monitor, G_TYPE_OBJECT)
  62
  63 enum
  64 {
  65   PROP_0,
  66   PROP_RATE_LIMIT,
  67   PROP_CANCELLED
  68 };
  69
  70 static guint g_file_monitor_changed_signal;
  71
  72 static void
  73 g_file_monitor_set_property (GObject      *object,
  74                              guint         prop_id,
  75                              const GValue *value,
  76                              GParamSpec   *pspec)
  77 {
  78   //GFileMonitor *monitor;
  79
  80   //monitor = G_FILE_MONITOR (object);
  81
  82   switch (prop_id)
  83     {
  84     case PROP_RATE_LIMIT:
  85       /* not supported by default */
  86       break;
  87
  88     default:
  89       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
  90       break;
  91     }
  92 }
  93
  94 static void
  95 g_file_monitor_get_property (GObject    *object,
  96                              guint       prop_id,
  97                              GValue     *value,
  98                              GParamSpec *pspec)
  99 {
 100   switch (prop_id)
 101     {
 102     case PROP_RATE_LIMIT:
 103       /* we expect this to be overridden... */
 104       g_value_set_int (value, DEFAULT_RATE_LIMIT_MSECS);
 105       break;
 106
 107     case PROP_CANCELLED:
 108       //g_mutex_lock (&fms->lock);
 109       g_value_set_boolean (value, FALSE);//fms->cancelled);
 110       //g_mutex_unlock (&fms->lock);
 111       break;
 112
 113     default:
 114       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 115       break;
 116     }
 117 }
 118
 119 static void
 120 g_file_monitor_dispose (GObject *object)
 121 {
 122   GFileMonitor *monitor = G_FILE_MONITOR (object);
 123
 124   /* Make sure we cancel on last unref */
 125   g_file_monitor_cancel (monitor);
 126
 127   G_OBJECT_CLASS (g_file_monitor_parent_class)->dispose (object);
 128 }
 129
 130 static void
 131 g_file_monitor_init (GFileMonitor *monitor)
 132 {
 133   monitor->priv = g_file_monitor_get_instance_private (monitor);
 134 }
 135
 136 static void
 137 g_file_monitor_class_init (GFileMonitorClass *klass)
 138 {
 139   GObjectClass *object_class;
 140
 141   object_class = G_OBJECT_CLASS (klass);
 142   object_class->dispose = g_file_monitor_dispose;
 143   object_class->get_property = g_file_monitor_get_property;
 144   object_class->set_property = g_file_monitor_set_property;
 145
 146   /**
 147    * GFileMonitor::changed:
 148    * @monitor: a #GFileMonitor.
 149    * @file: a #GFile.
 150    * @other_file: (nullable): a #GFile or #NULL.
 151    * @event_type: a #GFileMonitorEvent.
 152    *
 153    * Emitted when @file has been changed.
 154    *
 155    * If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and
 156    * the information is available (and if supported by the backend),
 157    * @event_type may be %G_FILE_MONITOR_EVENT_RENAMED,
 158    * %G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT.
 159    *
 160    * In all cases @file will be a child of the monitored directory.  For
 161    * renames, @file will be the old name and @other_file is the new
 162    * name.  For "moved in" events, @file is the name of the file that
 163    * appeared and @other_file is the old name that it was moved from (in
 164    * another directory).  For "moved out" events, @file is the name of
 165    * the file that used to be in this directory and @other_file is the
 166    * name of the file at its new location.
 167    *
 168    * It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as
 169    * equivalent to %G_FILE_MONITOR_EVENT_CREATED and
 170    * %G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to
 171    * %G_FILE_MONITOR_EVENT_DELETED, with extra information.
 172    * %G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create
 173    * pair.  This is exactly how the events will be reported in the case
 174    * that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use.
 175    *
 176    * If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is
 177    * %G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
 178    * old path, and @other_file will be set to a #GFile containing the new path.
 179    *
 180    * In all the other cases, @other_file will be set to #NULL.
 181    **/
 182   g_file_monitor_changed_signal = g_signal_new (I_("changed"),
 183                                                 G_TYPE_FILE_MONITOR,
 184                                                 G_SIGNAL_RUN_LAST,
 185                                                 G_STRUCT_OFFSET (GFileMonitorClass, changed),
 186                                                 NULL, NULL,
 187                                                 _g_cclosure_marshal_VOID__OBJECT_OBJECT_ENUM,
 188                                                 G_TYPE_NONE, 3,
 189                                                 G_TYPE_FILE, G_TYPE_FILE, G_TYPE_FILE_MONITOR_EVENT);
 190   g_signal_set_va_marshaller (g_file_monitor_changed_signal,
 191                               G_TYPE_FROM_CLASS (klass),
 192                               _g_cclosure_marshal_VOID__OBJECT_OBJECT_ENUMv);
 193
 194   g_object_class_install_property (object_class, PROP_RATE_LIMIT,
 195                                    g_param_spec_int ("rate-limit",
 196                                                      P_("Rate limit"),
 197                                                      P_("The limit of the monitor to watch for changes, in milliseconds"),
 198                                                      0, G_MAXINT, DEFAULT_RATE_LIMIT_MSECS, G_PARAM_READWRITE |
 199                                                      G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS));
 200
 201   g_object_class_install_property (object_class, PROP_CANCELLED,
 202                                    g_param_spec_boolean ("cancelled",
 203                                                          P_("Cancelled"),
 204                                                          P_("Whether the monitor has been cancelled"),
 205                                                          FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 206 }
 207
 208 /**
 209  * g_file_monitor_is_cancelled:
 210  * @monitor: a #GFileMonitor
 211  *
 212  * Returns whether the monitor is canceled.
 213  *
 214  * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
 215  **/
 216 gboolean
 217 g_file_monitor_is_cancelled (GFileMonitor *monitor)
 218 {
 219   gboolean res;
 220
 221   g_return_val_if_fail (G_IS_FILE_MONITOR (monitor), FALSE);
 222
 223   res = monitor->priv->cancelled;
 224
 225   return res;
 226 }
 227
 228 /**
 229  * g_file_monitor_cancel:
 230  * @monitor: a #GFileMonitor.
 231  *
 232  * Cancels a file monitor.
 233  *
 234  * Returns: always %TRUE
 235  **/
 236 gboolean
 237 g_file_monitor_cancel (GFileMonitor *monitor)
 238 {
 239   g_return_val_if_fail (G_IS_FILE_MONITOR (monitor), FALSE);
 240
 241   if (!monitor->priv->cancelled)
 242     {
 243       G_FILE_MONITOR_GET_CLASS (monitor)->cancel (monitor);
 244
 245       monitor->priv->cancelled = TRUE;
 246       g_object_notify (G_OBJECT (monitor), "cancelled");
 247     }
 248
 249   return TRUE;
 250 }
 251
 252 /**
 253  * g_file_monitor_set_rate_limit:
 254  * @monitor: a #GFileMonitor.
 255  * @limit_msecs: a non-negative integer with the limit in milliseconds
 256  *     to poll for changes
 257  *
 258  * Sets the rate limit to which the @monitor will report
 259  * consecutive change events to the same file.
 260  */
 261 void
 262 g_file_monitor_set_rate_limit (GFileMonitor *monitor,
 263                                gint          limit_msecs)
 264 {
 265   g_object_set (monitor, "rate-limit", limit_msecs, NULL);
 266 }
 267
 268 /**
 269  * g_file_monitor_emit_event:
 270  * @monitor: a #GFileMonitor.
 271  * @child: a #GFile.
 272  * @other_file: a #GFile.
 273  * @event_type: a set of #GFileMonitorEvent flags.
 274  *
 275  * Emits the #GFileMonitor::changed signal if a change
 276  * has taken place. Should be called from file monitor
 277  * implementations only.
 278  *
 279  * Implementations are responsible to call this method from the
 280  * [thread-default main context][g-main-context-push-thread-default] of the
 281  * thread that the monitor was created in.
 282  **/
 283 void
 284 g_file_monitor_emit_event (GFileMonitor      *monitor,
 285                            GFile             *child,
 286                            GFile             *other_file,
 287                            GFileMonitorEvent  event_type)
 288 {
 289   g_return_if_fail (G_IS_FILE_MONITOR (monitor));
 290   g_return_if_fail (G_IS_FILE (child));
 291   g_return_if_fail (!other_file || G_IS_FILE (other_file));
 292
 293   if (monitor->priv->cancelled)
 294     return;
 295
 296   g_signal_emit (monitor, g_file_monitor_changed_signal, 0, child, other_file, event_type);
 297 }