sl@0: // Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description: 
sl@0: // fileserver/inc/f32notification.h
sl@0: //
sl@0: 
sl@0: #ifndef __F32NOTIFICATION_H__
sl@0: #define __F32NOTIFICATION_H__
sl@0: 
sl@0: /*
sl@0:  * This class is not intended for instantiation neither on the stack
sl@0:  * nor on the heap.
sl@0:  * 
sl@0:  * Clients wishing to use this class should use a pointer provided by 
sl@0:  * CFsNotify::NextNotification().
sl@0:  * 
sl@0:  * @publishedAll
sl@0:  * @released
sl@0:  */
sl@0: class TFsNotification
sl@0: 	{
sl@0: public:
sl@0: 	enum TFsNotificationType
sl@0: 		{
sl@0: 		EFileChange		= 0x0001,	// File contents have changed or/and file has changed size
sl@0: 		ERename 		= 0x0002,	// File/directory renamed, or file replaced using RFs::Replace()
sl@0: 		ECreate 		= 0x0004,	// File/directory created, or file recreated using RFile::Replace()
sl@0: 		EAttribute 		= 0x0008,	// File attribute(s) changed
sl@0: 		EDelete 		= 0x0010, 	// File/directory deleted
sl@0: 		EVolumeName		= 0x0020, 	// Volume name modified
sl@0: 		EDriveName		= 0x0040, 	// Drive name modified
sl@0: 		EMediaChange 	= 0x0080, 	// File system mounted/dismounted, media inserted/removed or device formatted
sl@0: 		EOverflow		= 0x0100,	// Sent by the file server to notify when a buffer overflow occurs
sl@0: 		EAllOps 		= KMaxTUint
sl@0: 		};
sl@0: 
sl@0: 	/*
sl@0: 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has
sl@0: 	 * completed and before the next call to RequestNotifications. 
sl@0: 	 * 
sl@0: 	 * @returns the type of notification as TFsNotificationType.
sl@0: 	 * @publishedAll
sl@0: 	 * @released
sl@0: 	 */
sl@0: 	IMPORT_C TFsNotificationType NotificationType() const;
sl@0: 	
sl@0: 	/*
sl@0: 	 * Returns via the aPath parameter
sl@0: 	 * the path of the file or directory that this notification is notifying about.
sl@0: 	 * 
sl@0: 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has
sl@0: 	 * completed and before the next call to RequestNotifications. 
sl@0: 	 * 
sl@0: 	 * @returns KErrNone upon success, otherwise one of the system wide errors
sl@0: 	 * @param aPath - TPtrC& which is assigned to the path that was changed as notified by this notification.
sl@0: 	 * @publishedAll
sl@0: 	 * @released
sl@0: 	 */
sl@0: 	IMPORT_C TInt Path(TPtrC& aPath) const;
sl@0: 	
sl@0: 	/*
sl@0: 	 * Certain notification types such as Rename, can provide 2 paths.
sl@0: 	 * The first path will be the file that has changed, whilst the second path
sl@0: 	 * with be the new name. (New filename in the case of rename).
sl@0: 	 * 
sl@0: 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has
sl@0: 	 * completed and before the next call to RequestNotifications. 
sl@0: 	 * 
sl@0: 	 * @returns KErrNone upon success, else one of the system wide errors
sl@0: 	 * @param aNewName - TPtrC& which is set to the newname as described.
sl@0: 	 * @publishedAll
sl@0: 	 * @released
sl@0: 	 */
sl@0: 	IMPORT_C TInt NewName(TPtrC& aNewName) const; 
sl@0: 	
sl@0: 	/*
sl@0: 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has
sl@0: 	 * completed and before the next call to RequestNotifications. 
sl@0: 	 * 
sl@0: 	 * @returns KErrNone upon success, else one of the system wide error codes
sl@0: 	 * @param aSetAtt - In the case of the NotificationType being EAttributes, for the path that was changed
sl@0: 	 * 					aSetAtt will return the attributes that were set.
sl@0: 	 * @param aClearAtt - In the case of the NotificationType being EAttributes,
sl@0: 	 * 					  returns the attributes that were cleared.
sl@0: 	 * @publishedAll
sl@0: 	 * @released
sl@0: 	 */
sl@0: 	IMPORT_C TInt Attributes(TUint& aSetAtt,TUint& aClearAtt) const;
sl@0: 	
sl@0: 	/*
sl@0: 	 * In the case of the file size having changed, such as in calls to file write and set size,
sl@0: 	 * aSize returns the new size of the file.
sl@0: 	 * 
sl@0: 	 * Any data returned is only valid after the previous asynchronous call to RequestNotifications has
sl@0: 	 * completed and before the next call to RequestNotifications. 
sl@0: 	 * 
sl@0: 	 * @returns KErrNone upon success, else one of the system wide error codes
sl@0: 	 * @param aSize - The new size of the file being notified about.
sl@0: 	 * @publishedAll
sl@0: 	 * @released
sl@0: 	 */
sl@0: 	IMPORT_C TInt FileSize(TInt64& aSize) const; 
sl@0: 
sl@0: 	/*
sl@0: 	 * @returns The Drive Number associated with the Path.
sl@0: 	IMPORT_C TInt DriveNumber(TInt& aDriveNumber) const;
sl@0: 	 */
sl@0: 	
sl@0: 	/*
sl@0: 	 * @returns the UID of the process that caused this change.
sl@0: 	IMPORT_C TInt UID(TUid& aUID) const;
sl@0: 	 */
sl@0: private:
sl@0: 	//Declared private to prevent construction
sl@0: 	TFsNotification();
sl@0: 	~TFsNotification();
sl@0: 	//To prevent copying.  No implementation is provided.
sl@0: 	TFsNotification& operator=(TFsNotification& aNotification);
sl@0: 	
sl@0: 	TInt PathSize() const;
sl@0: 	TInt NewNameSize() const;
sl@0: 	TInt NotificationSize() const;
sl@0: 
sl@0: 	friend class CFsNotify;
sl@0: 	friend class CFsNotificationList;
sl@0: 	};
sl@0: 
sl@0: class RFsNotify; //incomplete decl
sl@0: class CFsNotifyBody; //incomplete decl
sl@0: 
sl@0: /*
sl@0:  * CFsNotify is a class which allows changes to file and directories to be monitored
sl@0:  *
sl@0:  * The notification framework supported by CFsNotify is able to keep track of multiple notifications,
sl@0:  * whilst ensuring that notifications cannot be missed (unlike RFs::NotifyChange which can miss changes).
sl@0:  *
sl@0:  * CFsNotify encapsulates the client-side sub-session associated with
sl@0:  * the file server notification framework.
sl@0:  * 
sl@0:  * In order to recieve notifications of changes to a file system, a 
sl@0:  * client may use this class in order to set up notification 'filters' and
sl@0:  * request notifications.
sl@0:  * 
sl@0:  * Filters can be set for specific types of operations on specific (and wildcard) paths.
sl@0:  * 
sl@0:  * The difference between using this framework and RFs::NotifyChange is that
sl@0:  * this framework will provide significant performance improvements, especially so
sl@0:  * when operating on a large number of files.
sl@0:  * 
sl@0:  * In addition, this framework will provide verbose information about each
sl@0:  * change that occurs, meaning that from a user's perspective they no longer have
sl@0:  * to perform expensive directory scans in order to acertain what has changed.
sl@0:  *
sl@0:  * Notifications can also provide additional information:
sl@0:  * EFileChange provides the new file size
sl@0:  * ERename provide the new name of the affected file.
sl@0:  * EDriveName/EVolumeName provides the name of the drive which has changed
sl@0:  * EAttribute provides the attributes which were set and cleared on the affected file. 
sl@0:  * 
sl@0:  * @publishedAll
sl@0:  * @released
sl@0:  */
sl@0: class CFsNotify : public CBase
sl@0: 	{
sl@0: 	public:
sl@0: 		
sl@0: 		/*
sl@0: 		 * Factory function. Creates a new CFsNotify and returns a pointer to it.
sl@0: 		 *
sl@0: 		 * CFsNotify stores notifications in a buffer. 
sl@0: 		 * Clients of CFsNotify must specify how large this buffer should be.
sl@0: 		 * 
sl@0: 		 * As a guideline: Notification objects in the buffer typically have a 8byte header,
sl@0: 		 * followed by a word aligned string containing the fullname of the file that has changed.
sl@0: 		 * In the case of a rename notification both the original and the new fullnames are stored.
sl@0: 		 *
sl@0: 		 * However, clients must not assume to know the exact size of notifications when determining the size of their buffer,
sl@0: 		 * as it is not possible to know how often a client will be able to read the notifications from the buffer.
sl@0: 		 * In addition, if further notification types are added, then the header size or maximum data could increase.
sl@0: 		 * 
sl@0: 		 * Thus, clients must ensure that their notification handling code appropriately deals with an overflow notification, whereby the
sl@0: 		 * buffer was not large enough to store all of the notifications.
sl@0: 		 *
sl@0: 		 * If aBufferSize is greater than (KMaxTInt/2) then it will return KErrArgument.
sl@0: 		 * If aBufferSize is less than KMinNotificationBufferSize (which is an internal constant but is approximately equal to 1KB) then aBufferSize will be 
sl@0: 		 * set to KMinNotificationBufferSize.
sl@0: 		 * 
sl@0: 		 * @param aFs - RFs session. Must be connected.
sl@0: 		 * @param aBufferSize  - Size of buffer in which to store notification objects.
sl@0: 		 * @return CFsNotify* - Pointer to newly created CFsNotify.
sl@0: 		 * @publishedAll
sl@0: 		 * @released
sl@0: 		 */
sl@0: 		IMPORT_C static CFsNotify* NewL(RFs& aFs, TInt aBufferSize);
sl@0: 		
sl@0: 		/*
sl@0: 		 * CFsNotify Destructor.
sl@0: 		 * @publishedAll
sl@0: 		 * @released
sl@0: 		 */
sl@0: 		IMPORT_C virtual ~CFsNotify();
sl@0: 
sl@0: 		/*
sl@0: 		 * Clients are able to set-up notifications for changes based on Notification filters.
sl@0: 		 * 
sl@0: 		 * Filters can be set according to the type of notification required and the path to monitor.
sl@0: 		 * Notification types are set up as a bitmask of TFsNotification::TNotificationType.
sl@0: 		 * 		e.g.  (TUint) TFsNotification::ECreate | TFsNotification::EFileChange
sl@0: 		 * 
sl@0: 		 * So long as clients have filters set for a particular drive, they will automatically
sl@0: 		 * receive TFsNotification::EMediaChange notifications regardless 
sl@0: 		 * of whether they are registered for EMediaChange or not.
sl@0: 		 * This notification can be caused by media card removal, the file system being dismounted or 
sl@0: 		 * the media being formatted.
sl@0: 		 *
sl@0: 		 * If clients set the EOverflow notification type then AddNotification will return an error.
sl@0: 		 * The exception to this is when using EAllOps which is used as a convenience notification type
sl@0: 		 * which matches all of the notification types.
sl@0: 		 * 
sl@0: 		 * aPath specifies which path should be monitored for changes.
sl@0: 		 * aFilename specifies which filename should be monitored for changes.
sl@0: 		 * 
sl@0: 		 * Either aPath or aFilename may be zero-length strings:
sl@0: 		 * 	If you want to match a specific filename in every directory, you can leave aPath blank.
sl@0: 		 *	Leaving aFilename blank results in matching against aPath only (i.e. a directory).
sl@0: 		 * 
sl@0: 		 * '*' and '?' wild cards are allowed in the path and filename.
sl@0: 		 * 
sl@0: 		 * To match against:
sl@0: 		 * Specified directory only : (This is the specified directly only, not its contents.)
sl@0: 		 * 		- aPath 	== drive:\\[path\\]directory\\
sl@0: 		 * 		  aFilename == 					(zero length descriptor)
sl@0: 		 *
sl@0: 		 * Specified file only : 
sl@0: 		 * 		- aPath		== drive:\\[path\\]directory\\
sl@0: 		 * 		  aFilename == file.txt (or *, *.*, or *.txt)
sl@0: 		 *
sl@0: 		 * To enable matching against directories recursively:
sl@0: 		 * 		- aPath		== drive:\\[path\\]directory\\*    (NB: trailing * denotes directory recursion)
sl@0: 		 * 		- aFilename == file.txt (or *, *.*, or *.txt)
sl@0: 		 *
sl@0: 		 * 
sl@0: 		 * @param aNotificationType - A Bitmask of the type of change to be monitored for based on the values of TFsNotification::TNotifyType
sl@0: 		 * @param aPath - The directory to monitor
sl@0: 		 * @param aFilename - The filename to monitor
sl@0: 		 * @return KErrNone upon success, else one of the system wide error codes
sl@0: 		 * @publishedAll
sl@0: 		 * @released 
sl@0: 		 */
sl@0: 		IMPORT_C TInt AddNotification(TUint aNotificationType, const TDesC& aPath, const TDesC& aFilename);
sl@0: 		
sl@0: 		/*
sl@0: 		 * Remove Notifications will remove all of the filters that have been 
sl@0: 		 * set by calls to AddNotification.
sl@0: 		 * 
sl@0: 		 * This does not cancel any ongoing requests, but any on going requests will not complete until
sl@0: 		 * filters have been added via calls to AddNotification
sl@0: 		 * @return KErrNone or a system-wide error code.
sl@0: 		 * @publishedAll
sl@0: 		 * @released
sl@0: 		 */
sl@0: 		IMPORT_C TInt RemoveNotifications();
sl@0: 		
sl@0: 		/*
sl@0: 		 * This is an Asynchronous function.
sl@0: 		 * 
sl@0: 		 * RequestNotification will issue a notification request asynchronously.
sl@0: 		 * When this request has completed, aStatus's value will be set something other than KRequestPending.
sl@0: 		 * 
sl@0: 		 * Completion means that at least 1 notification has been put in the notification buffer.
sl@0: 		 * Clients should call NextNotification() until it returns NULL.
sl@0: 		 * 
sl@0: 		 * When all the notifications have been read, the client should call RequestNotifications to set up another request.
sl@0: 		 * 
sl@0: 		 * Notifications will continue to be stored by the file server 
sl@0: 		 * until CancelNotifications is called, meaning that notifications that occur 
sl@0: 		 * whilst the client is processing the current notifications are not lost.
sl@0: 		 * @param aStatus - A TRequestStatus that shall be completed when the Asynchronous request is completed.
sl@0: 		 * @return KErrNone or a system-wide error code.
sl@0: 		 * @publishedAll
sl@0: 		 * @released
sl@0: 		 */
sl@0: 		IMPORT_C TInt RequestNotifications(TRequestStatus& aStatus);
sl@0: 		
sl@0: 		/*
sl@0: 		 * Cancels the outstanding Asynchronous notification request that was set up
sl@0: 		 * in the call to RequestNotifications.
sl@0: 		 * @param aStatus - The TRequestStatus that was used in the call to RequestNotification
sl@0: 		 * @return KErrNone or a system-wide error code.
sl@0: 		 * @publishedAll
sl@0: 		 * @released
sl@0: 		 */
sl@0: 		IMPORT_C TInt CancelNotifications(TRequestStatus& aStatus);
sl@0: 		
sl@0: 		/*
sl@0: 		 * Once a notification request has completed, the client should call
sl@0: 		 * NextNotification in order to access the notifications that have been stored in a notification buffer.
sl@0: 		 * 
sl@0: 		 * NextNotification returns a pointer to a TFsNotification. Each TFsNotification
sl@0: 		 * represents a single notification.
sl@0: 		 * 
sl@0: 		 * When NULL is returned, there are no more Notifications to read and RequestNotification must be called.
sl@0: 		 * 
sl@0: 		 * @return const TFsNotification* - A pointer to a notification
sl@0: 		 * @publishedAll
sl@0: 		 * @released
sl@0: 		 */
sl@0: 		IMPORT_C const TFsNotification * NextNotification();
sl@0: 		
sl@0: 	private:
sl@0: 		// Allocates buffer.
sl@0: 		void ConstructL(RFs& aFs,TInt aBufferSize);
sl@0: 		CFsNotify();
sl@0: 
sl@0: 		//Hide internals
sl@0: 		CFsNotifyBody* iBody;
sl@0: 		
sl@0: 		friend class RFsNotify;
sl@0: 		};
sl@0: 
sl@0: #endif //__F32NOTIFICATION_H__
sl@0: