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

http://google-email-uploader-mac.googlecode.com/ · C++ Header · 377 lines · 166 code · 76 blank · 135 comment · 1 complexity · a9788b4d9d020f4477e95dcfaa1abcef MD5 · raw file

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