Symbian OS includes software to backup data to, and restore it from a connected PC. For this software to function correctly, it requires the co-operation of servers and applications running on the phone.

This "How-To" describes how these applications and servers need to behave in order to participate in backup and restore under Symbian OS v9.1 and later versions. It is intended for anyone responsible for developing or maintaining components or applications within the Symbian OS platform.

• Overview and Background

  • File locks and public files

  • Private data and data caging requirements

  • Active and passive backup

  • Base and incremental backup and restore

  • Full and partial backup and restore

• Making Applications Backup-aware

  • Default behaviour for GUI applications

  • Servers that hold locks for clients

  • Servers and applications that hold other locks

  • Reboot after restore flag

• Deciding What to Back up and How

  • Criteria for backing up private data

  • Choosing active or passive backup

  • Private data to be actively backed up

  • Private data to be passively backed up

  • Private data not backed up

  • Data in a proxy to be backed up

  • DBMS files to be backed up

  • System (installed application) data to be backed up

• Backup Registration Files

  • Content of the backup registration file

  • Example backup registration files

  • Additional backup registration files

• Testing backup and restore

• Backup registration file DTD

Backup works by copying files and data from the phone to the PC. Restore works by copying the files and data in the other direction.

The backup and restore rely on being able to copy files when they need to. If a file is locked, it cannot be copied. In normal phone use, a range of servers and applications will have files open for reading or writing, and may have updates pending on some files.

Files in the public area of the filing system can be backed up and restored directly by the PC Connectivity subsystem but this requires all other processes to free up file locks when required. Platform Security (introduced in Symbian OS v9), and specifically data caging, provides for ownership of private data files (see Private data and data caging requirements). Ownership of public data files is more complex.

• 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.

• 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.

With the introduction of Platform Security, directories are divided into public and private areas. Public files can be viewed and altered by any application (although file locks may still get in the way). However, processes can define private data areas where they store files that only they can operate on. The system also defines some areas as private to store executables and read-only data. The choice of whether and what files should be stored in public and private areas is devolved to the servers and applications (with some audits). All of the restrictions can be overridden by executables that have the requisite privileges (the use of these is minimized on principle).

As a principle, the backup process attempts to protect private data in the following ways:

• Application executables will not be backed up without the consent of the developer. This means that if you develop an application and forget about backup, you should not find your application backed up. It is normally meaningless to restore an application without at least some of its private data.

• Private data will not be backed up without the consent of the data owner. This means that if you don’t explicitly enable the private data to be backed up, you should not discover it has been exposed without your knowledge.

• Private data may be encrypted before delivery to the backup client (normally a PC). The backup process supports encryption and provides the hooks for key access but does not guarantee that a useful key will be used. (This relies on the phone manufacturer to include a specific mechanism to provide the encryption key). It should be assumed that the user will have access to the encryption key and so application developers should not assume that data will be protected from the user. For this reason, encryption of backed up data may be omitted.

There are two ways of backing up private data:

• Active backup. Under this method, the process which owns the data, registers with the secure backup engine using a registration file (see Backup Registration Files). 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, 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.

• Passive backup. Under this method, the process which owns the data, registers with the secure backup engine using a backup 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).

Passive backup is very simple for developers to implement – all that is required is a backup registration file that defines which private files should be backed up or restored and the same type of lock-releasing behaviour already required for public files. Active backup requires more effort to implement but provides the data-owning process with more control over the data backed up and restored.

Note that data-owning processes can also list public files or directories that should be backed up or restored along with their private data in cases of a partial backup or restore.

Backup is intended to be a routine operation for the user. Therefore, it should be as quick and painless as possible. For this reason, Symbian OS implements base and incremental backups. A base backup (sometimes described as a full backup) is a backup of all or part of a drive that includes all the selected files. In contrast, an incremental backup is a backup of all or part of a drive that only includes files that are new or changed since a previous backup. An incremental backup is thus smaller than a base backup and will take less time.

Note that there are (at least) two possible patterns of use for incremental backups.

• The first pattern involves taking one base backup and then a series of incremental backups with each increment including only the files that are new or changed since the last increment. This pattern minimises the time taken for each increment but has some drawbacks for restoring private files (because all the increments are required for restores).

