| /* |
| * Copyright (C) 2006 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.os; |
| |
| import android.annotation.IntDef; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.compat.annotation.UnsupportedAppUsage; |
| import android.util.Log; |
| |
| import java.io.File; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.ref.WeakReference; |
| import java.util.Arrays; |
| import java.util.HashMap; |
| import java.util.List; |
| |
| /** |
| * Monitors files (using <a href="http://en.wikipedia.org/wiki/Inotify">inotify</a>) |
| * to fire an event after files are accessed or changed by by any process on |
| * the device (including this one). FileObserver is an abstract class; |
| * subclasses must implement the event handler {@link #onEvent(int, String)}. |
| * |
| * <p>Each FileObserver instance can monitor multiple files or directories. |
| * If a directory is monitored, events will be triggered for all files and |
| * subdirectories inside the monitored directory.</p> |
| * |
| * <p>An event mask is used to specify which changes or actions to report. |
| * Event type constants are used to describe the possible changes in the |
| * event mask as well as what actually happened in event callbacks.</p> |
| * |
| * <p class="caution"><b>Warning</b>: If a FileObserver is garbage collected, it |
| * will stop sending events. To ensure you keep receiving events, you must |
| * keep a reference to the FileObserver instance from some other live object.</p> |
| */ |
| public abstract class FileObserver { |
| /** @hide */ |
| @IntDef(flag = true, value = { |
| ACCESS, |
| MODIFY, |
| ATTRIB, |
| CLOSE_WRITE, |
| CLOSE_NOWRITE, |
| OPEN, |
| MOVED_FROM, |
| MOVED_TO, |
| CREATE, |
| DELETE, |
| DELETE_SELF, |
| MOVE_SELF |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface NotifyEventType {} |
| |
| /** Event type: Data was read from a file */ |
| public static final int ACCESS = 0x00000001; |
| /** Event type: Data was written to a file */ |
| public static final int MODIFY = 0x00000002; |
| /** Event type: Metadata (permissions, owner, timestamp) was changed explicitly */ |
| public static final int ATTRIB = 0x00000004; |
| /** Event type: Someone had a file or directory open for writing, and closed it */ |
| public static final int CLOSE_WRITE = 0x00000008; |
| /** Event type: Someone had a file or directory open read-only, and closed it */ |
| public static final int CLOSE_NOWRITE = 0x00000010; |
| /** Event type: A file or directory was opened */ |
| public static final int OPEN = 0x00000020; |
| /** Event type: A file or subdirectory was moved from the monitored directory */ |
| public static final int MOVED_FROM = 0x00000040; |
| /** Event type: A file or subdirectory was moved to the monitored directory */ |
| public static final int MOVED_TO = 0x00000080; |
| /** Event type: A new file or subdirectory was created under the monitored directory */ |
| public static final int CREATE = 0x00000100; |
| /** Event type: A file was deleted from the monitored directory */ |
| public static final int DELETE = 0x00000200; |
| /** Event type: The monitored file or directory was deleted; monitoring effectively stops */ |
| public static final int DELETE_SELF = 0x00000400; |
| /** Event type: The monitored file or directory was moved; monitoring continues */ |
| public static final int MOVE_SELF = 0x00000800; |
| |
| /** Event mask: All valid event types, combined */ |
| @NotifyEventType |
| public static final int ALL_EVENTS = ACCESS | MODIFY | ATTRIB | CLOSE_WRITE |
| | CLOSE_NOWRITE | OPEN | MOVED_FROM | MOVED_TO | DELETE | CREATE |
| | DELETE_SELF | MOVE_SELF; |
| |
| private static final String LOG_TAG = "FileObserver"; |
| |
| private static class ObserverThread extends Thread { |
| private HashMap<Integer, WeakReference> m_observers = new HashMap<Integer, WeakReference>(); |
| private int m_fd; |
| |
| public ObserverThread() { |
| super("FileObserver"); |
| m_fd = init(); |
| } |
| |
| public void run() { |
| observe(m_fd); |
| } |
| |
| public int[] startWatching(List<File> files, |
| @NotifyEventType int mask, FileObserver observer) { |
| final int count = files.size(); |
| final String[] paths = new String[count]; |
| for (int i = 0; i < count; ++i) { |
| paths[i] = files.get(i).getAbsolutePath(); |
| } |
| final int[] wfds = new int[count]; |
| Arrays.fill(wfds, -1); |
| |
| startWatching(m_fd, paths, mask, wfds); |
| |
| final WeakReference<FileObserver> fileObserverWeakReference = |
| new WeakReference<>(observer); |
| synchronized (m_observers) { |
| for (int wfd : wfds) { |
| if (wfd >= 0) { |
| m_observers.put(wfd, fileObserverWeakReference); |
| } |
| } |
| } |
| |
| return wfds; |
| } |
| |
| public void stopWatching(int[] descriptors) { |
| stopWatching(m_fd, descriptors); |
| } |
| |
| @UnsupportedAppUsage |
| public void onEvent(int wfd, @NotifyEventType int mask, String path) { |
| // look up our observer, fixing up the map if necessary... |
| FileObserver observer = null; |
| |
| synchronized (m_observers) { |
| WeakReference weak = m_observers.get(wfd); |
| if (weak != null) { // can happen with lots of events from a dead wfd |
| observer = (FileObserver) weak.get(); |
| if (observer == null) { |
| m_observers.remove(wfd); |
| } |
| } |
| } |
| |
| // ...then call out to the observer without the sync lock held |
| if (observer != null) { |
| try { |
| observer.onEvent(mask, path); |
| } catch (Throwable throwable) { |
| Log.wtf(LOG_TAG, "Unhandled exception in FileObserver " + observer, throwable); |
| } |
| } |
| } |
| |
| private native int init(); |
| private native void observe(int fd); |
| private native void startWatching(int fd, String[] paths, |
| @NotifyEventType int mask, int[] wfds); |
| private native void stopWatching(int fd, int[] wfds); |
| } |
| |
| @UnsupportedAppUsage |
| private static ObserverThread s_observerThread; |
| |
| static { |
| s_observerThread = new ObserverThread(); |
| s_observerThread.start(); |
| } |
| |
| // instance |
| private final List<File> mFiles; |
| private int[] mDescriptors; |
| private final int mMask; |
| |
| /** |
| * Equivalent to FileObserver(path, FileObserver.ALL_EVENTS). |
| * |
| * @deprecated use {@link #FileObserver(File)} instead. |
| */ |
| @Deprecated |
| public FileObserver(String path) { |
| this(new File(path)); |
| } |
| |
| /** |
| * Equivalent to FileObserver(file, FileObserver.ALL_EVENTS). |
| */ |
| public FileObserver(@NonNull File file) { |
| this(Arrays.asList(file)); |
| } |
| |
| /** |
| * Equivalent to FileObserver(paths, FileObserver.ALL_EVENTS). |
| * |
| * @param files The files or directories to monitor |
| */ |
| public FileObserver(@NonNull List<File> files) { |
| this(files, ALL_EVENTS); |
| } |
| |
| /** |
| * Create a new file observer for a certain file or directory. |
| * Monitoring does not start on creation! You must call |
| * {@link #startWatching()} before you will receive events. |
| * |
| * @param path The file or directory to monitor |
| * @param mask The event or events (added together) to watch for |
| * |
| * @deprecated use {@link #FileObserver(File, int)} instead. |
| */ |
| @Deprecated |
| public FileObserver(String path, @NotifyEventType int mask) { |
| this(new File(path), mask); |
| } |
| |
| /** |
| * Create a new file observer for a certain file or directory. |
| * Monitoring does not start on creation! You must call |
| * {@link #startWatching()} before you will receive events. |
| * |
| * @param file The file or directory to monitor |
| * @param mask The event or events (added together) to watch for |
| */ |
| public FileObserver(@NonNull File file, @NotifyEventType int mask) { |
| this(Arrays.asList(file), mask); |
| } |
| |
| /** |
| * Version of {@link #FileObserver(File, int)} that allows callers to monitor |
| * multiple files or directories. |
| * |
| * @param files The files or directories to monitor |
| * @param mask The event or events (added together) to watch for |
| */ |
| public FileObserver(@NonNull List<File> files, @NotifyEventType int mask) { |
| mFiles = files; |
| mMask = mask; |
| } |
| |
| protected void finalize() { |
| stopWatching(); |
| } |
| |
| /** |
| * Start watching for events. The monitored file or directory must exist at |
| * this time, or else no events will be reported (even if it appears later). |
| * If monitoring is already started, this call has no effect. |
| */ |
| public void startWatching() { |
| if (mDescriptors == null) { |
| mDescriptors = s_observerThread.startWatching(mFiles, mMask, this); |
| } |
| } |
| |
| /** |
| * Stop watching for events. Some events may be in process, so events |
| * may continue to be reported even after this method completes. If |
| * monitoring is already stopped, this call has no effect. |
| */ |
| public void stopWatching() { |
| if (mDescriptors != null) { |
| s_observerThread.stopWatching(mDescriptors); |
| mDescriptors = null; |
| } |
| } |
| |
| /** |
| * The event handler, which must be implemented by subclasses. |
| * |
| * <p class="note">This method is invoked on a special FileObserver thread. |
| * It runs independently of any threads, so take care to use appropriate |
| * synchronization! Consider using {@link Handler#post(Runnable)} to shift |
| * event handling work to the main thread to avoid concurrency problems.</p> |
| * |
| * <p>Event handlers must not throw exceptions.</p> |
| * |
| * @param event The type of event which happened |
| * @param path The path, relative to the main monitored file or directory, |
| * of the file or directory which triggered the event. This value can |
| * be {@code null} for certain events, such as {@link #MOVE_SELF}. |
| */ |
| public abstract void onEvent(int event, @Nullable String path); |
| } |