Class: CLLocationManager

Inherits:
NSObject show all

Overview

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 and to start and stop the actual delivery of those events. You can also use a location manager object to retrieve the most recent location and heading data.

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (CLActivityType) activityType

The type of user activity associated with the location updates. The location manager uses the information in this property as a cue to determine when location updates may be automatically paused. Pausing updates gives the system the opportunity to save power in situations where the user's location is not likely to be changing. For example, if the activity type is CLActivityTypeAutomotiveNavigation and no location changes have occurred recently, the radios might be powered down until movement is detected again.

Returns:

  • (CLActivityType)

- (Object) delegate

The delegate object to receive update events.

Returns:

- (CLLocationAccuracy) desiredAccuracy

The accuracy of the location data. 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 the current location only 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. This property is used only in conjunction with the standard location services and is not used when monitoring significant location changes.

Returns:

  • (CLLocationAccuracy)

- (CLLocationDistance) distanceFilter

The minimum distance (measured in meters) a device must move horizontally before an update event is generated. 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. This property is used only in conjunction with the standard location services and is not used when monitoring significant location changes.

Returns:

  • (CLLocationDistance)

- (CLHeading) heading (readonly)

The most recently reported heading. (read-only) The value of this property is nil if heading updates have never been initiated.

Returns:

- (CLLocationDegrees) headingFilter

The minimum angular change (measured in degrees) required to generate new heading events. 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 1 degree.

Returns:

  • (CLLocationDegrees)

- (CLDeviceOrientation) headingOrientation

The device orientation to use when computing heading values. When computing heading values, the location manager assumes that the top of the device in portrait mode represents due north (0 degrees) by default. For applications that run in other orientations, this may not always be the most convenient orientation. This property allows you to specify which device orientation you want the location manager to use as the reference point for due north.Although you can set the value of this property to CLDeviceOrientationUnknown, CLDeviceOrientationFaceUp, or CLDeviceOrientationFaceDown, doing so has no effect on the orientation reference point. The original reference point is retained instead.Changing the value in this property affects only those heading values reported after the change is made.

Returns:

  • (CLDeviceOrientation)

- (CLLocation) location (readonly)

The most recently retrieved user location. (read-only) The value of this property is nil if no location data has ever been retrieved. In iOS 4.0 and later, this property may contain a more recent location object at launch time. Specifically, if significant location updates are running and your application is terminated, this property is updated with the most recent location data when your application is relaunched (and you create a new location manager object). This location data may be more recent than the last location event processed by your application. It is always a good idea to check the timestamp of the location stored in this property. 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.

Returns:

- (CLLocationDistance) maximumRegionMonitoringDistance (readonly)

The largest boundary distance that can be assigned to a region. (read-only) This property defines the largest boundary distance allowed from a region’s center point. Attempting to monitor a region with a distance larger than this value causes the location manager to send a kCLErrorRegionMonitoringFailure error to the delegate.If region monitoring is unavailable or not supported, the value in this property is -1.

Returns:

  • (CLLocationDistance)

- (NSSet) monitoredRegions (readonly)

The set of shared regions monitored by all location manager objects. (read-only) You cannot add regions to this property directly. Instead, you must register regions by calling the startMonitoringForRegion:desiredAccuracy: method. The regions in this property are shared by all instances of the CLLocationManager class in your application.The objects in this set may not necessarily be the same objects you specified at registration time. Only the region data itself is maintained by the system. Therefore, the only way to uniquely identify a registered region is using its identifier property.The location manager persists region data between launches of your application. If your application is terminated and then relaunched, the contents of this property are repopulated with region objects that contain the previously registered data.

Returns:

- (Boolean) pausesLocationUpdatesAutomatically

A Boolean value indicating whether the location manager object may pause location updates. Allowing the location manager to pause updates can improve battery life on the target device without sacrificing location data. When this property is set to YES, the location manager pauses updates (and powers down the appropriate hardware) at times when the location data is unlikely to change. For example, if the user stops for food while using a navigation app, the location manager might pause updates for a period of time. You can help the determination of when to pause location updates by assigning a value to the activityType property.The default value of this property is YES.

Returns:

  • (Boolean)

Class Method Details

+ (CLAuthorizationStatus) authorizationStatus

Returns the application’s authorization status for using location services. The authorization status of a given application is managed by the system and determined by several factors. Applications must be explicitly authorized to use location services by the user and location services must themselves currently be enabled for the system. A request for user authorization is displayed automatically when your application first attempts to use location services.