• The second pattern involves taking one base backup and then a series of incremental backups with each increment including only the files that are new or changed since the base backup. In this pattern, the time taken for an incremental backup is not minimised and may approach the time taken for a base backup but a restore operation only requires the base and a single increment.

The choice of which pattern to use will be made by the PC software - not by the phone software.

Note: An incremental backup cannot be created purely based on a date and time stamp. If a new file is added with an old time-stamp, a time-based increment would omit it. Therefore, any incremental backup requires a list of the files included in the preceding backup.

By default, a backup (whether base or incremental) aims to include all files on a specified drive. In practice, the user may only care about data belonging to one or more specific applications. By omitting other data files the time taken for the backup (or restore) is reduced. It can be seen that the choice between full and partial backups is orthogonal to the choice between base and incremental backups.

Versions of Symbian OS prior to v9 do not support partial backup or restore well. This is because all files are public and Symbian OS provides no means of associating specific files with specific applications. Some phone manufacturers have provided (at least partial) solutions to this problem but the extension of these categories to third-party software is problematical. Similarly, some PC suites have provided partial restore but the association of files with applications is problematical.

Because Platform Security requires a process (application or server - basically a private data owner) to specify the private files to be backed up, there is a close association of private files with specific applications. In addition, it is possible to associate public files with specific applications. However, there is no guarantee that more than one data owner will not lay claim to any public file and there is no guarantee that all public files will be associated with a data owner.

An additional possible benefit of partial backup and restore is that a data owner may be able to participate in backup or restore without requiring all file locks to be freed. For example, if a data owner only deals with its own private files, it may be possible to back up its data in isolation. This would allow backups to have less impact on the user.

On Platform Security-enabled Symbian OS phones, installed applications are no longer backed up by default as was the case on earlier releases of Symbian OS. The backup and restore of installed applications is now requested via a tag in the backup registration file – more details can be found in System (installed application) data to be backed up.

Processes are made aware that a backup or restore is taking place via the publish-and-subscribe (P&S) API. The P&S server maintains a list of subscribers expressing an interest in the backup and restore status flag. Any published changes to this flag by the backup and restore engine result 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 category and key values should be used (these are defined in epoc32\include\connect\sbdefs.h):

Category: KUidSystemCategoryValue

Key: KUidBackupRestoreKey

The following code fragment demonstrates this:

#include <e32property.h> 

RProperty iProperty;

iProperty.Attach(KUidSystemCategory, KUidBackupRestoreKey);
CActiveScheduler::Add(this);
iStatus = KRequestPending;
iProperty.Subscribe(iStatus);
SetActive();

// In RunL, to get the state: TInt
backupStateValue = 0;
iProperty.Get(backupStateValue); 
     

Prior to P&S being used to make applications backup-aware, the Base backup server was used. However, this is now only used to manage GUI applications during backup or restore, and is being deprecated in a future OS release; so you should use P&S. When a backup or restore takes place, a signal is passed from a backup client on the PC or phone and a number of special servers take action. The Base backup server maintains a list of servers that have registered an interest in backup and restore and invokes observers to take appropriate action. When a backup or restore is complete, the Base backup server informs its observers that normal service has been resumed.

The behaviour for GUI applications is deliberately straightforward: by default, all GUI applications are politely terminated when a backup or restore operation takes place. As a result of most applications exiting, many system servers release file locks. This technique avoids GUI application developers having to implement backup- and restore- aware code in most cases; the relevant server and exit code is implemented within the Uikon subsystem.

At its simplest, a GUI application can take no specific backup or restore action. If a GUI application does not have the ‘system’ status it will be terminated when file locks are required and will be re-started after the backup or restore. The terminate-restart behaviour will ensure that direct and (most) indirect file locks will be freed. A potential optimization for a GUI application is to store the current view and state when terminated and to adopt the same view when it restarts (this choice may be required or deprecated as part of UI design guidelines outside the scope of this document). This will make for a seamless restart after a backup, i.e. the application will appear the same to the user, as if it had not terminated and restarted.

The UIKON backup server terminates most running GUI applications (all GUI applications that are not registered as system applications). When a backup or restore is complete, the UIKON backup server restarts the GUI applications that were terminated. A GUI application that must not be terminated during a backup or restore, a ‘system’ GUI application, must behave in the same way as a server (see below) and manage its own file locks directly. Only phone manufacturers should develop such applications because of the possible side effects, the default behaviour should be to accept termination.

