MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Using Backup Framework

MeeGo 1.2 Harmattan Backup Framework is responsible for backing up and restoring the user data (such as user configuration and settings) stored by your application when, for instance:

  • User upgrades the device to a new version. If the upgrade fails, the user wants to be sure that the data can be restored from backup files.
  • Instead of storing the data to the Harmattan device, the user wants to store the data to a different location, such as a workstation.

By default, the Backup Framework backs up the Tracker database and the GConf system (default system in Harmattan for storing application settings). If you only want to back up data that your application stores in these locations, you do not need to make any further modifications.

However, if you want the Backup Framework to back up data stored in other locations, you must configure the backup functionality accordingly. You can use either of the following backup methods:

To use the Backup Framework:

  1. Create an XML configuration file. The contents depend on the selected backup method. See Using D-bus API and Using backup and restore scripts for the required contents and examples of the configuration files.
  2. Name the file <package name>.conf.
  3. Store the configuration file in the following folder:
/usr/share/backup-framework/applications/

Using D-bus API

Use D-bus API as the backup method if your application needs to know when the backup and restore operation starts and finishes. An application may need to know this information for creating temporary backup files (location type file). If the application has only locations of type permanent-backup-file, the application must remove any locks on these files at the time of restore.

The D-bus API is useful if your application handles real-time data. For example, if a call is received during backup, it must be updated in the call log. In this case, a D-bus method call is made to the call application, which decides whether the call information needs to be stored in the call database, or preserves the data in memory for a later update to the call database.

If your application needs to store data during backup or restore and uses Tracker as the back-end engine for storing data, use the D-bus API as the backup method.

Backup and restore D-bus calls

The following example illustrates the D-bus calls during backup and restore operations:

dbus-send --print-reply --type=method_call --dest=com.nokia.organizerstub /organizerstub/backup
com.nokia.backupclient.backupStarts
dbus-send --print-reply --type=method_call --dest=com.nokia.organizerstub /organizerstub/backup
com.nokia.backupclient.backupFinished
dbus-send --print-reply --type=method_call --dest=com.nokia.organizerstub /organizerstub/backup
com.nokia.backupclient.restoreStarts
dbus-send --print-reply --type=method_call --dest=com.nokia.organizerstub /organizerstub/backup
com.nokia.backupclient.restoreFinished

The D-bus service name and path (in the example, com.nokia.organizerstub and /organizerstub/backup) are read from the configuration file of the application. The D-bus methods return one of the following unsigned characters:

  • 0 indicates no error
  • 1 indicates memory-related errors
  • 2 indicates any other errors

If the application has to be started for backup or restore, it can install a D-bus service file in the /usr/share/dbus-1/services/ folder.

The following table presents the backup and restore D-bus calls.

Backup and restore D-bus calls
D-bus call Description
backupStarts call The backupStarts method is called just before the actual backup starts. The application can dump all the data in RAM to their persistent storage, or create a temporary file which is backed up when the application gets this call.
backupFinished call The application is notified when the backup is finished. The application can start using its storage again when it gets this call.
restoreStarts call The application is notified when the restore operation is about to start.
restoreFinished call The application is notified that a restore operation has finished. An application that uses temporary backup files imports the data from the temporary files when it gets this call.

Backup configuration file for D-bus API

To use D-bus API as the backup method, create a configuration file with the following information:

  • application-type: nokia
  • application-name: any name used to identify the application
  • backup-method: permanent-backup-files
  • dbus-service: service path and name
  • location type: permanent-backup-file or file.
    • The Backup Framework deletes the location of type file after the backup or restore operation is complete.
  • location: file or a directory.
    • The configuration file does not need to specify whether the location is a file or a directory, the framework checks this internally.
  • category: contacts, organizer, emails, messaging, bookmarks, settings, or applications.

Example

<backup-configuration>
<application-type>nokia</application-type>
<application-name>Calendar Backup</application-name>
<backup-method>permanent-backup-files</backup-method>
<backup-dbus>
<dbus-service object="/organizerstub/backup">com.nokia.organizerstub</dbus-service>
</backup-dbus>
<locations>
<location type="permanent-backup-file" category="organizer">$HOME/.calendardbbbbb </location>
<location type="file" category="organizer">$HOME/.calendardbbbbb.changed
</location>
</locations>
</backup-configuration>

Using backup and restore scripts

If an application uses the scripts method for backup and restore, it does not have to be running during the backup and restore operations. The backup script can fetch data from database and create the file to be backed up, and the restore script can extract data from these files and put it back into the database.

After invoking all the backup scripts, the Backup Framework continues the backup operation. It creates a separate archive zip file for each content category on the MMC card. After that, the Backup Framework deletes the temporary backup files (locations of type file) from the locations where the applications created them (the locations are specified in the application XML configuration files).

When a user starts a restore operation, the Backup Framework extracts the files from the backup archive and invokes the application restore scripts for all backup-aware applications that provide restore scripts. The restore script reads the data from the backup files and restores the data.

The backup and restore scripts return one of the following integer values:

  • 0 indicates no errors
  • 1 indicates memory full error
  • 2 indicates other error during operation

Naming policy for the backup and restore scripts

The following table presents the predefined format for the script names.

Backup and restore scripts
Name format Examples
<package name>-backup
  • example_application-backup
  • ExampleApplication-backup
<package name>-restore
  • example_application-restore
  • ExampleApplication-restore


Configuration file for backup and restore scripts

To use backup and restore scripts as the backup method, create a configuration file with the following information:

  • application-type: nokia
  • application-name: any name used to identify the application
  • backup-method: backup-scripts
  • backup-script-name: name of backup script including full path
  • restore-script-name: name of restore script including full path
  • location type: permanent-backup-file or file.
    • The Backup Framework deletes the location of type file after the backup or restore operation is complete.
  • location: file or a directory.
    • The configuration file does not need to specify whether the location is a file or a directory, the framework checks this internally.
  • category: contacts, organizer, emails, messaging, bookmarks, settings, or applications.

Example

<backup-configuration>
<application-type>nokia</application-type>
<application-name>Messaging Application Stub</application-name>
<backup-method>backup-scripts</backup-method>
<backup-scripts>
<backup-script-name>/usr/share/messaging/messaging-backup</backup-script-name>
<restore-script-name>/usr/share/messaging/messaging-restore</restore-script-name>
</backup-scripts>
<locations>
<location type="file" category="messaging">/home/user/messaging/messaging
_backup.bin</location>
</locations>
</backup-configuration>