Writing a CSBEClient for Backup

Context

A partial backup backs up the data of specified data owners. Application developers provide a full list of data owners in the backup and restore registration file. To back up a subset of the list, the Security IDs (SIDs) of the specified data owners must be passed to the Backup Engine.

An incremental backup backs up files that are new or modified since the last backup. After each incremental backup, a snapshot, which saves a list of file names and details of each data owner, is saved. Before each incremental backup, the previously saved snapshots must be provided to the Backup Engine.

Steps

1. The user application must instantiate conn::CSBEClient to connect to the Backup Engine.

   iBackupClient = CSBEClient::NewL();

2. Get a list of registered data owners from the Backup Engine.

   iBackupClient->ListOfDataOwnersL(RPointerArray<CDataOwnerInfo>& iDataOwners);

   The Backup Engine parses the backup registration files to return an array of CDataOwnerInfo objects. A CDataOwnerInfo object encapsulates all the information regarding a particular data owner on the phone, such as packages that the data owners belong to and data types (public data or private data). These objects can be internalized and externalized to create backup archives.

3. Send a list of data owners to the Backup Engine.

   To back up the data of specified data owners, pass the array of the Secure IDs (SID) of these data owners to the Backup Engine.

   Note: Each Symbian process is identified by its SID.

   iBackupClient->SetSIDListForPartialBURL(RSIDArray& aSIDs);

4. Set the Backup Engine to the backup mode which signals the start of a backup.

   The Backup Engine publishes the mode to the subscribed data owners. This gives the data owners some time to prepare for the backup, for example they can release resources in case of file lock or data conflict.

   The mode contains the backup types: full or partial, base or incremental.

   iBackupClient->SetBURModeL (
                                const TDriveList& aDriveList,
                                
                                //Specify partial backup,
                                //defined in epoc32/include/connect/sbdefs.h
                                TBURPartType aBURType,      
   
                                //Specify incremental backup,
                                //defined in epoc32/include/connect/sbdefs.h
                                TBackupIncType aBackupIncType
                              );
   

5. Request the state of active data owners from the Backup Engine.

   This step ensures that the data owners are ready to supply data in the following steps, for example file locks are released.

   iBackupClient->SIDStatusL(RSIDStatusArray& aSIDStatus);

6. Supply data snapshots got from the host PC to the Backup Engine.

   Before doing an incremental backup, the Backup Engine needs to know a list of the files included in the preceding backup. Refer to step 13 for saving snapshots after an incremental backup.

   iBackupClient->SupplyDataL(
                                CSBGenericTransferType& aSnapShotTransferType,
                                TBool aFinished
                              );

   A snapshot transfer type must be passed to the function above. For more information about creating snapshot transfer types, refer to the Creating transfer types section.

7. Inform the Backup Engine that all snapshots have been supplied and it is ready to do the backup.

   iBackupClient->AllSnapshotsSuppliedL();

8. Request the size of the data to be backed up from the Backup Engine.

   The file size information can be sent to the PC to track the backup progress.

   iBackupClient->ExpectedDataSizeL(CSBGenericTransferType& aGenericTransferType);

9. Get a list of public files to be backed up from the Backup Engine.

   The file list can be sent to the PC to track backup progress.

   iBackupClient->PublicFileListL(
                                   TDriveNumber aDrive,
                                   CSBGenericDataType& aGenericDataType,
                                   RFileArray& aFiles
                                 );

   The Backup Engine can get a list of public files, but it does not supply public files directly to the backup server. Device creators must copy the public files from the device and supply them to the host PC in their backup server implementations.

10. Request the system data from the Backup Engine for backup.

    iBackupClient->RequestDataL(CSBGenericTransferType& aGenericTransferType);

    Note: Refer to the Creating transfer types section for an example of creating the required CSBGenericTransferType.

11. Request active private data from the backup Engine for backup.

    iBackupClient->RequestDataL(CSBGenericTransferType& aGenericTransferType);

12. Request passive private data from the backup Engine for backup.

    iBackupClient->RequestDataL(CSBGenericTransferType& aGenericTransferType);

13. Request the snapshots of all data owners. The backup server can then send the snapshots to the host PC for backup.

    After an incremental backup, conn::CSBEClient must request snapshots from the Backup Engine. The backup server sends the snapshots to the host PC and the host PC saves the information.

    iBackupClient->RequestDataL(CSBGenericTransferType& aSnapShotTransferType);

14. Set the Backup Engine into the normal mode.

    After the data is backed up on the PC, set the Backup Engine to the normal mode. The subscribed data owners respond to the signal and resume the state before the backup. For example, resume file locks or a GUI application recovers to the state and view prior to the backup.

    iBackupClient->SetBURModeL(
                                 const TDriveList& aDriveList, 
                                 TBURPartType aBURType,
                                 TBackupIncType aBackupIncType
                               );