Some servers access files only as a result of calls from clients. As long as these servers only have well-behaved clients they need take no special action. Their clients will either terminate (if they are GUI applications) or will drop connections (if they are well-behaved servers or system applications) so the server will then drop locks on files.

However, the developer should be aware of the sequence of actions during a backup or restore as some behaviours, which might appear to be performance optimizations, could prevent a successful backup:

• If a server kept a file open after all attached clients had closed that file (for example, to improve performance in case a client was likely require it again), the backup and restore would be blocked.

• If a server kept cached data, in case the same file was re-opened, a restore operation could be corrupted.

If such optimizations are required, the server must become backup-aware and drop file locks promptly and flush data caches on backup and restore.

Servers (and other applications) that do not terminate during a backup or restore operation and do not drop file locks because of their clients’ behaviour need to become backup-aware in their own right.

If a process is not liable to external events during backup and restore, it simply needs to react to backup and restore events and release file locks. However, if a process can receive external events during a backup or restore (such as a telephone call, an incoming message or an external request for some action) ,the process needs to ensure that the event does not interfere with any files during the backup or restore. Examples of possible interference include:

• Writing to call log files when a telephone call is received;

• Storing an incoming message in the messaging store;

• Applying an incoming configuration message.

How the process handles the event is up to the process developers but some possibilities include:

• Ignoring incoming events (only acceptable if they will be automatically re-sent later);

• Caching incoming events in memory or in a safe private file and then applying them after the backup or restore operation.

The reboot after restore flag is currently ignored, because the Symbian OS does not provide a standard way to ensure that the phone reboots. Consequently, applications should be written so that they do not require a reboot. The functionality will be enabled when Symbian OS supports a standard reboot mechanism; and the reboot after restore flag will be made available to clients using the backup architecture, allowing phone manufacturer-specific reboot mechanisms to be used.

If you are responsible for an application, server or some other component that accesses public files or which owns private data files, you need to answer the following questions to make your process participate in backup and restore:

• Should any of your private data be backed up and - if so - how much of it?

• Should you use active or passive backup on your private data?

• Depending on your answers to the two previous questions - and whether it is a GUI application - how should your process respond to backup and restore events?

Note: For Java MIDlets, the backup registration file is created by the SystemAMS component because of Java’s method for data caging them.

If you are the developer responsible for creating or maintaining a process that owns private data, you will have to decide whether it should take part in the backup of private data. In general, as much private data as possible should be backed up (to help the user) but certain data should not be backed up:

• If the private data must not be exposed to the user, it should not be backed up. Assume that all data backed up can be read and potentially altered by the user. This might change if a phone manufacturer implements encryption which does not rely on keys provided by the user but that is a phone manufacturer-specific decision and cannot be guaranteed.

• If the process cannot keep the private data stable during a backup or restore, they cannot safely back it up. This is a poor reason for not backing up data but may be a practical one. It depends on the sources of external events and whether they can be delayed or placed in a temporary location.

• If the private data can be easily recreated by other means, it may be excluded. This may not be a good criteria, but if a process would find it difficult to back up private data (perhaps for the reasons above) and the data could easily be created (for example by receiving configuration messages), choosing not to back it up may be more acceptable.

In addition, consider the implications on other processes of backing up the data or not. If your data must remain consistent with that in public files, the private data must be backed up. If your data must remain consistent with that owned by another process, either both or neither should back up data.

As described above, passive backup and restore of private data is simpler than active backup. It also takes less system resources because processes taking part in active backup must be running during a backup or restore. However, active backup allows the data-owning process more control over the data and this can have both security and performance gains.

The choice between passive and active backup may not be a black-and-white one - it may involve weighing up a number of factors. The following list includes a range of advantages and disadvantages and you need to consider all of these and make a decision.

• The registration for passive data backup only specifies whole files or directories. It is not possible to backup only part of a file using passive backup. If you need to backup only part of a file you need to either split the file into two or use active backup.

• The backup registration file that defines the files and directories to be subject to passive backup is created at system build time (for a system process) or at installation time (for an installed application). The backup registration files cannot be modified or created at runtime. If your process will create new directories after installation, the backup registration file cannot be extended for these. If you want these backed up, you need to either put them under a common directory which all gets backed up or use active backup and make a run-time decision on what to backup. This aspect may be partially or wholly addressed by installing additional backup registration files.

