Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Using Backup Application
Usage of Back-up Application
The back-up application saves and restores user data stored in /MyDocs (by default) and setting directories/files /etc/osso-af-init/gconf-dir (a link to GConf database /var/lib/gconf), /etc/osso-af-init/locale, and /etc/bluetooth/name. It can be configured to back up other locations and files as well, by custom configuration files.
The back-up application must not be disrupted by other applications writing or reading during a back-up or restore operation.
For restore process, back-up therefore will, if the user approves, ask the application killer to close all applications, and then wait until it has been done.
For backing up, the backup_start and backup_finish D-BUS signals will be emitted on the session bus, indicating to applications that they should not write to disk.
D-BUS description and methods of back-up Application
Service com.nokia.backup Interfaces com.nokia.backup Object Paths /com/nokia/backup Method: cancel Name cancel Parameters none Returns Empty reply Description Cancels any ongoing back-up or restore operation Method: activate Name activate Parameters none Returns Empty reply Description Used to activate the application with auto-activation
Custom back-up locations
For other data not normally backed up, the so-called locations configuration is used. It is important that the locations configuration paths MUST NOT overlap with the documents path.
The locations configuration lets applications install a configuration file with a list of files and directories that should be included in the back-up. The files should be installed into /etc/osso-backup/applications, named <application>.conf and consist of simple XML format. For the application, the example_libosso.conf looks like the following:
<backup-configuration> <locations> <location type="file" category="settings" auto="true">/etc/example.ini</location> <location type="dir" category="documents">/home/user/foo</location> <exclusion type="file" category="settings">/home/user/bigfile</exclusion> <exclusion type="file" category="settings">/tmp/*.jpg</exclusion> </locations> </backup-configuration>
With the <location> tag, different locations can be given to be backed up. N.B. The path must be absolute. <exclusion> tag can be used, if some files in certain directories are not wanted to be backed up, for example, in the case of some setting file changing from one software version to another. This way, the new setting file of updated software will not be destroyed, if the back-up is restored. Wild cards '?' and '*' are also supported.
Both tags have TYPE and CATEGORY arguments and <location> tag additional AUTO argument:
TYPE - Its value can be "file" or "dir" for a file or directory. This argument must be provided.
CATEGORY - It is used for handling selective back-up and restore. It may be omitted, in which case the location will only be backed up when backing up or restoring everything. The value can be:
- comm_and_cal - for communication and calender
- settings - for system settings
- bookmarks - for bookmark
- applications - for 3rd apps list
AUTO - Its value can be true or false. It is used to tell the back-up application not to request a user response in case of a conflict, but automatically replace the file. N.B. The auto argument is only used for files, not for directories. It may be omitted, in which case it defaults to false.
After restore run scripts
The back-up application makes it possible to execute scripts after a restore operation. There are two kinds of scripts. First, there can be scripts that are executed after every restore operation. Then there are also scripts that are executed only, if the restore is made from a back-up created in an earlier product.
For the scripts that are used to transform data between the device software versions, the location for applications to install the scripts is /etc/osso-backup/restore.d/<dir>, where <dir> is a subdirectory for each transition between two different consecutive version of the platform. For transforming between IT-2006 and IT-2007 versions, the directory is
/etc/osso-backup/restore.d/it2007/. For scripts that are executed after every restore, the location is /etc/osso-backup/restore.d/always.
The files installed here should have the executable bit set. Any files ending with "~" or ".bak" are ignored, just like directories or files starting with a dot (".").
Each script will be executed with a command line argument that is the path of a file containing the list of all files that have been restored, per category. The format of this file is:
[CATEGORY] /path/to/file1 /path/to/file2 ... [CATEGORY] ...
CATEGORY is one of the OSSO categories (emails, documents, media, contacts, bookmarks, settings or applications). This makes it possible for the scripts to check, which files they need to upgrade, if any at all. The format is chosen to be easy to parse with a simple script or program.
The scripts will be executed after a successful restoration, or after a restoration has been canceled. In both cases, the scripts will only be executed if any files were actually restored. Scripts should clean up after transforming, so that old files are not left behind. The script or program should use the common convention and return zero on success, and non-zero in case of failure. Application developers should try and make their programs execute and finish quickly.