CLLocationManagerDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/CoreLocation.framework
Availability
Available in OS X v10.6 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

Responding to Region 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 OS X v10.7 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 OS X v10.8 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 OS X v10.8 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 OS X v10.6 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 OS X v10.9 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 OS X v10.8 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 OS X v10.9 and later.
Declared In
CLLocationManagerDelegate.h

locationManager:didUpdateToLocation:fromLocation:

Tells the delegate that a new location value is available. (Deprecated. Use locationManager:didUpdateLocations: instead.)

- (void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation
Parameters
manager

The location manager object that generated the update event.

newLocation

The new location data.

oldLocation

The location data from the previous update. If this is the first update event delivered by this location manager, this parameter is nil.

Discussion

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.

Availability
  • Available in OS X v10.6 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 OS X v10.8 and later.
Declared In
CLLocationManagerDelegate.h