137 |
137 |
138 class RFsNotify; //incomplete decl |
138 class RFsNotify; //incomplete decl |
139 class CFsNotifyBody; //incomplete decl |
139 class CFsNotifyBody; //incomplete decl |
140 |
140 |
141 /* |
141 /* |
|
142 * CFsNotify is a class which allows changes to file and directories to be monitored |
|
143 * |
|
144 * The notification framework supported by CFsNotify is able to keep track of multiple notifications, |
|
145 * whilst ensuring that notifications cannot be missed (unlike RFs::NotifyChange which can miss changes). |
|
146 * |
142 * CFsNotify encapsulates the client-side sub-session associated with |
147 * CFsNotify encapsulates the client-side sub-session associated with |
143 * the file server notification framework. |
148 * the file server notification framework. |
144 * |
149 * |
145 * In order to recieve notifications of changes to a file system, a |
150 * In order to recieve notifications of changes to a file system, a |
146 * client may use this class in order to set up notification 'filters' and |
151 * client may use this class in order to set up notification 'filters' and |
170 public: |
175 public: |
171 |
176 |
172 /* |
177 /* |
173 * Factory function. Creates a new CFsNotify and returns a pointer to it. |
178 * Factory function. Creates a new CFsNotify and returns a pointer to it. |
174 * |
179 * |
|
180 * CFsNotify stores notifications in a buffer. |
|
181 * Clients of CFsNotify must specify how large this buffer should be. |
|
182 * |
|
183 * As a guideline: Notification objects in the buffer typically have a 8byte header, |
|
184 * followed by a word aligned string containing the fullname of the file that has changed. |
|
185 * In the case of a rename notification both the original and the new fullnames are stored. |
|
186 * |
|
187 * However, clients must not assume to know the exact size of notifications when determining the size of their buffer, |
|
188 * as it is not possible to know how often a client will be able to read the notifications from the buffer. |
|
189 * In addition, if further notification types are added, then the header size or maximum data could increase. |
|
190 * |
|
191 * Thus, clients must ensure that their notification handling code appropriately deals with an overflow notification, whereby the |
|
192 * buffer was not large enough to store all of the notifications. |
|
193 * |
175 * If aBufferSize is greater than (KMaxTInt/2) then it will return KErrArgument. |
194 * If aBufferSize is greater than (KMaxTInt/2) then it will return KErrArgument. |
176 * If it is less than KMinNotificationBufferSize (approximately 1KB) then aBufferSize will be |
195 * If aBufferSize is less than KMinNotificationBufferSize (which is an internal constant but is approximately equal to 1KB) then aBufferSize will be |
177 * set to KMinNotificationBufferSize. |
196 * set to KMinNotificationBufferSize. |
178 * |
197 * |
179 * @param aFs - RFs session. Must be connected. |
198 * @param aFs - RFs session. Must be connected. |
180 * @param aBufferSize - Size of buffer in which to store notification objects. |
199 * @param aBufferSize - Size of buffer in which to store notification objects. |
181 * @return CFsNotify* - Pointer to newly created CFsNotify. |
200 * @return CFsNotify* - Pointer to newly created CFsNotify. |