base/files/file_path_watcher.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This module provides a way to monitor a file or directory for changes.
   6
   7 #ifndef BASE_FILES_FILE_PATH_WATCHER_H_
   8 #define BASE_FILES_FILE_PATH_WATCHER_H_
   9
  10 #include "base/base_export.h"
  11 #include "base/basictypes.h"
  12 #include "base/callback.h"
  13 #include "base/file_path.h"
  14 #include "base/memory/ref_counted.h"
  15 #include "base/message_loop_proxy.h"
  16
  17 namespace base {
  18 namespace files {
  19
  20 // This class lets you register interest in changes on a FilePath.
  21 // The delegate will get called whenever the file or directory referenced by the
  22 // FilePath is changed, including created or deleted. Due to limitations in the
  23 // underlying OS APIs, FilePathWatcher has slightly different semantics on OS X
  24 // than on Windows or Linux. FilePathWatcher on Linux and Windows will detect
  25 // modifications to files in a watched directory. FilePathWatcher on Mac will
  26 // detect the creation and deletion of files in a watched directory, but will
  27 // not detect modifications to those files. See file_path_watcher_kqueue.cc for
  28 // details.
  29 class BASE_EXPORT FilePathWatcher {
  30  public:
  31   // Callback type for Watch(). |path| points to the file that was updated,
  32   // and |error| is true if the platform specific code detected an error. In
  33   // that case, the callback won't be invoked again.
  34   typedef base::Callback<void(const FilePath& path, bool error)> Callback;
  35
  36   // Declares the callback client code implements to receive notifications. Note
  37   // that implementations of this interface should not keep a reference to the
  38   // corresponding FileWatcher object to prevent a reference cycle.
  39   //
  40   // Deprecated: see comment on Watch() below.
  41   class Delegate : public base::RefCountedThreadSafe<Delegate> {
  42    public:
  43     virtual void OnFilePathChanged(const FilePath& path) = 0;
  44     // Called when platform specific code detected an error. The watcher will
  45     // not call OnFilePathChanged for future changes.
  46     virtual void OnFilePathError(const FilePath& path) {}
  47
  48    protected:
  49     friend class base::RefCountedThreadSafe<Delegate>;
  50     virtual ~Delegate() {}
  51   };
  52
  53   // Used internally to encapsulate different members on different platforms.
  54   // TODO(jhawkins): Move this into its own file. Also fix the confusing naming
  55   // wrt Delegate vs PlatformDelegate.
  56   class PlatformDelegate : public base::RefCountedThreadSafe<PlatformDelegate> {
  57    public:
  58     PlatformDelegate();
  59
  60     // Start watching for the given |path| and notify |delegate| about changes.
  61     virtual bool Watch(const FilePath& path,
  62                        bool recursive,
  63                        Delegate* delegate) WARN_UNUSED_RESULT = 0;
  64
  65     // Stop watching. This is called from FilePathWatcher's dtor in order to
  66     // allow to shut down properly while the object is still alive.
  67     // It can be called from any thread.
  68     virtual void Cancel() = 0;
  69
  70    protected:
  71     friend class base::RefCountedThreadSafe<PlatformDelegate>;
  72     friend class FilePathWatcher;
  73
  74     virtual ~PlatformDelegate();
  75
  76     // Stop watching. This is only called on the thread of the appropriate
  77     // message loop. Since it can also be called more than once, it should
  78     // check |is_cancelled()| to avoid duplicate work.
  79     virtual void CancelOnMessageLoopThread() = 0;
  80
  81     scoped_refptr<base::MessageLoopProxy> message_loop() const {
  82       return message_loop_;
  83     }
  84
  85     void set_message_loop(base::MessageLoopProxy* loop) {
  86       message_loop_ = loop;
  87     }
  88
  89     // Must be called before the PlatformDelegate is deleted.
  90     void set_cancelled() {
  91       cancelled_ = true;
  92     }
  93
  94     bool is_cancelled() const {
  95       return cancelled_;
  96     }
  97
  98    private:
  99     scoped_refptr<base::MessageLoopProxy> message_loop_;
 100     bool cancelled_;
 101   };
 102
 103   FilePathWatcher();
 104   virtual ~FilePathWatcher();
 105
 106   // A callback that always cleans up the PlatformDelegate, either when executed
 107   // or when deleted without having been executed at all, as can happen during
 108   // shutdown.
 109   static void CancelWatch(const scoped_refptr<PlatformDelegate>& delegate);
 110
 111   // Register interest in any changes on |path|. OnPathChanged will be called
 112   // back for each change. Returns true on success.
 113   // OnFilePathChanged() will be called on the same thread as Watch() is called,
 114   // which should have a MessageLoop of TYPE_IO.
 115   //
 116   // Deprecated: new code should use the callback interface, declared below.
 117   // The FilePathWatcher::Delegate interface will be removed once all client
 118   // code has been updated. http://crbug.com/130980
 119   virtual bool Watch(const FilePath& path, Delegate* delegate)
 120       WARN_UNUSED_RESULT;
 121
 122   // Invokes |callback| whenever updates to |path| are detected. This should be
 123   // called at most once, and from a MessageLoop of TYPE_IO. Set |recursive| to
 124   // true, to watch |path| and its children. The callback will be invoked on
 125   // the same loop. Returns true on success.
 126   //
 127   // NOTE: Recursive watch is not supported on all platforms and file systems.
 128   // Watch() will return false in the case of failure.
 129   bool Watch(const FilePath& path, bool recursive, const Callback& callback);
 130
 131  private:
 132   scoped_refptr<PlatformDelegate> impl_;
 133
 134   DISALLOW_COPY_AND_ASSIGN(FilePathWatcher);
 135 };
 136
 137 }  // namespace files
 138 }  // namespace base
 139
 140 #endif  // BASE_FILES_FILE_PATH_WATCHER_H_