mergBgTask

mergBgTask is an iOS external that adds commands to start and stop background tasks on iOS. Background tasks allow your app to continue executing code while in the backgound. This external should be considered experimental as it invloves letting LiveCode go into a suspended state rather than quit which is currently unsupported by RunRev. Your background tasks should not be blocking so that you can handle the mergBgTaskExpired message appropriately to start a new task if neccessary. Use mergNotify notifications from UIApplication such as UIApplicationDidEnterBackgroundNotification and UIApplicationWillEnterForegroundNotification to determine if your task is running in the background and therefore shouldn't do unnecessary things like update the UI (even though I have done that in the demo).

Installation

To install this external open the Standalone Settings for your app and go to the Copy Files pane. For LiveCode 5.5.2+ choose the mergBgTask.lcext from the distribution archive. For earlier versions of LiveCode select the appropriate folder inside the Pre-LiveCode-5.5.2 folder for the version of the iOS SDK you have installed. Xcode 4.2 = iOS 5.0, Xcode 4.3-4 = iOS 5.1. Xcode 4.5 is not supported by versions of LiveCode prior to 5.5.3. Any feature marked with a minimum iOS version must be comipled against that SDK or higher even if the app is run on a higher version of iOS. If there is a resources folder then these files and folders must be selected individually so that they end up at the root of the app directory. Any files or folders inside the demo folder are required for the demo to run correctly.

Documentation

command mergBgTaskStart

Start a background task. To manage multiple concurrent background tasks (such as multiple downloads) then keep track of the background task identifiers so as tasks end they can be be stopped and your app will suspend when all background tasks are stopped.

Sets the result to An id used to identify the task.

message mergBgTaskExpired pBackgroundTaskIdentifier

Sent to the object that called mergBgTaskStart when the background task expires. Background tasks last approximately 10 minutes. When you get this message (if your app is in the background) you have under 5 seconds to do any cleanup you require and call mergBgTaskStop otherwise iOS will kill your app instead of suspending it. As soon as you call mergBgTaskStop if your app is in the background it will be suspended unless there are other background tasks that have some time left.

Parameters:

  • pBackgroundTaskIdentifier - An id used to identify the task.

command mergBgTaskStop pBackgroundTaskIdentifier

Stop a background task. Call this if your code has finished executing before your app recieved the mergBgTaskExpired message and your app will go into suspend. You can use this to manage multiple background tasks. As soon as you call mergBgTaskStop if your app is in the background it will be suspended unless there are other background tasks that have some time left.

Parameters:

  • pBackgroundTaskIdentifier - A name used to identify the task as set in mergBgTaskStart

function mergBgTaskTimeRemaining

This function returns the amount of time the application has to run in the background before it may be forcibly killed by the system. While the application is running in the foreground, the value in this function remains suitably large. If the application starts one or more long-running tasks using mergBgTaskStart and then transitions to the background, the value of this property is adjusted to reflect the amount of time the application has left to run.

Returns time remaining in long seconds.