1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-F40BA7EA-AF7E-5BCF-96DD-9C4D8E947F0C" xml:lang="en"><title>Writing

    13 a CSBEClient for Backup</title><shortdesc>This section describes the recommended <apiname>conn::CSBEClient</apiname> function

    14 calls for a partial and incremental backup. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <section><title>Context</title> <p>A partial backup backs up the data of specified

    16 data owners. Application developers provide a full list of data owners in

    17 the backup and restore registration file. To back up a subset of the list,

    18 the Security IDs (SIDs) of the specified data owners must be passed to the

    19 Backup Engine. </p> <p>An incremental backup backs up files that are new or

    20 modified since the last backup. After each incremental backup, a snapshot,

    21 which saves a list of file names and details of each data owner, is saved.

    22 Before each incremental backup, the previously saved snapshots must be provided

    23 to the Backup Engine. </p> </section>

    24 <section><title>Steps</title> <ol id="GUID-C9A4B10B-8D7A-562E-A7FF-B5C039CE514E">

    25 <li id="GUID-3C3EA5AB-B255-55A6-BE4D-58EFF9B0CE50"><p>The user application

    26 must instantiate <xref href="GUID-169BB4E2-5B0E-3719-A7B8-A3C0AAA602E2.dita#GUID-169BB4E2-5B0E-3719-A7B8-A3C0AAA602E2/GUID-FB671D02-0F15-396F-9FB7-EE3E9372093C"><apiname>conn::CSBEClient</apiname></xref> to connect to the Backup

    27 Engine. </p> <p><codeblock id="GUID-E84080F8-2D77-5C9C-82EF-12D2CD6B4686" xml:space="preserve">iBackupClient = CSBEClient::NewL();</codeblock> </p> </li>

    28 <li id="GUID-5F6972FC-9183-5908-9A3C-2FA45742A485"><p>Get a list of registered

    29 data owners from the Backup Engine. </p> <p><codeblock id="GUID-E67258BD-A391-5378-A496-932097F22BE8" xml:space="preserve">iBackupClient-&gt;ListOfDataOwnersL(RPointerArray&lt;CDataOwnerInfo&gt;&amp; iDataOwners);</codeblock> </p> <p>The Backup Engine parses the backup registration files to return

    30 an array of <xref href="GUID-DD6B46F8-8B3F-3BDD-A2C0-1B12287911D3.dita"><apiname>CDataOwnerInfo</apiname></xref> objects. A <xref href="GUID-DD6B46F8-8B3F-3BDD-A2C0-1B12287911D3.dita"><apiname>CDataOwnerInfo</apiname></xref> object

    31 encapsulates all the information regarding a particular data owner on the

    32 phone, such as packages that the data owners belong to and data types (public

    33 data or private data). These objects can be internalized and externalized

    34 to create backup archives. </p> </li>

    35 <li id="GUID-51142C40-E334-5865-A07D-EC65ED8CDB95"><p>Send a list of data

    36 owners to the Backup Engine. </p> <p>To back up the data of specified data

    37 owners, pass the array of the Secure IDs (SID) of these data owners to the

    38 Backup Engine. </p> <p> Note: Each Symbian process is identified by its SID. </p> <p><codeblock id="GUID-DC33230F-C5FD-5B4D-A083-C256B31D99C7" xml:space="preserve">iBackupClient-&gt;SetSIDListForPartialBURL(RSIDArray&amp; aSIDs);</codeblock> </p> </li>

    39 <li id="GUID-3FEC5DB5-BD3A-5BB4-8CBB-AF1E02CD13CF"><p>Set the Backup Engine

    40 to the backup mode which signals the start of a backup. </p> <p>The Backup

    41 Engine <xref href="GUID-88A5F321-17BA-566B-B025-22DB11664E54.dita">publishes the

    42 mode to the subscribed data owners</xref>. This gives the data owners some

    43 time to prepare for the backup, for example they can release resources in

    44 case of file lock or data conflict. </p> <p>The mode contains the backup types:

    45 full or partial, base or incremental. </p> <p><codeblock id="GUID-26AD4017-DE62-5E24-8A24-AEF9B1748CF5" xml:space="preserve">iBackupClient-&gt;SetBURModeL (

    46                              const TDriveList& aDriveList,

    47                              

    48                              //Specify partial backup,

    49                              //defined in epoc32/include/connect/sbdefs.h

    50                              TBURPartType aBURType,      

    51 

    52                              //Specify incremental backup,

    53                              //defined in epoc32/include/connect/sbdefs.h

    54                              TBackupIncType aBackupIncType

    55                            );

    56 </codeblock> </p> </li>

    57 <li id="GUID-04A8BE86-6D96-5ECF-9E7F-844DFEB6824C"><p>Request the state of

    58 active data owners from the Backup Engine. </p> <p>This step ensures that

    59 the data owners are ready to supply data in the following steps, for example

    60 file locks are released. </p> <p><codeblock id="GUID-06ECF9D7-D735-5B29-90A3-68FEFD3F31E0" xml:space="preserve">iBackupClient-&gt;SIDStatusL(RSIDStatusArray&amp; aSIDStatus);</codeblock> </p> </li>

    61 <li id="GUID-8BA8CC19-2324-5D0A-84B0-9F50BF10C6CD"><p>Supply data snapshots

    62 got from the host PC to the Backup Engine. </p> <p>Before doing an incremental

    63 backup, the Backup Engine needs to know a list of the files included in the

    64 preceding backup. Refer to step 13 for saving snapshots after an incremental

    65 backup. </p> <p><codeblock id="GUID-D74CE5A8-CBB2-5217-8953-389EEC358E66" xml:space="preserve">iBackupClient-&gt;SupplyDataL(

    66                              CSBGenericTransferType& aSnapShotTransferType,

    67                              TBool aFinished

    68                            );</codeblock> </p> <p>A snapshot transfer type

    69 must be passed to the function above. For more information about creating

    70 snapshot transfer types, refer to the <xref href="GUID-8BFC185E-91FD-5E04-A26C-728B06F31FDD-GENID-1-7-1-23-1-1-4-1-3-1-6-1-6-1.dita">Creating

    71 transfer types</xref> section. </p> </li>

    72 <li id="GUID-DB8A0DB8-2FD9-5F86-A791-960043DC8C78"><p>Inform the Backup Engine

    73 that all snapshots have been supplied and it is ready to do the backup. </p> <p><codeblock id="GUID-FEC18F5C-B2CE-5A97-B14C-0684F9839F7B" xml:space="preserve">iBackupClient-&gt;AllSnapshotsSuppliedL();</codeblock> </p> </li>

    74 <li id="GUID-6BE5428B-ADEC-514D-A3C5-43953E1911E0"><p>Request the size of

    75 the data to be backed up from the Backup Engine. </p> <p>The file size information

    76 can be sent to the PC to track the backup progress. </p> <p><codeblock id="GUID-C99CC93F-FD0F-508D-8638-F3D2C7885796" xml:space="preserve">iBackupClient-&gt;ExpectedDataSizeL(CSBGenericTransferType&amp; aGenericTransferType);</codeblock> </p> </li>

    77 <li id="GUID-A3711593-3A3A-5A16-AB40-5CE79582509E"><p>Get a list of public

    78 files to be backed up from the Backup Engine. </p> <p>The file list can be

    79 sent to the PC to track backup progress. </p> <p><codeblock id="GUID-07D3F3B9-152A-582B-BF9C-8336FB73A0E9" xml:space="preserve">iBackupClient-&gt;PublicFileListL(

    80                                 TDriveNumber aDrive,

    81                                 CSBGenericDataType& aGenericDataType,

    82                                 RFileArray& aFiles

    83                               );</codeblock> </p> <p>The Backup Engine can

    84 get a list of public files, but it does not supply public files directly to

    85 the backup server. Device creators must copy the public files from the device

    86 and supply them to the host PC in their backup server implementations. </p> </li>

    87 <li id="GUID-22A6F0AD-F0DF-56C9-8D91-DE3B1B96271C"><p>Request the system data

    88 from the Backup Engine for backup. </p> <p><codeblock id="GUID-270B8E6E-4E3E-51D0-8965-2A1CBB85655D" xml:space="preserve">iBackupClient-&gt;RequestDataL(CSBGenericTransferType&amp; aGenericTransferType);</codeblock> </p> <p> Note: Refer to the <xref href="GUID-8BFC185E-91FD-5E04-A26C-728B06F31FDD-GENID-1-7-1-23-1-1-4-1-3-1-6-1-6-1.dita">Creating

    89 transfer types</xref> section for an example of creating the required <xref href="GUID-2A9C2278-088A-3C16-BAA1-5E97DBBC4979.dita"><apiname>CSBGenericTransferType</apiname></xref>. </p> </li>

    90 <li id="GUID-D449FECD-C8DE-53D9-9541-592526491E76"><p>Request active private

    91 data from the backup Engine for backup. </p> <p><codeblock id="GUID-0E64EE9A-2756-551C-9442-A5BCEDABC2DC" xml:space="preserve">iBackupClient-&gt;RequestDataL(CSBGenericTransferType&amp; aGenericTransferType);</codeblock> </p> </li>

    92 <li id="GUID-066A67CD-2E42-51E7-BCFB-6FE56B6F7613"><p>Request passive private

    93 data from the backup Engine for backup. </p> <p><codeblock id="GUID-5D16114E-9E66-52A2-BE25-1EDFFB245D95" xml:space="preserve">iBackupClient-&gt;RequestDataL(CSBGenericTransferType&amp; aGenericTransferType);</codeblock> </p> </li>

    94 <li id="GUID-6B33556D-7F5A-5F33-9695-BAE32A590796"><p>Request the snapshots

    95 of all data owners. The backup server can then send the snapshots to the host

    96 PC for backup. </p> <p>After an incremental backup, <xref href="GUID-169BB4E2-5B0E-3719-A7B8-A3C0AAA602E2.dita#GUID-169BB4E2-5B0E-3719-A7B8-A3C0AAA602E2/GUID-FB671D02-0F15-396F-9FB7-EE3E9372093C"><apiname>conn::CSBEClient</apiname></xref> must

    97 request snapshots from the Backup Engine. The backup server sends the snapshots

    98 to the host PC and the host PC saves the information. </p> <p><codeblock id="GUID-110BD5E6-A2D7-5AF5-8F36-1E8C3B065877" xml:space="preserve">iBackupClient-&gt;RequestDataL(CSBGenericTransferType&amp; aSnapShotTransferType);</codeblock> </p> </li>

    99 <li id="GUID-D3528970-74F0-5F64-A2D4-0342C00E585C"><p>Set the Backup Engine

   100 into the normal mode. </p> <p>After the data is backed up on the PC, set the

   101 Backup Engine to the normal mode. The subscribed data owners respond to the

   102 signal and resume the state before the backup. For example, resume file locks

   103 or a GUI application recovers to the state and view prior to the backup. </p> <p><codeblock id="GUID-648F6685-01C3-5D17-98CB-9EACB8929C0F" xml:space="preserve">iBackupClient-&gt;SetBURModeL(

   104                              const TDriveList& aDriveList, 

   105                              TBURPartType aBURType,

   106                              TBackupIncType aBackupIncType

   107                            );

   108 </codeblock> </p> </li>

   109 </ol> </section>

   110 </conbody><related-links>

   111 <link href="GUID-0BD22FDB-1A5C-56AA-A7FC-BD2271B2F928.dita"><linktext>Writing a

   112 Backup Engine Client (CSBEClient)</linktext></link>

   113 </related-links></concept>