1 /*
2  * Copyright (C) 2006 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.os;
18 
19 import android.util.Log;
20 
21 import java.lang.ref.WeakReference;
22 import java.util.HashMap;
23 
24 /**
25  * Monitors files (using <a href="http://en.wikipedia.org/wiki/Inotify">inotify</a>)
26  * to fire an event after files are accessed or changed by by any process on
27  * the device (including this one).  FileObserver is an abstract class;
28  * subclasses must implement the event handler {@link #onEvent(int, String)}.
29  *
30  * <p>Each FileObserver instance monitors a single file or directory.
31  * If a directory is monitored, events will be triggered for all files and
32  * subdirectories inside the monitored directory.</p>
33  *
34  * <p>An event mask is used to specify which changes or actions to report.
35  * Event type constants are used to describe the possible changes in the
36  * event mask as well as what actually happened in event callbacks.</p>
37  *
38  * <p class="caution"><b>Warning</b>: If a FileObserver is garbage collected, it
39  * will stop sending events.  To ensure you keep receiving events, you must
40  * keep a reference to the FileObserver instance from some other live object.</p>
41  */
42 public abstract class FileObserver {
43     /** Event type: Data was read from a file */
44     public static final int ACCESS = 0x00000001;
45     /** Event type: Data was written to a file */
46     public static final int MODIFY = 0x00000002;
47     /** Event type: Metadata (permissions, owner, timestamp) was changed explicitly */
48     public static final int ATTRIB = 0x00000004;
49     /** Event type: Someone had a file or directory open for writing, and closed it */
50     public static final int CLOSE_WRITE = 0x00000008;
51     /** Event type: Someone had a file or directory open read-only, and closed it */
52     public static final int CLOSE_NOWRITE = 0x00000010;
53     /** Event type: A file or directory was opened */
54     public static final int OPEN = 0x00000020;
55     /** Event type: A file or subdirectory was moved from the monitored directory */
56     public static final int MOVED_FROM = 0x00000040;
57     /** Event type: A file or subdirectory was moved to the monitored directory */
58     public static final int MOVED_TO = 0x00000080;
59     /** Event type: A new file or subdirectory was created under the monitored directory */
60     public static final int CREATE = 0x00000100;
61     /** Event type: A file was deleted from the monitored directory */
62     public static final int DELETE = 0x00000200;
63     /** Event type: The monitored file or directory was deleted; monitoring effectively stops */
64     public static final int DELETE_SELF = 0x00000400;
65     /** Event type: The monitored file or directory was moved; monitoring continues */
66     public static final int MOVE_SELF = 0x00000800;
67 
68     /** Event mask: All valid event types, combined */
69     public static final int ALL_EVENTS = ACCESS | MODIFY | ATTRIB | CLOSE_WRITE
70             | CLOSE_NOWRITE | OPEN | MOVED_FROM | MOVED_TO | DELETE | CREATE
71             | DELETE_SELF | MOVE_SELF;
72 
73     private static final String LOG_TAG = "FileObserver";
74 
75     private static class ObserverThread extends Thread {
76         private HashMap<Integer, WeakReference> m_observers = new HashMap<Integer, WeakReference>();
77         private int m_fd;
78 
ObserverThread()79         public ObserverThread() {
80             super("FileObserver");
81             m_fd = init();
82         }
83 
run()84         public void run() {
85             observe(m_fd);
86         }
87 
startWatching(String path, int mask, FileObserver observer)88         public int startWatching(String path, int mask, FileObserver observer) {
89             int wfd = startWatching(m_fd, path, mask);
90 
91             Integer i = new Integer(wfd);
92             if (wfd >= 0) {
93                 synchronized (m_observers) {
94                     m_observers.put(i, new WeakReference(observer));
95                 }
96             }
97 
98             return i;
99         }
100 
stopWatching(int descriptor)101         public void stopWatching(int descriptor) {
102             stopWatching(m_fd, descriptor);
103         }
104 
onEvent(int wfd, int mask, String path)105         public void onEvent(int wfd, int mask, String path) {
106             // look up our observer, fixing up the map if necessary...
107             FileObserver observer = null;
108 
109             synchronized (m_observers) {
110                 WeakReference weak = m_observers.get(wfd);
111                 if (weak != null) {  // can happen with lots of events from a dead wfd
112                     observer = (FileObserver) weak.get();
113                     if (observer == null) {
114                         m_observers.remove(wfd);
115                     }
116                 }
117             }
118 
119             // ...then call out to the observer without the sync lock held
120             if (observer != null) {
121                 try {
122                     observer.onEvent(mask, path);
123                 } catch (Throwable throwable) {
124                     Log.wtf(LOG_TAG, "Unhandled exception in FileObserver " + observer, throwable);
125                 }
126             }
127         }
128 
init()129         private native int init();
observe(int fd)130         private native void observe(int fd);
startWatching(int fd, String path, int mask)131         private native int startWatching(int fd, String path, int mask);
stopWatching(int fd, int wfd)132         private native void stopWatching(int fd, int wfd);
133     }
134 
135     private static ObserverThread s_observerThread;
136 
137     static {
138         s_observerThread = new ObserverThread();
s_observerThread.start()139         s_observerThread.start();
140     }
141 
142     // instance
143     private String m_path;
144     private Integer m_descriptor;
145     private int m_mask;
146 
147     /**
148      * Equivalent to FileObserver(path, FileObserver.ALL_EVENTS).
149      */
FileObserver(String path)150     public FileObserver(String path) {
151         this(path, ALL_EVENTS);
152     }
153 
154     /**
155      * Create a new file observer for a certain file or directory.
156      * Monitoring does not start on creation!  You must call
157      * {@link #startWatching()} before you will receive events.
158      *
159      * @param path The file or directory to monitor
160      * @param mask The event or events (added together) to watch for
161      */
FileObserver(String path, int mask)162     public FileObserver(String path, int mask) {
163         m_path = path;
164         m_mask = mask;
165         m_descriptor = -1;
166     }
167 
finalize()168     protected void finalize() {
169         stopWatching();
170     }
171 
172     /**
173      * Start watching for events.  The monitored file or directory must exist at
174      * this time, or else no events will be reported (even if it appears later).
175      * If monitoring is already started, this call has no effect.
176      */
startWatching()177     public void startWatching() {
178         if (m_descriptor < 0) {
179             m_descriptor = s_observerThread.startWatching(m_path, m_mask, this);
180         }
181     }
182 
183     /**
184      * Stop watching for events.  Some events may be in process, so events
185      * may continue to be reported even after this method completes.  If
186      * monitoring is already stopped, this call has no effect.
187      */
stopWatching()188     public void stopWatching() {
189         if (m_descriptor >= 0) {
190             s_observerThread.stopWatching(m_descriptor);
191             m_descriptor = -1;
192         }
193     }
194 
195     /**
196      * The event handler, which must be implemented by subclasses.
197      *
198      * <p class="note">This method is invoked on a special FileObserver thread.
199      * It runs independently of any threads, so take care to use appropriate
200      * synchronization!  Consider using {@link Handler#post(Runnable)} to shift
201      * event handling work to the main thread to avoid concurrency problems.</p>
202      *
203      * <p>Event handlers must not throw exceptions.</p>
204      *
205      * @param event The type of event which happened
206      * @param path The path, relative to the main monitored file or directory,
207      *     of the file or directory which triggered the event
208      */
onEvent(int event, String path)209     public abstract void onEvent(int event, String path);
210 }
211