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_FILEMONITOR_H 22 #define QEMU_FILEMONITOR_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_FILEMONITOR_H */ 129