• Backed up data is compressed en-route to speed up data transfer (this can be disabled). However, if your private data has a specific format and you can manage to backup only a fraction of it you may be able to make the backup of your data more efficient by implementing active backup.

• Backups can be base backups or incremental backups. With passive backup (as with the backing up of public files) incremental backups include all relevant files which have changed or are new since the last backup took place. If a file contains record-based data (such as a database), the addition or changing of one record will cause the whole file to require backup. If you implement active backup, you could only backup the changed or new records (plus recording deleted records in some way). This could increase the performance of backup and restore for your data.

• Active backup requires your process to be started during a backup or restore operation. Your process will be started automatically as required by the secure backup engine if not already running. If your process normally runs at all times, this imposes no additional burden on the phone. However, if your process is not normally running, it will require additional resources during a backup or restore and you should consider if the benefits of active backup justify the additional burden.

A hybrid approach may be useful. Here the secure backup engine allows a data owner to register as both an active backup client and a passive backup client. This was originally intended to allow a data owner to back up some data in each way but an alternative use is for the active backup client to prepare data for backup and then let the secure backup engine handle the actual transfer as a passive backup. The active backup client does not need to actually provide any data.

In order to support this, the secure backup engine should not retrieve data for passive backup until an active backup client has signalled that the data is ready (this set-up is configurable in the backup registration file). That is, if a data owner is registered to take part in both passive and active backup, the PC host or other client is expected to request active backup data before passive backup data.

When a restore operation is carried out, the data will be restored as passive data and the data owner is responsible for dealing with it when the restore operation is complete. In order to support this, the PC host or other client is expected to restore passively backed up data before actively backed up data if a data owner has registered for both active and passive backup and restore.

The active backup client API class declarations are in the file epoc32\include\connect\abclient.h, which requires epoc32\include\connect\sbdefs.h.

Processes that own private data that needs to be actively backed up, will have to register with the backup engine as an owner of private data for active backup.

If an application is designed for separate installation (as opposed to upgrade), it will need to copy a backup registration file into the private directory during installation. (If an application is part of the platform, this involves creating a backup registration file as part of the build and ensuring that it is located in the relevant private directory.)

In addition, the process must subscribe to the backup status flag described in Making Applications Backup-aware in order to detect when a backup or restore takes place. Processes which own private data that needs to be actively backed up will be started up if required by the secure backup engine in order to do the backup or restore. Therefore, they must check the backup flag on startup rather than making a normal startup (which may involve undesirable access to other servers and files).

Behaviour required of a process that takes part in active backup of private data:

1. When the backup status flag gets set to ‘backup in progress’ any data that has not yet been saved may need to be saved.

2. The process has to release locks on all public data files that require to be backed up (files that are excluded from backup can be kept locked but assume that all public files will be backed up) so they can be copied off and stop modify private data files. This may require that the process ‘freezes’ all sessions to external processes to avoid external events that would cause files to be written to (whether requests are blocked or errors returned depends on the context).

3. The process tries to make a connection to the secure backup engine by name.

4. At the start of backing up private files, the process must ask the secure backup engine whether it is a base backup or an incremental backup using the active client APIs described in Choosing active or passive backup and, if it is an incremental backup, the process must wait until the file snapshot to use for the increment is provided.

5. The process sends its private data as a stream using the active client APIs described in Choosing active or passive backup. The owning process is responsible for taking its data files (all or whichever subset it wants to back up) and streaming them. Reference code will be provided to take all files in a private directory and stream them. Any other behaviour will have to be implemented by the data owners.

   If the backup is a base backup, all the data in the relevant files should be provided.

   If it is an incremental backup, it should only stream data corresponding to the changes since the snapshot. The data-owning process has a choice of how sophisticated its behaviour is in this regard. The simplest behaviour is to always do a base backup (this will be an option, even when an incremental backup has been requested). An alternative is to provide backups of files that have changed since the last backup. The final option is to provide only that data that has changed since the last backup. Which choice is made will depend on the nature of the data to be backed up.

   Note that an application may have been installed after the base backup so a process must handle this (no snapshot will be provided).

   The data-owning process is responsible for providing a snapshot of files that can be used as a baseline for subsequent incremental backups.

