CLLocationManagerDelegate Protocol Reference
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreLocation.framework |
| Availability | Available in iOS 2.0 and later. |
| Companion guide | |
| Declared in | CLLocationManagerDelegate.h |
Overview
The CLLocationManagerDelegate protocol defines the methods used to receive location and heading updates from a CLLocationManager object.
Upon receiving a successful location or heading update, you can use the result to update your user interface or perform other actions. If the location or heading could not be determined, you might want to stop updates for a short period of time and try again later. You can use the stopUpdatingLocation, stopMonitoringSignificantLocationChanges, stopUpdatingHeading, or stopMonitoringForRegion: methods of CLLocationManager to stop location, heading, and region updates.
The methods of your delegate object are called from the thread in which you started the corresponding location services. That thread must itself have an active run loop, like the one found in your application’s main thread.
Tasks
Responding to Location Events
-
– locationManager:didUpdateLocations: -
– locationManager:didFailWithError: -
– locationManager:didFinishDeferredUpdatesWithError: -
– locationManager:didUpdateToLocation:fromLocation:Deprecated in iOS 6.0
Pausing Location Updates
Responding to Heading Events
Responding to Region Events
-
– locationManager:didEnterRegion: -
– locationManager:didExitRegion: -
– locationManager:monitoringDidFailForRegion:withError: -
– locationManager:didStartMonitoringForRegion:
Responding to Authorization Changes
Instance Methods
locationManager:didChangeAuthorizationStatus:
Tells the delegate that the authorization status for the application changed.
Parameters
- manager
The location manager object reporting the event.
- status
The new authorization status for the application.
Discussion
This method is called whenever the application’s ability to use location services changes. Changes can occur because the user allowed or denied the use of location services for your application or for the system as a whole.
Availability
- Available in iOS 4.2 and later.
Declared In
CLLocationManagerDelegate.hlocationManager:didEnterRegion:
Tells the delegate that the user entered the specified region.
Parameters
- manager
The location manager object reporting the event.
- region
An object containing information about the region that was entered.
Discussion
Because regions are a shared application resource, every active location manager object delivers this message to its associated delegate. It does not matter which location manager actually registered the specified region. And if multiple location managers share a delegate object, that delegate receives the message multiple times.
The region object provided may not be the same one that was registered. As a result, you should never perform pointer-level comparisons to determine equality. Instead, use the region’s identifier string to determine if your delegate should respond.
Availability
- Available in iOS 4.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManager:didExitRegion:
Tells the delegate that the user left the specified region.
Parameters
- manager
The location manager object reporting the event.
- region
An object containing information about the region that was exited.
Discussion
Because regions are a shared application resource, every active location manager object delivers this message to its associated delegate. It does not matter which location manager actually registered the specified region. And if multiple location managers share a delegate object, that delegate receives the message multiple times.
The region object provided may not be the same one that was registered. As a result, you should never perform pointer-level comparisons to determine equality. Instead, use the region’s identifier string to determine if your delegate should respond.
Availability
- Available in iOS 4.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManager:didFailWithError:
Tells the delegate that the location manager was unable to retrieve a location value.
Parameters
- manager
The location manager object that was unable to retrieve the location.
- error
The error object containing the reason the location or heading could not be retrieved.
Discussion
Implementation of this method is optional. You should implement this method, however.
If the location service is unable to retrieve a location right away, it reports a kCLErrorLocationUnknown error and keeps trying. In such a situation, you can simply ignore the error and wait for a new event.
If the user denies your application’s use of the location service, this method reports a kCLErrorDenied error. Upon receiving such an error, you should stop the location service.
If a heading could not be determined because of strong interference from nearby magnetic fields, this method returns kCLErrorHeadingFailure.
Availability
- Available in iOS 2.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManager:didFinishDeferredUpdatesWithError:
Tells the delegate that updates will no longer be deferred.
Parameters
- manager
The location manager object that generated the update event.
- error
The error object containing the reason deferred location updates could not be delivered.
Discussion
The location manager object calls this method to let you know that it has stopped deferring the delivery of location events. The manager does this when deferrals are active and when one of several actions takes place. For example, it can happen when you stop location updates altogether, when you ask the location manager to disallow deferred updates, or when a condition for deferring updates (such as exceeding a timeout or distance parameter) is met.
Availability
- Available in iOS 6.0 and later.
See Also
Declared In
CLLocationManagerDelegate.hlocationManager:didStartMonitoringForRegion:
Tells the delegate that a new region is being monitored.
Parameters
- manager
The location manager object reporting the event.
- region
The region that is being monitored.
Availability
- Available in iOS 5.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManager:didUpdateHeading:
Tells the delegate that the location manager received updated heading information.
Parameters
- manager
The location manager object that generated the update event.
- newHeading
The new heading data.
Discussion
Implementation of this method is optional but expected if you start heading updates using the startUpdatingHeading method.
The location manager object calls this method after you initially start the heading service. Subsequent events are delivered when the previously reported value changes by more than the value specified in the headingFilter property of the location manager object.
Availability
- Available in iOS 3.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManager:didUpdateLocations:
Tells the delegate that new location data is available.
Parameters
- manager
The location manager object that generated the update event.
- locations
An array of
CLLocationobjects containing the location data. This array always contains at least one object representing the current location. If update events were deferred or if multiple events arrived before they could be delivered, the array may contain additional entries. The objects in the array are organized in the order in which they occurred. Therefore, the most recent location update is at the end of the array.
Discussion
Implementation of this method is optional. You should implement this method, however.
By the time this message is delivered to your delegate, the most recent location data is also available directly from the CLLocationManager object. The newLocation parameter may contain the data that was cached from a previous usage of the location service. You can use the timestamp property of the location object to determine how recent the location data is.
Availability
- Available in iOS 6.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManager:monitoringDidFailForRegion:withError:
Tells the delegate that a region monitoring error occurred.
Parameters
- manager
The location manager object reporting the event.
- region
The region for which the error occurred.
- error
An error object containing the error code that indicates why region monitoring failed.
Discussion
If an error occurs while trying to monitor a given region, the location manager sends this message to its delegate. Region monitoring might fail because the region itself cannot be monitored or because there was a more general failure in configuring the region monitoring service.
Although implementation of this method is optional, it is recommended that you implement it if you use region monitoring in your application.
Availability
- Available in iOS 4.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManagerDidPauseLocationUpdates:
Tells the delegate that location updates were paused. (required)
Parameters
- manager
The location manager object that paused the delivery of events.
Discussion
When the location manager detects that the device’s location is not changing, it can pause the delivery of updates in order to shut down the appropriate hardware and save power. When it does this, it calls this method to let your app know that this has happened.
Availability
- Available in iOS 6.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManagerDidResumeLocationUpdates:
Tells the delegate that the delivery of location updates has resumed. (required)
Parameters
- manager
The location manager that resumed the delivery of events.
Discussion
When location updates are paused and need to be resumed (perhaps because the user is moving again), the location manager calls this method to let your app know that it is about to begin the delivery of those updates again.
Availability
- Available in iOS 6.0 and later.
Declared In
CLLocationManagerDelegate.hlocationManagerShouldDisplayHeadingCalibration:
Asks the delegate whether the heading calibration alert should be displayed.
Parameters
- manager
The location manager object coordinating the display of the heading calibration alert.
Return Value
YES if you want to allow the heading calibration alert to be displayed; NO if you do not.
Discussion
Core Location may call this method in an effort to calibrate the onboard hardware used to determine heading values. Typically, Core Location calls this method at the following times:
The first time heading updates are ever requested
When Core Location observes a significant change in magnitude or inclination of the observed magnetic field
If you return YES from this method, Core Location displays the heading calibration alert on top of the current window immediately. The calibration alert prompts the user to move the device in a particular pattern so that Core Location can distinguish between the Earth’s magnetic field and any local magnetic fields. The alert remains visible until calibration is complete or until you explicitly dismiss it by calling the dismissHeadingCalibrationDisplay method. In the latter case, you can use this method to set up a timer and dismiss the interface after a specified amount of time has elapsed.
If you return NO from this method or do not provide an implementation for it in your delegate, Core Location does not display the heading calibration alert. Even if the alert is not displayed, calibration can still occur naturally when any interfering magnetic fields move away from the device. However, if the device is unable to calibrate itself for any reason, the value in the headingAccuracy property of any subsequent events will reflect the uncalibrated readings.
Availability
- Available in iOS 3.0 and later.
Declared In
CLLocationManagerDelegate.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)