| Conforms to | |
| Framework | /System/Library/Frameworks/CoreLocation.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | CLLocationManagerDelegate.h |
| Related sample code |
The CLLocationManagerDelegate protocol defines the methods used to receive location and heading updates from a CLLocationManager object. The methods of this protocol are optional.
Upon receiving a successful location or heading update, you should consider stopping the corresponding service to save power. Similarly, 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 and stopUpdatingHeading methods of the CLLocationManager object to stop location and heading updates.
Tells the delegate that the location manager was unable to retrieve a location value.
- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error
The location manager object that was unable to retrieve the location.
The error object containing the reason why the location or heading could not be retrieved.
Implementation of this method is optional. You should implement this method, however.
If the location service is unable to retrieve a location fix 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 retuns kCLErrorHeadingFailure.
CLLocationManagerDelegate.hTells the delegate that the location manager received updated heading information.
- (void)locationManager:(CLLocationManager *)manager didUpdateHeading:(CLHeading *)newHeading
The location manager object that generated the update event.
The new heading data.
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.
CLLocationManagerDelegate.hTells the delegate that a new location value is available.
- (void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation
The location manager object that generated the update event.
The new location data.
The location data from the previous update. If this is the first update event delivered by this location manager, this parameter is nil.
Implementation of this method is optional. You should implement this method, however.
By the time this message is delivered to your delegate, the new 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.
CLLocationManagerDelegate.hAsks the delegate whether the heading calibration panel should be displayed.
- (BOOL)locationManagerShouldDisplayHeadingCalibration:(CLLocationManager *)manager
The location manager object coordinating the display of the heading calibration panel.
YES if you want to allow the heading calibration view to be displayed or NO if you do not.
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 device calibration panel on top of the current window immediately. The calibration panel 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 panel remains visible until calibration is complete or until you explicitly dismiss it by calling the dismissHeadingCalibrationDisplay method. In this 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 device calibration panel. Even if the panel 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.
CLLocationManagerDelegate.hLast updated: 2009-07-28
iPhone OS Reference Library Data Management: Device Information CLLocationManagerDelegate Protocol Reference