Returns:

  • (CLAuthorizationStatus) —

    A value indicating whether the application is authorized to use location services.

+ (Boolean) deferredLocationUpdatesAvailable

Returns a Boolean value indicating whether the device supports deferred location updates. Deferred location updates are a way for the location manager to avoid frequently waking up a background app to deliver location changes. Normally, when an app wants location updates in the background, the app must be woken up whenever a new event arrives. Waking up the app consumes power, which in some situations might be wasted if the app cannot do anything with the location information other than log it and go back to sleep anyway. Deferring location updates gives you the ability to wait until a time when your app can do something useful with the data and then process the updates all at once.

Returns:

  • (Boolean) —

    YES if the device supports deferred location updates or NO if it does not.

+ (Boolean) headingAvailable

Returns a Boolean value indicating whether the location manager is able to generate heading-related events. Heading data may not be available on all iOS-based devices. You should check the value returned by this method before asking the location manager to deliver heading-related events.

Returns:

  • (Boolean) —

    YES if heading data is available; NO if it is not.

+ (Boolean) locationServicesEnabled

Returns a Boolean value indicating whether location services are enabled on the device. The user can enable or disable location services from the Settings application by toggling the Location Services switch in General. You should check the return value of this method before starting location updates to determine whether the user has location services enabled for the current device. If this method returns NO and you start location updates anyway, the Core Location framework prompts the user to confirm whether location services should be reenabled.

Returns:

  • (Boolean) —

    YES if location services are enabled; NO if they are not.

+ (Boolean) regionMonitoringAvailable

Returns a Boolean value indicating whether region monitoring is supported on the current device. Support for region monitoring may not be available on all devices and models. You should check the value of this property before attempting to set up any regions or initiate region monitoring. Even if region monitoring support is present on a device, it may still be unavailable because the user disabled it for the current application or for all applications.

Returns:

  • (Boolean) —

    YES if region monitoring is available; NO if it is not.

+ (Boolean) significantLocationChangeMonitoringAvailable

Returns a Boolean value indicating whether significant location change tracking is available. This method indicates whether the device is able to report updates based on significant location changes only. (Significant location change monitoring primarily involves detecting changes in the cell tower currently associated with the device.) This capability provides tremendous power savings for applications that want to track a user’s approximate location and do not need highly accurate position information.

Returns:

  • (Boolean) —

    YES if location change monitoring is available; NO if it is not.

Instance Method Details

- (Object) allowDeferredLocationUpdatesUntilTraveled(distance, timeout:timeout)

Tells the location manager to defer the delivery of location data until one of the specified criteria is met. Call this method when you know that your app does not need to process events until the specified distance or timeout values are exceeded. Deferring location updates gives the location manager the option of powering down location-related hardware, thereby saving power. Any location events that arrive during this time are queued and delivered to your app when one of the specified exit criteria is met. The location manager defers updates only when your app is in the background. If your app is in the foreground, events are delivered normally and not deferred. Important: The location manager supports deferred updates only when the desired accuracy is set to kCLLocationAccuracyBest or kCLLocationAccuracyBestForNavigation. When one of the specified criteria is met, the location manager calls its delegate’s locationManager:didFinishDeferredUpdatesWithError: method to let it know that event deferral has ended.

Parameters:

  • distance (CLLocationDistance) —

    The distance (in meters) from the current location that must be travelled before event delivery resumes on a regular basis.

  • timeout (NSTimeInterval) —

    The amount of time (in seconds) from the current time that must pass before event delivery resumes on a regular basis.

Returns:

- (Object) disallowDeferredLocationUpdates

Cancels the deferral of location updates for this app. Call this method if you previously deferred location event delivery using the allowDeferredLocationUpdatesUntilTraveled:timeout: method and now want to resume the delivery of events at normal intervals.

Returns:

- (Object) dismissHeadingCalibrationDisplay

Dismisses the heading calibration view from the screen immediately. Core Location uses the heading calibration alert 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.

Returns:

- (Object) startMonitoringForRegion(region)

