Data storage

On the MeeGo 1.2 Harmattan platform, different types of applications need to store various types of data, ranging from a few simple settings or saved states to large databases or files (such as images). Common examples of stored data are:

settings (which may or may not be handled through a settings-applet)

data generated by the application (such as high scores of a game)

data generated by the user (such as images that need to be preserved across device updates)

cached data (that may be useful later on, but can always be retrieved again from the source or otherwise regenerated)

3rd party application's data. System databases, such as e-mail and calendar

/home/user/MyDocs

VFAT

58

User data, such as images, videos, music, documents

The /home/user/MyDocs partition is of type VFAT for easy access as mass-storage through USB. Other partitions are not accessible in that way.

The root file system (rootfs) directories are based on the Filesystem Hierarchy Standard, version 2.3, which defines standard Linux conventions for storing various file types. Harmattan follows these conventions without any significant exceptions.

On the Harmattan platform, applications are packaged according to the Debian Policy with some Harmattan platform-specific extensions. Binaries and other files (except for some exceptions) needed for running an application must be stored under the /opt/<package_name> subdirectory, where <package_name> corresponds to the application's main package.

Data storage interfaces

Harmattan platform provides you with various APIs for storing application settings and state information and storing data into databases.

Settings

For storing application settings and state information, the Harmattan platform provides you with:

Use this API if you use the declarative applet API to create a settings page for your application.

When you use the QSettings class, the applications settings are stored in .conf files under the directory $XDG_CONFIG_HOME. If XDG_CONFIG_HOME is not set, use $HOME/.config/<application_name> . Note, however, the limitation mentioned in Backup and restore.

If you use the declarative applet API of libduicontrolpanel (see Storing and managing application settings, the settings edited by the user are automatically stored in GConf. In that case you can also use GConf for other, non-user editable settings, such as application state information. GConf key/value pairs can be easily read and also written using the libgq-gconf API. The additional benefit of using GConf is that the data stored there is included in the system backup by default, see Using Backup Framework. For more information on MeeGo Touch declarative syntax, see libduicontrolpanel in the Platform API reference.

Databases

For storing data into databases, the Harmattan platform provides you with:

SQLite relational database, which is a light-weight SQL library for in-process databases.

To use this database, use one of the following:

QtSql, which contains classes for working with relational databases using the SQL query language.

Offline Storage API (provided by Qt Quick), which allows QML applications to access local offline storage in an SQL database.

To use this database, use QtSparql which contains classes for working with RDF using the SPARQL query language.

You can also store your data in other formats directly on the native file system.

Note: When an application is removed from the system, it needs to delete the data stored in the databases.

Data storage locations

If you are storing data directly as files in the file system, you need to carefully design where to put the data. If you use the services like GConf through the standard APIs described above, the storage location is handled by the system and you do not need to worry about it.

Use XDG Base Directory Specification to avoid dependence on particular storage locations. When you follow the XDG Base Directory Specification, the locations for storing data can be changed later on (if needed) without affecting the applications' code.

In most cases, you need to ask the location for different types of data with the QDesktopServices API.

To access the settings defined for Harmattan ($XDG_ variables):

Use class QDesktopServices, such as the QDesktopServices::storageLocation() method.

To query the location for storing permanent data:

Use the storageLocation() function with the QDesktopServices::DataLocation parameter.

To query the location for storing temporary data:

Use the storageLocation() function with the QDesktopServices::CacheLocation parameter.

Note: Applications must not use the parameter, QDesktopServices::HomeLocation, because storage there is not allowed.

Note: Since partition /home/user is not very large, there is a risk that it fills up if applications indiscriminately store large amounts of data there. This also applies to the use of the Tracker itself since the Tracker's database is also stored on that partition. The best way for applications to deal with this is to use QDesktopServices consistently, as described above.

Backup and restore

The Harmattan Backup Framework is responsible for backing up and restoring system, user and application data on request by the user. It automatically backs up anything stored in the Tracker (that is, data stored by QtSparql) and GConf databases. Any other data and files are excluded by default. Currently, there are no Qt-style C++ interfaces for configuring the backup functionality for data stored in other locations.

To include data in the backup, do either of the following:

If feasible, store all data and settings in Tracker and in GConf databases.