6. The private data being sent may not be received all at once (multiple processes may be trying to supply data at the same time) and may not be received at all (if the backup is partial or has been broken off).

7. When the backup flag reverts to normal, files can be re-accessed and clients responded to. The process must handle the case where the backup data has only been partially received or has not been received at all.

Behaviour required of a process that responds to an active restore of private data:

1. When the backup status flag gets set to ‘restore in progress’ the process has to release locks on all public data files that require to be restored (files that are excluded from restore can be kept locked) so they can be overwritten. This may require that the process ‘freezes’ all sessions to external processes to avoid external events that would cause files to be read or written to (whether requests are blocked or errors returned depends on the context).

2. The process tries to make a connection to the secure backup engine by name.

3. The process receives its private data as a stream using the active client APIs described in Choosing active or passive backup. The owning process is responsible for receiving the data as previously provided and recreating the relevant files. Reference code will be provided to take a stream and create files in a private directory. Any other behaviour will have to be implemented by the data owners.

The first chunk of data received will be a base backup of (potentially) multiple files.

If incremental backups have been carried out the base backup data will be followed by a sequence of increments. They will be supplied in the correct (i.e. chronological) order. The receiving process is responsible for amending the data accordingly. If the process can only provide full backups, it will not receive increments.

1. The private data being restored may not be received immediately (multiple processes may be trying to receive data at the same time) and may not be received at all (if the restore is partial or has been broken off).

2. When the backup flag reverts to normal, files can be re-accessed and clients responded to. The process must handle the case where the restore data has only been partially received or has not been received at all. Any cached data must be flushed after a restore.

Processes that own private data that needs to be passively backed up will have to register the fact with the backup engine.

If an application is designed for separate installation (as opposed to upgrade) it will need to copy a backup registration file into the private directory during installation. If an application is part of the platform, this involves creating a backup registration file as part of the build and ensuring that it is located in the relevant private directory. See Backup Registration Files.

In addition, the process must subscribe to the backup status flag described in Making Applications Backup-aware to be able to detect when a backup or restore takes place.

During the backup or restore, the process can exit or release locks on all public and private data files. If the process is a GUI app, the default behaviour will be for it to be terminated politely so no extra code is required.

A process that accesses public data, but which does not wish to have private data backed up, does not have to register for backup and restore but it does have to respond to the backup status flag:

• If your process is a UI application which can exit during backup and restore, you need do nothing – you will be terminated politely as before. Note that this means that the default behaviour is for private data of applications not to be backed up. The application needs to make a positive decision to get private data backed up. This ‘opt-in’ behaviour is a deliberate choice for security reasons – applications cannot find their private data backed up without their knowledge.

• If your process is a non-UI application, or a UI application which will not terminate during backup and restore, and accesses public data, you will need to subscribe to the backup status flag. It must check it on start-up and, if it is set, enter the correct state (this should never happen because the process should not be started during a backup or restore. If it does, however, it should behave robustly just in case). If the process starts during a backup or restore, it should wait until it is complete before attempting to access any public data files.

  • When the backup status flag goes to ‘backup in progress’ your process must release all locks or at least make all public data files readable. This may require that the process ‘freeze’ all sessions to external processes to avoid external events that would cause files to be written to (whether requests are blocked or errors returned depends on the context). When the backup flag reverts to normal, sessions can be re-activated and files re-accessed.

  • When the backup status flag goes to ‘restore in progress’ your process must change to a state where public files can be overwritten. This will involve releasing all public data files accessed and ensuring that external events cannot cause an attempt to re-access any files. When the restore is complete your process must re-load data files and refresh any data stored in cache.

Data owners can have data stored within another data owner’s data cage, such as with the central repository. In this scenario, data from each data cage must be backed up. The data owner holding data on behalf of another data owner is known as a proxy. From the PC’s point of view, this data belongs to the data owner, but internally the data is being requested from the proxy via the active client interface. A data owner requiring data from one of these proxies must specify the proxy in the element <proxy_data_manager /> using its secure ID. See the example in Example backup registration files.

Note: During a backup or restore operation, the data owner will behave as an active data owner as far as the PC is concerned, although this requires no special action on behalf of the data owner itself.

