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 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_FILE_MONITOR_H
  22 #define QEMU_FILE_MONITOR_H
  23
  24 #include "qemu-common.h"
  25
  26
  27 typedef struct QFileMonitor QFileMonitor;
  28
  29 typedef enum {
  30     /* File has been created in a dir */
  31     QFILE_MONITOR_EVENT_CREATED,
  32     /* File has been modified in a dir */
  33     QFILE_MONITOR_EVENT_MODIFIED,
  34     /* File has been deleted in a dir */
  35     QFILE_MONITOR_EVENT_DELETED,
  36     /* File has attributes changed */
  37     QFILE_MONITOR_EVENT_ATTRIBUTES,
  38     /* Dir is no longer being monitored (due to deletion) */
  39     QFILE_MONITOR_EVENT_IGNORED,
  40 } QFileMonitorEvent;
  41
  42
  43 /**
  44  * QFileMonitorHandler:
  45  * @id: id from qemu_file_monitor_add_watch()
  46  * @event: the file change that occurred
  47  * @filename: the name of the file affected
  48  * @opaque: opaque data provided to qemu_file_monitor_add_watch()
  49  *
  50  * Invoked whenever a file changes. If @event is
  51  * QFILE_MONITOR_EVENT_IGNORED, @filename will be
  52  * empty.
  53  *
  54  */
  55 typedef void (*QFileMonitorHandler)(int64_t id,
  56                                     QFileMonitorEvent event,
  57                                     const char *filename,
  58                                     void *opaque);
  59
  60 /**
  61  * qemu_file_monitor_new:
  62  * @errp: pointer to a NULL-initialized error object
  63  *
  64  * Create a handle for a file monitoring object.
  65  *
  66  * This object does locking internally to enable it to be
  67  * safe to use from multiple threads
  68  *
  69  * If the platform does not support file monitoring, an
  70  * error will be reported. Likewise if file monitoring
  71  * is supported, but cannot be initialized
  72  *
  73  * Currently this is implemented on Linux platforms with
  74  * the inotify subsystem.
  75  *
  76  * Returns: the new monitoring object, or NULL on error
  77  */
  78 QFileMonitor *qemu_file_monitor_new(Error **errp);
  79
  80 /**
  81  * qemu_file_monitor_free:
  82  * @mon: the file monitor context
  83  *
  84  * Free resources associated with the file monitor,
  85  * including any currently registered watches.
  86  */
  87 void qemu_file_monitor_free(QFileMonitor *mon);
  88
  89 /**
  90  * qemu_file_monitor_add_watch:
  91  * @mon: the file monitor context
  92  * @dirpath: the directory whose contents to watch
  93  * @filename: optional filename to filter on
  94  * @cb: the function to invoke when @dirpath has changes
  95  * @opaque: data to pass to @cb
  96  * @errp: pointer to a NULL-initialized error object
  97  *
  98  * Register to receive notifications of changes
  99  * in the directory @dirpath. All files in the
 100  * directory will be monitored. If the caller is
 101  * only interested in one specific file, @filename
 102  * can be used to filter events.
 103  *
 104  * Returns: a positive integer watch ID, or -1 on error
 105  */
 106 int64_t qemu_file_monitor_add_watch(QFileMonitor *mon,
 107                                     const char *dirpath,
 108                                     const char *filename,
 109                                     QFileMonitorHandler cb,
 110                                     void *opaque,
 111                                     Error **errp);
 112
 113 /**
 114  * qemu_file_monitor_remove_watch:
 115  * @mon: the file monitor context
 116  * @dirpath: the directory whose contents to unwatch
 117  * @id: id of the watch to remove
 118  *
 119  * Removes the file monitoring watch @id, associated
 120  * with the directory @dirpath. This must never be
 121  * called from a QFileMonitorHandler callback, or a
 122  * deadlock will result.
 123  */
 124 void qemu_file_monitor_remove_watch(QFileMonitor *mon,
 125                                     const char *dirpath,
 126                                     int64_t id);
 127
 128 #endif /* QEMU_FILE_MONITOR_H */