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