Data stored in the central repository (CentRep) will be backed up if the proxy data manager tag is selected in the backup registration file specifying the central repository’s secure ID. Not all data may be backed up. Each value in CentRep has some metadata associated with it and one bit of the metadata is a backup flag. The value will be backed up only if the backup flag bit is set. It is the responsibility of the data owner to specify the correct settings within the repository initialization file.

CentRep backups are always base, as opposed to incremental, because the CentRep does not contain sufficient information to efficiently support incremental backups and because CentRep data is not expected to be sufficiently large to justify incremental backup.

A data owner may be responsible for a number of databases that may need to be subject to back up and restore. Shared databases will be backed up if the policy number is specified in the data owners backup registration file using the <dbms_backup> tag. There is no need to specify database names as the DBMS will provide the list of the databases belonging to the data owner based on the policy identifier. See the example in Example backup registration files.

On Platform Security-enabled Symbian OS phones, installed applications are no longer backed up by default and now require the consent of the application designer. The backup and restore of an application’s binaries and its data is also done separately and requested differently. For an application's data see Choosing active or passive backup, and subsequent sections. For binaries the <system_backup/> tag should be specified in the backup registration file. See Backup Registration Files for more details.

The <system_backup/> tag triggers the secure backup engine to query which package the application belongs to and retrieves a list of all the files referenced by the package. Only the following read-only files will be backed up as system data (any file or directory not listed below will need to be backed up separately using one of the other mechanisms described previously):

• \sys\bin\*

• \resource\*

• \private\123456\backup_registration*.xml

Writeable files will not be backed up as system data as they will fail to be restored as system data.

Note: It is essential to add the backup registration file(s) to the package. If forgotten, nothing will be backed up or restored.

An additional mechanism exists to specify backup registration files for data owners that do not have private directories - this is to be used for DLLs which are installed as part of a package. To use this method, the backup registration file must be placed in a special location under the Secure Backup Engine’s private directory:

\private\10202D56\import\packages\<package-id>\backup_registration.xml

(10202D56 is the SID of the Secure Backup Engine, and <package-id> should be replaced with the ID of the package containing the DLL)

Note: As the data owner does not have a private directory, the only methods that are valid in this backup registration file are system and public file backup.

Backup registration files are stored in the root of the private directory of the corresponding process. They have the standard name: backup_registration.xml. By placing the backup registration files in the private data areas they are protected on the phone.

When a specific drive is backed up, the backup registration file is searched for on the drive being backed up. If no backup registration file is found, the corresponding private directory of the Z: drive is searched. This is purely an administrative convenience to avoid processes having to copy backup registration files when it would not otherwise be necessary. If a backup registration file is found in the drive to be backed up, the Z: drive will not be searched – this allows the backup registration file on the Z: drive to be masked where necessary. One implication of this use of backup registration files from the Z: drive is that the backup registration file may refer to files (including private data files, public data files, databases, repositories and system files) that may not exist on a drive to be backed up. This is handled robustly by the backup process.

A backup registration file contains the following information:

• For passive data backups, a list of private directories and files that should be backed up. It is possible to list a directory for backup and then list sub-directories or files for exclusion. These directories and files are defined relative to the process private area so it is not possible to refer to private files owned by another process (a value of a single backslash denotes the whole of the private directory). If any files or directories do not exist, no error will be raised – i.e. it is acceptable to list directories which do not exist yet. If a data owner’s data is such that incremental data will be inefficient, it is possible to specify that only base backups should be done (for example, if a data owner stores all of its data in one database file, any increment will be the whole database file; and it is more efficient to always do a base backup, otherwise a restore will involve transferring large amounts of redundant data).

• A list of public files and directories to be backed up as part of a partial backup. The same syntax is used as for private files but with regard to the public part of the filing system. Any system files or private files will be ignored from this section (because they are not public files). As with files listed for passive backup, directories can be listed that do not yet exist.

• For processes that require backup of system files (executables and resource files), a statement of the fact – it is not necessary to list the system files to be backed up as the list is available from package data. Note that a package containing multiple data owners should have all its data owners backed up – if any of its data owners specify that system files are to be backed up, all the system files for the package will be backed up and restored as a unit.

• For passive backup and partial backup of public files, should directories be cleared before a restore operation? I.e. should extra files be deleted?

