Behaviour for significant change location API when terminated/suspended?

Question

This is the section from the CLLocationManager documentation describing the app behavior with startMonitoringSignificantLocationChanges:

If you start this service and your application is subsequently terminated, the system automatically relaunches the application into the background if a new event arrives. In such a case, the options dictionary passed to the application:didFinishLaunchingWithOptions: method of your application delegate contains the key UIApplicationLaunchOptionsLocationKey to indicate that your application was launched because of a location event. Upon relaunch, you must still configure a location manager object and call this method to continue receiving location events. When you restart location services, the current event is delivered to your delegate immediately. In addition, the location property of your location manager object is populated with the most recent location object even before you start location services.

So my understanding is that if your app terminates (and I assume if you don't call stopMonitoringSignificantLocationChanges from applicationWillTerminate) you will get woken up with a UIApplicationLaunchOptionsLocationKey parameter to application:didFinishLaunchingWithOptions. At that point you create your CLLocationManager, call startMonitoringSignificantLocationChanges and do your background location processing for a limited time. So I am fine with this bit.

The previous paragraph only talks about what happens when the app is terminated, it doesn't suggest what you do when the application is suspended. The documentation for didFinishLaunchingWithOptions says:

The application tracks location updates in the background, was purged, and has now been relaunched. In this case, the dictionary contains a key indicating that the application was relaunched because of a new location event.

Suggesting that you will only receive this call when your app is launched (because of a location change) after you have been terminated.

However the paragraph on the Significant Change Service in the Location Awareness Programming Guide has the following to say:

If you leave this service running and your application is subsequently suspended or terminated, the service automatically wakes up your application when new location data arrives. At wake-up time, your application is put into the background and given a small amount of time to process the location data. Because your application is in the background, it should do minimal work and avoid any tasks (such as querying the network) that might prevent it from returning before the allocated time expires. If it does not, your application may be terminated.

This suggests you are woken up with location data if your app has been suspended, but fails to mention how you are woken up:

• Does the UIApplicationDelegate get a callback telling me that I am resuming from a suspended state into a background state?
• Does the location manager (that was freeze dried when the app was suspended) start receiving locationManager:didUpdateToLocation:fromLocation callbacks?
• Do I just need to implement code in my didUpdateToLocation message which checks the application state and does minimal processing if in background mode?

In the process of writing this up, I think I may have just answered my own question, but it would be great to have my understanding of this confirmed by someone more knowledgeable.

Answer 1

My understanding is as follows (I'm in the process of writing an application that relies on this API, but haven't completed this component enough to start testing):

1. Your application is run for the first time, you register to startMonitoringSignificantLocationChanges, and provide a callback function. While your application is running, it will call that callback whenever it receives a significant change.
2. If your application is put to the background, UIApplication will receive applicationWillResignActive, followed by applicationDidEnterBackground.
3. If your application is killed while it is suspended in the background, you will not be notified; however, if your application is killed while it is running (foreground or background to my knowledge), you will get a moment with applicationWillTerminate. You cannot request extra background time from this function.

4. Despite being killed in the background, the OS will relaunch your application. If your application is simply launched by the OS for a change, you will get a call to application didFinishLaunchingWithOptions:

   if ([launchOptions objectForKey:UIApplicationLaunchOptionsLocationKey])
   

   will help you determine if you've come back from a background location change.

5. If, instead, you were currently running in the background, and your app is manually relaunched by the user, you will receive an applicationWillEnterForeground followed by applicationDidBecomeActive.
6. Regardless of how it happened, when your application is relaunched (unless it was still running in the background as a result of a background task and said task had started monitoring changes), you need to explicitly tell it to startMonitoringSignificantLocationChanges again because the callback is no longer attached after "freeze drying." And yes, you just need to implement code in didUpdateToLocation once you've re-attached a location handler of some kind once coming back from the suspended state.

This is what I'm going on with my code development right now. As I mentioned before, I'm not quite ready to test this on a device so I can't tell if I've interpreted everything correctly, so commenters, please feel free to correct me (though I've done substantial reading on the topic).

Oh, and if by some stroke of bad luck, you release an app that does what I want mine to do, I might cry :)

Good luck!

Answer 2

Since I asked this question, I have done a fair bit of testing (mostly on the train between home and work) and have confirmed that the behaviour for suspended apps is as I suspected at the end of the question.

That is, your suspended app is woken up, you don't receive any callbacks on your app delegate, instead you receive your location updates through your existing CLLocationManagerDelegate. You can detect that you are running the background by checking the applicationState, and do limited work for the case where you are woken from a suspended state to do location processing.

[UIApplication sharedApplication].applicationState == UIApplicationStateBackground

I came to this conclusion with a location test harness that you are welcome to download and try out. It is a pretty simple app that allows you to turn on significant change and gps change APIs through the UI and log all the responses that you get back.

N.B. Point six in the previous answer is not correct. Freeze dried suspended apps do receive CLLocationManagerDelegate callbacks when they are woken up from a suspended state.