190e33dfeSDaniel P. Berrangé /* 290e33dfeSDaniel P. Berrangé * QEMU file monitor helper 390e33dfeSDaniel P. Berrangé * 490e33dfeSDaniel P. Berrangé * Copyright (c) 2018 Red Hat, Inc. 590e33dfeSDaniel P. Berrangé * 690e33dfeSDaniel P. Berrangé * This library is free software; you can redistribute it and/or 790e33dfeSDaniel P. Berrangé * modify it under the terms of the GNU Lesser General Public 890e33dfeSDaniel P. Berrangé * License as published by the Free Software Foundation; either 9*61f3c91aSChetan Pant * version 2.1 of the License, or (at your option) any later version. 1090e33dfeSDaniel P. Berrangé * 1190e33dfeSDaniel P. Berrangé * This library is distributed in the hope that it will be useful, 1290e33dfeSDaniel P. Berrangé * but WITHOUT ANY WARRANTY; without even the implied warranty of 1390e33dfeSDaniel P. Berrangé * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 1490e33dfeSDaniel P. Berrangé * Lesser General Public License for more details. 1590e33dfeSDaniel P. Berrangé * 1690e33dfeSDaniel P. Berrangé * You should have received a copy of the GNU Lesser General Public 1790e33dfeSDaniel P. Berrangé * License along with this library; if not, see <http://www.gnu.org/licenses/>. 1890e33dfeSDaniel P. Berrangé * 1990e33dfeSDaniel P. Berrangé */ 2090e33dfeSDaniel P. Berrangé 2158ea30f5SMarkus Armbruster #ifndef QEMU_FILEMONITOR_H 2258ea30f5SMarkus Armbruster #define QEMU_FILEMONITOR_H 2390e33dfeSDaniel P. Berrangé 2490e33dfeSDaniel P. Berrangé 2590e33dfeSDaniel P. Berrangé 2690e33dfeSDaniel P. Berrangé typedef struct QFileMonitor QFileMonitor; 2790e33dfeSDaniel P. Berrangé 2890e33dfeSDaniel P. Berrangé typedef enum { 2990e33dfeSDaniel P. Berrangé /* File has been created in a dir */ 3090e33dfeSDaniel P. Berrangé QFILE_MONITOR_EVENT_CREATED, 3190e33dfeSDaniel P. Berrangé /* File has been modified in a dir */ 3290e33dfeSDaniel P. Berrangé QFILE_MONITOR_EVENT_MODIFIED, 3390e33dfeSDaniel P. Berrangé /* File has been deleted in a dir */ 3490e33dfeSDaniel P. Berrangé QFILE_MONITOR_EVENT_DELETED, 3590e33dfeSDaniel P. Berrangé /* File has attributes changed */ 3690e33dfeSDaniel P. Berrangé QFILE_MONITOR_EVENT_ATTRIBUTES, 3790e33dfeSDaniel P. Berrangé /* Dir is no longer being monitored (due to deletion) */ 3890e33dfeSDaniel P. Berrangé QFILE_MONITOR_EVENT_IGNORED, 3990e33dfeSDaniel P. Berrangé } QFileMonitorEvent; 4090e33dfeSDaniel P. Berrangé 4190e33dfeSDaniel P. Berrangé 4290e33dfeSDaniel P. Berrangé /** 4390e33dfeSDaniel P. Berrangé * QFileMonitorHandler: 4490e33dfeSDaniel P. Berrangé * @id: id from qemu_file_monitor_add_watch() 4590e33dfeSDaniel P. Berrangé * @event: the file change that occurred 4690e33dfeSDaniel P. Berrangé * @filename: the name of the file affected 4790e33dfeSDaniel P. Berrangé * @opaque: opaque data provided to qemu_file_monitor_add_watch() 4890e33dfeSDaniel P. Berrangé * 4990e33dfeSDaniel P. Berrangé * Invoked whenever a file changes. If @event is 5090e33dfeSDaniel P. Berrangé * QFILE_MONITOR_EVENT_IGNORED, @filename will be 5190e33dfeSDaniel P. Berrangé * empty. 5290e33dfeSDaniel P. Berrangé * 5390e33dfeSDaniel P. Berrangé */ 54b4682a63SDaniel P. Berrangé typedef void (*QFileMonitorHandler)(int64_t id, 5590e33dfeSDaniel P. Berrangé QFileMonitorEvent event, 5690e33dfeSDaniel P. Berrangé const char *filename, 5790e33dfeSDaniel P. Berrangé void *opaque); 5890e33dfeSDaniel P. Berrangé 5990e33dfeSDaniel P. Berrangé /** 6090e33dfeSDaniel P. Berrangé * qemu_file_monitor_new: 6190e33dfeSDaniel P. Berrangé * @errp: pointer to a NULL-initialized error object 6290e33dfeSDaniel P. Berrangé * 6390e33dfeSDaniel P. Berrangé * Create a handle for a file monitoring object. 6490e33dfeSDaniel P. Berrangé * 6590e33dfeSDaniel P. Berrangé * This object does locking internally to enable it to be 6690e33dfeSDaniel P. Berrangé * safe to use from multiple threads 6790e33dfeSDaniel P. Berrangé * 6890e33dfeSDaniel P. Berrangé * If the platform does not support file monitoring, an 6990e33dfeSDaniel P. Berrangé * error will be reported. Likewise if file monitoring 7090e33dfeSDaniel P. Berrangé * is supported, but cannot be initialized 7190e33dfeSDaniel P. Berrangé * 7290e33dfeSDaniel P. Berrangé * Currently this is implemented on Linux platforms with 7390e33dfeSDaniel P. Berrangé * the inotify subsystem. 7490e33dfeSDaniel P. Berrangé * 7590e33dfeSDaniel P. Berrangé * Returns: the new monitoring object, or NULL on error 7690e33dfeSDaniel P. Berrangé */ 7790e33dfeSDaniel P. Berrangé QFileMonitor *qemu_file_monitor_new(Error **errp); 7890e33dfeSDaniel P. Berrangé 7990e33dfeSDaniel P. Berrangé /** 8090e33dfeSDaniel P. Berrangé * qemu_file_monitor_free: 8190e33dfeSDaniel P. Berrangé * @mon: the file monitor context 8290e33dfeSDaniel P. Berrangé * 8390e33dfeSDaniel P. Berrangé * Free resources associated with the file monitor, 8490e33dfeSDaniel P. Berrangé * including any currently registered watches. 8590e33dfeSDaniel P. Berrangé */ 8690e33dfeSDaniel P. Berrangé void qemu_file_monitor_free(QFileMonitor *mon); 8790e33dfeSDaniel P. Berrangé 8890e33dfeSDaniel P. Berrangé /** 8990e33dfeSDaniel P. Berrangé * qemu_file_monitor_add_watch: 9090e33dfeSDaniel P. Berrangé * @mon: the file monitor context 9190e33dfeSDaniel P. Berrangé * @dirpath: the directory whose contents to watch 9290e33dfeSDaniel P. Berrangé * @filename: optional filename to filter on 9390e33dfeSDaniel P. Berrangé * @cb: the function to invoke when @dirpath has changes 9490e33dfeSDaniel P. Berrangé * @opaque: data to pass to @cb 9590e33dfeSDaniel P. Berrangé * @errp: pointer to a NULL-initialized error object 9690e33dfeSDaniel P. Berrangé * 9790e33dfeSDaniel P. Berrangé * Register to receive notifications of changes 9890e33dfeSDaniel P. Berrangé * in the directory @dirpath. All files in the 9990e33dfeSDaniel P. Berrangé * directory will be monitored. If the caller is 10090e33dfeSDaniel P. Berrangé * only interested in one specific file, @filename 10190e33dfeSDaniel P. Berrangé * can be used to filter events. 10290e33dfeSDaniel P. Berrangé * 10390e33dfeSDaniel P. Berrangé * Returns: a positive integer watch ID, or -1 on error 10490e33dfeSDaniel P. Berrangé */ 105b4682a63SDaniel P. Berrangé int64_t qemu_file_monitor_add_watch(QFileMonitor *mon, 10690e33dfeSDaniel P. Berrangé const char *dirpath, 10790e33dfeSDaniel P. Berrangé const char *filename, 10890e33dfeSDaniel P. Berrangé QFileMonitorHandler cb, 10990e33dfeSDaniel P. Berrangé void *opaque, 11090e33dfeSDaniel P. Berrangé Error **errp); 11190e33dfeSDaniel P. Berrangé 11290e33dfeSDaniel P. Berrangé /** 11390e33dfeSDaniel P. Berrangé * qemu_file_monitor_remove_watch: 11490e33dfeSDaniel P. Berrangé * @mon: the file monitor context 11590e33dfeSDaniel P. Berrangé * @dirpath: the directory whose contents to unwatch 11690e33dfeSDaniel P. Berrangé * @id: id of the watch to remove 11790e33dfeSDaniel P. Berrangé * 11890e33dfeSDaniel P. Berrangé * Removes the file monitoring watch @id, associated 11990e33dfeSDaniel P. Berrangé * with the directory @dirpath. This must never be 12090e33dfeSDaniel P. Berrangé * called from a QFileMonitorHandler callback, or a 12190e33dfeSDaniel P. Berrangé * deadlock will result. 12290e33dfeSDaniel P. Berrangé */ 12390e33dfeSDaniel P. Berrangé void qemu_file_monitor_remove_watch(QFileMonitor *mon, 12490e33dfeSDaniel P. Berrangé const char *dirpath, 125b4682a63SDaniel P. Berrangé int64_t id); 12690e33dfeSDaniel P. Berrangé 12758ea30f5SMarkus Armbruster #endif /* QEMU_FILEMONITOR_H */ 128