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
  48     // error events
  49     wxFSW_EVENT_WARNING = 0x20,
  50     wxFSW_EVENT_ERROR = 0x40,
  51
  52     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
  53                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
  54                          wxFSW_EVENT_ACCESS |
  55                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
  56 };
  57
  58 /**
  59  * Event containing information about file system change.
  60  */
  61 class WXDLLIMPEXP_FWD_BASE wxFileSystemWatcherEvent;
  62 wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_BASE, wxEVT_FSWATCHER,
  63                          wxFileSystemWatcherEvent);
  64
  65 class WXDLLIMPEXP_BASE wxFileSystemWatcherEvent: public wxEvent
  66 {
  67 public:
  68     wxFileSystemWatcherEvent(int changeType, int watchid = wxID_ANY) :
  69         wxEvent(watchid, wxEVT_FSWATCHER),
  70         m_changeType(changeType)
  71     {
  72     }
  73
  74     wxFileSystemWatcherEvent(int changeType, const wxString& errorMsg,
  75                              int watchid = wxID_ANY) :
  76         wxEvent(watchid, wxEVT_FSWATCHER),
  77         m_changeType(changeType), m_errorMsg(errorMsg)
  78     {
  79     }
  80
  81     wxFileSystemWatcherEvent(int changeType,
  82                              const wxFileName& path, const wxFileName& newPath,
  83                              int watchid = wxID_ANY) :
  84          wxEvent(watchid, wxEVT_FSWATCHER),
  85          m_changeType(changeType), m_path(path), m_newPath(newPath)
  86     {
  87     }
  88
  89     /**
  90      * Returns the path at which the event occurred.
  91      */
  92     const wxFileName& GetPath() const
  93     {
  94         return m_path;
  95     }
  96
  97     /**
  98      * Sets the path at which the event occurred
  99      */
 100     void SetPath(const wxFileName& path)
 101     {
 102         m_path = path;
 103     }
 104
 105     /**
 106      * In case of rename(move?) events, returns the new path related to the
 107      * event. The "new" means newer in the sense of time. In case of other
 108      * events it returns the same path as GetPath().
 109      */
 110     const wxFileName& GetNewPath() const
 111     {
 112         return m_newPath;
 113     }
 114
 115     /**
 116      * Sets the new path related to the event. See above.
 117      */
 118     void SetNewPath(const wxFileName& path)
 119     {
 120         m_newPath = path;
 121     }
 122
 123     /**
 124      * Returns the type of file system event that occurred.
 125      */
 126     int GetChangeType() const
 127     {
 128         return m_changeType;
 129     }
 130
 131     virtual wxEvent* Clone() const
 132     {
 133         wxFileSystemWatcherEvent* evt = new wxFileSystemWatcherEvent(*this);
 134         evt->m_errorMsg = m_errorMsg.Clone();
 135         evt->m_path = wxFileName(m_path.GetFullPath().Clone());
 136         evt->m_newPath = wxFileName(m_newPath.GetFullPath().Clone());
 137         return evt;
 138     }
 139
 140     virtual wxEventCategory GetEventCategory() const
 141     {
 142         // TODO this has to be merged with "similiar" categories and changed
 143         return wxEVT_CATEGORY_UNKNOWN;
 144     }
 145
 146     /**
 147      * Returns if this error is an error event
 148      */
 149     bool IsError() const
 150     {
 151         return (m_changeType & (wxFSW_EVENT_ERROR | wxFSW_EVENT_WARNING)) != 0;
 152     }
 153
 154     wxString GetErrorDescription() const
 155     {
 156         return m_errorMsg;
 157     }
 158
 159     /**
 160      * Returns a wxString describing an event useful for debugging or testing
 161      */
 162     wxString ToString() const;
 163
 164 protected:
 165     int m_changeType;
 166     wxFileName m_path;
 167     wxFileName m_newPath;
 168     wxString m_errorMsg;
 169 };
 170
 171 typedef void (wxEvtHandler::*wxFileSystemWatcherEventFunction)
 172                                                 (wxFileSystemWatcherEvent&);
 173
 174 #define wxFileSystemWatcherEventHandler(func) \
 175     wxEVENT_HANDLER_CAST(wxFileSystemWatcherEventFunction, func)
 176
 177
 178 // ----------------------------------------------------------------------------
 179 // wxFileSystemWatcherBase: interface for wxFileSystemWatcher
 180 // ----------------------------------------------------------------------------
 181
 182 /**
 183  * Simple container to store information about one watched file
 184  */
 185 class wxFSWatchInfo
 186 {
 187 public:
 188     wxFSWatchInfo() :
 189         m_path(wxEmptyString), m_events(-1)
 190     {
 191     }
 192
 193     wxFSWatchInfo(const wxString& path, int events) :
 194         m_path(path), m_events(events)
 195     {
 196     }
 197
 198     const wxString& GetPath() const
 199     {
 200         return m_path;
 201     }
 202
 203     int GetFlags() const
 204     {
 205         return m_events;
 206     }
 207
 208 protected:
 209     wxString m_path;
 210     int m_events;
 211 };
 212
 213 WX_DECLARE_STRING_HASH_MAP(wxFSWatchInfo, wxFSWatchInfoMap);
 214
 215 /**
 216  * Encapsulation of platform-specific file system event mechanism
 217  */
 218 class wxFSWatcherImpl;
 219
 220 /**
 221  * Main entry point for clients interested in file system events.
 222  * Defines interface that can be used to receive that kind of events.
 223  */
 224 class WXDLLIMPEXP_BASE wxFileSystemWatcherBase: public wxEvtHandler
 225 {
 226 public:
 227     wxFileSystemWatcherBase();
 228
 229     virtual ~wxFileSystemWatcherBase();
 230
 231     /**
 232      * Adds path to currently watched files. Any events concerning this
 233      * particular path will be sent to handler. Optionally a filter can be
 234      * specified to receive only events of particular type.
 235      *
 236      * Please note that when adding a dir, immediate children will be watched
 237      * as well.
 238      */
 239     virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
 240
 241     /**
 242      * Like above, but recursively adds every file/dir in the tree rooted in
 243      * path. Additionally a file mask can be specified to include only files
 244      * of particular type.
 245      */
 246     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
 247                          const wxString& filter = wxEmptyString);
 248
 249     /**
 250      * Removes path from the list of watched paths.
 251      */
 252     virtual bool Remove(const wxFileName& path);
 253
 254     /**
 255      * Same as above, but also removes every file belonging to the tree rooted
 256      * at path.
 257      */
 258     virtual bool RemoveTree(const wxFileName& path);
 259
 260     /**
 261      * Clears the list of currently watched paths.
 262      */
 263     virtual bool RemoveAll();
 264
 265     /**
 266      * Returns the number of watched paths
 267      */
 268     int GetWatchedPathsCount() const;
 269
 270     /**
 271      * Retrevies all watched paths and places them in wxArrayString. Returns
 272      * the number of paths.
 273      *
 274      * TODO think about API here: we need to return more information (like is
 275      * the path watched recursively)
 276      */
 277     int GetWatchedPaths(wxArrayString* paths) const;
 278
 279     wxEvtHandler* GetOwner() const
 280     {
 281         return m_owner;
 282     }
 283
 284     void SetOwner(wxEvtHandler* handler)
 285     {
 286         if (!handler)
 287             m_owner = this;
 288         else
 289             m_owner = handler;
 290     }
 291
 292 protected:
 293
 294     static wxString GetCanonicalPath(const wxFileName& path)
 295     {
 296         wxFileName path_copy = wxFileName(path);
 297         if ( !path_copy.Normalize() )
 298         {
 299             wxFAIL_MSG(wxString::Format("Unable to normalize path '%s'",
 300                                          path.GetFullPath()));
 301             return wxEmptyString;
 302         }
 303
 304         return path_copy.GetFullPath();
 305     }
 306
 307     wxFSWatchInfoMap m_watches;        // path=>wxFSWatchInfo map
 308     wxFSWatcherImpl* m_service;     // file system events service
 309     wxEvtHandler* m_owner;             // handler for file system events
 310
 311     friend class wxFSWatcherImpl;
 312 };
 313
 314 // include the platform specific file defining wxFileSystemWatcher
 315 // inheriting from wxFileSystemWatcherBase
 316
 317 #ifdef wxHAS_INOTIFY
 318     #include "wx/unix/fswatcher_inotify.h"
 319     #define wxFileSystemWatcher wxInotifyFileSystemWatcher
 320 #elif defined(wxHAS_KQUEUE)
 321     #include "wx/unix/fswatcher_kqueue.h"
 322     #define wxFileSystemWatcher wxKqueueFileSystemWatcher
 323 #elif defined(__WXMSW__)
 324     #include "wx/msw/fswatcher.h"
 325     #define wxFileSystemWatcher wxMSWFileSystemWatcher
 326 #else
 327     #include "wx/generic/fswatcher.h"
 328     #define wxFileSystemWatcher wxPollingFileSystemWatcher
 329 #endif
 330
 331 #endif // wxUSE_FSWATCHER
 332
 333 #endif /* _WX_FSWATCHER_BASE_H_ */