MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Selecting the resource application class

The MeeGo 1.2 Harmattan platform uses a concept called Resource Policy Framework to handle the different roles and modes that a modern smartphone is used in. It functions by allowing the developer to assign applications in different categories, for which the device determines sufficient permissions and behaviours.

For example, when running an application that is identified as belonging to the camera group, an incoming SMS does not trigger the vibration function. The vibration can distract users who are currently recording video or taking pictures.

Note: Applications rarely have to take Resource Policies into account. Such resource-unaware applications are classified into the media player class or group by default, which is suitable for most applications. An example of the design considerations taken into account when designing a policy-aware application can be seen in the Using Resource Policy to enhance games section below.

Resource Policy Framework components

There are four levels in the Resource Policy Framework:

  • Device modes define the general role of the application. An application can only belong to one device mode.
  • Resources are used to coordinate access and synchronization of the device resources and features, such as audio playback capability or backlight. These are grouped into resource classes.
  • Media groups define the resource classes for audio and video handling purposes.
  • Control groups define the priority and memory allowance properties of an application.

For a list of supported device mode, resource class, media group and control group attributes, see MeeGo Policy Framework Developer Guide (pdf).

Using the Resource Policy Framework

To to make an application you are designing policy-aware:

  • Identify the role or class your application belongs to.
  • Manage the resources your application may require.

The above tasks are done with the Qt Resource Management APIs of the Policy Framework in runtime. Additionally, you can add policy configuration files for individual applications. In cases where application roles not are explicitly set, the application is assigned to the default group, media player.

On runtime, resources are used by first creating a new ResourceSet object and then adding further resources to it with the addResource() function. The following snippet creates a new resource set based on the player resource class and reserves audio and video playback capabilities for the application:

ResourcePolicy::ResourceSet *resources = new ResourcePolicy::ResourceSet("player");

For more information, see the Resource Policy API.

The complete workflow to making applications policy-aware goes as follows:

  • Identify the resources your application needs.
  • Define the resource sets to be used (using APIs).
  • Define resources as mandatory or optional (using APIs).
  • Determine resource class for the resource sets (using APIs).
  • Specify operational mode for the resource sets (using APIs).
  • Specify media groups for your application's media objects:
    • If your application handles audio: tag audio streams and link the stream to the appropriate audio group either by providing an audio configuration file (and post-install script), or using the resource management API to provide the process ID (PID) of the process that plays back the stream, if the process is not the same as the one requesting the resource. The stream name needs to be set to match the tagged audio stream.
    • If your application handles video: include all necessary video resources in the same resource set (using APIs).
  • Declare which control group your application belongs to by providing a control group configuration file.

For a more detailed description of the Resource Policy Framework, a list of supported device mode, resource class, media group and control group attributes, and examples on using configuration files, see MeeGo Policy Framework Developer Guide.

Using Resource Policy to enhance games

The first question is, do you want to enable your game to run together with several other applications, or games in the background?

Here is a quick check list:

  • Do you want your game volume to be controlled along with device volume (using the volume hardware buttons)?
  • Do you want to use the XV port, and get signaled when the XV port needs to be closed because another application needs it?
  • Do you want your game audio not to be muted when an incoming notification sound is played?

If your answer is YES to any of the questions above, follow the instructions in the sections below.

Classifying a game with Policy

For the Resource Policy Framework to detect that your application is actually a game, you need to package a small dynamic configuration file on your game's Debian package.

The file is added to the directory /usr/share/policy/etc/syspart.conf.d.

Use the game binary name as the configuration file name. For example, if your game's binary is /usr/bin/games/myexcellentgame, then you must package the configuration file to /usr/share/policy/etc/syspart.conf.d/myexcellentgame.conf with the following content:

[classify gaming]

This classifies your binary to the gaming class. This makes the game the topmost running application. Also, the volume control for the game works by default, unless there are some other applications producing sound. This means that if you, for example, receive an SMS, the volume control for the game does not work while the SMS tone is being played, but it resumes after the tone playback. Make sure that you use the correct path, otherwise the classification rule does not match and apply to your game.

Using resources

By making your game policy-aware has the following benefits:

  • Before using an audio or video resource, your game application is signaled if the resource is available.
  • Your game application is signaled if some other application is going to use the resources used by your application.

Making your application policy-aware basically means that you need to use one of the Resource Policy Framework libraries: The Meego Resource Policy Qt API: libresourceqt or libresource C/Glib API (see the libresourceqt library in the Platform API reference).

The basic Policy usage for a game is that it uses AudioPlayback and VideoPlayback resources and subscribes to the needed signals to get notified when some other application preempts you. First the application acquires the necessary resources, and when the application stops using them, it releases the resources.

For further information, see the MeeGo 1.2 Harmattan API Reference Library.