1 /*

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Wrapper for file server notification handling.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef C_DISK_NOTIFY_HANDLER_H

    21 #define C_DISK_NOTIFY_HANDLER_H

    22 

    23 //  INCLUDES

    24 #include <e32std.h>

    25 #include <f32file.h>

    26 

    27 // FORWARD DECLARATIONS

    28 class MDiskNotifyHandlerCallback;

    29 class CDiskNotifyHandlerImpl;

    30 

    31 // CLASS DECLARATION

    32 /**

    33 * Disk Notification API provides an easy-to-use implementation of a wrapper 

    34 * to handle file server notifications. It contains all required active objects 

    35 * needed for handling the notifications. In the most cases, it automatically 

    36 * resubscribes the notifications. 

    37 * The API consists of classes CDiskNotifyHandler and MDiskNotifyHandlerCallback.

    38 * The user of CDiskNotifyHandler class needs to implement relevant 

    39 * MDiskNotifyHandlerCallback interface methods to handle the notifications.

    40 *

    41 * Usage:

    42 *  

    43 * Initialization example (from a class that implements MDiskNotifyHandlerCallback interface):

    44 * @code

    45 * // iFsSession contains open file server session

    46 * iNotifyHandler = CDiskNotifyHandler::NewL( *this, iFsSession );

    47 * User::LeaveIfError( iNotifyHandler->NotifyDisk() ); // Subscribe disk notifications

    48 * // Note that also the other notifications can be subcribed simultaneously using 

    49 * // the same disk notify handler

    50 * @endcode

    51 *

    52 * Uninitialization example:

    53 * @code

    54 * delete iNotifyHandler; // Cancel all notifications set by this handler

    55 * @endcode

    56 *

    57 * Handler method implementation example:

    58 * @code

    59 * // Implement just the needed callback methods

    60 * void CMyDiskNotifyTest::HandleNotifyDisk( TInt aError, const TDiskEvent& aEvent )

    61 *    {

    62 *    // Print out the event data

    63 *    RDebug::Print( _L("Error: %d, Disk %d changed, Change type: %d"),

    64 *       aError, aEvent.iDrive, aEvent.iType );

    65 *    }

    66 * @endcode

    67 *

    68 * @lib disknotifyhandler.lib

    69 * @since S60 5.0

    70 */

    71 NONSHARABLE_CLASS(CDiskNotifyHandler) : public CBase

    72     {

    73 

    74 public:

    75 

    76     /**

    77     * This is a two-phase constructor method that is used to

    78     * create a new instance for listening to the disk changes.

    79     *

    80     * @since S60 5.0

    81     * @param aCallback Reference to a callback instance, MDiskNotifyHandlerCallback

    82     * @param aFs       Reference to an open file server session, RFs

    83     *                  Do not close this session until all CDiskNotifyHandler

    84     *                  instances referring to it have been deleted.

    85     * @return          A pointer to a new instance of the CDiskNotifyHandler class.

    86     *

    87     * @see MDiskNotifyHandlerCallback

    88     * @see RFs

    89     */

    90     IMPORT_C static CDiskNotifyHandler* NewL(

    91         MDiskNotifyHandlerCallback& aCallback, RFs& aFs );

    92 

    93     /**

    94     * Destructor.

    95     */

    96     IMPORT_C ~CDiskNotifyHandler();

    97 

    98     /**

    99     * When this method is called, the CDiskNotifyHandler starts 

   100     * listening for disk notifications. If it is already listening disk notifications,

   101     * KErrAlreadyExists is returned.

   102     *

   103     * This notification is automatically resubscibed until explicitly canceled or 

   104     * error has happened. The notifications and errors are informed using 

   105     * MDiskNotifyHandlerCallback's HandleNotifyDisk method.

   106     *

   107     * @since S60 5.0

   108     * @return A system wide error code.

   109     *

   110     * @see MDiskNotifyHandlerCallback

   111     */

   112     IMPORT_C TInt NotifyDisk();

   113 

   114     /**

   115     * When this method is called, the CDiskNotifyHandler cancels 

   116     * listening for disk notifications. If it is not listening disk notifications,

   117     * nothing happens.

   118     *

   119     * @since S60 5.0

   120     */

   121     IMPORT_C void CancelNotifyDisk();

   122 

   123     /**

   124     * When this method is called, the CDiskNotifyHandler starts listening 

   125     * for dismount notification. If it is already listening dismount notification for 

   126     * given drive, KErrAlreadyExists is returned.

   127     *

   128     * This notification is not resubscibed because drive is not available anymore 

   129     * after dismount notification. The notification and error are informed using 

   130     * MDiskNotifyHandlerCallback's HandleNotifyDismount method.

   131     *

   132     * @since S60 5.0

   133     * @param aDrive A drive identifier specified by TDriveNumber

   134     * @return A system wide error code.

   135     *

   136     * @see TDriveNumber

   137     * @see MDiskNotifyHandlerCallback

   138     *

   139     */

   140     IMPORT_C TInt NotifyDismount( TInt aDrive );

   141 

   142     /**

   143     * When this method is called, the CDiskNotifyHandler cancels

   144     * listening for dismount notification of given drive.

   145     * If it is not listening the dismount of given drive, nothing happens.

   146     *

   147     * @since S60 5.0

   148     * @param aDrive A drive identifier specified by TDriveNumber

   149     *

   150     * @see TDriveNumber

   151     */

   152     IMPORT_C void CancelNotifyDismount( TInt aDrive );

   153 

   154     /**

   155     * When this method is called, the CDiskNotifyHandler cancels

   156     * listening for all dismount notifications that are set by this handler.

   157     * If it is not listening any dismount notifications, nothing happens.

   158     *

   159     * @since S60 5.0

   160     */

   161     IMPORT_C void CancelNotifyDismount();

   162 

   163     /**

   164     * When this method is called, the CDiskNotifyHandler allows the dismount of given drive.

   165     * If it is not listening the dismount of given drive, nothing happens.

   166     *

   167     * This method must be called only from MDiskNotifyHandlerCallback's HandleNotifyDismount 

   168     * to inform file server that dismount of the drive can be done.

   169     *

   170     * @since S60 5.0

   171     * @param aDrive A drive identifier specified by TDriveNumber

   172     * @return A system wide error code.

   173     *

   174     * @see TDriveNumber

   175     */

   176     IMPORT_C TInt AllowDismount( TInt aDrive );

   177 

   178     /**

   179     * When this method is called, the CDiskNotifyHandler starts listening

   180     * for disk space notifications. If it is already listening disk space for 

   181     * given drive with given threshold, KErrAlreadyExists is returned.

   182     *

   183     * This notification is automatically resubscibed until explicitly canceled or 

   184     * error has happened. The notification and error are informed using 

   185     * MDiskNotifyHandlerCallback's HandleNotifyDiskSpace method.

   186     *

   187     * @since S60 5.0

   188     * @param aThreshold A threshold that causes notification when crossed.

   189     * @param aDrive A drive identifier specified by TDriveNumber

   190     * @return A system wide error code.

   191     *

   192     * @see TDriveNumber

   193     * @see MDiskNotifyHandlerCallback

   194     *

   195     */

   196     IMPORT_C TInt NotifyDiskSpace( const TInt64& aThreshold, TInt aDrive );

   197 

   198     /**

   199     * When this method is called, the CDiskNotifyHandler cancels listening 

   200     * for disk space notification of given drive with given threshold.

   201     * If it is not listening the disk space of given drive with given threshold,

   202     * nothing happens.

   203     *

   204     * @since S60 5.0

   205     * @param aThreshold A threshold that causes notification when crossed.

   206     * @param aDrive A drive identifier specified by TDriveNumber

   207     *

   208     * @see TDriveNumber

   209     */

   210     IMPORT_C void CancelNotifyDiskSpace( const TInt64& aThreshold, TInt aDrive );

   211 

   212     /**

   213     * When this method is called, the CDiskNotifyHandler cancels listening 

   214     * for all disk space notifications of given drive. 

   215     * If it is not listening the disk space of given drive, nothing happens. 

   216     *

   217     * @since S60 5.0

   218     * @param aDrive A drive identifier specified by TDriveNumber

   219     *

   220     * @see TDriveNumber

   221     */

   222     IMPORT_C void CancelNotifyDiskSpace( TInt aDrive );

   223 

   224     /**

   225     * When this method is called, the CDiskNotifyHandler cancels listening 

   226     * for all disk space notifications that are set by this handler. 

   227     * If it is not listening any disk space notifications, nothing happens. 

   228     *

   229     * @since S60 5.0

   230     */

   231     IMPORT_C void CancelNotifyDiskSpace();

   232 

   233     /**

   234     * When this method is called, the CDiskNotifyHandler starts 

   235     * listening for entry (i.e. file or folder) change notifications. 

   236     * If it is already listening any type of change notification for 

   237     * given entry with given notification type, KErrAlreadyExists is returned. 

   238     *

   239     * A given folder entry's full path must include backslash ending. 

   240     *

   241     * This notification is automatically resubscibed until explicitly canceled or 

   242     * error has happened. The notification and error are informed using 

   243     * MDiskNotifyHandlerCallback's HandleNotifyEntry method. 

   244     *

   245     * @since S60 5.0

   246     * @param aType A type of notification specified by TNotifyType.

   247     * @param aEntry A full path of the file or folder to be listened.

   248     * @return A system wide error code.

   249     *

   250     * @see TNotifyType

   251     * @see TDriveNumber

   252     * @see MDiskNotifyHandlerCallback

   253     */

   254     IMPORT_C TInt NotifyEntry( TNotifyType aType, const TDesC& aEntry );

   255 

   256     /**

   257     * When this method is called, the CDiskNotifyHandler cancels listening 

   258     * for change notification of given entry with notify type. 

   259     * If it is not listening the given entry with notify type, nothing happens. 

   260     *

   261     * @since S60 5.0

   262     * @param aType A type of notification specified by TNotifyType.

   263     * @param aEntry A full path of the file or folder entry to listen.

   264     *

   265     * @see TDriveNumber

   266     */

   267     IMPORT_C void CancelNotifyEntry( TNotifyType aType, const TDesC& aEntry );

   268 

   269     /**

   270     * When this method is called, the CDiskNotifyHandler cancels listening 

   271     * for all change notifications of given entry. 

   272     * If it is not listening the given entry, nothing happens. 

   273     *

   274     * @since S60 5.0

   275     * @param aEntry A full path of the file or folder to be listened.

   276     *

   277     * @see TDriveNumber

   278     */

   279     IMPORT_C void CancelNotifyEntry( const TDesC& aEntry );

   280 

   281     /**

   282     * When this method is called, the CDiskNotifyHandler cancels listening 

   283     * for entry notifications that are set by this handler. 

   284     * If it is not listening any entry notifications, nothing happens. 

   285     *

   286     * @since S60 5.0

   287     */

   288     IMPORT_C void CancelNotifyEntry();

   289 

   290     /**

   291     * When this method is called, the CDiskNotifyHandler starts dismount 

   292     * with sending notification to registered clients. If dismount is 

   293     * pending after given timeout, forced dismount is done.

   294     * If dismount of given drive was already started, KErrAlreadyExists 

   295     * is returned.

   296     *

   297     * This notification is not resubscibed because drive is not available anymore 

   298     * after dismount. The notification and error are informed using 

   299     * MDiskNotifyHandlerCallback's HandleNotifyDismountFinished method.

   300     *

   301     * @since S60 5.2

   302     * @param aDrive A drive identifier specified by TDriveNumber

   303     * @param aForcedTimeout A timeout to forced dismount in micro seconds.

   304     * @return A system wide error code.

   305     */

   306     IMPORT_C TInt StartDismount( TInt aDrive, TTimeIntervalMicroSeconds32 aForcedTimeout );

   307 

   308     /**

   309     * When this method is called, the CDiskNotifyHandler cancels started 

   310     * dismount of given drive.

   311     * If dismount of given drive was not started, nothing happens.

   312     *

   313     * @since S60 5.2

   314     * @param aDrive A drive identifier specified by TDriveNumber

   315     */

   316     IMPORT_C void CancelStartedDismount( TInt aDrive );

   317 

   318     /**

   319     * When this method is called, the CDiskNotifyHandler cancels all  

   320     * started dismounts.

   321     * If any dismount was not started, nothing happens.

   322     *

   323     * @since S60 5.2

   324     */

   325     IMPORT_C void CancelStartedDismount();

   326 

   327 private:

   328 

   329     /**

   330     * C++ default constructor.

   331     */

   332     CDiskNotifyHandler();

   333 

   334 	/**

   335 	* Symbian two-phased constructor.

   336 	*/

   337     void ConstructL( MDiskNotifyHandlerCallback& aCallback, RFs& aFs );

   338 

   339 

   340 private: // Data

   341 

   342     // Owned. The actual implementation.

   343     CDiskNotifyHandlerImpl* iImpl;

   344 

   345     };

   346 

   347 

   348 /**

   349 * Class provides a callback interface for handling the notififications 

   350 * from the file server. The Client derives a class from this interface 

   351 * and implements the HandleNotify-methods that interest it. 

   352 * An empty default implementation is provided for all of the methods. 

   353 * In debug build the default implementations print out a debug trace. 

   354 *

   355 * @lib disknotifyhandler.lib

   356 * @since S60 5.0

   357 */

   358 class MDiskNotifyHandlerCallback

   359     {

   360 

   361 public:

   362 

   363     /**

   364      * Defines the disk notification types.

   365      */

   366     enum TDiskEventType

   367         {

   368         /** To indicate disk notification error.

   369         * It also indicates that there is no valid disk event data available.

   370         */

   371         EDiskError = 0,

   372 

   373         /** To indicate that a new drive has been added to the drive list of file server.

   374         */

   375         EDiskAdded,

   376 

   377         /** To indicate that a drive has been removed from the drive list of file server.

   378         */

   379         EDiskRemoved,

   380 

   381         /** To indicate that drive status has been changed.

   382         * E.g. A memory card has been inserted, removed or unlocked.

   383         */

   384         EDiskStatusChanged

   385         };

   386 

   387     /**

   388      * Defines the data of disk notification event.

   389      */

   390     class TDiskEvent

   391         {

   392         public:

   393             /** To indicates the disk event type

   394             */

   395             TDiskEventType iType;

   396 

   397             /** To store the drive identifier for EDiskAdded,

   398             * EDiskRemoved and EDiskStatusChanged events.

   399             * The drive indentifier is specified bt TDriveNumber.

   400             */

   401             TInt iDrive;

   402 

   403             /** To store the drive info for EDiskAdded and

   404             * EDiskStatusChanged events.

   405             */

   406             TDriveInfo iInfo;

   407 

   408             /** To store the previous drive info for EDiskRemoved and

   409             * EDiskStatusChanged events.

   410             */

   411             TDriveInfo iPrevInfo;

   412         };

   413 

   414     /** 

   415     * This callback method is used to notify the client about

   416     * disk notifications, i.e. memory card has been inserted

   417     *

   418     * @param aError System wide error code from file server

   419     * @param aEvent The disk event data data specified by TDiskEvent

   420     *

   421     * TDiskEvent

   422     */

   423     IMPORT_C virtual void HandleNotifyDisk(

   424         TInt aError,

   425         const TDiskEvent& aEvent );

   426 

   427     /**

   428      * Defines the data of dismount notification event.

   429      */

   430     class TDismountEvent

   431         {

   432         public:

   433             // Stores the drive identifier specified by TDriveNumber to be dismounted

   434             TInt iDrive;

   435         };

   436 

   437     /** 

   438     * This callback method is used to notify the client about

   439     * dismount notifications. Client have to call CDiskNotifyHandler's AllowDismount

   440     * after it has finished preparing for dismount.

   441     *

   442     * @param aError System wide error code from file server

   443     * @param aEvent The dismount event data specified by TDismountEvent

   444     *

   445     * @see TDismountEvent

   446     */

   447     IMPORT_C virtual void HandleNotifyDismount(

   448         TInt aError,

   449         const TDismountEvent& aEvent );

   450 

   451     /**

   452      * Defines the data of disk space notification event.

   453      */

   454     class TDiskSpaceEvent

   455         {

   456         public:

   457             // Stores the drive identifier specified by TDriveNumber

   458             TInt iDrive;

   459             // Stores the crosses threshold

   460             TInt64 iThreshold;

   461         };

   462 

   463     /** 

   464     * This callback method is used to notify the client about

   465     * disk space notifications.

   466     *

   467     * @param aError System wide error code from file server

   468     * @param aEvent The disk space event data specified by TDiskSpaceEvent

   469     *

   470     * @see TDiskSpaceEvent

   471     */

   472     IMPORT_C virtual void HandleNotifyDiskSpace(

   473         TInt aError,

   474         const TDiskSpaceEvent& aEvent );

   475 

   476     /**

   477      * Defines the data of entry notification event.

   478      */

   479     class TEntryEvent

   480         {

   481         public:

   482             // Stores the notification type

   483             TNotifyType iType;

   484             // Stores full path of the file or folder entry

   485             TFileName iEntry;

   486         };

   487 

   488     /** 

   489     * This callback method is used to notify the client about

   490     * entry notifications.

   491     *

   492     * @param aError System wide error code from file server

   493     * @param aEvent The entry event data specified by TEntryEvent

   494     *

   495     * @see TEntryEvent

   496     */

   497     IMPORT_C virtual void HandleNotifyEntry(

   498         TInt aError,

   499         const TEntryEvent& aEvent );

   500 

   501     /**

   502      * Defines the data of dismount finished notification event.

   503      */

   504     class TDismountFinishedEvent

   505         {

   506         public:

   507             // Stores the dismounted drive identifier specified by TDriveNumber

   508             TInt iDrive;

   509             // Indicates if dismount was forced or not

   510             TBool iForcedDismount;

   511         };

   512 

   513     /**

   514     * This callback method is used to notify the client when 

   515     * started dismount has finished.

   516     *

   517     * @param aError System wide error code

   518     * @param aEvent The event data specified by TDismountFinishedEvent

   519     *

   520     * @see TDismountFinishedEvent

   521     */

   522     IMPORT_C virtual void HandleNotifyDismountFinished(

   523         TInt aError,

   524         const TDismountFinishedEvent& aEvent );

   525 

   526     };

   527 

   528 #endif      // C_DISK_NOTIFY_HANDLER_H   

   529 

   530 // End of File