• Is active backup required? If so which process should be started or which server contacted. It is possible to invoke active backup and also request private and/or public files to be backed up. There is no guaranteed order of backup or restore (i.e. there is no guarantee of which data owner’s data will be restored first) between SIDs although it is guaranteed that active data will be requested before passive on backup and active supplied before passive on restore.

• Can this private data be backed up or restored selectively for a partial backup or restore? This is not necessarily only possible for a process that implements active backup (but a passive data owner will need to not keep files locked). This option is intended for the future where it may be possible to avoid terminating most processes during a backup or restore. At present it can be ignored as partial backup or restore will be achieved by using the normal backup or restore mode but only transferring data belonging to selected data owners.

• Does this process require a reboot after a restore operation?

• Is a shared database to be passively backed up? If so, the security policy ID of the database to be backed up or restored must be specified.

• Does the data owner have data stored in a proxy? If so, the secure ID of the proxy must be specified in the proxy data manager tag.

• Does this process require a significant time to prepare for backup or restore?

The following is an example of a backup registration file for a data owner that requires only passive backup of files in a sub-directory named ‘preserve’:

<?xml version="1.0" standalone="yes"?> 
<backup_registration> 
        <passive_backup> 
        <include_directory name = "preserve"/> 
        </passive_backup> 
        <restore requires_reboot = "no"/> 
</backup_registration>

The following is an example of a backup registration file for a data owner that requires passive backup of all its files and also wants its system files to be backed up:

<?xml version="1.0" standalone="yes"?> 
<backup_registration> 
        <passive_backup> 
        <include_directory name = "\" /> 
        </passive_backup> 
        <system_backup/> 
        <restore requires_reboot = "no"/> 
</backup_registration>

The following is an example of a backup registration file for a data owner that has only central repository data:

<?xml version="1.0" standalone="yes"?> 
<backup_registration> 
        <proxy_data_manager SID="0x10202BE9" /> 
</backup_registration>

The following is an example of backup registration file for an data owner that requires an active backup only:

<?xml version="1.0" encoding="UTF-16" standalone="yes" ?> 
<backup_registration version="1.0"> 
        <active_backup process_name="processname.exe"
         requires_delay_to_prepare_data="yes" 
         active_type="activeonly" /> 
</backup_registration>

The following is an example of backup registration file for data owner which implements a proxy:

<?xml version="1.0" encoding="UTF-16" standalone="yes" ?> 
<backup_registration version="1.0"> 
        <active_backup process_name="processname.exe" 
         active_type="proxyonly" /> 
</backup_registration>

The following is an example of backup registration file for a data owner who wishes to back up its DBMS databases:

<?xml version="1.0" standalone="yes" ?> 
<backup_registration> 
        <dbms_backup policy="AABBCCDD" /> 
</backup_registration>

The backup registration file format allows the specification of directories for private data rather than having to specify all files individually. This means that some types of expansion (e.g., extra files or directories under a specified directory for private or public files) can be handled without changing backup registration files. However, the same technique may not handle additional system files (such as additional plug-in executables).

Therefore, additional backup registration files can be present and will be parsed. Additional backup registration files must have a name of the form backup_registration*.xml and be located in the root of the relevant private directory. Additional backup registration files can be distinguished from the principal backup registration file by the file names (the principal backup registration file has the name backup_registration.xml).

Additional backup registration files must only contain a subset of the normal backup registration file elements. They are intended to be purely additive of passive private, public and system files. They may not include an additional type of backup (i.e. they may not specify active backup or restore if it was not included in the principal backup registration file).

The effect of additional backup registration files is the same as if the passive backup, public and system file elements were included in the principal backup registration file.

All drives will be searched for additional backup registration files including the Z: drive. Additional backup registration files are always used in a backup and can not be masked.

Please note that additional backup registration files cannot be created or modified at runtime.

The behaviour of any software should be tested and the behaviour of software with respect to backup and restore is no exception. Symbian tests the secure backup engine and the associated framework as part of testing Symbian OS and developers are responsible for testing their own components.

If a process is implementing active backup and restore, these should be tested. As a minimum, a simple sequence of base and incremental backups followed by a restore to a clean device, followed by smoke tests will demonstrate that the main functions of backup and restore work. Robustness tests should involve interrupting a backup or restore operation by disconnecting the phone from the PC and checking that the data owning process handles the interruption without corruption.

