//
//  ASIHTTPRequest.h
//
//  Created by Ben Copsey on 04/10/2007.
//  Copyright 2007-2008 All-Seeing Interactive. All rights reserved.
//
//  A guide to the main features is available at:
//  http://allseeing-i.com/ASIHTTPRequest
//
//  Portions are based on the ImageClient example from Apple:
//  See: http://developer.apple.com/samplecode/ImageClient/listing37.html


// Dammit, importing frameworks when you are targetting two platforms is a PITA
#if TARGET_OS_IPHONE
    #import <CFNetwork/CFNetwork.h>
#endif
#import <stdio.h>

typedef enum _ASINetworkErrorType {
    ASIConnectionFailureErrorType = 1,
    ASIRequestTimedOutErrorType = 2,
    ASIAuthenticationErrorType = 3,
    ASIRequestCancelledErrorType = 4,
    ASIUnableToCreateRequestErrorType = 5,
    ASIInternalErrorWhileBuildingRequestType  = 6,
    ASIInternalErrorWhileApplyingCredentialsType  = 7,
    ASIFileManagementError = 8
    
} ASINetworkErrorType;

@interface ASIHTTPRequest : NSOperation {
    
    // The url for this operation, should include GET params in the query string where appropriate
    NSURL *url; 
    
    // The delegate, you need to manage setting and talking to your delegate in your subclasses
    id delegate;
    
    // HTTP method to use (GET / POST / PUT / DELETE). Defaults to GET
    NSString *requestMethod;
    
    // Request body
    NSData *postBody;
    
    // Dictionary for custom HTTP request headers
    NSMutableDictionary *requestHeaders;
    
    // Will be populated with HTTP response headers from the server
    NSDictionary *responseHeaders;
    
    // Can be used to manually insert cookie headers to a request, but it's more likely that sessionCookies will do this for you
    NSMutableArray *requestCookies;
    
    // Will be populated with cookies
    NSArray *responseCookies;
    
    // If use useCookiePersistance is true, network requests will present valid cookies from previous requests
    BOOL useCookiePersistance;
    
    // If useKeychainPersistance is true, network requests will attempt to read credentials from the keychain, and will save them in the keychain when they are successfully presented
    BOOL useKeychainPersistance;
    
    // If useSessionPersistance is true, network requests will save credentials and reuse for the duration of the session (until clearSession is called)
    BOOL useSessionPersistance;
    
    // If allowCompressedResponse is true, requests will inform the server they can accept compressed data, and will automatically decompress gzipped responses. Default is true.
    BOOL allowCompressedResponse;
    
    // When downloadDestinationPath is set, the result of this request will be downloaded to the file at this location
    // If downloadDestinationPath is not set, download data will be stored in memory
    NSString *downloadDestinationPath;
    
    //The location that files will be downloaded to. Once a download is complete, files will be decompressed (if necessary) and moved to downloadDestinationPath
    NSString *temporaryFileDownloadPath;
    
    // Used for writing data to a file when downloadDestinationPath is set
    NSOutputStream *outputStream;
    
    // When the request fails or completes successfully, complete will be true
    BOOL complete;
    
    // If an error occurs, error will contain an NSError
    // If error code is = ASIConnectionFailureErrorType (1, Connection failure occurred) - inspect [[error userInfo] objectForKey:NSUnderlyingErrorKey] for more information
    NSError *error;
    
    // If an authentication error occurs, we give the delegate a chance to handle it, ignoreError will be set to true
    BOOL ignoreError;
    
    // Username and password used for authentication
    NSString *username;
    NSString *password;
    
    // Domain used for NTLM authentication
    NSString *domain;
    
    // Delegate for displaying upload progress (usually an NSProgressIndicator, but you can supply a different object and handle this yourself)
    id uploadProgressDelegate;
    
    // Delegate for displaying download progress (usually an NSProgressIndicator, but you can supply a different object and handle this yourself)
    id downloadProgressDelegate;
    
    // Whether we've seen the headers of the response yet
    BOOL haveExaminedHeaders;
    
    // Data we receive will be stored here. Data may be compressed unless allowCompressedResponse is false - you should use [request responseData] instead in most cases
    NSMutableData *rawResponseData;
    
    // Used for sending and receiving data
    CFHTTPMessageRef request;    
    CFReadStreamRef readStream;
    
