Mac Developer Library

Developer

CoreLocation Framework Reference CLLocationManagerDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

CLLocationManagerDelegate

Inheritance


Not Applicable

Import Statement


Swift

import CoreLocation

Objective-C

@import CoreLocation;

Availability


Available in OS X v10.6 and later.

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.

  • 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 OS X v10.9 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 OS X v10.6 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 OS X v10.9 and later.

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

    Use locationManager:didUpdateLocations: instead.

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didUpdateToLocation newLocation: CLLocation!, fromLocation oldLocation: CLLocation!)

    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;

    Swift

    import CoreLocation

    Availability

    Available in OS X v10.6 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 OS X v10.8 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 OS X v10.8 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 OS X v10.10 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 OS X v10.8 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 OS X v10.8 and later.

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

    Declaration

    Swift

    optional func locationManager(_ manager: CLLocationManager!, didChangeAuthorizationStatus status: CLAuthorizationStatus)

    Objective-C

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

    If the authorization status is already known when you call the requestWhenInUseAuthorization or requestAlwaysAuthorization method, the location manager does not report the current authorization status to this method. The location manager only reports changes to the authorization status. For example, it calls this method when the status changes from kCLAuthorizationStatusNotDetermined to kCLAuthorizationStatusAuthorizedWhenInUse.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in OS X v10.7 and later.