Implementing Active backup

Yeah.. Its would be really good if you understood the idea / concept behind the backup & Restore.

If not please refer to my previous post on "Backup & Restore"

Now its time to code your application / process to interact with Symbian Backup Engine (SBE). That is implementing active backup for your application.

Before that let me explain few more things.

Backup Listener:
You must have a listener class which listens to the events from SBE. It should be an Active Obeject and it should implement MActiveBackupDataClient
class CMyBackupListener : public CActive, public conn::MActiveBackupDataClient

Signaling from SBE to Listener:
The signalling method provided to inform processes that a backup or restore is taking place is via the publish-and-subscribe API. The publish-and-subscribe server maintains a list of subscribers expressing an interest in the backup and restore flag. Any published changes to this flag by the backup and restore engine results in all subscribers being notified. The flag provides information on whether a backup or restore operation is in progress, whether a backup is base or incremental and whether the operation is full or partial. Subscribing to the flag is done via RProperty, which must be used in conjunction with an active object to be notified when the value changes.
The following key and category values should be used (these are defined in epoc32\include\connect\sbdefs.h):

Category : KUidSystemCategoryValue

Key : KUidBackupRestoreKey

The following code fragment demonstrates this:

#include RProperty iProperty;
iProperty.Attach(KUidSystemCategory, KUidBackupRestoreKey);
CActiveScheduler::Add(this);
iStatus = KRequestPending;
iProperty.Subscribe(iStatus);
SetActive(); // In CMyBackupListener::RunL, you will get the notification

Yep. You got a notification from SBE that its going to backup the data. How to make connection with SBE then?

Connecting to SBE:
Once you got the notification from SBE, then make a connection as follows

iConn = conn::CActiveBackupClient::NewL(this); // Listener is again the observer for this
iConn ->ConfirmReadyForBURL(KErrNone);

yes.. we initimated SBE that we are ready for backup.


Hereafter you will start getting events from SBE to backup and restore. Its up to the application writer, what data to be backed up and what not to be. Because its active backup method 

If its passive, it would have been already mentioned in the backup registration file and the fact is that the data owning process need not to be run at that time.

As you know the active backup expects the data owning processes need to be run. So, a question should flash in your mind here.

“Where did we mention which process to be expected to run?”

Yeah.. Here is the answer

It should be mentioned in the backup registration file. The following is the syntax of that.

xml version="1.0" standalone="yes"?
backup_registration
active_backup process_name = "Myprocess" requires_delay_to_prepare_data = "yes"
backup_registration

Conclusion:

When your phone is connected to PC, the SBE from backup software signals all the processes that are registered for the backup process. (obviously by referring the backup registration files )

On receiving those events, the process creates a connection (CActiveBackupClient)

Then Processes receive events from SBE and they backups the data they wish. The same way as restore.

Read More......

"Backup & Restore" for symbian OS applications

Do you want to upgrade your phone? Then what about your existing application data? Ok. Lets take a backup of them and upgrade your phone.

Symbian OS includes software to carry out backup and restore operations to and from a connected PC. In order to do this, the applications should be made aware of backup and restore.

Make your application "Intelligent"
Before making your application aware of the backup and restore, Determine the following:
1. What are the contents to be backed up?
Private data? yes. ok. Do you wish to backup the complete private directory or specific files?
Public data? yes. Then where its located?
Do you want to backup system directory?
2. Do you want to use Active backup or passive method?
Have you got the answers for this? If yes, then write them up in a file. Yes that is called "backup registration file"

Wait... wait.. Tell me onething.. Are you clear with the concept of backup and restore?? Nope?? Then read the below paragraphs :)

Backup Operation
Hi dudes (processes in the phone) I am Mr.backup. I want to store all of your data's safely. Could you please let me do my job?
Ok Mr.Backup... we are all releasing our resources for the time being, you copy our data into PC :)
Yes.. A backup operation needs to read files so processes must relinquish exclusive-locks on files but can retain read-locks (although in practice many processes just relinquish all locks for the sake of safety and simplicity). In order for a backup operation to take place, applications and servers must flush any pending updates to files and allow all files to be read (but cached data can be retained as backup will not alter data files). When the backup has taken place, servers and applications can re-take file locks and carry on.

Restore Operation
A restore operation requires exclusive access to files so processes must relinquish all locks on files. In order for a restore operation to take place, applications and servers must discard all cached data and allow files to be written or overwritten. When the restore has taken place, servers and applications must reload their data from files that can be expected to have changed.
Hopefully it better explained about the resposibilities of the application / process, when backup & restore takes place.

Now lets see what is active and passive ways of backup.

There are two ways of backing up private data:
1. Active backup of private data. In this model, the process which owns the data, registers with the secure backup engine using a registration file. The secure backup engine will start any process registered for active backup if not already started. The data owning process then responds to a central signal when a backup or restore operation takes place and actively provides its private data to or receives it from the secure backup engine. This requires that the data-owning process include specific code to take part in backup and restore operations, and that it must be running when a backup or restore takes place. In this model the data-owning process registers with the secure backup engine but exercises complete control of which data is backed up and restored.

2. Passive backup of private data. In this model, the process which owns the data, registers with the secure backup engine using a registration file and records whether executables, private files or directories of private files should be backed up. The data-owning process then releases file locks for private files in the same way as for public files (described above) and the files are backed up by the secure backup engine (which has the required capability to access private data files belonging to other processes).

Now lets concentrate on Backup_registration.xml file format

Basic application backup
The following represent the minimum you have to do for the backup of your application. Write a backup_registration.xml file as shown below
xml version="1.0" standalone="yes"
backup_registration
system_backup
restore requires_reboot="no"
backup_registration

add it into your pkg file:
"backup_registration.xml"-"!:\private\\backup_registration.xml"

Adding private data into the backup
Another common requirement would be to save the content of your private directory (located in \private\). This is done by adding the following declaration in your backup_registration.xml file
passive_backup
include_directory name="\"
passive_backup

You can also decide to save all your private directory but a 'nobackup' subdirectory:
passive_backup
include_directory name="\"
exclude name = "\nobackup\"
include_directory
passive_backup

You may also prefer to specify files instead of directories:
include_file name="important.dat"
include_file name="me_too.dat"

Adding public data into the backup
In the paragraph above, the "\" directory is referring to your application private directory. So how to save data when they are located outside of your private area ? This is done by simply using another xml tag. Replace by and the path will be relative to the root directory of the phone file system (you don't need to specify the drive):
public_backup
include_directory name="C:\MyData"
public_backup

Okay.. The blog is increasing in length. I will stop here. Hope its somewhat useful to understand the idea behind the backup & Restore. I will give the complete details, how to use symbian backup engine in your code to make your application aware of backup & Restore.

Bye for now. Comments are welcome. That will help me to put my points correctly as this is my first ever blog :)

Read More......