    // Authentication currently being used for prompting and resuming
    CFHTTPAuthenticationRef requestAuthentication; 
    NSMutableDictionary *requestCredentials;
    
    // HTTP status code, eg: 200 = OK, 404 = Not found etc
    int responseStatusCode;
    
    // Size of the response
    unsigned long long contentLength;
    
    // Size of the POST payload
    unsigned long long postLength;    
    
    // The total amount of downloaded data
    unsigned long long totalBytesRead;
    
    // Last amount of data read (used for incrementing progress)
    unsigned long long lastBytesRead;
    // Last amount of data sent (used for incrementing progress)
    unsigned long long lastBytesSent;
    
    // Realm for authentication when credentials are required
    NSString *authenticationRealm;
    
    // This lock will block the request until the delegate supplies authentication info
    NSConditionLock *authenticationLock;
    
    // This lock prevents the operation from being cancelled at an inopportune moment
    NSLock *cancelledLock;
    
    // Called on the delegate when the request completes successfully
    SEL didFinishSelector;
    
    // Called on the delegate when the request fails
    SEL didFailSelector;
    
    // Used for recording when something last happened during the request, we will compare this value with the current date to time out requests when appropriate
    NSDate *lastActivityTime;
    
    // Number of seconds to wait before timing out - default is 10
    NSTimeInterval timeOutSeconds;
    
    // Autorelease pool for the main loop, since it's highly likely that this operation will run in a thread
    NSAutoreleasePool *pool;
    
    // Will be YES when a HEAD request will handle the content-length before this request starts
    BOOL shouldResetProgressIndicators;
    
    // Used by HEAD requests when showAccurateProgress is YES to preset the content-length for this request
    ASIHTTPRequest *mainRequest;
    
    // When NO, this request will only update the progress indicator when it completes
    // When YES, this request will update the progress indicator according to how much data it has received so far
    // The default for requests is YES
    // Also see the comments in ASINetworkQueue.h
    BOOL showAccurateProgress;
    
    // Used to ensure the progress indicator is only incremented once when showAccurateProgress = NO
    BOOL updatedProgress;
    
    // Prevents the body of the post being built more than once (largely for subclasses)
    BOOL haveBuiltPostBody;
    
    unsigned long long uploadBufferSize;
    
    NSStringEncoding defaultResponseEncoding;
    NSStringEncoding responseEncoding;
}

#pragma mark init / dealloc

// Should be an HTTP or HTTPS url, may include username and password if appropriate
- (id)initWithURL:(NSURL *)newURL;

#pragma mark setup request

// Add a custom header to the request
- (void)addRequestHeader:(NSString *)header value:(NSString *)value;

- (void)buildPostBody;

#pragma mark get information about this request

// Returns the contents of the result as an NSString (not appropriate for binary data - used responseData instead)
- (NSString *)responseString;

// Response data, automatically uncompressed where appropriate
- (NSData *)responseData;

// Returns true if the response was gzip compressed
- (BOOL)isResponseCompressed;

#pragma mark request logic

// Start loading the request
- (void)loadRequest;

// Cancel loading and clean up
- (void)cancelLoad;

#pragma mark upload/download progress

// Called on main thread to update progress delegates
- (void)updateProgressIndicators;
- (void)resetUploadProgress:(unsigned long long)value;
- (void)updateUploadProgress;
- (void)resetDownloadProgress:(unsigned long long)value;
- (void)updateDownloadProgress;

// Called when authorisation is needed, as we only find out we don't have permission to something when the upload is complete
- (void)removeUploadProgressSoFar;

// Helper method for interacting with progress indicators to abstract the details of different APIS (NSProgressIndicator and UIProgressView)
+ (void)setProgress:(double)progress forProgressIndicator:(id)indicator;

#pragma mark handling request complete / failure

// Called when a request completes successfully, lets the delegate now via didFinishSelector
- (void)requestFinished;

// Called when a request fails, and lets the delegate now via didFailSelector
- (void)failWithError:(NSError *)theError;

#pragma mark http authentication stuff

// Reads the response headers to find the content length, and returns true if the request needs a username and password (or if those supplied were incorrect)
- (BOOL)readResponseHeadersReturningAuthenticationFailure;

