1 // Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description: 

    14 // fileserver/inc/f32notification.h

    15 //

    16 

    17 #ifndef __F32NOTIFICATION_H__

    18 #define __F32NOTIFICATION_H__

    19 

    20 /*

    21  * This class is not intended for instantiation neither on the stack

    22  * nor on the heap.

    23  * 

    24  * Clients wishing to use this class should use a pointer provided by 

    25  * CFsNotify::NextNotification().

    26  * 

    27  * @publishedAll

    28  * @released

    29  */

    30 class TFsNotification

    31 	{

    32 public:

    33 	enum TFsNotificationType

    34 		{

    35 		EFileChange		= 0x0001,	// File contents have changed or/and file has changed size

    36 		ERename 		= 0x0002,	// File/directory renamed, or file replaced using RFs::Replace()

    37 		ECreate 		= 0x0004,	// File/directory created, or file recreated using RFile::Replace()

    38 		EAttribute 		= 0x0008,	// File attribute(s) changed

    39 		EDelete 		= 0x0010, 	// File/directory deleted

    40 		EVolumeName		= 0x0020, 	// Volume name modified

    41 		EDriveName		= 0x0040, 	// Drive name modified

    42 		EMediaChange 	= 0x0080, 	// File system mounted/dismounted, media inserted/removed or device formatted

    43 		EOverflow		= 0x0100,	// Sent by the file server to notify when a buffer overflow occurs

    44 		EAllOps 		= KMaxTUint

    45 		};

    46 

    47 	/*

    48 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has

    49 	 * completed and before the next call to RequestNotifications. 

    50 	 * 

    51 	 * @returns the type of notification as TFsNotificationType.

    52 	 * @publishedAll

    53 	 * @released

    54 	 */

    55 	IMPORT_C TFsNotificationType NotificationType() const;

    56 	

    57 	/*

    58 	 * Returns via the aPath parameter

    59 	 * the path of the file or directory that this notification is notifying about.

    60 	 * 

    61 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has

    62 	 * completed and before the next call to RequestNotifications. 

    63 	 * 

    64 	 * @returns KErrNone upon success, otherwise one of the system wide errors

    65 	 * @param aPath - TPtrC& which is assigned to the path that was changed as notified by this notification.

    66 	 * @publishedAll

    67 	 * @released

    68 	 */

    69 	IMPORT_C TInt Path(TPtrC& aPath) const;

    70 	

    71 	/*

    72 	 * Certain notification types such as Rename, can provide 2 paths.

    73 	 * The first path will be the file that has changed, whilst the second path

    74 	 * with be the new name. (New filename in the case of rename).

    75 	 * 

    76 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has

    77 	 * completed and before the next call to RequestNotifications. 

    78 	 * 

    79 	 * @returns KErrNone upon success, else one of the system wide errors

    80 	 * @param aNewName - TPtrC& which is set to the newname as described.

    81 	 * @publishedAll

    82 	 * @released

    83 	 */

    84 	IMPORT_C TInt NewName(TPtrC& aNewName) const; 

    85 	

    86 	/*

    87 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has

    88 	 * completed and before the next call to RequestNotifications. 

    89 	 * 

    90 	 * @returns KErrNone upon success, else one of the system wide error codes

    91 	 * @param aSetAtt - In the case of the NotificationType being EAttributes, for the path that was changed

    92 	 * 					aSetAtt will return the attributes that were set.

    93 	 * @param aClearAtt - In the case of the NotificationType being EAttributes,

    94 	 * 					  returns the attributes that were cleared.

    95 	 * @publishedAll

    96 	 * @released

    97 	 */

    98 	IMPORT_C TInt Attributes(TUint& aSetAtt,TUint& aClearAtt) const;

    99 	

   100 	/*

   101 	 * In the case of the file size having changed, such as in calls to file write and set size,

   102 	 * aSize returns the new size of the file.

   103 	 * 

   104 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has

   105 	 * completed and before the next call to RequestNotifications. 

   106 	 * 

   107 	 * @returns KErrNone upon success, else one of the system wide error codes

   108 	 * @param aSize - The new size of the file being notified about.

   109 	 * @publishedAll

   110 	 * @released

   111 	 */

   112 	IMPORT_C TInt FileSize(TInt64& aSize) const; 

   113 

   114 	/*

   115 	 * @returns The Drive Number associated with the Path.

   116 	IMPORT_C TInt DriveNumber(TInt& aDriveNumber) const;

   117 	 */

   118 	

   119 	/*

   120 	 * @returns the UID of the process that caused this change.

   121 	IMPORT_C TInt UID(TUid& aUID) const;

   122 	 */

   123 private:

   124 	//Declared private to prevent construction

   125 	TFsNotification();

   126 	~TFsNotification();

   127 	//To prevent copying.  No implementation is provided.

   128 	TFsNotification& operator=(TFsNotification& aNotification);

   129 	

   130 	TInt PathSize() const;

   131 	TInt NewNameSize() const;

   132 	TInt NotificationSize() const;

   133 

   134 	friend class CFsNotify;

   135 	friend class CFsNotificationList;

   136 	};

   137 

   138 class RFsNotify; //incomplete decl

   139 class CFsNotifyBody; //incomplete decl

   140 

   141 /*

   142  * CFsNotify encapsulates the client-side sub-session associated with

   143  * the file server notification framework.

   144  * 

   145  * 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

   147  * request notifications.

   148  * 

   149  * Filters can be set for specific types of operations on specific (and wildcard) paths.

   150  * 

   151  * The difference between using this framework and RFs::NotifyChange is that

   152  * this framework will provide significant performance improvements, especially so

   153  * when operating on a large number of files.

   154  * 

   155  * In addition, this framework will provide verbose information about each

   156  * change that occurs, meaning that from a user's perspective they no longer have

   157  * to perform expensive directory scans in order to acertain what has changed.

   158  *

   159  * Notifications can also provide additional information:

   160  * EFileChange provides the new file size

   161  * ERename provide the new name of the affected file.

   162  * EDriveName/EVolumeName provides the name of the drive which has changed

   163  * EAttribute provides the attributes which were set and cleared on the affected file. 

   164  * 

   165  * @publishedAll

   166  * @released

   167  */

   168 class CFsNotify : public CBase

   169 	{

   170 	public:

   171 		

   172 		/*

   173 		 * Factory function. Creates a new CFsNotify and returns a pointer to it.

   174 		 *

   175 		 * 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 

   177 		 * set to KMinNotificationBufferSize.

   178 		 * 

   179 		 * @param aFs - RFs session. Must be connected.

   180 		 * @param aBufferSize  - Size of buffer in which to store notification objects.

   181 		 * @return CFsNotify* - Pointer to newly created CFsNotify.

   182 		 * @publishedAll

   183 		 * @released

   184 		 */

   185 		IMPORT_C static CFsNotify* NewL(RFs& aFs, TInt aBufferSize);

   186 		

   187 		/*

   188 		 * CFsNotify Destructor.

   189 		 * @publishedAll

   190 		 * @released

   191 		 */

   192 		IMPORT_C virtual ~CFsNotify();

   193 

   194 		/*

   195 		 * Clients are able to set-up notifications for changes based on Notification filters.

   196 		 * 

   197 		 * Filters can be set according to the type of notification required and the path to monitor.

   198 		 * Notification types are set up as a bitmask of TFsNotification::TNotificationType.

   199 		 * 		e.g.  (TUint) TFsNotification::ECreate | TFsNotification::EFileChange

   200 		 * 

   201 		 * So long as clients have filters set for a particular drive, they will automatically

   202 		 * receive TFsNotification::EMediaChange notifications regardless 

   203 		 * of whether they are registered for EMediaChange or not.

   204 		 * This notification can be caused by media card removal, the file system being dismounted or 

   205 		 * the media being formatted.

   206 		 *

   207 		 * If clients set the EOverflow notification type then AddNotification will return an error.

   208 		 * The exception to this is when using EAllOps which is used as a convenience notification type

   209 		 * which matches all of the notification types.

   210 		 * 

   211 		 * aPath specifies which path should be monitored for changes.

   212 		 * aFilename specifies which filename should be monitored for changes.

   213 		 * 

   214 		 * Either aPath or aFilename may be zero-length strings:

   215 		 * 	If you want to match a specific filename in every directory, you can leave aPath blank.

   216 		 *	Leaving aFilename blank results in matching against aPath only (i.e. a directory).

   217 		 * 

   218 		 * '*' and '?' wild cards are allowed in the path and filename.

   219 		 * 

   220 		 * To match against:

   221 		 * Specified directory only : (This is the specified directly only, not its contents.)

   222 		 * 		- aPath 	== drive:\\[path\\]directory\\

   223 		 * 		  aFilename == 					(zero length descriptor)

   224 		 *

   225 		 * Specified file only : 

   226 		 * 		- aPath		== drive:\\[path\\]directory\\

   227 		 * 		  aFilename == file.txt (or *, *.*, or *.txt)

   228 		 *

   229 		 * To enable matching against directories recursively:

   230 		 * 		- aPath		== drive:\\[path\\]directory\\*    (NB: trailing * denotes directory recursion)

   231 		 * 		- aFilename == file.txt (or *, *.*, or *.txt)

   232 		 *

   233 		 * 

   234 		 * @param aNotificationType - A Bitmask of the type of change to be monitored for based on the values of TFsNotification::TNotifyType

   235 		 * @param aPath - The directory to monitor

   236 		 * @param aFilename - The filename to monitor

   237 		 * @return KErrNone upon success, else one of the system wide error codes

   238 		 * @publishedAll

   239 		 * @released 

   240 		 */

   241 		IMPORT_C TInt AddNotification(TUint aNotificationType, const TDesC& aPath, const TDesC& aFilename);

   242 		

   243 		/*

   244 		 * Remove Notifications will remove all of the filters that have been 

   245 		 * set by calls to AddNotification.

   246 		 * 

   247 		 * This does not cancel any ongoing requests, but any on going requests will not complete until

   248 		 * filters have been added via calls to AddNotification

   249 		 * @return KErrNone or a system-wide error code.

   250 		 * @publishedAll

   251 		 * @released

   252 		 */

   253 		IMPORT_C TInt RemoveNotifications();

   254 		

   255 		/*

   256 		 * This is an Asynchronous function.

   257 		 * 

   258 		 * RequestNotification will issue a notification request asynchronously.

   259 		 * When this request has completed, aStatus's value will be set something other than KRequestPending.

   260 		 * 

   261 		 * Completion means that at least 1 notification has been put in the notification buffer.

   262 		 * Clients should call NextNotification() until it returns NULL.

   263 		 * 

   264 		 * When all the notifications have been read, the client should call RequestNotifications to set up another request.

   265 		 * 

   266 		 * Notifications will continue to be stored by the file server 

   267 		 * until CancelNotifications is called, meaning that notifications that occur 

   268 		 * whilst the client is processing the current notifications are not lost.

   269 		 * @param aStatus - A TRequestStatus that shall be completed when the Asynchronous request is completed.

   270 		 * @return KErrNone or a system-wide error code.

   271 		 * @publishedAll

   272 		 * @released

   273 		 */

   274 		IMPORT_C TInt RequestNotifications(TRequestStatus& aStatus);

   275 		

   276 		/*

   277 		 * Cancels the outstanding Asynchronous notification request that was set up

   278 		 * in the call to RequestNotifications.

   279 		 * @param aStatus - The TRequestStatus that was used in the call to RequestNotification

   280 		 * @return KErrNone or a system-wide error code.

   281 		 * @publishedAll

   282 		 * @released

   283 		 */

   284 		IMPORT_C TInt CancelNotifications(TRequestStatus& aStatus);

   285 		

   286 		/*

   287 		 * Once a notification request has completed, the client should call

   288 		 * NextNotification in order to access the notifications that have been stored in a notification buffer.

   289 		 * 

   290 		 * NextNotification returns a pointer to a TFsNotification. Each TFsNotification

   291 		 * represents a single notification.

   292 		 * 

   293 		 * When NULL is returned, there are no more Notifications to read and RequestNotification must be called.

   294 		 * 

   295 		 * @return const TFsNotification* - A pointer to a notification

   296 		 * @publishedAll

   297 		 * @released

   298 		 */

   299 		IMPORT_C const TFsNotification * NextNotification();

   300 		

   301 	private:

   302 		// Allocates buffer.

   303 		void ConstructL(RFs& aFs,TInt aBufferSize);

   304 		CFsNotify();

   305 

   306 		//Hide internals

   307 		CFsNotifyBody* iBody;

   308 		

   309 		friend class RFsNotify;

   310 		};

   311 

   312 #endif //__F32NOTIFICATION_H__

   313