am 65ff54c4: Merge change 1967 into donut

Merge commit '65ff54c44bbd8c1dd6818d42b7c91c634c644aa9'

* commit '65ff54c44bbd8c1dd6818d42b7c91c634c644aa9':
  Document the media scanner's flow through native and java code, since

1 files changed, 39 insertions, 1 deletions

diff --git a/media/java/android/media/MediaScanner.java b/media/java/android/media/MediaScanner.java
index c0cd5e3..c46f64e 100644
--- a/media/java/android/media/MediaScanner.java
+++ b/media/java/android/media/MediaScanner.java
@@ -53,7 +53,45 @@ import java.util.HashSet;
 import java.util.Iterator;
 
 /**
- * Internal service that no-one should use directly.
+ * Internal service helper that no-one should use directly.
+ * 
+ * The way the scan currently works is:
+ * - The Java MediaScannerService creates a MediaScanner (this class), and calls
+ *   MediaScanner.scanDirectories on it.
+ * - scanDirectories() calls the native processDirectory() for each of the specified directories.
+ * - the processDirectory() JNI method wraps the provided mediascanner client in a native
+ *   'MyMediaScannerClient' class, then calls processDirectory() on the native MediaScanner
+ *   object (which got created when the Java MediaScanner was created).
+ * - native MediaScanner.processDirectory() (currently part of opencore) calls
+ *   doProcessDirectory(), which recurses over the folder, and calls
+ *   native MyMediaScannerClient.scanFile() for every file whose extension matches.
+ * - native MyMediaScannerClient.scanFile() calls back on Java MediaScannerClient.scanFile,
+ *   which calls doScanFile, which after some setup calls back down to native code, calling
+ *   MediaScanner.processFile().
+ * - MediaScanner.processFile() calls one of several methods, depending on the type of the
+ *   file: parseMP3, parseMP4, parseMidi, parseOgg or parseWMA.
+ * - each of these methods gets metadata key/value pairs from the file, and repeatedly
+ *   calls native MyMediaScannerClient.handleStringTag, which calls back up to its Java
+ *   counterparts in this file.
+ * - Java handleStringTag() gathers the key/value pairs that it's interested in.
+ * - once processFile returns and we're back in Java code in doScanFile(), it calls
+ *   Java MyMediaScannerClient.endFile(), which takes all the data that's been
+ *   gathered and inserts an entry in to the database.
+ *
+ * In summary:
+ * Java MediaScannerService calls
+ * Java MediaScanner scanDirectories, which calls
+ * Java MediaScanner processDirectory (native method), which calls
+ * native MediaScanner processDirectory, which calls
+ * native MyMediaScannerClient scanFile, which calls
+ * Java MyMediaScannerClient scanFile, which calls
+ * Java MediaScannerClient doScanFile, which calls
+ * Java MediaScanner processFile (native method), which calls
+ * native MediaScanner processFile, which calls
+ * native parseMP3, parseMP4, parseMidi, parseOgg or parseWMA, which calls
+ * native MyMediaScanner handleStringTag, which calls
+ * Java MyMediaScanner handleStringTag.
+ * Once MediaScanner processFile returns, an entry is inserted in to the database.
  *
  * {@hide}
  */