include/wx/fswatcher.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/fswatcher.h
   3 // Purpose:     wxFileSystemWatcherBase
   4 // Author:      Bartosz Bekier
   5 // Created:     2009-05-23
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com>
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_FSWATCHER_BASE_H_
  12 #define _WX_FSWATCHER_BASE_H_
  13
  14 #include "wx/defs.h"
  15
  16 #if wxUSE_FSWATCHER
  17
  18 #include "wx/log.h"
  19 #include "wx/event.h"
  20 #include "wx/evtloop.h"
  21 #include "wx/filename.h"
  22 #include "wx/dir.h"
  23 #include "wx/hashmap.h"
  24
  25 #define wxTRACE_FSWATCHER "fswatcher"
  26
  27 // ----------------------------------------------------------------------------
  28 // wxFileSystemWatcherEventType & wxFileSystemWatcherEvent
  29 // ----------------------------------------------------------------------------
  30
  31 /**
  32  * Possible types of file system events.
  33  * This is a subset that will work fine an all platforms (actually, we will
  34  * see how it works on Mac).
  35  *
  36  * We got 2 types of error events:
  37  * - warning: these are not fatal and further events can still be generated
  38  * - error: indicates fatal error and causes that no more events will happen
  39  */
  40 enum
  41 {
  42     wxFSW_EVENT_CREATE = 0x01,
  43     wxFSW_EVENT_DELETE = 0x02,
  44     wxFSW_EVENT_RENAME = 0x04,
  45     wxFSW_EVENT_MODIFY = 0x08,
  46     wxFSW_EVENT_ACCESS = 0x10,
  47     wxFSW_EVENT_ATTRIB = 0x20, // Currently this is wxGTK-only
  48
  49     // error events
  50     wxFSW_EVENT_WARNING = 0x40,
  51     wxFSW_EVENT_ERROR = 0x80,
  52     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
  53                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
  54                          wxFSW_EVENT_ACCESS | wxFSW_EVENT_ATTRIB |
  55                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
  56 #ifdef wxHAS_INOTIFY
  57     ,wxFSW_EVENT_UNMOUNT = 0x2000
  58 #endif
  59 };
  60
  61 // Type of the path watched, used only internally for now.
  62 enum wxFSWPathType
  63 {
  64     wxFSWPath_None,     // Invalid value for an initialized watch.
  65     wxFSWPath_File,     // Plain file.
  66     wxFSWPath_Dir,      // Watch a directory and the files in it.
  67     wxFSWPath_Tree      // Watch a directory and all its children recursively.
  68 };
  69
  70
  71 /**
  72  * Event containing information about file system change.
  73  */
  74 class WXDLLIMPEXP_FWD_BASE wxFileSystemWatcherEvent;
  75 wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_BASE, wxEVT_FSWATCHER,
  76                          wxFileSystemWatcherEvent);
  77
  78 class WXDLLIMPEXP_BASE wxFileSystemWatcherEvent: public wxEvent
  79 {
  80 public:
  81     wxFileSystemWatcherEvent(int changeType = 0, int watchid = wxID_ANY) :
  82         wxEvent(watchid, wxEVT_FSWATCHER),
  83         m_changeType(changeType)
  84     {
  85     }
  86
  87     wxFileSystemWatcherEvent(int changeType, const wxString& errorMsg,
  88                              int watchid = wxID_ANY) :
  89         wxEvent(watchid, wxEVT_FSWATCHER),
  90         m_changeType(changeType), m_errorMsg(errorMsg)
  91     {
  92     }
  93
  94     wxFileSystemWatcherEvent(int changeType,
  95                              const wxFileName& path, const wxFileName& newPath,
  96                              int watchid = wxID_ANY) :
  97          wxEvent(watchid, wxEVT_FSWATCHER),
  98          m_changeType(changeType), m_path(path), m_newPath(newPath)
  99     {
 100     }
 101
 102     /**
 103      * Returns the path at which the event occurred.
 104      */
 105     const wxFileName& GetPath() const
 106     {
 107         return m_path;
 108     }
 109
 110     /**
 111      * Sets the path at which the event occurred
 112      */
 113     void SetPath(const wxFileName& path)
 114     {
 115         m_path = path;
 116     }
 117
 118     /**
 119      * In case of rename(move?) events, returns the new path related to the
 120      * event. The "new" means newer in the sense of time. In case of other
 121      * events it returns the same path as GetPath().
 122      */
 123     const wxFileName& GetNewPath() const
 124     {
 125         return m_newPath;
 126     }
 127
 128     /**
 129      * Sets the new path related to the event. See above.
 130      */
 131     void SetNewPath(const wxFileName& path)
 132     {
 133         m_newPath = path;
 134     }
 135
 136     /**
 137      * Returns the type of file system event that occurred.
 138      */
 139     int GetChangeType() const
 140     {
 141         return m_changeType;
 142     }
 143
 144     virtual wxEvent* Clone() const
 145     {
 146         wxFileSystemWatcherEvent* evt = new wxFileSystemWatcherEvent(*this);
 147         evt->m_errorMsg = m_errorMsg.Clone();
 148         evt->m_path = wxFileName(m_path.GetFullPath().Clone());
 149         evt->m_newPath = wxFileName(m_newPath.GetFullPath().Clone());
 150         return evt;
 151     }
 152
 153     virtual wxEventCategory GetEventCategory() const
 154     {
 155         // TODO this has to be merged with "similar" categories and changed
 156         return wxEVT_CATEGORY_UNKNOWN;
 157     }
 158
 159     /**
 160      * Returns if this error is an error event
 161      */
 162     bool IsError() const
 163     {
 164         return (m_changeType & (wxFSW_EVENT_ERROR | wxFSW_EVENT_WARNING)) != 0;
 165     }
 166
 167     wxString GetErrorDescription() const
 168     {
 169         return m_errorMsg;
 170     }
 171
 172     /**
 173      * Returns a wxString describing an event useful for debugging or testing
 174      */
 175     wxString ToString() const;
 176
 177 protected:
 178     int m_changeType;
 179     wxFileName m_path;
 180     wxFileName m_newPath;
 181     wxString m_errorMsg;
 182 private:
 183     DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxFileSystemWatcherEvent)
 184 };
 185
 186 typedef void (wxEvtHandler::*wxFileSystemWatcherEventFunction)
 187                                                 (wxFileSystemWatcherEvent&);
 188
 189 #define wxFileSystemWatcherEventHandler(func) \
 190     wxEVENT_HANDLER_CAST(wxFileSystemWatcherEventFunction, func)
 191
 192 #define EVT_FSWATCHER(winid, func) \
 193     wx__DECLARE_EVT1(wxEVT_FSWATCHER, winid, wxFileSystemWatcherEventHandler(func))
 194
 195 // ----------------------------------------------------------------------------
 196 // wxFileSystemWatcherBase: interface for wxFileSystemWatcher
 197 // ----------------------------------------------------------------------------
 198
 199 // Simple container to store information about one watched path.
 200 class wxFSWatchInfo
 201 {
 202 public:
 203     wxFSWatchInfo() :
 204         m_events(-1), m_type(wxFSWPath_None), m_refcount(-1)
 205     {
 206     }
 207
 208     wxFSWatchInfo(const wxString& path,
 209                   int events,
 210                   wxFSWPathType type,
 211                   const wxString& filespec = wxString()) :
 212         m_path(path), m_filespec(filespec), m_events(events), m_type(type),
 213         m_refcount(1)
 214     {
 215     }
 216
 217     const wxString& GetPath() const
 218     {
 219         return m_path;
 220     }
 221
 222     const wxString& GetFilespec() const { return m_filespec; }
 223
 224     int GetFlags() const
 225     {
 226         return m_events;
 227     }
 228
 229     wxFSWPathType GetType() const
 230     {
 231         return m_type;
 232     }
 233
 234     // Reference counting of watch entries is used to avoid watching the same
 235     // file system path multiple times (this can happen even accidentally, e.g.
 236     // when you have a recursive watch and then decide to watch some file or
 237     // directory under it separately).
 238     int IncRef()
 239     {
 240         return ++m_refcount;
 241     }
 242
 243     int DecRef()
 244     {
 245         wxASSERT_MSG( m_refcount > 0, wxS("Trying to decrement a zero count") );
 246         return --m_refcount;
 247     }
 248
 249 protected:
 250     wxString m_path;
 251     wxString m_filespec;      // For tree watches, holds any filespec to apply
 252     int m_events;
 253     wxFSWPathType m_type;
 254     int m_refcount;
 255 };
 256
 257 WX_DECLARE_STRING_HASH_MAP(wxFSWatchInfo, wxFSWatchInfoMap);
 258
 259 /**
 260  * Encapsulation of platform-specific file system event mechanism
 261  */
 262 class wxFSWatcherImpl;
 263
 264 /**
 265  * Main entry point for clients interested in file system events.
 266  * Defines interface that can be used to receive that kind of events.
 267  */
 268 class WXDLLIMPEXP_BASE wxFileSystemWatcherBase: public wxEvtHandler
 269 {
 270 public:
 271     wxFileSystemWatcherBase();
 272
 273     virtual ~wxFileSystemWatcherBase();
 274
 275     /**
 276      * Adds path to currently watched files. Any events concerning this
 277      * particular path will be sent to handler. Optionally a filter can be
 278      * specified to receive only events of particular type.
 279      *
 280      * Please note that when adding a dir, immediate children will be watched
 281      * as well.
 282      */
 283     virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
 284
 285     /**
 286      * Like above, but recursively adds every file/dir in the tree rooted in
 287      * path. Additionally a file mask can be specified to include only files
 288      * of particular type.
 289      */
 290     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
 291                          const wxString& filespec = wxEmptyString);
 292
 293     /**
 294      * Removes path from the list of watched paths.
 295      */
 296     virtual bool Remove(const wxFileName& path);
 297
 298     /**
 299      * Same as above, but also removes every file belonging to the tree rooted
 300      * at path.
 301      */
 302     virtual bool RemoveTree(const wxFileName& path);
 303
 304     /**
 305      * Clears the list of currently watched paths.
 306      */
 307     virtual bool RemoveAll();
 308
 309     /**
 310      * Returns the number of watched paths
 311      */
 312     int GetWatchedPathsCount() const;
 313
 314     /**
 315      * Retrevies all watched paths and places them in wxArrayString. Returns
 316      * the number of paths.
 317      *
 318      * TODO think about API here: we need to return more information (like is
 319      * the path watched recursively)
 320      */
 321     int GetWatchedPaths(wxArrayString* paths) const;
 322
 323     wxEvtHandler* GetOwner() const
 324     {
 325         return m_owner;
 326     }
 327
 328     void SetOwner(wxEvtHandler* handler)
 329     {
 330         if (!handler)
 331             m_owner = this;
 332         else
 333             m_owner = handler;
 334     }
 335
 336
 337     // This is a semi-private function used by wxWidgets itself only.
 338     //
 339     // Delegates the real work of adding the path to wxFSWatcherImpl::Add() and
 340     // updates m_watches if the new path was successfully added.
 341     bool AddAny(const wxFileName& path, int events, wxFSWPathType type,
 342                 const wxString& filespec = wxString());
 343
 344 protected:
 345
 346     static wxString GetCanonicalPath(const wxFileName& path)
 347     {
 348         wxFileName path_copy = wxFileName(path);
 349         if ( !path_copy.Normalize() )
 350         {
 351             wxFAIL_MSG(wxString::Format("Unable to normalize path '%s'",
 352                                          path.GetFullPath()));
 353             return wxEmptyString;
 354         }
 355
 356         return path_copy.GetFullPath();
 357     }
 358
 359
 360     wxFSWatchInfoMap m_watches;        // path=>wxFSWatchInfo map
 361     wxFSWatcherImpl* m_service;     // file system events service
 362     wxEvtHandler* m_owner;             // handler for file system events
 363
 364     friend class wxFSWatcherImpl;
 365 };
 366
 367 // include the platform specific file defining wxFileSystemWatcher
 368 // inheriting from wxFileSystemWatcherBase
 369
 370 #ifdef wxHAS_INOTIFY
 371     #include "wx/unix/fswatcher_inotify.h"
 372     #define wxFileSystemWatcher wxInotifyFileSystemWatcher
 373 #elif defined(wxHAS_KQUEUE)
 374     #include "wx/unix/fswatcher_kqueue.h"
 375     #define wxFileSystemWatcher wxKqueueFileSystemWatcher
 376 #elif defined(__WINDOWS__)
 377     #include "wx/msw/fswatcher.h"
 378     #define wxFileSystemWatcher wxMSWFileSystemWatcher
 379 #else
 380     #include "wx/generic/fswatcher.h"
 381     #define wxFileSystemWatcher wxPollingFileSystemWatcher
 382 #endif
 383
 384 #endif // wxUSE_FSWATCHER
 385
 386 #endif /* _WX_FSWATCHER_BASE_H_ */