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 | |
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 | |