/core/externals/update-engine/externals/gdata-objectivec-client/Source/HTTPFetcher/GTMHTTPFetchHistory.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//  GTMHTTPFetchHistory.h
 18//
 19
 20//
 21// Users of the GTMHTTPFetcher class may optionally create and set a fetch
 22// history object.  The fetch history provides "memory" between subsequent
 23// fetches, including:
 24//
 25// - For fetch responses with Etag headers, the fetch history
 26//   remembers the response headers. Future fetcher requests to the same URL
 27//   will be given an "If-None-Match" header, telling the server to return
 28//   a 304 Not Modified status if the response is unchanged, reducing the
 29//   server load and network traffic.
 30//
 31// - Optionally, the fetch history can cache the ETagged data that was returned
 32//   in the responses that contained Etag headers. If a later fetch
 33//   results in a 304 status, the fetcher will return the cached ETagged data
 34//   to the client along with a 200 status, hiding the 304.
 35//
 36// - The fetch history can track cookies.
 37//
 38
 39#pragma once
 40
 41#import <Foundation/Foundation.h>
 42
 43#import "GTMHTTPFetcher.h"
 44
 45// default data cache size for when we're caching responses to handle "not
 46// modified" errors for the client
 47
 48#ifdef __cplusplus
 49extern "C" {
 50#endif
 51
 52extern const NSUInteger kGTMDefaultETaggedDataCacheMemoryCapacity;
 53
 54#ifdef __cplusplus
 55}
 56#endif
 57
 58// forward declarations
 59@class GTMURLCache;
 60@class GTMCookieStorage;
 61
 62@interface GTMHTTPFetchHistory : NSObject <GTMHTTPFetchHistoryProtocol> {
 63 @private
 64  GTMURLCache *etaggedDataCache_;
 65  BOOL shouldRememberETags_;
 66  BOOL shouldCacheETaggedData_;        // if NO, then only headers are cached
 67  GTMCookieStorage *cookieStorage_;
 68}
 69
 70// With caching enabled, previously-cached data will be returned instead of
 71// 304 Not Modified responses when repeating a fetch of an URL that previously
 72// included an ETag header in its response
 73@property (assign) BOOL shouldRememberETags;     // default: NO
 74@property (assign) BOOL shouldCacheETaggedData;  // default: NO
 75
 76// the default ETag data cache capacity is kGTMDefaultETaggedDataCacheMemoryCapacity
 77@property (assign) NSUInteger memoryCapacity;
 78
 79@property (retain) GTMCookieStorage *cookieStorage;
 80
 81- (id)initWithMemoryCapacity:(NSUInteger)totalBytes
 82      shouldCacheETaggedData:(BOOL)shouldCacheETaggedData;
 83
 84- (void)updateRequest:(NSMutableURLRequest *)request isHTTPGet:(BOOL)isHTTPGet;
 85
 86- (void)clearETaggedDataCache;
 87- (void)clearHistory;
 88
 89- (void)removeAllCookies;
 90
 91@end
 92
 93
 94// GTMURLCache and GTMCachedURLResponse have interfaces similar to their
 95// NSURLCache counterparts, in hopes that someday the NSURLCache versions
 96// can be used. But in 10.5.8, those are not reliable enough except when
 97// used with +setSharedURLCache. Our goal here is just to cache
 98// responses for handling If-None-Match requests that return
 99// "Not Modified" responses, not for replacing the general URL
100// caches.
101
102@interface GTMCachedURLResponse : NSObject {
103 @private
104  NSURLResponse *response_;
105  NSData *data_;
106  NSDate *useDate_;         // date this response was last saved or used
107  NSDate *reservationDate_; // date this response's ETag was used
108}
109
110@property (readonly) NSURLResponse* response;
111@property (readonly) NSData* data;
112
113// date the response was saved or last accessed
114@property (retain) NSDate *useDate;
115
116// date the response's ETag header was last used for a fetch request
117@property (retain) NSDate *reservationDate;
118
119- (id)initWithResponse:(NSURLResponse *)response data:(NSData *)data;
120@end
121
122@interface GTMURLCache : NSObject {
123  NSMutableDictionary *responses_; // maps request URL to GTMCachedURLResponse
124  NSUInteger memoryCapacity_;      // capacity of NSDatas in the responses
125  NSUInteger totalDataSize_;       // sum of sizes of NSDatas of all responses
126  NSTimeInterval reservationInterval_; // reservation expiration interval
127}
128
129@property (assign) NSUInteger memoryCapacity;
130
131- (id)initWithMemoryCapacity:(NSUInteger)totalBytes;
132
133- (GTMCachedURLResponse *)cachedResponseForRequest:(NSURLRequest *)request;
134- (void)storeCachedResponse:(GTMCachedURLResponse *)cachedResponse forRequest:(NSURLRequest *)request;
135- (void)removeCachedResponseForRequest:(NSURLRequest *)request;
136- (void)removeAllCachedResponses;
137
138// for unit testing
139- (void)setReservationInterval:(NSTimeInterval)secs;
140- (NSDictionary *)responses;
141- (NSUInteger)totalDataSize;
142@end
143
144@interface GTMCookieStorage : NSObject <GTMCookieStorageProtocol> {
145 @private
146  // The cookie storage object manages an array holding cookies, but the array
147  // is allocated externally (it may be in a fetcher object or the static
148  // fetcher cookie array.)  See the fetcher's setCookieStorageMethod:
149  // for allocation of this object and assignment of its cookies array.
150  NSMutableArray *cookies_;
151}
152
153// add all NSHTTPCookies in the supplied array to the storage array,
154// replacing cookies in the storage array as appropriate
155// Side effect: removes expired cookies from the storage array
156- (void)setCookies:(NSArray *)newCookies;
157
158// retrieve all cookies appropriate for the given URL, considering
159// domain, path, cookie name, expiration, security setting.
160// Side effect: removes expired cookies from the storage array
161- (NSArray *)cookiesForURL:(NSURL *)theURL;
162
163// return a cookie with the same name, domain, and path as the
164// given cookie, or else return nil if none found
165//
166// Both the cookie being tested and all stored cookies should
167// be valid (non-nil name, domains, paths)
168- (NSHTTPCookie *)cookieMatchingCookie:(NSHTTPCookie *)cookie;
169
170// remove any expired cookies, excluding cookies with nil expirations
171- (void)removeExpiredCookies;
172
173- (void)removeAllCookies;
174
175@end