--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/dependencies/disknotifyhandler.h Thu Mar 25 16:25:17 2010 +0100
@@ -0,0 +1,530 @@
+/*
+* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Wrapper for file server notification handling.
+*
+*/
+
+
+
+#ifndef C_DISK_NOTIFY_HANDLER_H
+#define C_DISK_NOTIFY_HANDLER_H
+
+// INCLUDES
+#include <e32std.h>
+#include <f32file.h>
+
+// FORWARD DECLARATIONS
+class MDiskNotifyHandlerCallback;
+class CDiskNotifyHandlerImpl;
+
+// CLASS DECLARATION
+/**
+* Disk Notification API provides an easy-to-use implementation of a wrapper
+* to handle file server notifications. It contains all required active objects
+* needed for handling the notifications. In the most cases, it automatically
+* resubscribes the notifications.
+* The API consists of classes CDiskNotifyHandler and MDiskNotifyHandlerCallback.
+* The user of CDiskNotifyHandler class needs to implement relevant
+* MDiskNotifyHandlerCallback interface methods to handle the notifications.
+*
+* Usage:
+*
+* Initialization example (from a class that implements MDiskNotifyHandlerCallback interface):
+* @code
+* // iFsSession contains open file server session
+* iNotifyHandler = CDiskNotifyHandler::NewL( *this, iFsSession );
+* User::LeaveIfError( iNotifyHandler->NotifyDisk() ); // Subscribe disk notifications
+* // Note that also the other notifications can be subcribed simultaneously using
+* // the same disk notify handler
+* @endcode
+*
+* Uninitialization example:
+* @code
+* delete iNotifyHandler; // Cancel all notifications set by this handler
+* @endcode
+*
+* Handler method implementation example:
+* @code
+* // Implement just the needed callback methods
+* void CMyDiskNotifyTest::HandleNotifyDisk( TInt aError, const TDiskEvent& aEvent )
+* {
+* // Print out the event data
+* RDebug::Print( _L("Error: %d, Disk %d changed, Change type: %d"),
+* aError, aEvent.iDrive, aEvent.iType );
+* }
+* @endcode
+*
+* @lib disknotifyhandler.lib
+* @since S60 5.0
+*/
+NONSHARABLE_CLASS(CDiskNotifyHandler) : public CBase
+ {
+
+public:
+
+ /**
+ * This is a two-phase constructor method that is used to
+ * create a new instance for listening to the disk changes.
+ *
+ * @since S60 5.0
+ * @param aCallback Reference to a callback instance, MDiskNotifyHandlerCallback
+ * @param aFs Reference to an open file server session, RFs
+ * Do not close this session until all CDiskNotifyHandler
+ * instances referring to it have been deleted.
+ * @return A pointer to a new instance of the CDiskNotifyHandler class.
+ *
+ * @see MDiskNotifyHandlerCallback
+ * @see RFs
+ */
+ IMPORT_C static CDiskNotifyHandler* NewL(
+ MDiskNotifyHandlerCallback& aCallback, RFs& aFs );
+
+ /**
+ * Destructor.
+ */
+ IMPORT_C ~CDiskNotifyHandler();
+
+ /**
+ * When this method is called, the CDiskNotifyHandler starts
+ * listening for disk notifications. If it is already listening disk notifications,
+ * KErrAlreadyExists is returned.
+ *
+ * This notification is automatically resubscibed until explicitly canceled or
+ * error has happened. The notifications and errors are informed using
+ * MDiskNotifyHandlerCallback's HandleNotifyDisk method.
+ *
+ * @since S60 5.0
+ * @return A system wide error code.
+ *
+ * @see MDiskNotifyHandlerCallback
+ */
+ IMPORT_C TInt NotifyDisk();
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels
+ * listening for disk notifications. If it is not listening disk notifications,
+ * nothing happens.
+ *
+ * @since S60 5.0
+ */
+ IMPORT_C void CancelNotifyDisk();
+
+ /**
+ * When this method is called, the CDiskNotifyHandler starts listening
+ * for dismount notification. If it is already listening dismount notification for
+ * given drive, KErrAlreadyExists is returned.
+ *
+ * This notification is not resubscibed because drive is not available anymore
+ * after dismount notification. The notification and error are informed using
+ * MDiskNotifyHandlerCallback's HandleNotifyDismount method.
+ *
+ * @since S60 5.0
+ * @param aDrive A drive identifier specified by TDriveNumber
+ * @return A system wide error code.
+ *
+ * @see TDriveNumber
+ * @see MDiskNotifyHandlerCallback
+ *
+ */
+ IMPORT_C TInt NotifyDismount( TInt aDrive );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels
+ * listening for dismount notification of given drive.
+ * If it is not listening the dismount of given drive, nothing happens.
+ *
+ * @since S60 5.0
+ * @param aDrive A drive identifier specified by TDriveNumber
+ *
+ * @see TDriveNumber
+ */
+ IMPORT_C void CancelNotifyDismount( TInt aDrive );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels
+ * listening for all dismount notifications that are set by this handler.
+ * If it is not listening any dismount notifications, nothing happens.
+ *
+ * @since S60 5.0
+ */
+ IMPORT_C void CancelNotifyDismount();
+
+ /**
+ * When this method is called, the CDiskNotifyHandler allows the dismount of given drive.
+ * If it is not listening the dismount of given drive, nothing happens.
+ *
+ * This method must be called only from MDiskNotifyHandlerCallback's HandleNotifyDismount
+ * to inform file server that dismount of the drive can be done.
+ *
+ * @since S60 5.0
+ * @param aDrive A drive identifier specified by TDriveNumber
+ * @return A system wide error code.
+ *
+ * @see TDriveNumber
+ */
+ IMPORT_C TInt AllowDismount( TInt aDrive );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler starts listening
+ * for disk space notifications. If it is already listening disk space for
+ * given drive with given threshold, KErrAlreadyExists is returned.
+ *
+ * This notification is automatically resubscibed until explicitly canceled or
+ * error has happened. The notification and error are informed using
+ * MDiskNotifyHandlerCallback's HandleNotifyDiskSpace method.
+ *
+ * @since S60 5.0
+ * @param aThreshold A threshold that causes notification when crossed.
+ * @param aDrive A drive identifier specified by TDriveNumber
+ * @return A system wide error code.
+ *
+ * @see TDriveNumber
+ * @see MDiskNotifyHandlerCallback
+ *
+ */
+ IMPORT_C TInt NotifyDiskSpace( const TInt64& aThreshold, TInt aDrive );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels listening
+ * for disk space notification of given drive with given threshold.
+ * If it is not listening the disk space of given drive with given threshold,
+ * nothing happens.
+ *
+ * @since S60 5.0
+ * @param aThreshold A threshold that causes notification when crossed.
+ * @param aDrive A drive identifier specified by TDriveNumber
+ *
+ * @see TDriveNumber
+ */
+ IMPORT_C void CancelNotifyDiskSpace( const TInt64& aThreshold, TInt aDrive );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels listening
+ * for all disk space notifications of given drive.
+ * If it is not listening the disk space of given drive, nothing happens.
+ *
+ * @since S60 5.0
+ * @param aDrive A drive identifier specified by TDriveNumber
+ *
+ * @see TDriveNumber
+ */
+ IMPORT_C void CancelNotifyDiskSpace( TInt aDrive );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels listening
+ * for all disk space notifications that are set by this handler.
+ * If it is not listening any disk space notifications, nothing happens.
+ *
+ * @since S60 5.0
+ */
+ IMPORT_C void CancelNotifyDiskSpace();
+
+ /**
+ * When this method is called, the CDiskNotifyHandler starts
+ * listening for entry (i.e. file or folder) change notifications.
+ * If it is already listening any type of change notification for
+ * given entry with given notification type, KErrAlreadyExists is returned.
+ *
+ * A given folder entry's full path must include backslash ending.
+ *
+ * This notification is automatically resubscibed until explicitly canceled or
+ * error has happened. The notification and error are informed using
+ * MDiskNotifyHandlerCallback's HandleNotifyEntry method.
+ *
+ * @since S60 5.0
+ * @param aType A type of notification specified by TNotifyType.
+ * @param aEntry A full path of the file or folder to be listened.
+ * @return A system wide error code.
+ *
+ * @see TNotifyType
+ * @see TDriveNumber
+ * @see MDiskNotifyHandlerCallback
+ */
+ IMPORT_C TInt NotifyEntry( TNotifyType aType, const TDesC& aEntry );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels listening
+ * for change notification of given entry with notify type.
+ * If it is not listening the given entry with notify type, nothing happens.
+ *
+ * @since S60 5.0
+ * @param aType A type of notification specified by TNotifyType.
+ * @param aEntry A full path of the file or folder entry to listen.
+ *
+ * @see TDriveNumber
+ */
+ IMPORT_C void CancelNotifyEntry( TNotifyType aType, const TDesC& aEntry );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels listening
+ * for all change notifications of given entry.
+ * If it is not listening the given entry, nothing happens.
+ *
+ * @since S60 5.0
+ * @param aEntry A full path of the file or folder to be listened.
+ *
+ * @see TDriveNumber
+ */
+ IMPORT_C void CancelNotifyEntry( const TDesC& aEntry );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels listening
+ * for entry notifications that are set by this handler.
+ * If it is not listening any entry notifications, nothing happens.
+ *
+ * @since S60 5.0
+ */
+ IMPORT_C void CancelNotifyEntry();
+
+ /**
+ * When this method is called, the CDiskNotifyHandler starts dismount
+ * with sending notification to registered clients. If dismount is
+ * pending after given timeout, forced dismount is done.
+ * If dismount of given drive was already started, KErrAlreadyExists
+ * is returned.
+ *
+ * This notification is not resubscibed because drive is not available anymore
+ * after dismount. The notification and error are informed using
+ * MDiskNotifyHandlerCallback's HandleNotifyDismountFinished method.
+ *
+ * @since S60 5.2
+ * @param aDrive A drive identifier specified by TDriveNumber
+ * @param aForcedTimeout A timeout to forced dismount in micro seconds.
+ * @return A system wide error code.
+ */
+ IMPORT_C TInt StartDismount( TInt aDrive, TTimeIntervalMicroSeconds32 aForcedTimeout );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels started
+ * dismount of given drive.
+ * If dismount of given drive was not started, nothing happens.
+ *
+ * @since S60 5.2
+ * @param aDrive A drive identifier specified by TDriveNumber
+ */
+ IMPORT_C void CancelStartedDismount( TInt aDrive );
+
+ /**
+ * When this method is called, the CDiskNotifyHandler cancels all
+ * started dismounts.
+ * If any dismount was not started, nothing happens.
+ *
+ * @since S60 5.2
+ */
+ IMPORT_C void CancelStartedDismount();
+
+private:
+
+ /**
+ * C++ default constructor.
+ */
+ CDiskNotifyHandler();
+
+ /**
+ * Symbian two-phased constructor.
+ */
+ void ConstructL( MDiskNotifyHandlerCallback& aCallback, RFs& aFs );
+
+
+private: // Data
+
+ // Owned. The actual implementation.
+ CDiskNotifyHandlerImpl* iImpl;
+
+ };
+
+
+/**
+* Class provides a callback interface for handling the notififications
+* from the file server. The Client derives a class from this interface
+* and implements the HandleNotify-methods that interest it.
+* An empty default implementation is provided for all of the methods.
+* In debug build the default implementations print out a debug trace.
+*
+* @lib disknotifyhandler.lib
+* @since S60 5.0
+*/
+class MDiskNotifyHandlerCallback
+ {
+
+public:
+
+ /**
+ * Defines the disk notification types.
+ */
+ enum TDiskEventType
+ {
+ /** To indicate disk notification error.
+ * It also indicates that there is no valid disk event data available.
+ */
+ EDiskError = 0,
+
+ /** To indicate that a new drive has been added to the drive list of file server.
+ */
+ EDiskAdded,
+
+ /** To indicate that a drive has been removed from the drive list of file server.
+ */
+ EDiskRemoved,
+
+ /** To indicate that drive status has been changed.
+ * E.g. A memory card has been inserted, removed or unlocked.
+ */
+ EDiskStatusChanged
+ };
+
+ /**
+ * Defines the data of disk notification event.
+ */
+ class TDiskEvent
+ {
+ public:
+ /** To indicates the disk event type
+ */
+ TDiskEventType iType;
+
+ /** To store the drive identifier for EDiskAdded,
+ * EDiskRemoved and EDiskStatusChanged events.
+ * The drive indentifier is specified bt TDriveNumber.
+ */
+ TInt iDrive;
+
+ /** To store the drive info for EDiskAdded and
+ * EDiskStatusChanged events.
+ */
+ TDriveInfo iInfo;
+
+ /** To store the previous drive info for EDiskRemoved and
+ * EDiskStatusChanged events.
+ */
+ TDriveInfo iPrevInfo;
+ };
+
+ /**
+ * This callback method is used to notify the client about
+ * disk notifications, i.e. memory card has been inserted
+ *
+ * @param aError System wide error code from file server
+ * @param aEvent The disk event data data specified by TDiskEvent
+ *
+ * TDiskEvent
+ */
+ IMPORT_C virtual void HandleNotifyDisk(
+ TInt aError,
+ const TDiskEvent& aEvent );
+
+ /**
+ * Defines the data of dismount notification event.
+ */
+ class TDismountEvent
+ {
+ public:
+ // Stores the drive identifier specified by TDriveNumber to be dismounted
+ TInt iDrive;
+ };
+
+ /**
+ * This callback method is used to notify the client about
+ * dismount notifications. Client have to call CDiskNotifyHandler's AllowDismount
+ * after it has finished preparing for dismount.
+ *
+ * @param aError System wide error code from file server
+ * @param aEvent The dismount event data specified by TDismountEvent
+ *
+ * @see TDismountEvent
+ */
+ IMPORT_C virtual void HandleNotifyDismount(
+ TInt aError,
+ const TDismountEvent& aEvent );
+
+ /**
+ * Defines the data of disk space notification event.
+ */
+ class TDiskSpaceEvent
+ {
+ public:
+ // Stores the drive identifier specified by TDriveNumber
+ TInt iDrive;
+ // Stores the crosses threshold
+ TInt64 iThreshold;
+ };
+
+ /**
+ * This callback method is used to notify the client about
+ * disk space notifications.
+ *
+ * @param aError System wide error code from file server
+ * @param aEvent The disk space event data specified by TDiskSpaceEvent
+ *
+ * @see TDiskSpaceEvent
+ */
+ IMPORT_C virtual void HandleNotifyDiskSpace(
+ TInt aError,
+ const TDiskSpaceEvent& aEvent );
+
+ /**
+ * Defines the data of entry notification event.
+ */
+ class TEntryEvent
+ {
+ public:
+ // Stores the notification type
+ TNotifyType iType;
+ // Stores full path of the file or folder entry
+ TFileName iEntry;
+ };
+
+ /**
+ * This callback method is used to notify the client about
+ * entry notifications.
+ *
+ * @param aError System wide error code from file server
+ * @param aEvent The entry event data specified by TEntryEvent
+ *
+ * @see TEntryEvent
+ */
+ IMPORT_C virtual void HandleNotifyEntry(
+ TInt aError,
+ const TEntryEvent& aEvent );
+
+ /**
+ * Defines the data of dismount finished notification event.
+ */
+ class TDismountFinishedEvent
+ {
+ public:
+ // Stores the dismounted drive identifier specified by TDriveNumber
+ TInt iDrive;
+ // Indicates if dismount was forced or not
+ TBool iForcedDismount;
+ };
+
+ /**
+ * This callback method is used to notify the client when
+ * started dismount has finished.
+ *
+ * @param aError System wide error code
+ * @param aEvent The event data specified by TDismountFinishedEvent
+ *
+ * @see TDismountFinishedEvent
+ */
+ IMPORT_C virtual void HandleNotifyDismountFinished(
+ TInt aError,
+ const TDismountFinishedEvent& aEvent );
+
+ };
+
+#endif // C_DISK_NOTIFY_HANDLER_H
+
+// End of File