// Apply credentials to this request
- (BOOL)applyCredentials:(NSMutableDictionary *)newCredentials;

// Attempt to obtain credentials for this request from the URL, username and password or keychain
- (NSMutableDictionary *)findCredentials;

// Unlock (unpause) the request thread so it can resume the request
// Should be called by delegates when they have populated the authentication information after an authentication challenge
- (void)retryWithAuthentication;

// Apply authentication information and resume the request after an authentication challenge
- (void)attemptToApplyCredentialsAndResume;


#pragma mark stream status handlers

// CFnetwork event handlers
- (void)handleNetworkEvent:(CFStreamEventType)type;
- (void)handleBytesAvailable;
- (void)handleStreamComplete;
- (void)handleStreamError;

#pragma mark managing the session

+ (void)setSessionCredentials:(NSMutableDictionary *)newCredentials;
+ (void)setSessionAuthentication:(CFHTTPAuthenticationRef)newAuthentication;

#pragma mark keychain storage

// Save credentials for this request to the keychain
- (void)saveCredentialsToKeychain:(NSMutableDictionary *)newCredentials;

// Save creddentials to the keychain
+ (void)saveCredentials:(NSURLCredential *)credentials forHost:(NSString *)host port:(int)port protocol:(NSString *)protocol realm:(NSString *)realm;

// Return credentials from the keychain
+ (NSURLCredential *)savedCredentialsForHost:(NSString *)host port:(int)port protocol:(NSString *)protocol realm:(NSString *)realm;

// Remove credentials from the keychain
+ (void)removeCredentialsForHost:(NSString *)host port:(int)port protocol:(NSString *)protocol realm:(NSString *)realm;

// We keep track of any cookies we accept, so that we can remove them from the persistent store later
+ (void)setSessionCookies:(NSMutableArray *)newSessionCookies;
+ (NSMutableArray *)sessionCookies;

// Dump all session data (authentication and cookies)
+ (void)clearSession;

#pragma mark gzip compression

// Uncompress gzipped data with zlib
+ (NSData *)uncompressZippedData:(NSData*)compressedData;

// Uncompress gzipped data from a file into another file, used when downloading to a file
+ (int)uncompressZippedDataFromFile:(NSString *)sourcePath toFile:(NSString *)destinationPath;
+ (int)uncompressZippedDataFromSource:(FILE *)source toDestination:(FILE *)dest;

@property (retain) NSString *username;
@property (retain) NSString *password;
@property (retain) NSString *domain;

@property (retain,readonly) NSURL *url;
@property (assign) id delegate;
@property (assign) id uploadProgressDelegate;
@property (assign) id downloadProgressDelegate;
@property (assign) BOOL useKeychainPersistance;
@property (assign) BOOL useSessionPersistance;
@property (retain) NSString *downloadDestinationPath;
@property (retain,readonly) NSString *temporaryFileDownloadPath;
@property (assign) SEL didFinishSelector;
@property (assign) SEL didFailSelector;
@property (retain,readonly) NSString *authenticationRealm;
@property (retain) NSError *error;
@property (assign,readonly) BOOL complete;
@property (retain) NSDictionary *responseHeaders;
@property (retain) NSMutableDictionary *requestHeaders;
@property (retain) NSMutableArray *requestCookies;
@property (retain) NSArray *responseCookies;
@property (assign) BOOL useCookiePersistance;
@property (retain) NSDictionary *requestCredentials;
@property (assign) int responseStatusCode;
@property (retain) NSMutableData *rawResponseData;
@property (retain) NSDate *lastActivityTime;
@property (assign) NSTimeInterval timeOutSeconds;
@property (retain) NSString *requestMethod;
@property (retain,setter=setPostBody:) NSData *postBody;
@property (assign) unsigned long long contentLength;
@property (assign) unsigned long long postLength;
@property (assign) BOOL shouldResetProgressIndicators;
@property (retain) ASIHTTPRequest *mainRequest;
@property (assign) BOOL showAccurateProgress;
@property (assign,readonly) unsigned long long totalBytesRead;
@property (assign) unsigned long long uploadBufferSize;
@property (assign) NSStringEncoding defaultResponseEncoding;
@property (assign) NSStringEncoding responseEncoding;
@property (assign) BOOL allowCompressedResponse;
@end
