| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreLocation.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | CLError.h CLErrorDomain.h CLHeading.h CLLocation.h CLLocationManager.h |
| Related sample code |
The CLLocationManager class defines the interface for configuring the delivery of location- and heading-related events to your application. You use an instance of this class to establish the parameters that determine when location and heading events should be delivered. You can also use a location manager object to retrieve the most recent location data.
To use a CLLocationManager object to deliver location events, create an instance, assign a delegate object to it, configure the desired accuracy and distance filter values, and call the startUpdatingLocation method. The location service returns an initial location as quickly as possible, returning cached information when available. After delivery of the initial event notification, the CLLocationManager object may deliver additional events if the minimum threshold distance (as specified by the distanceFilter property) is exceeded or a more accurate location value is determined.
Important: The user has the option of denying an application’s access to the location service data. During its initial uses by an application, the Core Location framework prompts the user to confirm that using the location service is acceptable. If the user denies the request, the CLLocationManager object reports an appropriate error to its delegate during future requests.
In iPhone OS, a device with the appropriate hardware may also report heading information. When the value in the headingAvailable property is YES, you can use a location manager object to retrieve heading information. To begin the delivery of heading-related events, assign a delegate to the location manager object and call the location manager’s startUpdatingHeading method. If location updates are also enabled, the location manager returns both the true heading and magnetic heading values. If location updates are not enabled, the location manager returns only the magnetic heading value. These features are not available in Mac OS X.
The delegate you assign to the CLLocationManager object must conform to the CLLocationManagerDelegate protocol. For information about the methods of this protocol, see CLLocationManagerDelegate Protocol Reference.
delegate property
distanceFilter property
desiredAccuracy property
headingFilter property
headingAvailable property
– startUpdatingLocation
– stopUpdatingLocation
locationServicesEnabled property
– startUpdatingHeading
– stopUpdatingHeading
– dismissHeadingCalibrationDisplay
location property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The delegate object you want to receive update events.
@property(assign, NS_NONATOMIC_IPHONEONLY) id<CLLocationManagerDelegate> delegate
In iPhone OS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hThe desired accuracy of the location data.
@property(assign, NS_NONATOMIC_IPHONEONLY) CLLocationAccuracy desiredAccuracy
The receiver does its best to achieve the requested accuracy; however, the actual accuracy is not guaranteed.
You should assign a value to this property that is appropriate for your usage scenario. In other words, if you need only the current location within a few kilometers, you should not specify kCLLocationAccuracyBest for the accuracy. Determining a location with greater accuracy requires more time and more power.
When requesting high accuracy location data, the initial event delivered by the location service may not have the accuracy you requested. The location service delivers the initial event as quickly as possible. It then continues to determine the location with the accuracy you requested and delivers additional events, as necessary, when that data is available.
The default value of this property is kCLLocationAccuracyBest.
In iPhone OS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hThe minimum distance (measured in meters) a device must move laterally before an update event is generated.
@property(assign, NS_NONATOMIC_IPHONEONLY) CLLocationDistance distanceFilter
This distance is measured relative to the previously delivered location. Use the value kCLDistanceFilterNone to be notified of all movements.
The default value of this property is kCLDistanceFilterNone.
In iPhone OS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hA Boolean value indicating whether the location manager is able to generate heading-related events.
@property(readonly, nonatomic) BOOL headingAvailable
Heading data may not be available on all iPhone OS–based devices. You should check the value of this property before asking the location manager to deliver heading-related events.
CLLocationManager.hThe minimum angular change (measured in degrees) required to generate new heading events.
@property(assign, nonatomic) CLLocationDegrees headingFilter
The angular distance is measured relative to the last delivered heading event. Use the value kCLHeadingFilterNone to be notified of all movements.
The default value of this property is kCLHeadingFilterNone.
CLLocationManager.hThe most recently retrieved user location. (read-only)
@property(readonly, NS_NONATOMIC_IPHONEONLY) CLLocation *location
The value of this property is nil if no location data has ever been retrieved.
It is a good idea to check the timestamp of the location that is returned. If the receiver is currently gathering location data, but the minimum distance filter is large, the returned location might be relatively old. If it is, you can stop the receiver and start it again to force an update.
In iPhone OS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hA Boolean value indicating whether location services are enabled on the device.
@property(readonly, NS_NONATOMIC_IPHONEONLY) BOOL locationServicesEnabled
The user can enable or disable location services altogether from the Settings application by toggling the switch in Settings > General > Location Services.
You should check this property before starting location updates to determine if the user has location services enabled for the current device. If this property contains the value NO and you start location updates anyway, the Core Location framework prompts the user with a confirmation panel asking whether location services should be reenabled.
In iPhone OS, this property is declared as nonatomic. In Mac OS X, it is declared as atomic.
CLLocationManager.hDismisses the heading calibration view from the screen immediately.
- (void)dismissHeadingCalibrationDisplay
Core Location uses the heading calibration panel to calibrate the available heading hardware as needed. The display of this view is automatic, assuming your delegate supports displaying the view at all. If the view is displayed, you can use this method to dismiss it after an appropriate amount of time to ensure that your application’s user interface is not unduly disrupted.
CLLocationManager.hStarts the generation of updates that report the user’s current heading.
- (void)startUpdatingHeading
This method returns immediately. Calling this method when the receiver is stopped causes it to obtain an initial heading and notify your delegate. After that, the receiver generates update events when the value in the headingFilter property is exceeded.
Before calling this method, you should always check the headingAvailable property to see if heading information is supported on the current device. If heading information is not supported, calling this method has no effect and does not result in the delivery of events to your delegate.
Calling this method several times in succession does not automatically result in new events being generated. Calling stopUpdatingHeading in between, however, does cause a new initial event to be sent the next time you call this method.
CLLocationManager.hStarts the generation of updates that report the user’s current location.
- (void)startUpdatingLocation
This method returns immediately. Calling this method when the receiver is stopped causes it to obtain an initial location fix (which may take several seconds) and notify your delegate. After that, the receiver generates update events primarily when the value in the distanceFilter property is exceeded. Updates may be delivered in other situations though. For example, the receiver may send another notification if the hardware gathers a more accurate location reading.
Calling this method several times in succession does not automatically result in new events being generated. Calling stopUpdatingLocation in between, however, does cause a new initial event to be sent the next time you call this method.
CLLocationManager.hStops the generation of heading updates.
- (void)stopUpdatingHeading
You should call this method whenever your code no longer needs to receive heading-related events. Disabling event delivery gives the receiver the option of disabling the appropriate hardware (and thereby saving power) when no clients need location data. You can always restart the generation of heading updates by calling the startUpdatingHeading method again.
CLLocationManager.hStops the generation of location updates.
- (void)stopUpdatingLocation
You should call this method whenever your code no longer needs to receive location-related events. Disabling event delivery gives the receiver the option of disabling the appropriate hardware (and thereby saving power) when no clients need location data. You can always restart the generation of location updates by calling the startUpdatingLocation method again.
CLLocationManager.hA distance measurement (in meters) from an existing location.
typedef double CLLocationDistance;
CLLocation.hThis constant indicates the minimum distance required before an event is generated.
extern const CLLocationDistance kCLDistanceFilterNone;
kCLDistanceFilterNoneAll movements are reported.
Available in iPhone OS 2.0 and later.
Declared in CLLocation.h.
This constant indicates the minimum heading change before an event is generated.
const CLLocationDegrees kCLHeadingFilterNone;
kCLHeadingFilterNoneAll heading changes are reported.
Available in iPhone OS 3.0 and later.
Declared in CLHeading.h.
Error codes returned by the location manager object.
typedef enum {
kCLErrorLocationUnknown = 0,
kCLErrorDenied,
kCLErrorNetwork,
kCLErrorHeadingFailure
} CLError;
kCLErrorLocationUnknownThe location manager was unable to obtain a location value right now.
Available in iPhone OS 2.0 and later.
Declared in CLError.h.
kCLErrorDeniedAccess to the location service was denied by the user.
Available in iPhone OS 2.0 and later.
Declared in CLError.h.
kCLErrorNetworkThe network was unavailable or a network error occurred.
Available in iPhone OS 3.0 and later.
Declared in CLError.h.
kCLErrorHeadingFailureThe heading could not be determined.
Available in iPhone OS 3.0 and later.
Declared in CLError.h.
Errors are delivered to the delegate using an NSError object.
The domain for Core Location errors.
extern NSString *const kCLErrorDomain;
kCLErrorDomainThe domain for Core Location errors. This value is used in the NSError class.
Available in iPhone OS 2.0 and later.
Declared in CLErrorDomain.h.
Last updated: 2009-08-04
iPhone OS Reference Library Data Management: Device Information CLLocationManager Class Reference