The developers of a component, subsystem or other set of software are responsible for testing to ensure that their private data is backed up and restored correctly. Here are some suggested tests for inclusion in a test plan. First, run the software under test and create some data; then:

• Back it up to a PC; reformat the phone or obtain a new device; and restore the data from the PC. Then run smoke tests to ensure that all the expected data is present.

• Back it up to a PC, and then run the software again to edit the data or create more data. Restore the data from the PC (without reformatting the phone); then run smoke tests to ensure that the data present is that which was backed up - not the later data - and is consistent.

• Run the software under test and create some data.

  Run a backup while the software is running to test that the software makes data available and does not interfere with the backup. If possible, run the software during the backup and attempt to create or edit data. This should not interfere with the backup. Run the same tests during a restore operation to test that the software does not interfere with the restore. Pay particular attention to what happens to data entered or edited during a backup or restore operation – is it lost or retained?

More thorough tests should include verifying the active restore client’s handling of unexpected data versions, handling of out-of-sequence increments during restore and handling of incomplete or corrupt restore data but these will require specialized test software to be developed as the Symbian OS backup and restore framework tries to prevent these problems.

After a restore, it is essential that the accuracy and completeness of the restored data is verified. This applies to passive backup data owners as much as active backup data owners. The Symbian OS backup and restore framework can only back up and restore the data that is specified or provided. If certain private files or directories are omitted, the Symbian OS backup framework will function correctly but the restored data will not be as expected.

The DTD for the backup registration file is as follows:

<?xml version=”1.0” standalone=”yes”?> 
<!DOCTYPE backup_registration [ 
     <!ELEMENT backup_registration  
       (passive_backup?, system_backup?, public_backup?, active_backup?, 
       cenrep_backup*, proxy_data_manager*, dbms_backup*, restore?) > 
       <!ATTLIST backup_registration version CDATA #FIXED "1.0" > 
     <!-- Include file or directory name should include path relative to private directory 
          for private data. To include all private data use “\”. 
          Include file or directory name should include path relative to root of drive
       for public data. This may or may not include the drive letter. Inclusions with 
          drive letter will be excluded from backups of other drives. Inclusions without 
          drive letter will be assumed to apply to all drives. 
  --> 
     <!ELEMENT include_file EMPTY > 
       <!ATTLIST include_file name CDATA #REQUIRED > 
     <!-- Exclude file or directory name should be of the same form as the owning 
          <include_directory> and is not treated as relative to the <include_directory> 
     --> 
     <!ELEMENT exclude EMPTY > 
       <!ATTLIST exclude  name CDATA #REQUIRED > 
     <!ELEMENT include_directory (exclude*) > 
       <!ATTLIST include_directory  name CDATA #REQUIRED > 
     <!ELEMENT passive_backup (include_directory|include_file)* > 
       <!ATTLIST passive_backup  
         supports_selective (yes|no) "no" 
         delete_before_restore (yes|no) "no" 
         base_backup_only (yes|no) "no"   > 
     <!ELEMENT public_backup (include_directory|include_file)* > 
       <!ATTLIST public_backup  delete_before_restore (yes|no) "no" > 
     <!-- If the <system_backup> element is present then all executables 
          and resource files that were included in SIS files will be backed up. 
          The set of files does not need to be specified as it can be found from 
          package data. They can only be restored after checking against signed hashes. 
     --> 
     <!ELEMENT system_backup > 
     <!-- <proxy_data_manager> indicates that the data owner represented by this backup registration file has data that is accessed through a proxy which is itself an active data owner. 
     --> 
     <!ELEMENT proxy_data_manager EMPTY > 
       <!ATTLIST proxy_data_manager SID CDATA #REQUIRED > 
     <!ELEMENT dbms_backup EMPTY > 
       <!ATTLIST dbms_backup policy CDATA #REQUIRED > 
     <!ELEMENT active_backup EMPTY > 
       <!ATTLIST active_backup 
         process_name CDATA #REQUIRED 
         requires_delay_to_prepare_data (yes|no) "no" 
         supports_selective (yes|no) "no" 
         supports_incremental (yes|no) "yes" 
         active_type (activeonly|activeandproxy|proxyonly) “activeonly” > 
     <!ELEMENT restore EMPTY > 
       <!ATTLIST restore  requires_reboot (yes|no) "no" >
]>