/*
* 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.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);
}