1 /*

     2 * Copyright (c) 2008-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:  Backup Plugin interface

    15 *

    16 */

    17 

    18 

    19 #ifndef BACKUPPLUGIN_H

    20 #define BACKUPPLUGIN_H

    21 

    22 #include <e32base.h>

    23 #include <ecom/ecom.h>

    24 #include "javauids.h"

    25 

    26 namespace java

    27 {

    28 namespace backup

    29 {

    30 

    31 // UID of this interface

    32 const TUid KBackupEcomIfTUid = { KBackupEcomIfUid };

    33 

    34 

    35 /**

    36  * Backup Plugin abstract class.

    37  */

    38 class CBackupPlugin : public CBase

    39 {

    40 

    41 public:

    42 

    43     /**

    44      * Instantiates an object of this type

    45      * using the aMatchString as the resolver parameters.

    46      *

    47      * @param aMatchString String identifier of the implementation

    48      */

    49     inline static CBackupPlugin*  NewL(const TDesC8& aMatchString);

    50 

    51     /**

    52      * Lists all implementations of this interface

    53      *

    54      * @param aImplInfoArray Array containing the info of implementations

    55      */

    56     inline static void ListAllImplementationsL(RImplInfoPtrArray& aImplInfoArray);

    57 

    58     inline virtual ~CBackupPlugin();

    59 

    60     /**

    61      * This method is called when a backup or restore operation is

    62      * starting. Preparations can be done to prepare for BUR.

    63      *

    64      * @param aBackupStateValue the value of the current backup state

    65      */

    66     virtual void PrepareForBURL(TInt aBackupStateValue) = 0;

    67 

    68     /**

    69      * This method receives all or part of a snapshot of data to allow

    70      * calculation of an incremental backup.  The snapshot is one that

    71      * was previously supplied by the data owner.  The snapshot data

    72      * should be read from the location supplied. The snapshot data may

    73      * be larger than the location supplied in which case the routine

    74      * will be called repeatedly until all data has been supplied.

    75      *

    76      * Snapshot data will also be supplied as part of a restore operation

    77      *

    78      * @param aDrive the drive being backed up

    79      * @param aBuffer a pointer to the base of the location from whence

    80      *        data can be copied.

    81      * @param aLastSection ETrue if this is the last section of snapshot

    82      *        data, else EFalse.

    83      */

    84     virtual void ReceiveSnapshotDataL(TDriveNumber aDrive,

    85                                       TDesC8& aBuffer,

    86                                       TBool aLastSection) = 0;

    87 

    88     /**

    89      * This method returns the expected size of backup data that will be

    90      * supplied. If an incremental backup is underway then this method

    91      * will not be called until after ReceiveSnapshotDataL().

    92      * The size data will be used for the purpose of tracking progess

    93      * during a backup. If it is inaccurate then the user may see

    94      * irregular progress but the actual backup data will not be

    95      * affected so it is acceptable to return an estimated value.

    96      *

    97      * @param aDrive the drive being backed up.

    98      * @return the size of the data that will be returned

    99      */

   100     virtual TUint GetExpectedDataSize(TDriveNumber aDrive) = 0;

   101 

   102     /**

   103      * This method returns a snapshot of data to accompany a backup. The

   104      * snapshot is expected to contain details on files / data being

   105      * backed up. The format of the snapshot is only meaningful to the

   106      * data owner. The snapshot will be supplied if the data owner is

   107      * asked for an incremental backup and for a restore operation. The

   108      * snapshot data should be copied to the location supplied.

   109      *

   110      * The snapshot data may be larger than the location supplied in

   111      * which case the routine will be called repeatedly until all data

   112      * has been retrieved.

   113      *

   114      * @param aDrive the drive being backed up

   115      * @param aBuffer a pointer to the base of the location where data

   116      *        can be copied.

   117      * @param aFinished on return ETrue if all data has been returned

   118      *        for this drive, else EFalse.

   119      */

   120     virtual void GetSnapshotDataL(TDriveNumber aDrive,

   121                                   TPtr8& aBuffer,

   122                                   TBool& aFinished) = 0;

   123 

   124     /**

   125      * This method prepares the implementor to return backup data. It

   126      * will be followed by a sequence of calls to request the actual

   127      * data.

   128      *

   129      * @param aDrive the drive being backed up.

   130      */

   131     virtual void InitialiseGetBackupDataL(TDriveNumber aDrive) = 0;

   132 

   133     /**

   134      * This method requests a section of backup data.

   135      * InitialiseGetBackupDataL() will have been called previously to

   136      * specify the drive concerned.  The data returned may be base or

   137      * incremental depending on the type of backup and the capability of

   138      * the data owner.

   139      *

   140      * @param aBuffer a pointer to the base of the location where data

   141      *        can be copied.

   142      * @param aFinished on return ETrue if all data has been returned

   143      *        for this drive, else EFalse.

   144      */

   145     virtual void GetBackupDataSectionL(TPtr8& aBuffer,

   146                                        TBool& aFinished) = 0;

   147 

   148     /**

   149      * This method prepares the implementor to receive base restore data

   150      * for a drive. It will be followed by a sequence of calls to supply

   151      * the actual data.

   152      *

   153      * @param aDrive the drive being restored.

   154      */

   155     virtual void InitialiseRestoreBaseDataL(TDriveNumber aDrive) = 0;

   156 

   157     /**

   158      * This method receives a section of base restore data.

   159      * InitialiseRestoreBaseDataL() will have been called previously to

   160      * specify the drive concerned.

   161      *

   162      * @param aBuffer a pointer to the base of the location whence data

   163      *        can be read.

   164      * @param aFinished ETrue if all data has been returned for this

   165      *        drive, else EFalse.

   166      */

   167     virtual void RestoreBaseDataSectionL(TDesC8& aBuffer,

   168                                          TBool aFinished) = 0;

   169 

   170     /**

   171      * This method prepares the implementor to receive incremental

   172      * restore data for a drive. It will be followed by a sequence

   173      * of calls to supply the actual data.  If multiple increments

   174      * are supplied then this methid will be called before each increment

   175      *

   176      * @param aDrive the drive being restored.

   177      */

   178     virtual void InitialiseRestoreIncrementDataL(TDriveNumber aDrive) = 0;

   179 

   180     /**

   181      * This method receives a section of increment restore data.

   182      * InitialiseRestoreIncrementDataL() will have been called

   183      * previously to specify the drive concerned.

   184      *

   185      * @param aBuffer a pointer to the base of the location whence data

   186      *        can be read.

   187      * @param aFinished ETrue if all data has been returned for this

   188      *        increment, else EFalse.

   189      */

   190     virtual void RestoreIncrementDataSectionL(TDesC8& aBuffer,

   191             TBool aFinished) = 0;

   192 

   193     /**

   194      * This method is called when all data to be restored has been

   195      * supplied.

   196      *

   197      * @param aDrive the drive being restored.

   198      */

   199     virtual void RestoreComplete(TDriveNumber aDrive) = 0;

   200 

   201 private:

   202 

   203     // Unique instance identifier key

   204     TUid iDtor_ID_Key;

   205 };

   206 

   207 } //namespace backup

   208 } //namespace java

   209 

   210 #include "backupplugin.inl"

   211 

   212 #endif // BACKUPPLUGIN_H