summaryrefslogtreecommitdiff
authormickeyl <mickeyl>2004-04-21 16:54:01 (UTC)
committer mickeyl <mickeyl>2004-04-21 16:54:01 (UTC)
commit8d6f6d769e945eac05c7089964d1e2c764f0ee7a (patch) (unidiff)
treec1b2ead6471f6f5d625b02e56c036e99186c655b
parent7dc2ed4e55acf69b0edf01ded81f00b61c472312 (diff)
downloadopie-8d6f6d769e945eac05c7089964d1e2c764f0ee7a.zip
opie-8d6f6d769e945eac05c7089964d1e2c764f0ee7a.tar.gz
opie-8d6f6d769e945eac05c7089964d1e2c764f0ee7a.tar.bz2
add API documentation for OFileNotification
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--libopie2/opiecore/ofilenotify.h90
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
@@ -44,6 +44,26 @@ _;:,     .>    :=|. This program is free software; you can
44namespace Opie { 44namespace Opie {
45namespace Core { 45namespace Core {
46 46
47/*======================================================================================
48 * OFileNotificationType
49 *======================================================================================*/
50
51/**
52 * @brief An enumerate for the different types of file notifications
53 *
54 * This enumerate provides a means to specify the type of events that you are interest in.
55 * Valid values are:
56 * <ul>
57 * <li>Access: The file was accessed (read)
58 * <li>Modify The file was modified (write,truncate)
59 * <li>Create = The file was created in the directory
60 * <li>Delete = The file was unlinked from directory
61 * <li>Rename = The file was renamed
62 * <li>Attrib = The file had its attributes changed (chmod,chown,chgrp)
63 * </ul>
64 *
65 **/
66
47enum OFileNotificationType { Single = 0x0000000, 67enum OFileNotificationType { Single = 0x0000000,
48 Multi = DN_MULTISHOT, 68 Multi = DN_MULTISHOT,
49 Access = DN_ACCESS, 69 Access = DN_ACCESS,
@@ -53,6 +73,22 @@ enum OFileNotificationType { Single = 0x0000000,
53 Rename = DN_RENAME, 73 Rename = DN_RENAME,
54 Attrib = DN_ATTRIB }; 74 Attrib = DN_ATTRIB };
55 75
76/*======================================================================================
77 * OFileNotification
78 *======================================================================================*/
79
80/**
81 * @brief Represents a file notification
82 *
83 * This class allows to watch for events happening to files.
84 * It uses the dnotify kernel interface which is a very efficient signalling interface.
85 *
86 * @see <file:///usr/src/linux/Documentation/dnotify.txt>
87 *
88 * @author Michael 'Mickey' Lauer <mickey@vanille.de>
89 *
90 **/
91
56class OFileNotification : public QObject 92class OFileNotification : public QObject
57{ 93{
58 Q_OBJECT 94 Q_OBJECT
@@ -60,18 +96,63 @@ class OFileNotification : public QObject
60 public: 96 public:
61 OFileNotification( QObject* parent = 0, const char* name = 0 ); 97 OFileNotification( QObject* parent = 0, const char* name = 0 );
62 ~OFileNotification(); 98 ~OFileNotification();
63 99 /**
100 * This static function calls a slot when an event with @a type happens to file @a path.
101 *
102 * It is very convenient to use this function because you do not need to
103 * bother with a timerEvent or to create a local QTimer object.
104 *
105 * Example:
106 * <pre>
107 *
108 * #include <opie2/oapplication.h>
109 * #include <opie2/onitify.h>
110 * using namespace Opie::Core;
111 *
112 * int main( int argc, char **argv )
113 * {
114 * OApplication a( argc, argv, "File Notification Example" );
115 * OFileNotification::singleShot( "/tmp/quit", &a, SLOT(quit()), Create );
116 * ... // create and show your widgets
117 * return a.exec();
118 * }
119 *
120 * This sample program automatically terminates when the file "/tmp/quite" has been created.
121 *
122 *
123 * The @a receiver is the receiving object and the @a member is the slot.
124 **/
64 static void singleShot( const QString& path, QObject* receiver, const char* member, OFileNotificationType type = Modify ); 125 static void singleShot( const QString& path, QObject* receiver, const char* member, OFileNotificationType type = Modify );
65 126 /**
127 * Starts to watch for @a type changes to @a path. Set @a sshot to True if you want to be notified only once.
128 * Note that in that case it may be more convenient to use @ref OFileNotification::singleShot() then.
129 **/
66 int start( const QString& path, bool sshot = false, OFileNotificationType type = Modify ); 130 int start( const QString& path, bool sshot = false, OFileNotificationType type = Modify );
131 /**
132 * Stop watching for file events.
133 **/
67 void stop(); 134 void stop();
68 135 /**
136 * @returns the notification type as set by @ref start().
137 **/
69 OFileNotificationType type() const; 138 OFileNotificationType type() const;
139 /**
140 * @returns the path to the file being watched by this instance.
141 **/
70 QString path() const; 142 QString path() const;
143 /**
144 * @returns the UNIX file descriptor for the file being watched.
145 **/
71 int fileno() const; 146 int fileno() const;
147 /**
148 * @returns if a file is currently being watched.
149 **/
72 bool isActive() const; 150 bool isActive() const;
73 151
74 signals: 152 signals:
153 /**
154 * This signal is emitted if an event happens of the specified type happens to the file being watched.
155 **/
75 void triggered(); 156 void triggered();
76 157
77 protected: 158 protected:
@@ -90,13 +171,16 @@ class OFileNotification : public QObject
90 struct stat _stat; 171 struct stat _stat;
91}; 172};
92 173
174#if 0
93 175
94class ODirectoryNotification : public OFileNotification 176class ODirectoryNotification : public OFileNotification
95{ 177{
178
96 public: 179 public:
97 virtual bool hasChanged() { return true; }; 180 virtual bool hasChanged() { return true; };
98}; 181};
99 182
183#endif
100 184
101} 185}
102} 186}