Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Using Backup Application
Contents |
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 "locations" configuration is used. The "locations" configuration paths MUST NOT overlap with any paths which are to be backed up.
The "locations" configuration lets applications install a configuration file with a list of files and directories that should be included in the back-up, or explicitly excluded from it.
The files should be installed into /etc/osso-backup/applications, named <application>.conf and consist of simple XML format. An example of the format can be found in example_libosso.conf in the maemo-examples module:
<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>
We use the <location> tag to identify files or directories to be backed up. The path must be absolute. The <exclusion> tag can be used to exclude some files from the backup, such as temporary files, cached files, or settings for older versions of a software package. Wild cards '?' and '*' are also supported.
NOTE In order to be backup up, any files in the locations specified must be readable by the tablet user.
Both tags have TYPE and CATEGORY arguments and <location> tag additional AUTO argument:
TYPE can be "file" for a file or "dir" for a directory. This argument is required.
CATEGORY 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 calendar
- settings - for system settings
- bookmarks - for bookmark
- applications - for 3rd apps list
AUTO can be true or false. In case of a conflict during backup, the destination file will be automatically replaced if this argument is true. Otherwise, the user will be prompted. This argument is only used for files, and defaults to false if omitted.
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 (communications and calendar, settings, bookmarks and 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.
Tips
- You may want to consider erasing the cached inbox contents before doing backup if your email inbox is very large. E.g. if your mail contains a lot of attachments, the cache may be in the size of 100's of megabytes. To erase the cache and prevent its backup open an xterm and do:
\rm ./cache/mail/imap/foo.bar__imap.gmail.com_993/folders/INBOX/*.~
where foo.bar* is the name of the imap account. The size of your email may be determined by:
cd .modest du -k