FilePathWatcher::Watch() - Listen for sub directory changes.

base/files/file_path_watcher.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This module provides a way to monitor a file or directory for changes.
 
 #ifndef BASE_FILES_FILE_PATH_WATCHER_H_
 #define BASE_FILES_FILE_PATH_WATCHER_H_
 
 #include "base/base_export.h"
@@ skipping 41 matching lines @@
 
   // Used internally to encapsulate different members on different platforms.
   // TODO(jhawkins): Move this into its own file. Also fix the confusing naming
   // wrt Delegate vs PlatformDelegate.
   class PlatformDelegate : public base::RefCountedThreadSafe<PlatformDelegate> {
    public:
     PlatformDelegate();
 
     // Start watching for the given |path| and notify |delegate| about changes.
     virtual bool Watch(const FilePath& path,
+                       bool recursive,
                        Delegate* delegate) WARN_UNUSED_RESULT = 0;
 
     // Stop watching. This is called from FilePathWatcher's dtor in order to
     // allow to shut down properly while the object is still alive.
     // It can be called from any thread.
     virtual void Cancel() = 0;
 
    protected:
     friend class base::RefCountedThreadSafe<PlatformDelegate>;
     friend class FilePathWatcher;
@@ skipping 40 matching lines @@
   // OnFilePathChanged() will be called on the same thread as Watch() is called,
   // which should have a MessageLoop of TYPE_IO.
   //
   // Deprecated: new code should use the callback interface, declared below.
   // The FilePathWatcher::Delegate interface will be removed once all client
   // code has been updated. http://crbug.com/130980
   virtual bool Watch(const FilePath& path, Delegate* delegate)
       WARN_UNUSED_RESULT;
 
   // Invokes |callback| whenever updates to |path| are detected. This should be
-  // called at most once, and from a MessageLoop of TYPE_IO. The callback will
-  // be invoked on the same loop. Returns true on success.
-  bool Watch(const FilePath& path, const Callback& callback);
+  // called at most once, and from a MessageLoop of TYPE_IO. Set |recursive| to
+  // true, to watch |path| and its children. The callback will be invoked on
+  // the same loop. Returns true on success.
+  //
+  // NOTE: Recursive watch is not supported on all platforms. Watch() will

[Lei Zhang, 2012/12/03 21:44:39]

Does it work on network shared on Windows? This may not be just per-platform.

[kmadhusu, 2012/12/03 22:54:57]

On Windows, notifications may not be returned when calling
FindFirstChangeNotification for a remote file system. (Ref:
http://msdn.microsoft.com/en-us/library/windows/desktop/aa364417(v=vs.85).aspx).
This note is very specific for a recursive_watch functionality. On windows, we
support recursive_watch but if the Windows API fails it will return false. Do
you want me to add all these details here?

[Lei Zhang, 2012/12/03 23:16:20]

No, we should go into such details here, but I'm concerned this statement as
written makes readers think it's supported for all paths on a supported
platform.

[kmadhusu, 2012/12/04 00:06:36]

Rephrased the comment. Let me know your comments.

+  // return false on those platforms that don't support it.
+  bool Watch(const FilePath& path, bool recursive, const Callback& callback);
 
  private:
   scoped_refptr<PlatformDelegate> impl_;
 
   DISALLOW_COPY_AND_ASSIGN(FilePathWatcher);
 };
 
 }  // namespace files
 }  // namespace base
 
 #endif  // BASE_FILES_FILE_PATH_WATCHER_H_