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
Related sample code

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

Pausing Location Updates

Responding to Heading Events

Responding to Region Events

Responding to Ranging Events

Responding to Authorization Changes

Instance Methods

locationManager:didChangeAuthorizationStatus:

Tells the delegate that the authorization status for the application changed.

- (void)locationManager:(CLLocationManager *)manager didChangeAuthorizationStatus:(CLAuthorizationStatus)status
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.h

locationManager:didDetermineState:forRegion:

Tells the delegate about the state of the specified region. (required)

- (void)locationManager:(CLLocationManager *)manager didDetermineState:(CLRegionState)state forRegion:(CLRegion *)region
Parameters
manager

The location manager object reporting the event.

state

The state of the specified region. For a list of possible values, see the CLRegionState type.

region

The region whose state was determined.

Discussion

The location manager calls this method whenever there is a boundary transition for a region. It calls this method in addition to calling the locationManager:didEnterRegion: and locationManager:didExitRegion: methods. The location manager also calls this method in response to a call to its requestStateForRegion: method, which runs asynchronously.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManagerDelegate.h

locationManager:didEnterRegion:

Tells the delegate that the user entered the specified region.

- (void)locationManager:(CLLocationManager *)manager didEnterRegion:(CLRegion *)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.h

locationManager:didExitRegion:

Tells the delegate that the user left the specified region.

- (void)locationManager:(CLLocationManager *)manager didExitRegion:(CLRegion *)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.h

locationManager:didFailWithError:

Tells the delegate that the location manager was unable to retrieve a location value.

- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error
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 but recommended.

The location manager calls this method when it encounters an error trying to get the location or heading data. 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 a heading could not be determined because of strong interference from nearby magnetic fields, this method returns kCLErrorHeadingFailure.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
CLLocationManagerDelegate.h

locationManager:didFinishDeferredUpdatesWithError:

Tells the delegate that updates will no longer be deferred.

- (void)locationManager:(CLLocationManager *)manager didFinishDeferredUpdatesWithError:(NSError *)error
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 may call this method for any number of reasons. For example, it calls it 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.
Declared In
CLLocationManagerDelegate.h

locationManager:didRangeBeacons:inRegion:

Tells the delegate that one or more beacons are in range. (required)

- (void)locationManager:(CLLocationManager *)manager didRangeBeacons:(NSArray *)beacons inRegion:(CLBeaconRegion *)region
Parameters
manager

The location manager object reporting the event.

beacons

An array of CLBeacon objects representing the beacons currently in range. You can use the information in these objects to determine the range of each beacon and its identifying information.

region

The region object containing the parameters that were used to locate the beacons.

Discussion

The location manager calls this method whenever a beacon comes within range or goes out of range. The location manager also calls this method when the range of the beacon changes; for example, when the beacon gets closer.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManagerDelegate.h

locationManager:didStartMonitoringForRegion:

Tells the delegate that a new region is being monitored.

- (void)locationManager:(CLLocationManager *)manager didStartMonitoringForRegion:(CLRegion *)region
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.h

locationManager:didUpdateHeading:

Tells the delegate that the location manager received updated heading information.

- (void)locationManager:(CLLocationManager *)manager didUpdateHeading:(CLHeading *)newHeading
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.h

locationManager:didUpdateLocations:

Tells the delegate that new location data is available.

- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations
Parameters
manager

The location manager object that generated the update event.

locations

An array of CLLocation objects containing the location data. This array always contains at least one object representing the current location. If updates were deferred or if multiple locations 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 but recommended.

Availability
  • Available in iOS 6.0 and later.
Declared In
CLLocationManagerDelegate.h

locationManager:monitoringDidFailForRegion:withError:

Tells the delegate that a region monitoring error occurred.

- (void)locationManager:(CLLocationManager *)manager monitoringDidFailForRegion:(CLRegion *)region withError:(NSError *)error
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.h

locationManager:rangingBeaconsDidFailForRegion:withError:

Tells the delegate that an error occurred while gathering ranging information for a set of beacons. (required)

- (void)locationManager:(CLLocationManager *)manager rangingBeaconsDidFailForRegion:(CLBeaconRegion *)region withError:(NSError *)error
Parameters
manager

The location manager object reporting the event.

region

The region object that encountered the error.

error

An error object containing the error code that indicates why ranging failed.

Discussion

Errors occur most often when registering a beacon region failed. If the region object itself is invalid or if it contains invalid data, the location manager calls this method to report the problem.

Availability
  • Available in iOS 7.0 and later.
Declared In
CLLocationManagerDelegate.h

locationManagerDidPauseLocationUpdates:

Tells the delegate that location updates were paused. (required)

- (void)locationManagerDidPauseLocationUpdates:(CLLocationManager *)manager
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.h

locationManagerDidResumeLocationUpdates:

Tells the delegate that the delivery of location updates has resumed. (required)

- (void)locationManagerDidResumeLocationUpdates:(CLLocationManager *)manager
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.h

locationManagerShouldDisplayHeadingCalibration:

Asks the delegate whether the heading calibration alert should be displayed.

- (BOOL)locationManagerShouldDisplayHeadingCalibration:(CLLocationManager *)manager
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