Starts monitoring the specified region. You must call this method or the startMonitoringForRegion:desiredAccuracy: method separately for each region you want to monitor. If an existing region with the same identifier is already being monitored by the application, the old region is replaced by the new one. The regions you add using this method are shared by all location manager objects in your application and stored in the monitoredRegions property.Region events are delivered to the locationManager:didEnterRegion: and locationManager:didExitRegion: methods of your delegate. If there is an error, the location manager calls the locationManager:monitoringDidFailForRegion:withError: method of your delegate instead.An app can register up to 20 regions at a time. In order to report region changes in a timely manner, the region monitoring service requires network connectivity.In iOS 6, regions with a radius between 1 and 400 meters work better on iPhone 4S or later devices. (In iOS 5, regions with a radius between 1 and 150 meters work better on iPhone 4S and later devices.) On these devices, an app can expect to receive the appropriate region entered or region exited notification within 3 to 5 minutes on average, if not sooner.

Parameters:

  • region (CLRegion) —

    The region object that defines the boundary to monitor. This parameter must not be nil.

Returns:

- (Object) startMonitoringSignificantLocationChanges

Starts the generation of updates based on significant location changes. This method initiates the delivery of location events asynchronously, returning shortly after you call it. Location events are delivered to your delegate’s locationManager:didUpdateLocations: method. The first event to be delivered is usually the most recently cached location event (if any) but may be a newer event in some circumstances. Obtaining a current location fix may take several additional seconds, so be sure to check the timestamps on the location events in your delegate method. After returning a current location fix, the receiver generates update events only when a significant change in the user’s location is detected. For example, it might generate a new event when the device becomes associated with a different cell tower. It does not rely on the value in the distanceFilter property to generate events. Calling this method several times in succession does not automatically result in new events being generated. Calling stopMonitoringSignificantLocationChanges in between, however, does cause a new initial event to be sent the next time you call this method. If you start this service and your application is subsequently terminated, the system automatically relaunches the application into the background if a new event arrives. In such a case, the options dictionary passed to the locationManager:didUpdateLocations: method of your application delegate contains the key UIApplicationLaunchOptionsLocationKey to indicate that your application was launched because of a location event. Upon relaunch, you must still configure a location manager object and call this method to continue receiving location events. When you restart location services, the current event is delivered to your delegate immediately. In addition, the location property of your location manager object is populated with the most recent location object even before you start location services. In addition to your delegate object implementing the locationManager:didUpdateLocations: method, it should also implement the locationManager:didFailWithError: method to respond to potential errors.Note: Apps can expect a notification as soon as the device moves 500 meters or more from its previous notification. It should not expect notifications more frequently than once every five minutes. If the device is able to retrieve data from the network, the location manager is much more likely to deliver notifications in a timely manner.

Returns:

- (Object) startUpdatingHeading

Starts the generation of updates that report the user’s current heading. 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 whether 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. If you start this service and your application is suspended, the system stops the delivery of events until your application starts running again (either in the foreground or background). If your application is terminated, the delivery of new heading events stops altogether and must be restarted by your code when the application is relaunched.Heading events are delivered to the locationManager:didUpdateHeading: method of your delegate. If there is an error, the location manager calls the locationManager:didFailWithError: method of your delegate instead.

Returns:

- (Object) startUpdatingLocation

Starts the generation of updates that report the user’s current location. This method returns immediately. Calling this method causes the location manager to obtain an initial location fix (which may take several seconds) and notify your delegate by calling its locationManager:didUpdateLocations: method. (In iOS 5 and earlier, the location manager calls the locationManager:didUpdateToLocation:fromLocation: method instead.) 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. If you start this service and your application is suspended, the system stops the delivery of events until your application starts running again (either in the foreground or background). If your application is terminated, the delivery of new location events stops altogether. Therefore, if your application needs to receive location events while in the background, it must include the UIBackgroundModes key (with the location value) in its Info.plist file.In addition to your delegate object implementing the locationManager:didUpdateLocations: method, it should also implement the locationManager:didFailWithError: method to respond to potential errors.

Returns:

- (Object) stopMonitoringForRegion(region)

Stops monitoring the specified region. If the specified region object is not currently being monitored, this method has no effect.

Parameters:

  • region (CLRegion) —

    The region object currently being monitored. This parameter must not be nil.

Returns:

- (Object) stopMonitoringSignificantLocationChanges

Stops the delivery of location events based on significant location changes. Use this method to stop the delivery of location events that was started using the startMonitoringSignificantLocationChanges method.

Returns:

- (Object) stopUpdatingHeading

Stops the generation of heading updates. 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.

Returns:

- (Object) stopUpdatingLocation

Stops the generation of location updates. 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.

Returns: