userlibandfileserver/fileserver/inc/f32notification.h
changeset 11 329ab0095843
parent 9 96e5fb8b040d
child 43 c1f20ce4abcf
equal deleted inserted replaced
10:36bfc973b146 11:329ab0095843
   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.