| -rw-r--r-- | libopie2/opiecore/ofilenotify.h | 90 |
1 files changed, 87 insertions, 3 deletions
diff --git a/libopie2/opiecore/ofilenotify.h b/libopie2/opiecore/ofilenotify.h index 13b5a6b..bd2f9d0 100644 --- a/libopie2/opiecore/ofilenotify.h +++ b/libopie2/opiecore/ofilenotify.h @@ -23,83 +23,167 @@ _;:, .> :=|. This program is free software; you can -- :-=` this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef OFILENOTIFY_H #define OFILENOTIFY_H #if defined (__GNUC__) && (__GNUC__ < 3) #define _GNU_SOURCE #endif /* QT */ #include <qobject.h> #include <qsignal.h> #include <qstring.h> /* STD */ #include <signal.h> #include <fcntl.h> namespace Opie { namespace Core { +/*====================================================================================== + * OFileNotificationType + *======================================================================================*/ + +/** + * @brief An enumerate for the different types of file notifications + * + * This enumerate provides a means to specify the type of events that you are interest in. + * Valid values are: + * <ul> + * <li>Access: The file was accessed (read) + * <li>Modify The file was modified (write,truncate) + * <li>Create = The file was created in the directory + * <li>Delete = The file was unlinked from directory + * <li>Rename = The file was renamed + * <li>Attrib = The file had its attributes changed (chmod,chown,chgrp) + * </ul> + * + **/ + enum OFileNotificationType { Single = 0x0000000, Multi = DN_MULTISHOT, Access = DN_ACCESS, Modify = DN_MODIFY, Create = DN_CREATE, Delete = DN_DELETE, Rename = DN_RENAME, Attrib = DN_ATTRIB }; +/*====================================================================================== + * OFileNotification + *======================================================================================*/ + +/** + * @brief Represents a file notification + * + * This class allows to watch for events happening to files. + * It uses the dnotify kernel interface which is a very efficient signalling interface. + * + * @see <file:///usr/src/linux/Documentation/dnotify.txt> + * + * @author Michael 'Mickey' Lauer <mickey@vanille.de> + * + **/ + class OFileNotification : public QObject { Q_OBJECT public: OFileNotification( QObject* parent = 0, const char* name = 0 ); ~OFileNotification(); - + /** + * This static function calls a slot when an event with @a type happens to file @a path. + * + * It is very convenient to use this function because you do not need to + * bother with a timerEvent or to create a local QTimer object. + * + * Example: + * <pre> + * + * #include <opie2/oapplication.h> + * #include <opie2/onitify.h> + * using namespace Opie::Core; + * + * int main( int argc, char **argv ) + * { + * OApplication a( argc, argv, "File Notification Example" ); + * OFileNotification::singleShot( "/tmp/quit", &a, SLOT(quit()), Create ); + * ... // create and show your widgets + * return a.exec(); + * } + * + * This sample program automatically terminates when the file "/tmp/quite" has been created. + * + * + * The @a receiver is the receiving object and the @a member is the slot. + **/ static void singleShot( const QString& path, QObject* receiver, const char* member, OFileNotificationType type = Modify ); - + /** + * Starts to watch for @a type changes to @a path. Set @a sshot to True if you want to be notified only once. + * Note that in that case it may be more convenient to use @ref OFileNotification::singleShot() then. + **/ int start( const QString& path, bool sshot = false, OFileNotificationType type = Modify ); + /** + * Stop watching for file events. + **/ void stop(); - + /** + * @returns the notification type as set by @ref start(). + **/ OFileNotificationType type() const; + /** + * @returns the path to the file being watched by this instance. + **/ QString path() const; + /** + * @returns the UNIX file descriptor for the file being watched. + **/ int fileno() const; + /** + * @returns if a file is currently being watched. + **/ bool isActive() const; signals: + /** + * This signal is emitted if an event happens of the specified type happens to the file being watched. + **/ void triggered(); protected: bool activate(); virtual bool hasChanged(); static bool registerSignalHandler(); static void unregisterSignalHandler(); static void __signalHandler( int sig, siginfo_t *si, void *data ); private: QString _path; OFileNotificationType _type; QSignal _signal; int _fd; bool _active; struct stat _stat; }; +#if 0 class ODirectoryNotification : public OFileNotification { + public: virtual bool hasChanged() { return true; }; }; +#endif } } #endif |