Initial commit of INTULocationManager

README.md

@@ -1,2 +1,75 @@
-LocationManager
-===============
+# INTULocationManager
+INTULocationManager makes it easy to get the device's current location on iOS.
+
+## What's wrong with CLLocationManager?
+CLLocationManager's API works well when you need to track changes in the user's location over time, such as for turn-by-turn GPS navigation apps. However, if you just need to ask "Where am I?" every now and then, CLLocationManager is fairly difficult to work with.
+
+Getting one-off location updates is a common task for many apps, such as when you want to autofill an address from the current location, or determine which city the user is currently in. Not only does INTULocationManager make this easy, but it also conserves the user's battery by powering down location services (e.g. GPS) as soon as they are no longer needed.
+
+## Usage
+To get the device's current location, use the method `requestLocationWithDesiredAccuracy:timeout:block:`.
+
+The `desiredAccuracy` specifies how **accurate and recent** of a location you need. The possible values are:
+```objective-c
+INTULocationAccuracyCity          // 5000 meters or better, received within the last 10 minutes  -- lowest accuracy
+INTULocationAccuracyNeighborhood  // 1000 meters or better, received within the last 5 minutes
+INTULocationAccuracyBlock         // 100 meters or better, received within the last 1 minute
+INTULocationAccuracyHouse         // 15 meters or better, received within the last 15 seconds
+INTULocationAccuracyRoom          // 5 meters or better, received within the last 5 seconds      -- highest accuracy
+```
+
+The `timeout` specifies how long you are willing to wait for a location with the accuracy you requested. The timeout guarantees that your block will execute within this period of time, either with a location of at least the accuracy you requested (`INTULocationStatusSuccess`), or with whatever location could be determined before the timeout interval was up (`INTULocationStatusTimedOut`).
+
+```objective-c
+INTULocationManager *locMgr = [INTULocationManager sharedInstance];
+[locMgr requestLocationWithDesiredAccuracy:INTULocationAccuracyCity
+                                   timeout:10.0
+                                     block:^(CLLocation *currentLocation, INTULocationAccuracy achievedAccuracy, INTULocationStatus status) {
+                                         if (status == INTULocationStatusSuccess) {
+                                             // Request succeeded, meaning achievedAccuracy is at least the requested accuracy, and
+                                             // currentLocation contains the device's current location.
+                                         }
+                                         else if (status == INTULocationStatusTimedOut) {
+                                             // Wasn't able to locate the user with the requested accuracy within the timeout interval.
+                                             // However, currentLocation contains the best location available (if any) as of right now,
+                                             // and achievedAccuracy has info on the accuracy/recency of the location in currentLocation.
+                                         }
+                                         else {
+                                             // An error occurred, more info is available by looking at the specific status returned.
+                                         }
+                                     }];
+```
+
+When issuing a location request, you can optionally store the request ID, which allows you to force completion or cancel the request at any time:
+```objective-c
+NSInteger requestID = [[INTULocationManager sharedInstance] requestLocationWithDesiredAccuracy:INTULocationAccuracyHouse
+                                                                                       timeout:5.0
+                                                                                         block:locationRequestBlock];
+
+// Force the request to complete early, like a manual timeout (will execute the block)
+[[INTULocationManager sharedInstance] forceCompleteLocationRequest:requestID];
+
+// Cancel the request (won't execute the block)
+[[INTULocationManager sharedInstance] cancelLocationRequest:requestID];
+```
+
+## Installation
+*INTULocationManager requires iOS 6.0 or later.*
+
+**Using [CocoaPods](http://cocoapods.org)**
+
+1.	Add the pod `INTULocationManager` to your [Podfile](http://guides.cocoapods.org/using/the-podfile.html).
+
+    	pod 'INTULocationManager'
+
+2.	Run `pod install` from Terminal, then open your app's `.xcworkspace` file to launch Xcode.
+3.	`#import INTULocationManager.h` wherever you want to use it.
+
+**Manually from GitHub**
+
+1.	Download all the files in the [Source directory](https://github.com/intuit/LocationManager/tree/master/Source).
+2.	Add all the files to your Xcode project (drag and drop is easiest).
+3.	`#import INTULocationManager.h` wherever you want to use it.
+
+## License
+INTULocationManager is provided under the MIT license.

Source/INTULocationManager.h

@@ -0,0 +1,63 @@
+//
+//  INTULocationManager.h
+//
+//  Copyright (c) 2014 Intuit Inc.
+//
+//	Permission is hereby granted, free of charge, to any person obtaining
+//	a copy of this software and associated documentation files (the
+//	"Software"), to deal in the Software without restriction, including
+//	without limitation the rights to use, copy, modify, merge, publish,
+//	distribute, sublicense, and/or sell copies of the Software, and to
+//	permit persons to whom the Software is furnished to do so, subject to
+//	the following conditions:
+//
+//	The above copyright notice and this permission notice shall be
+//	included in all copies or substantial portions of the Software.
+//
+//	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+//	EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+//	MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//	NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+//	LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+//	OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+//	WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+
+#import <Foundation/Foundation.h>
+#import <CoreLocation/CoreLocation.h>
+#import "INTULocationRequestDefines.h"
+
+/**
+ An abstraction around CLLocationManager that provides a block-based asynchronous API for obtaining the device's location.
+ 
+ This class will automatically start and stop location services as needed to conserve battery. As a result, this class should
+ not be used in combination with any other code that directly uses the -[CLLocationManager startUpdatingLocation] or
+ -[CLLocationManager stopUpdatingLocation] methods.
+ */
+@interface INTULocationManager : NSObject
+
+/** Returns YES if location services are enabled in the system settings, and the app has NOT been denied/restricted access. Returns NO otherwise. */
+@property (nonatomic, readonly) BOOL locationServicesAvailable;
+
+/** Returns the singleton instance of this class. */
++ (instancetype)sharedInstance;
+
+/**
+ Asynchronously requests the current location of the device using location services.
+ 
+ @param desiredAccuracy The accuracy level desired (refers to the accuracy and recency of the location).
+ @param timeout The maximum amount of time (in seconds) to wait for the desired accuracy before completing.
+ @param block The block to execute upon success, failure, or timeout.
+ 
+ @return The location request ID, which can be used to force early completion or cancel the request while it is in progress.
+ */
+- (NSInteger)requestLocationWithDesiredAccuracy:(INTULocationAccuracy)desiredAccuracy timeout:(NSTimeInterval)timeout block:(INTULocationRequestBlock)block;
+
+/** Immediately forces completion of the location request with the given requestID (if it exists), and executes the original request block with the results.
+    This is effectively a manual timeout, and will result in the request completing with status INTULocationStatusTimedOut. */
+- (void)forceCompleteLocationRequest:(NSInteger)requestID;
+
+/** Immediately cancels the location request with the given requestID (if it exists), without executing the original request block. */
+- (void)cancelLocationRequest:(NSInteger)requestID;
+
+@end