Updated Feb 12, 2009 by gaizin
Labels:	documentation, usage, howto

Documentation

Documentation for the Backgrounder extension.

Introduction

Backgrounder is a Mobile Substrate-based extension to iPhone/iPod Touch's SpringBoard application launcher that allows applications to run in the background (applications are normally terminated upon suspension).

Warning & Limitations

Applications are not designed to be run in the background (as Apple does not permit it). Thus some applications may not behave correctly when placed in the background. Unfortunately, this is something that Backgrounder cannot resolve; the application itself would need to be modified. Please keep this in mind.

Also note that applications may use the suspend/resume methods to perform important tasks, such as saving preferences. If the application is not properly terminated, these tasks may never be run. For such applications, if your phone crashes or if you force power-off (by holding the power and menu/home buttons), your settings/information for that application will not be saved. Always make sure to properly shutdown such applications (by disabling backgrounding when the application is no longer needed).

While this extension should work for all applications, it is recommended to use it only for background-enabling AppStore applications (which, again, are not allowed to include backgrounding code). If you wish to run a non-AppStore 3rd-party application in the background, it is suggested that you contact the author of the application and request that proper background support be added.

Usage

Enable backgrounding for an application

Backgrounding can be enabled via one of two methods:

Per-instance

To enable backgrounding for the currently-running instance of an application, press and hold the menu/home button until a message pops-up stating "Backgrounding Enabled".

Note that only the current instance will be affected; if the application is terminated and relaunched, the new instance will not have backgrounding enabled.

By default

To specify that certain applications should have backgrounding enabled by default, create the following preferences file:

/var/mobile/Library/Preferences/jp.ashikase.backgrounder.plist

... with the following format, where the

<string>

values represent the bundle identifiers of the applications that are to be enabled:

<?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>enabled_apps</key>
    <array>
      <string>com.apple.weather</string>
      <string>com.apple.calculator</string>
    </array>
  </dict>
</plist>

Disable backgrounding / Properly terminate an application

To properly terminate an application instance that has backgrounding enabled, press and hold the menu/home button until a message pops-up stating "Backgrounding Disabled".

Questions & Issue Reporting

Please first take a look at the Frequently Asked Questions (FAQ) page.

All problems should be reported via the tracker. Please provide as much information about the problem as possible, including device type, firmware version, and steps to take to recreate the problem.

Note about comments

This page originally had comments (mistakenly) enabled. As a show of respect to those that took the time to post, I have preserved the comments on the following wiki page: Comments