PageRenderTime 53ms CodeModel.GetById 16ms app.highlight 31ms RepoModel.GetById 2ms app.codeStats 0ms

/Source/externals/GData/Source/BaseClasses/GDataServiceGoogle.h

http://google-email-uploader-mac.googlecode.com/
C++ Header | 313 lines | 165 code | 69 blank | 79 comment | 0 complexity | 6189e518275511bdafd2e102db9fbc45 MD5 | raw file
  1/* Copyright (c) 2007 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//  GDataServiceGoogle.h
 18//
 19
 20#import "GDataServiceBase.h"
 21
 22#undef _EXTERN
 23#undef _INITIALIZE_AS
 24#ifdef GDATASERVICEGOOGLE_DEFINE_GLOBALS
 25#define _EXTERN
 26#define _INITIALIZE_AS(x) =x
 27#else
 28#define _EXTERN GDATA_EXTERN
 29#define _INITIALIZE_AS(x)
 30#endif
 31
 32_EXTERN NSString* const kGDataServiceErrorCaptchaRequired _INITIALIZE_AS(@"CaptchaRequired");
 33
 34// The default user is the authenticated user
 35//
 36// In the projections of many feeds, the username can be replaced with "default"
 37// to indicate the feed should be for the authenticate user's account
 38_EXTERN NSString* const kGDataServiceDefaultUser _INITIALIZE_AS(@"default");
 39
 40// The Auth token is stored in the response dict under this key.
 41_EXTERN NSString* const kGDataServiceAuthTokenKey _INITIALIZE_AS(@"Auth");
 42
 43// additional server error info keys (capitalized to match the server's
 44// response key)
 45_EXTERN NSString* const kGDataServerInfoStringKey _INITIALIZE_AS(@"Info");
 46
 47_EXTERN NSString* const kGDataServerInfoInvalidSecondFactor _INITIALIZE_AS(@"InvalidSecondFactor");
 48
 49enum {
 50  kGDataBadAuthentication = 403,
 51  kGDataExpectationFailed = 417
 52};
 53
 54@interface NSDictionary (GDataServiceGoogleAdditions)
 55// category to get auth info from the callback error's userInfo
 56- (NSString *)authenticationError;
 57- (NSString *)authenticationInfo;
 58- (NSString *)captchaToken;
 59- (NSURL *)captchaURL;
 60@end
 61
 62@class GDataServiceGoogle;
 63@class GDataServiceTicket;
 64
 65#if NS_BLOCKS_AVAILABLE
 66typedef void (^GDataServiceGoogleCompletionHandler)(GDataServiceTicket *ticket, id object, NSError *error);
 67typedef void (^GDataServiceGoogleFeedBaseCompletionHandler)(GDataServiceTicket *ticket, GDataFeedBase *feed, NSError *error);
 68typedef void (^GDataServiceGoogleEntryBaseCompletionHandler)(GDataServiceTicket *ticket, GDataEntryBase *entry, NSError *error);
 69#else
 70typedef void *GDataServiceGoogleCompletionHandler;
 71typedef void *GDataServiceGoogleFeedBaseCompletionHandler;
 72typedef void *GDataServiceGoogleEntryBaseCompletionHandler;
 73#endif
 74
 75// GDataServiceTicket is the version of a ticket that supports
 76// Google authentication
 77@interface GDataServiceTicket : GDataServiceTicketBase {
 78 @private
 79  GTMHTTPFetcher *authFetcher_;
 80  NSString *authToken_;
 81  NSDate *credentialDate_;
 82}
 83
 84- (void)cancelTicket; // stops fetches in progress
 85
 86// ClientLogin support; not used with OAuth 1 & 2 authorizers
 87- (GTMHTTPFetcher *)authFetcher;
 88- (void)setAuthFetcher:(GTMHTTPFetcher *)fetcher;
 89
 90// ClientLogin support; not used with OAuth 1 & 2 authorizers
 91- (NSString *)authToken;
 92- (void)setAuthToken:(NSString *)str;
 93
 94// ClientLogin support; not used with OAuth 1 & 2 authorizers
 95- (NSDate *)credentialDate;
 96- (void)setCredentialDate:(NSDate *)date;
 97
 98@end
 99
100// GDataServiceGoogle is the version of the service class that supports
101// Google authentication.
102@interface GDataServiceGoogle : GDataServiceBase {
103 @private
104  // ClientLogin support
105  NSString *captchaToken_;
106  NSString *captchaAnswer_;
107
108  NSString *authToken_;
109
110  // AuthSub support
111  NSString *authSubToken_;
112
113  NSString *accountType_; // hosted or google
114
115  NSString *signInDomain_;
116
117  NSString *serviceID_; // typically supplied by the subclass overriding -serviceID
118
119  GTMHTTPFetcher *pendingAuthFetcher_;
120
121  NSDate *credentialDate_;
122
123  BOOL shouldUseMethodOverrideHeader_;
124}
125
126//
127// delegate callback fetches
128//
129
130// fetch a feed, authenticated
131//
132// when the class of the returned feed or entry is not specified, it
133// must be inferable from the XML (by "kind" category elements present
134// in the feed or entry)
135
136- (GDataServiceTicket *)fetchFeedWithURL:(NSURL *)feedURL
137                                delegate:(id)delegate
138                       didFinishSelector:(SEL)finishedSelector;
139
140- (GDataServiceTicket *)fetchFeedWithURL:(NSURL *)feedURL
141                               feedClass:(Class)feedClass
142                                delegate:(id)delegate
143                       didFinishSelector:(SEL)finishedSelector;
144
145- (GDataServiceTicket *)fetchFeedWithURL:(NSURL *)feedURL
146                               feedClass:(Class)feedClass
147                                    ETag:(NSString *)etag
148                                delegate:(id)delegate
149                       didFinishSelector:(SEL)finishedSelector;
150
151// fetch a query, authenticated
152- (GDataServiceTicket *)fetchFeedWithQuery:(GDataQuery *)query
153                                  delegate:(id)delegate
154                         didFinishSelector:(SEL)finishedSelector;
155
156- (GDataServiceTicket *)fetchFeedWithQuery:(GDataQuery *)query
157                                 feedClass:(Class)feedClass
158                                  delegate:(id)delegate
159                         didFinishSelector:(SEL)finishedSelector;
160
161// fetch an entry, authenticated
162- (GDataServiceTicket *)fetchEntryWithURL:(NSURL *)entryURL
163                                 delegate:(id)delegate
164                        didFinishSelector:(SEL)finishedSelector;
165
166- (GDataServiceTicket *)fetchEntryWithURL:(NSURL *)entryURL
167                               entryClass:(Class)entryClass
168                                 delegate:(id)delegate
169                        didFinishSelector:(SEL)finishedSelector;
170
171- (GDataServiceTicket *)fetchEntryWithURL:(NSURL *)entryURL
172                               entryClass:(Class)entryClass
173                                     ETag:(NSString *)etag
174                                 delegate:(id)delegate
175                        didFinishSelector:(SEL)finishedSelector;
176
177// insert an entry, authenticated
178- (GDataServiceTicket *)fetchEntryByInsertingEntry:(GDataEntryBase *)entryToInsert
179                                        forFeedURL:(NSURL *)feedURL
180                                          delegate:(id)delegate
181                                 didFinishSelector:(SEL)finishedSelector;
182
183// update an entry, authenticated
184- (GDataServiceTicket *)fetchEntryByUpdatingEntry:(GDataEntryBase *)entryToUpdate
185                                         delegate:(id)delegate
186                                didFinishSelector:(SEL)finishedSelector;
187
188- (GDataServiceTicket *)fetchEntryByUpdatingEntry:(GDataEntryBase *)entryToUpdate
189                                      forEntryURL:(NSURL *)entryURL
190                                         delegate:(id)delegate
191                                didFinishSelector:(SEL)finishedSelector;
192
193// delete an entry, authenticated
194// (on success, callback will have nil object and error pointers)
195- (GDataServiceTicket *)deleteEntry:(GDataEntryBase *)entryToDelete
196                           delegate:(id)delegate
197                  didFinishSelector:(SEL)finishedSelector;
198
199- (GDataServiceTicket *)deleteResourceURL:(NSURL *)resourceEditURL
200                                     ETag:(NSString *)etag
201                                 delegate:(id)delegate
202                        didFinishSelector:(SEL)finishedSelector;
203
204// fetch a batch feed
205- (GDataServiceTicket *)fetchFeedWithBatchFeed:(GDataFeedBase *)batchFeed
206                               forBatchFeedURL:(NSURL *)feedURL
207                                      delegate:(id)delegate
208                             didFinishSelector:(SEL)finishedSelector;
209
210#if NS_BLOCKS_AVAILABLE
211//
212// Blocks callback fetches
213//
214
215// fetch a feed, authenticated
216- (GDataServiceTicket *)fetchFeedWithURL:(NSURL *)feedURL
217                       completionHandler:(void (^)(GDataServiceTicket *ticket, GDataFeedBase *feed, NSError *error))handler;
218
219// fetch a feed using query, authenticated
220- (GDataServiceTicket *)fetchFeedWithQuery:(GDataQuery *)query
221                         completionHandler:(void (^)(GDataServiceTicket *ticket, GDataFeedBase *feed, NSError *error))handler;
222
223// fetch an entry, authenticated
224 - (GDataServiceTicket *)fetchEntryWithURL:(NSURL *)entryURL
225                         completionHandler:(void (^)(GDataServiceTicket *ticket, GDataEntryBase *entry, NSError *error))handler;
226
227// insert an entry, authenticated
228- (GDataServiceTicket *)fetchEntryByInsertingEntry:(GDataEntryBase *)entryToInsert
229                                        forFeedURL:(NSURL *)feedURL
230                                 completionHandler:(void (^)(GDataServiceTicket *ticket, GDataEntryBase *entry, NSError *error))handler;
231
232// update an entry, authenticated
233- (GDataServiceTicket *)fetchEntryByUpdatingEntry:(GDataEntryBase *)entryToUpdate
234                                completionHandler:(void (^)(GDataServiceTicket *ticket, GDataEntryBase *entry, NSError *error))handler;
235
236// update an entry, authenticated (use this for updating via chunked uploads,
237// with the URL from the entry's uploadEditLink)
238- (GDataServiceTicket *)fetchEntryByUpdatingEntry:(GDataEntryBase *)entryToUpdate
239                                      forEntryURL:(NSURL *)entryURL
240                                completionHandler:(void (^)(GDataServiceTicket *ticket, GDataEntryBase *entry, NSError *error))handler;
241
242// delete an entry, authenticated
243// (on success, callback will have receive nil pointers for both object and error)
244- (GDataServiceTicket *)deleteEntry:(GDataEntryBase *)entryToDelete
245                  completionHandler:(void (^)(GDataServiceTicket *ticket, id nilObject, NSError *error))handler;
246
247- (GDataServiceTicket *)deleteResourceURL:(NSURL *)resourceEditURL
248                                     ETag:(NSString *)etag
249                        completionHandler:(void (^)(GDataServiceTicket *ticket, id nilObject, NSError *error))handler;
250
251// fetch a batch feed, authenticated
252- (GDataServiceTicket *)fetchFeedWithBatchFeed:(GDataFeedBase *)batchFeed
253                               forBatchFeedURL:(NSURL *)feedURL
254                             completionHandler:(void (^)(GDataServiceTicket *ticket, GDataFeedBase *feed, NSError *error))handler;
255#endif // NS_BLOCKS_AVAILABLE
256
257
258// authenticate without fetching a feed or entry
259//
260// authSelector has a signature matching:
261//   - (void)ticket:(GDataServiceTicket *)ticket authenticatedWithError:(NSError *)error;
262//
263// If authentication succeeds, the selector is invoked with a nil error,
264// and the auth token is available as [[ticket service] authToken]
265//
266// The returned ticket may be ignored unless the caller wants to cancel it
267- (GDataServiceTicket *)authenticateWithDelegate:(id)delegate
268                         didAuthenticateSelector:(SEL)authSelector;
269
270- (void)setCaptchaToken:(NSString *)captchaToken
271          captchaAnswer:(NSString *)captchaAnswer;
272
273- (NSString *)authToken;
274- (void)setAuthToken:(NSString *)str;
275
276- (NSString *)authSubToken;
277- (void)setAuthSubToken:(NSString *)str;
278
279+ (NSString *)authorizationScope;
280
281// default account type is HOSTED_OR_GOOGLE
282- (NSString *)accountType;
283- (void)setAccountType:(NSString *)str;
284
285// default sign-in domain is www.google.com
286- (NSString *)signInDomain;
287- (void)setSignInDomain:(NSString *)domain;
288
289// when it's not possible to do http methods other than GET and POST,
290// the X-HTTP-Method-Override header can be used in conjunction with POST
291// for other commands.  Default for this is NO.
292- (BOOL)shouldUseMethodOverrideHeader;
293- (void)setShouldUseMethodOverrideHeader:(BOOL)flag;
294
295+ (NSString *)serviceID; // implemented by subclasses, like @"cl" for calendar
296
297- (void)setServiceID:(NSString *)str; // call only if not using a subclass
298- (NSString *)serviceID;
299
300+ (NSString *)serviceRootURLString;
301
302// subclasses may specify what namespaces to attach to posted user entries
303// when the entries lack explicit root-level namespaces
304+ (NSDictionary *)standardServiceNamespaces;
305
306- (GTMHTTPFetcher *)pendingAuthFetcher;
307- (void)setPendingAuthFetcher:(GTMHTTPFetcher *)fetcher;
308
309// the date the credentials were set
310- (NSDate *)credentialDate;
311- (void)setCredentialDate:(NSDate *)date;
312
313@end