1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/fswatcher.h
3 // Purpose: wxFileSystemWatcherBase
4 // Author: Bartosz Bekier
7 // Copyright: (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com>
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
11 #ifndef _WX_FSWATCHER_BASE_H_
12 #define _WX_FSWATCHER_BASE_H_
20 #include "wx/evtloop.h"
21 #include "wx/filename.h"
23 #include "wx/hashmap.h"
25 #define wxTRACE_FSWATCHER "fswatcher"
27 // ----------------------------------------------------------------------------
28 // wxFileSystemWatcherEventType & wxFileSystemWatcherEvent
29 // ----------------------------------------------------------------------------
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).
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
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
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
58 // Type of the path watched, used only internally for now.
61 wxFSWPath_None
, // Invalid value for an initialized watch.
62 wxFSWPath_File
, // Plain file.
63 wxFSWPath_Dir
, // Watch a directory and the files in it.
64 wxFSWPath_Tree
// Watch a directory and all its children recursively.
69 * Event containing information about file system change.
71 class WXDLLIMPEXP_FWD_BASE wxFileSystemWatcherEvent
;
72 wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_BASE
, wxEVT_FSWATCHER
,
73 wxFileSystemWatcherEvent
);
75 class WXDLLIMPEXP_BASE wxFileSystemWatcherEvent
: public wxEvent
78 wxFileSystemWatcherEvent(int changeType
, int watchid
= wxID_ANY
) :
79 wxEvent(watchid
, wxEVT_FSWATCHER
),
80 m_changeType(changeType
)
84 wxFileSystemWatcherEvent(int changeType
, const wxString
& errorMsg
,
85 int watchid
= wxID_ANY
) :
86 wxEvent(watchid
, wxEVT_FSWATCHER
),
87 m_changeType(changeType
), m_errorMsg(errorMsg
)
91 wxFileSystemWatcherEvent(int changeType
,
92 const wxFileName
& path
, const wxFileName
& newPath
,
93 int watchid
= wxID_ANY
) :
94 wxEvent(watchid
, wxEVT_FSWATCHER
),
95 m_changeType(changeType
), m_path(path
), m_newPath(newPath
)
100 * Returns the path at which the event occurred.
102 const wxFileName
& GetPath() const
108 * Sets the path at which the event occurred
110 void SetPath(const wxFileName
& path
)
116 * In case of rename(move?) events, returns the new path related to the
117 * event. The "new" means newer in the sense of time. In case of other
118 * events it returns the same path as GetPath().
120 const wxFileName
& GetNewPath() const
126 * Sets the new path related to the event. See above.
128 void SetNewPath(const wxFileName
& path
)
134 * Returns the type of file system event that occurred.
136 int GetChangeType() const
141 virtual wxEvent
* Clone() const
143 wxFileSystemWatcherEvent
* evt
= new wxFileSystemWatcherEvent(*this);
144 evt
->m_errorMsg
= m_errorMsg
.Clone();
145 evt
->m_path
= wxFileName(m_path
.GetFullPath().Clone());
146 evt
->m_newPath
= wxFileName(m_newPath
.GetFullPath().Clone());
150 virtual wxEventCategory
GetEventCategory() const
152 // TODO this has to be merged with "similiar" categories and changed
153 return wxEVT_CATEGORY_UNKNOWN
;
157 * Returns if this error is an error event
161 return (m_changeType
& (wxFSW_EVENT_ERROR
| wxFSW_EVENT_WARNING
)) != 0;
164 wxString
GetErrorDescription() const
170 * Returns a wxString describing an event useful for debugging or testing
172 wxString
ToString() const;
177 wxFileName m_newPath
;
181 typedef void (wxEvtHandler::*wxFileSystemWatcherEventFunction
)
182 (wxFileSystemWatcherEvent
&);
184 #define wxFileSystemWatcherEventHandler(func) \
185 wxEVENT_HANDLER_CAST(wxFileSystemWatcherEventFunction, func)
187 #define EVT_FSWATCHER(winid, func) \
188 wx__DECLARE_EVT1(wxEVT_FSWATCHER, winid, wxFileSystemWatcherEventHandler(func))
190 // ----------------------------------------------------------------------------
191 // wxFileSystemWatcherBase: interface for wxFileSystemWatcher
192 // ----------------------------------------------------------------------------
194 // Simple container to store information about one watched path.
199 m_events(-1), m_type(wxFSWPath_None
), m_refcount(-1)
203 wxFSWatchInfo(const wxString
& path
,
206 const wxString
& filespec
= wxString()) :
207 m_path(path
), m_filespec(filespec
), m_events(events
), m_type(type
),
212 const wxString
& GetPath() const
217 const wxString
& GetFilespec() const { return m_filespec
; }
224 wxFSWPathType
GetType() const
229 // Reference counting of watch entries is used to avoid watching the same
230 // file system path multiple times (this can happen even accidentally, e.g.
231 // when you have a recursive watch and then decide to watch some file or
232 // directory under it separately).
240 wxASSERT_MSG( m_refcount
> 0, wxS("Trying to decrement a zero count") );
246 wxString m_filespec
; // For tree watches, holds any filespec to apply
248 wxFSWPathType m_type
;
252 WX_DECLARE_STRING_HASH_MAP(wxFSWatchInfo
, wxFSWatchInfoMap
);
255 * Encapsulation of platform-specific file system event mechanism
257 class wxFSWatcherImpl
;
260 * Main entry point for clients interested in file system events.
261 * Defines interface that can be used to receive that kind of events.
263 class WXDLLIMPEXP_BASE wxFileSystemWatcherBase
: public wxEvtHandler
266 wxFileSystemWatcherBase();
268 virtual ~wxFileSystemWatcherBase();
271 * Adds path to currently watched files. Any events concerning this
272 * particular path will be sent to handler. Optionally a filter can be
273 * specified to receive only events of particular type.
275 * Please note that when adding a dir, immediate children will be watched
278 virtual bool Add(const wxFileName
& path
, int events
= wxFSW_EVENT_ALL
);
281 * Like above, but recursively adds every file/dir in the tree rooted in
282 * path. Additionally a file mask can be specified to include only files
283 * of particular type.
285 virtual bool AddTree(const wxFileName
& path
, int events
= wxFSW_EVENT_ALL
,
286 const wxString
& filespec
= wxEmptyString
);
289 * Removes path from the list of watched paths.
291 virtual bool Remove(const wxFileName
& path
);
294 * Same as above, but also removes every file belonging to the tree rooted
297 virtual bool RemoveTree(const wxFileName
& path
);
300 * Clears the list of currently watched paths.
302 virtual bool RemoveAll();
305 * Returns the number of watched paths
307 int GetWatchedPathsCount() const;
310 * Retrevies all watched paths and places them in wxArrayString. Returns
311 * the number of paths.
313 * TODO think about API here: we need to return more information (like is
314 * the path watched recursively)
316 int GetWatchedPaths(wxArrayString
* paths
) const;
318 wxEvtHandler
* GetOwner() const
323 void SetOwner(wxEvtHandler
* handler
)
332 // This is a semi-private function used by wxWidgets itself only.
334 // Delegates the real work of adding the path to wxFSWatcherImpl::Add() and
335 // updates m_watches if the new path was successfully added.
336 bool AddAny(const wxFileName
& path
, int events
, wxFSWPathType type
,
337 const wxString
& filespec
= wxString());
341 static wxString
GetCanonicalPath(const wxFileName
& path
)
343 wxFileName path_copy
= wxFileName(path
);
344 if ( !path_copy
.Normalize() )
346 wxFAIL_MSG(wxString::Format("Unable to normalize path '%s'",
347 path
.GetFullPath()));
348 return wxEmptyString
;
351 return path_copy
.GetFullPath();
355 wxFSWatchInfoMap m_watches
; // path=>wxFSWatchInfo map
356 wxFSWatcherImpl
* m_service
; // file system events service
357 wxEvtHandler
* m_owner
; // handler for file system events
359 friend class wxFSWatcherImpl
;
362 // include the platform specific file defining wxFileSystemWatcher
363 // inheriting from wxFileSystemWatcherBase
366 #include "wx/unix/fswatcher_inotify.h"
367 #define wxFileSystemWatcher wxInotifyFileSystemWatcher
368 #elif defined(wxHAS_KQUEUE)
369 #include "wx/unix/fswatcher_kqueue.h"
370 #define wxFileSystemWatcher wxKqueueFileSystemWatcher
371 #elif defined(__WINDOWS__)
372 #include "wx/msw/fswatcher.h"
373 #define wxFileSystemWatcher wxMSWFileSystemWatcher
375 #include "wx/generic/fswatcher.h"
376 #define wxFileSystemWatcher wxPollingFileSystemWatcher
379 #endif // wxUSE_FSWATCHER
381 #endif /* _WX_FSWATCHER_BASE_H_ */