/Source/externals/GData/Source/OAuth2/Touch/GTMOAuth2ViewControllerTouch.h

  1/* Copyright (c) 2011 Google Inc.
  2 *
  3 * Licensed under the Apache License, Version 2.0 (the "License");
  4 * you may not use this file except in compliance with the License.
  5 * You may obtain a copy of the License at
  6 *
  7 *     http://www.apache.org/licenses/LICENSE-2.0
  8 *
  9 * Unless required by applicable law or agreed to in writing, software
 10 * distributed under the License is distributed on an "AS IS" BASIS,
 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12 * See the License for the specific language governing permissions and
 13 * limitations under the License.
 14 */
 15
 16//
 17// GTMOAuth2ViewControllerTouch.h
 18//
 19// This view controller for iPhone handles sign-in via OAuth to Google or
 20// other services.
 21//
 22// This controller is not reusable; create a new instance of this controller
 23// every time the user will sign in.
 24//
 25
 26#if GTM_INCLUDE_OAUTH2 || !GDATA_REQUIRE_SERVICE_INCLUDES
 27
 28#import <Foundation/Foundation.h>
 29
 30#if TARGET_OS_IPHONE
 31
 32#import <UIKit/UIKit.h>
 33
 34#import "GTMOAuth2Authentication.h"
 35
 36#ifdef __cplusplus
 37extern "C" {
 38#endif
 39
 40extern NSString *const kGTMOAuth2KeychainErrorDomain;
 41
 42#ifdef __cplusplus
 43}
 44#endif
 45
 46@class GTMOAuth2SignIn;
 47@class GTMOAuth2ViewControllerTouch;
 48
 49typedef void (^GTMOAuth2ViewControllerCompletionHandler)(GTMOAuth2ViewControllerTouch *viewController, GTMOAuth2Authentication *auth, NSError *error);
 50
 51@interface GTMOAuth2ViewControllerTouch : UIViewController<UINavigationControllerDelegate, UIWebViewDelegate> {
 52 @private
 53  UIButton *backButton_;
 54  UIButton *forwardButton_;
 55  UIActivityIndicatorView *initialActivityIndicator_;
 56  UIView *navButtonsView_;
 57  UIBarButtonItem *rightBarButtonItem_;
 58  UIWebView *webView_;
 59
 60  // The object responsible for the sign-in networking sequence; it holds
 61  // onto the authentication object as well.
 62  GTMOAuth2SignIn *signIn_;
 63
 64  // the page request to load when awakeFromNib occurs
 65  NSURLRequest *request_;
 66
 67  // The user we're calling back
 68  //
 69  // The delegate is retained only until the callback is invoked
 70  // or the sign-in is canceled
 71  id delegate_;
 72  SEL finishedSelector_;
 73
 74#if NS_BLOCKS_AVAILABLE
 75  GTMOAuth2ViewControllerCompletionHandler completionBlock_;
 76
 77  void (^popViewBlock_)(void);
 78#endif
 79
 80  NSString *keychainItemName_;
 81  CFTypeRef keychainItemAccessibility_;
 82
 83  // if non-nil, the html string to be displayed immediately upon opening
 84  // of the web view
 85  NSString *initialHTMLString_;
 86
 87  // set to 1 or -1 if the user sets the showsInitialActivityIndicator
 88  // property
 89  int mustShowActivityIndicator_;
 90
 91  // if non-nil, the URL for which cookies will be deleted when the
 92  // browser view is dismissed
 93  NSURL *browserCookiesURL_;
 94
 95  id userData_;
 96  NSMutableDictionary *properties_;
 97
 98#if __IPHONE_OS_VERSION_MIN_REQUIRED < 60000
 99  // We delegate the decision to our owning NavigationController (if any).
100  // But, the NavigationController will call us back, and ask us.
101  // BOOL keeps us from infinite looping.
102  BOOL isInsideShouldAutorotateToInterfaceOrientation_;
103#endif
104
105  // YES, when view first shown in this signIn session.
106  BOOL isViewShown_;
107
108  // YES, after the view has fully transitioned in.
109  BOOL didViewAppear_;
110
111  // YES between sends of start and stop notifications
112  BOOL hasNotifiedWebViewStartedLoading_;
113
114  // To prevent us from calling our delegate's selector more than once.
115  BOOL hasCalledFinished_;
116
117  // Set in a webView callback.
118  BOOL hasDoneFinalRedirect_;
119
120  // Set during the pop initiated by the sign-in object; otherwise,
121  // viewWillDisappear indicates that some external change of the view
122  // has stopped the sign-in.
123  BOOL didDismissSelf_;
124
125  // Work around default cookie policy bug in iOS 7; see comments in viewWillAppear.
126  NSHTTPCookieAcceptPolicy savedCookiePolicy_;
127}
128
129// the application and service name to use for saving the auth tokens
130// to the keychain
131@property (nonatomic, copy) NSString *keychainItemName;
132
133// the keychain item accessibility is a system constant for use
134// with kSecAttrAccessible.
135//
136// Since it's a system constant, we do not need to retain it.
137@property (nonatomic, assign) CFTypeRef keychainItemAccessibility;
138
139// optional html string displayed immediately upon opening the web view
140//
141// This string is visible just until the sign-in web page loads, and
142// may be used for a "Loading..." type of message or to set the
143// initial view color
144@property (nonatomic, copy) NSString *initialHTMLString;
145
146// an activity indicator shows during initial webview load when no initial HTML
147// string is specified, but the activity indicator can be forced to be shown
148// with this property
149@property (nonatomic, assign) BOOL showsInitialActivityIndicator;
150
151// the underlying object to hold authentication tokens and authorize http
152// requests
153@property (nonatomic, retain, readonly) GTMOAuth2Authentication *authentication;
154
155// the underlying object which performs the sign-in networking sequence
156@property (nonatomic, retain, readonly) GTMOAuth2SignIn *signIn;
157
158// user interface elements
159@property (nonatomic, retain) IBOutlet UIButton *backButton;
160@property (nonatomic, retain) IBOutlet UIButton *forwardButton;
161@property (nonatomic, retain) IBOutlet UIActivityIndicatorView *initialActivityIndicator;
162@property (nonatomic, retain) IBOutlet UIView *navButtonsView;
163@property (nonatomic, retain) IBOutlet UIBarButtonItem *rightBarButtonItem;
164@property (nonatomic, retain) IBOutlet UIWebView *webView;
165
166#if NS_BLOCKS_AVAILABLE
167// An optional block to be called when the view should be popped. If not set,
168// the view controller will use its navigation controller to pop the view.
169@property (nonatomic, copy) void (^popViewBlock)(void);
170#endif
171
172// the default timeout for an unreachable network during display of the
173// sign-in page is 30 seconds; set this to 0 to have no timeout
174@property (nonatomic, assign) NSTimeInterval networkLossTimeoutInterval;
175
176// if set, cookies are deleted for this URL when the view is hidden
177//
178// For Google sign-ins, this is set by default to https://google.com/accounts
179// but it may be explicitly set to nil to disable clearing of browser cookies
180@property (nonatomic, retain) NSURL *browserCookiesURL;
181
182// userData is retained for the convenience of the caller
183@property (nonatomic, retain) id userData;
184
185// Stored property values are retained for the convenience of the caller
186- (void)setProperty:(id)obj forKey:(NSString *)key;
187- (id)propertyForKey:(NSString *)key;
188
189@property (nonatomic, retain) NSDictionary *properties;
190
191// Method for creating a controller to authenticate to Google services
192//
193// scope is the requested scope of authorization
194//   (like "http://www.google.com/m8/feeds")
195//
196// keychain item name is used for storing the token on the keychain,
197//   keychainItemName should be like "My Application: Google Latitude"
198//   (or set to nil if no persistent keychain storage is desired)
199//
200// the delegate is retained only until the finished selector is invoked
201//   or the sign-in is canceled
202//
203// If you don't like the default nibName and bundle, you can change them
204// using the UIViewController properties once you've made one of these.
205//
206// finishedSelector is called after authentication completes. It should follow
207// this signature.
208//
209// - (void)viewController:(GTMOAuth2ViewControllerTouch *)viewController
210//       finishedWithAuth:(GTMOAuth2Authentication *)auth
211//                  error:(NSError *)error;
212//
213#if !GTM_OAUTH2_SKIP_GOOGLE_SUPPORT
214+ (id)controllerWithScope:(NSString *)scope
215                 clientID:(NSString *)clientID
216             clientSecret:(NSString *)clientSecret
217         keychainItemName:(NSString *)keychainItemName
218                 delegate:(id)delegate
219         finishedSelector:(SEL)finishedSelector;
220
221- (id)initWithScope:(NSString *)scope
222           clientID:(NSString *)clientID
223       clientSecret:(NSString *)clientSecret
224   keychainItemName:(NSString *)keychainItemName
225           delegate:(id)delegate
226   finishedSelector:(SEL)finishedSelector;
227
228#if NS_BLOCKS_AVAILABLE
229+ (id)controllerWithScope:(NSString *)scope
230                 clientID:(NSString *)clientID
231             clientSecret:(NSString *)clientSecret
232         keychainItemName:(NSString *)keychainItemName
233        completionHandler:(GTMOAuth2ViewControllerCompletionHandler)handler;
234
235- (id)initWithScope:(NSString *)scope
236           clientID:(NSString *)clientID
237       clientSecret:(NSString *)clientSecret
238   keychainItemName:(NSString *)keychainItemName
239  completionHandler:(GTMOAuth2ViewControllerCompletionHandler)handler;
240#endif
241#endif
242
243// Create a controller for authenticating to non-Google services, taking
244//   explicit endpoint URLs and an authentication object
245+ (id)controllerWithAuthentication:(GTMOAuth2Authentication *)auth
246                  authorizationURL:(NSURL *)authorizationURL
247                  keychainItemName:(NSString *)keychainItemName  // may be nil
248                          delegate:(id)delegate
249                  finishedSelector:(SEL)finishedSelector;
250
251// This is the designated initializer
252- (id)initWithAuthentication:(GTMOAuth2Authentication *)auth
253            authorizationURL:(NSURL *)authorizationURL
254            keychainItemName:(NSString *)keychainItemName
255                    delegate:(id)delegate
256            finishedSelector:(SEL)finishedSelector;
257
258#if NS_BLOCKS_AVAILABLE
259+ (id)controllerWithAuthentication:(GTMOAuth2Authentication *)auth
260                  authorizationURL:(NSURL *)authorizationURL
261                  keychainItemName:(NSString *)keychainItemName  // may be nil
262                 completionHandler:(GTMOAuth2ViewControllerCompletionHandler)handler;
263
264- (id)initWithAuthentication:(GTMOAuth2Authentication *)auth
265            authorizationURL:(NSURL *)authorizationURL
266            keychainItemName:(NSString *)keychainItemName
267           completionHandler:(GTMOAuth2ViewControllerCompletionHandler)handler;
268#endif
269
270// subclasses may override authNibName to specify a custom name
271+ (NSString *)authNibName;
272
273// subclasses may override authNibBundle to specify a custom bundle
274+ (NSBundle *)authNibBundle;
275
276// subclasses may override setUpNavigation to provide their own navigation
277// controls
278- (void)setUpNavigation;
279
280// apps may replace the sign-in class with their own subclass of it
281+ (Class)signInClass;
282+ (void)setSignInClass:(Class)theClass;
283
284- (void)cancelSigningIn;
285
286// revocation of an authorized token from Google
287#if !GTM_OAUTH2_SKIP_GOOGLE_SUPPORT
288+ (void)revokeTokenForGoogleAuthentication:(GTMOAuth2Authentication *)auth;
289#endif
290
291//
292// Keychain
293//
294
295// create an authentication object for Google services from the access
296// token and secret stored in the keychain; if no token is available, return
297// an unauthorized auth object. OK to pass NULL for the error parameter.
298#if !GTM_OAUTH2_SKIP_GOOGLE_SUPPORT
299+ (GTMOAuth2Authentication *)authForGoogleFromKeychainForName:(NSString *)keychainItemName
300                                                     clientID:(NSString *)clientID
301                                                 clientSecret:(NSString *)clientSecret
302                                                        error:(NSError **)error;
303// Equivalent to calling the method above with a NULL error parameter.
304+ (GTMOAuth2Authentication *)authForGoogleFromKeychainForName:(NSString *)keychainItemName
305                                                     clientID:(NSString *)clientID
306                                                 clientSecret:(NSString *)clientSecret;
307#endif
308
309// add tokens from the keychain, if available, to the authentication object
310//
311// returns YES if the authentication object was authorized from the keychain
312+ (BOOL)authorizeFromKeychainForName:(NSString *)keychainItemName
313                      authentication:(GTMOAuth2Authentication *)auth
314                               error:(NSError **)error;
315
316// method for deleting the stored access token and secret, useful for "signing
317// out"
318+ (BOOL)removeAuthFromKeychainForName:(NSString *)keychainItemName;
319
320// method for saving the stored access token and secret
321//
322// returns YES if the save was successful.  OK to pass NULL for the error
323// parameter.
324+ (BOOL)saveParamsToKeychainForName:(NSString *)keychainItemName
325                      accessibility:(CFTypeRef)accessibility
326                     authentication:(GTMOAuth2Authentication *)auth
327                              error:(NSError **)error;
328
329// older version, defaults to kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
330+ (BOOL)saveParamsToKeychainForName:(NSString *)keychainItemName
331                     authentication:(GTMOAuth2Authentication *)auth;
332
333@end
334
335// To function, GTMOAuth2ViewControllerTouch needs a certain amount of access
336// to the iPhone's keychain. To keep things simple, its keychain access is
337// broken out into a helper class. We declare it here in case you'd like to use
338// it too, to store passwords.
339
340enum {
341  kGTMOAuth2KeychainErrorBadArguments = -1301,
342  kGTMOAuth2KeychainErrorNoPassword = -1302
343};
344
345
346@interface GTMOAuth2Keychain : NSObject
347
348+ (GTMOAuth2Keychain *)defaultKeychain;
349
350// OK to pass nil for the error parameter.
351- (NSString *)passwordForService:(NSString *)service
352                         account:(NSString *)account
353                           error:(NSError **)error;
354
355// OK to pass nil for the error parameter.
356- (BOOL)removePasswordForService:(NSString *)service
357                         account:(NSString *)account
358                           error:(NSError **)error;
359
360// OK to pass nil for the error parameter.
361//
362// accessibility should be one of the constants for kSecAttrAccessible
363// such as kSecAttrAccessibleWhenUnlocked
364- (BOOL)setPassword:(NSString *)password
365         forService:(NSString *)service
366      accessibility:(CFTypeRef)accessibility
367            account:(NSString *)account
368              error:(NSError **)error;
369
370// For unit tests: allow setting a mock object
371+ (void)setDefaultKeychain:(GTMOAuth2Keychain *)keychain;
372
373@end
374
375#endif // TARGET_OS_IPHONE
376
377#endif // #if GTM_INCLUDE_OAUTH2 || !GDATA_REQUIRE_SERVICE_INCLUDES