include/qemu/filemonitor.h

   1 /*
   2  * QEMU file monitor helper
   3  *
   4  * Copyright (c) 2018 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20
  21 #ifndef QEMU_FILEMONITOR_H
  22 #define QEMU_FILEMONITOR_H
  23
  24
  25
  26 typedef struct QFileMonitor QFileMonitor;
  27
  28 typedef enum {
  29     /* File has been created in a dir */
  30     QFILE_MONITOR_EVENT_CREATED,
  31     /* File has been modified in a dir */
  32     QFILE_MONITOR_EVENT_MODIFIED,
  33     /* File has been deleted in a dir */
  34     QFILE_MONITOR_EVENT_DELETED,
  35     /* File has attributes changed */
  36     QFILE_MONITOR_EVENT_ATTRIBUTES,
  37     /* Dir is no longer being monitored (due to deletion) */
  38     QFILE_MONITOR_EVENT_IGNORED,
  39 } QFileMonitorEvent;
  40
  41
  42 /**
  43  * QFileMonitorHandler:
  44  * @id: id from qemu_file_monitor_add_watch()
  45  * @event: the file change that occurred
  46  * @filename: the name of the file affected
  47  * @opaque: opaque data provided to qemu_file_monitor_add_watch()
  48  *
  49  * Invoked whenever a file changes. If @event is
  50  * QFILE_MONITOR_EVENT_IGNORED, @filename will be
  51  * empty.
  52  *
  53  */
  54 typedef void (*QFileMonitorHandler)(int64_t id,
  55                                     QFileMonitorEvent event,
  56                                     const char *filename,
  57                                     void *opaque);
  58
  59 /**
  60  * qemu_file_monitor_new:
  61  * @errp: pointer to a NULL-initialized error object
  62  *
  63  * Create a handle for a file monitoring object.
  64  *
  65  * This object does locking internally to enable it to be
  66  * safe to use from multiple threads
  67  *
  68  * If the platform does not support file monitoring, an
  69  * error will be reported. Likewise if file monitoring
  70  * is supported, but cannot be initialized
  71  *
  72  * Currently this is implemented on Linux platforms with
  73  * the inotify subsystem.
  74  *
  75  * Returns: the new monitoring object, or NULL on error
  76  */
  77 QFileMonitor *qemu_file_monitor_new(Error **errp);
  78
  79 /**
  80  * qemu_file_monitor_free:
  81  * @mon: the file monitor context
  82  *
  83  * Free resources associated with the file monitor,
  84  * including any currently registered watches.
  85  */
  86 void qemu_file_monitor_free(QFileMonitor *mon);
  87
  88 /**
  89  * qemu_file_monitor_add_watch:
  90  * @mon: the file monitor context
  91  * @dirpath: the directory whose contents to watch
  92  * @filename: optional filename to filter on
  93  * @cb: the function to invoke when @dirpath has changes
  94  * @opaque: data to pass to @cb
  95  * @errp: pointer to a NULL-initialized error object
  96  *
  97  * Register to receive notifications of changes
  98  * in the directory @dirpath. All files in the
  99  * directory will be monitored. If the caller is
 100  * only interested in one specific file, @filename
 101  * can be used to filter events.
 102  *
 103  * Returns: a positive integer watch ID, or -1 on error
 104  */
 105 int64_t qemu_file_monitor_add_watch(QFileMonitor *mon,
 106                                     const char *dirpath,
 107                                     const char *filename,
 108                                     QFileMonitorHandler cb,
 109                                     void *opaque,
 110                                     Error **errp);
 111
 112 /**
 113  * qemu_file_monitor_remove_watch:
 114  * @mon: the file monitor context
 115  * @dirpath: the directory whose contents to unwatch
 116  * @id: id of the watch to remove
 117  *
 118  * Removes the file monitoring watch @id, associated
 119  * with the directory @dirpath. This must never be
 120  * called from a QFileMonitorHandler callback, or a
 121  * deadlock will result.
 122  */
 123 void qemu_file_monitor_remove_watch(QFileMonitor *mon,
 124                                     const char *dirpath,
 125                                     int64_t id);
 126
 127 #endif /* QEMU_FILEMONITOR_H */