include/qemu/filemonitor.h

/*
 * QEMU file monitor helper
 *
 * Copyright (c) 2018 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef QEMU_FILEMONITOR_H
#define QEMU_FILEMONITOR_H



typedef struct QFileMonitor QFileMonitor;

typedef enum {
    /* File has been created in a dir */
    QFILE_MONITOR_EVENT_CREATED,
    /* File has been modified in a dir */
    QFILE_MONITOR_EVENT_MODIFIED,
    /* File has been deleted in a dir */
    QFILE_MONITOR_EVENT_DELETED,
    /* File has attributes changed */
    QFILE_MONITOR_EVENT_ATTRIBUTES,
    /* Dir is no longer being monitored (due to deletion) */
    QFILE_MONITOR_EVENT_IGNORED,
} QFileMonitorEvent;


/**
 * QFileMonitorHandler:
 * @id: id from qemu_file_monitor_add_watch()
 * @event: the file change that occurred
 * @filename: the name of the file affected
 * @opaque: opaque data provided to qemu_file_monitor_add_watch()
 *
 * Invoked whenever a file changes. If @event is
 * QFILE_MONITOR_EVENT_IGNORED, @filename will be
 * empty.
 *
 */
typedef void (*QFileMonitorHandler)(int64_t id,
                                    QFileMonitorEvent event,
                                    const char *filename,
                                    void *opaque);

/**
 * qemu_file_monitor_new:
 * @errp: pointer to a NULL-initialized error object
 *
 * Create a handle for a file monitoring object.
 *
 * This object does locking internally to enable it to be
 * safe to use from multiple threads
 *
 * If the platform does not support file monitoring, an
 * error will be reported. Likewise if file monitoring
 * is supported, but cannot be initialized
 *
 * Currently this is implemented on Linux platforms with
 * the inotify subsystem.
 *
 * Returns: the new monitoring object, or NULL on error
 */
QFileMonitor *qemu_file_monitor_new(Error **errp);

/**
 * qemu_file_monitor_free:
 * @mon: the file monitor context
 *
 * Free resources associated with the file monitor,
 * including any currently registered watches.
 */
void qemu_file_monitor_free(QFileMonitor *mon);

/**
 * qemu_file_monitor_add_watch:
 * @mon: the file monitor context
 * @dirpath: the directory whose contents to watch
 * @filename: optional filename to filter on
 * @cb: the function to invoke when @dirpath has changes
 * @opaque: data to pass to @cb
 * @errp: pointer to a NULL-initialized error object
 *
 * Register to receive notifications of changes
 * in the directory @dirpath. All files in the
 * directory will be monitored. If the caller is
 * only interested in one specific file, @filename
 * can be used to filter events.
 *
 * Returns: a positive integer watch ID, or -1 on error
 */
int64_t qemu_file_monitor_add_watch(QFileMonitor *mon,
                                    const char *dirpath,
                                    const char *filename,
                                    QFileMonitorHandler cb,
                                    void *opaque,
                                    Error **errp);

/**
 * qemu_file_monitor_remove_watch:
 * @mon: the file monitor context
 * @dirpath: the directory whose contents to unwatch
 * @id: id of the watch to remove
 *
 * Removes the file monitoring watch @id, associated
 * with the directory @dirpath. This must never be
 * called from a QFileMonitorHandler callback, or a
 * deadlock will result.
 */
void qemu_file_monitor_remove_watch(QFileMonitor *mon,
                                    const char *dirpath,
                                    int64_t id);

#endif /* QEMU_FILEMONITOR_H */