iOS Developer Library

Developer

CoreLocation Framework Reference CLLocationManagerDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

CLLocationManagerDelegate

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, stopMonitoringForRegion:, or stopMonitoringVisits methods of CLLocationManager to stop the various location services.

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.

Inheritance


Not Applicable

Import Statement


Swift

import CoreLocation

Objective-C

@import CoreLocation;

Availability


Available in iOS 2.0 and later.
  • Tells the delegate that new location data is available.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didUpdateLocations locations: [AnyObject]!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didFailWithError error: NSError!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 2.0 and later.

  • Tells the delegate that updates will no longer be deferred.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didFinishDeferredUpdatesWithError error: NSError!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that a new location value is available.

    Deprecation Statement

    Use locationManager:didUpdateLocations: instead.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 6.0.

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

    Declaration

    Swift

    optional func locationManagerDidPauseLocationUpdates(_ manager: CLLocationManager!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func locationManagerDidResumeLocationUpdates(_ manager: CLLocationManager!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didUpdateHeading newHeading: CLHeading!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func locationManagerShouldDisplayHeadingCalibration(_ manager: CLLocationManager!) -> Bool

    Objective-C

    - (BOOL)locationManagerShouldDisplayHeadingCalibration:(CLLocationManager *)manager

    Parameters

    manager

    The location manager object coordinating the display of the heading calibration alert.

    Return Value

    YEStrue if you want to allow the heading calibration alert to be displayed; NOfalse 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 YEStrue 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 NOfalse 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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 3.0 and later.

  • Tells the delegate that the user entered the specified region.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didEnterRegion region: CLRegion!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

  • Tells the delegate that the user left the specified region.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didExitRegion region: CLRegion!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didDetermineState state: CLRegionState, forRegion region: CLRegion!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • Tells the delegate that a region monitoring error occurred.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, monitoringDidFailForRegion region: CLRegion!, withError error: NSError!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 4.0 and later.

  • Tells the delegate that a new region is being monitored.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didStartMonitoringForRegion region: CLRegion!)

    Objective-C

    - (void)locationManager:(CLLocationManager *)manager didStartMonitoringForRegion:(CLRegion *)region

    Parameters

    manager

    The location manager object reporting the event.

    region

    The region that is being monitored.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

  • Tells the delegate that one or more beacons are in range.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didRangeBeacons beacons: [AnyObject]!, inRegion region: CLBeaconRegion!)

    Objective-C

    - (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. If beacons is empty, you can assume that no beacons matching the specified region are in range. When a specific beacon is no longer in beacons, that beacon is no longer received by the device. You can use the information in the CLBeacon 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 when a new set of beacons becomes available in the specified region or when a beacon goes out of range. The location manager also calls this method when the range of a beacon changes; for example, when a beacon gets closer.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, rangingBeaconsDidFailForRegion region: CLBeaconRegion!, withError error: NSError!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 7.0 and later.

  • Tells the delegate that a new visit-related event was received.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didVisit visit: CLVisit!)

    Objective-C

    - (void)locationManager:(CLLocationManager *)manager didVisit:(CLVisit *)visit

    Parameters

    manager

    The location manager object reporting the event.

    visit

    The visit object that contains the information about the event.

    Discussion

    The location manager calls this method whenever it has new visit event to report to your app.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 8.0 and later.