LXR qemu/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
  26typedef struct QFileMonitor QFileMonitor;
  27
  28typedef 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 */
  54typedef 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 */
  77QFileMonitor *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 */
  86void 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 */
 105int64_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 */
 123void qemu_file_monitor_remove_watch(QFileMonitor *mon,
 124                                    const char *dirpath,
 125                                    int64_t id);
 126
 127#endif /* QEMU_FILEMONITOR_H */
 128