Editing Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Using Backup Application

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

The back-up application saves and restores user data stored in [[MyDocs folder|/MyDocs]] (by default) and setting directories/files <code>/etc/osso-af-init/gconf-dir</code> (a link to GConf database <code>/var/lib/gconf</code>), <code>/etc/osso-af-init/locale</code>, and <code>/etc/bluetooth/name</code>. 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 <code>backup_start</code> and <code>backup_finish</code> 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
: <code>com.nokia.backup</code>
;Interfaces
: <code>com.nokia.backup</code>
;Object Paths
: <code>/com/nokia/backup</code>

;Method
: <code>cancel</code>
;Parameters
: none
;Returns
: Empty reply
;Description
: Cancels any ongoing back-up or restore operation

;Method
: 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 <code>/etc/osso-backup/applications</code>, named &lt;application&gt;.conf and consist of simple XML format. An example of the format can be found in [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_libosso.conf example_libosso.conf] in the maemo-examples module:

<source lang="xml">
<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>
</source>

We use the &lt;location&gt; tag to identify files or directories to be backed up. The path must be absolute. The &lt;exclusion&gt; 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 &lt;location&gt; 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:

* <code>comm_and_cal</code> - for communication and calendar
* <code>settings</code> - for system settings
* <code>bookmarks</code> - for bookmark
* <code>applications</code> - for third-party applciations 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/&lt;dir&gt;, where &lt;dir&gt; 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 <br />/etc/osso-backup/restore.d/it2007/. For scripts that are executed after every restore, the location is <code>/etc/osso-backup/restore.d/always</code>.

The files installed here should have the executable bit set. Any files ending with "<code>~</code>" 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.

== 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 .modest/cache/mail/imap/foo.bar__imap.gmail.com_993/folders/INBOX/*.~

where <code>foo.bar*</code> is the name of the imap account. The size of your email may be determined by:

cd .modest
 du -k

[[Category:Development]]
[[Category:Documentation]]
[[Category:Fremantle]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Using_Generic_Platform_Components/Using_Backup_Application"

Personal tools

Navigation

Views

Editing Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Using Backup Application

@@ Line 93: / Line 93: @@
   ...
-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.
+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.