// // ASIHTTPRequest.h // // Created by Ben Copsey on 04/10/2007. // Copyright 2007-2011 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 #import #if TARGET_OS_IPHONE #import #if __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_4_0 #import // Necessary for background task support #endif #endif #import #import "ASIHTTPRequestConfig.h" #import "ASIHTTPRequestDelegate.h" #import "ASIProgressDelegate.h" #import "ASICacheDelegate.h" @class ASIDataDecompressor; extern NSString *ASIHTTPRequestVersion; // Make targeting different platforms more reliable // See: http://www.blumtnwerx.com/blog/2009/06/cross-sdk-code-hygiene-in-xcode/ #ifndef __IPHONE_3_2 #define __IPHONE_3_2 30200 #endif #ifndef __IPHONE_4_0 #define __IPHONE_4_0 40000 #endif #ifndef __MAC_10_5 #define __MAC_10_5 1050 #endif #ifndef __MAC_10_6 #define __MAC_10_6 1060 #endif typedef enum _ASIAuthenticationState { ASINoAuthenticationNeededYet = 0, ASIHTTPAuthenticationNeeded = 1, ASIProxyAuthenticationNeeded = 2 } ASIAuthenticationState; typedef enum _ASINetworkErrorType { ASIConnectionFailureErrorType = 1, ASIRequestTimedOutErrorType = 2, ASIAuthenticationErrorType = 3, ASIRequestCancelledErrorType = 4, ASIUnableToCreateRequestErrorType = 5, ASIInternalErrorWhileBuildingRequestType = 6, ASIInternalErrorWhileApplyingCredentialsType = 7, ASIFileManagementError = 8, ASITooMuchRedirectionErrorType = 9, ASIUnhandledExceptionError = 10, ASICompressionError = 11 } ASINetworkErrorType; // The error domain that all errors generated by ASIHTTPRequest use extern NSString* const NetworkRequestErrorDomain; // You can use this number to throttle upload and download bandwidth in iPhone OS apps send or receive a large amount of data // This may help apps that might otherwise be rejected for inclusion into the app store for using excessive bandwidth // This number is not official, as far as I know there is no officially documented bandwidth limit extern unsigned long const ASIWWANBandwidthThrottleAmount; #if NS_BLOCKS_AVAILABLE typedef void (^ASIBasicBlock)(void); typedef void (^ASIHeadersBlock)(NSDictionary *responseHeaders); typedef void (^ASISizeBlock)(long long size); typedef void (^ASIProgressBlock)(unsigned long long size, unsigned long long total); typedef void (^ASIDataBlock)(NSData *data); #endif @interface ASIHTTPRequest : NSOperation { // The url for this operation, should include GET params in the query string where appropriate NSURL *url; // Will always contain the original url used for making the request (the value of url can change when a request is redirected) NSURL *originalURL; // Temporarily stores the url we are about to redirect to. Will be nil again when we do redirect NSURL *redirectURL; // The delegate - will be notified of various changes in state via the ASIHTTPRequestDelegate protocol id delegate; // Another delegate that is also notified of request status changes and progress updates // Generally, you won't use this directly, but ASINetworkQueue sets itself as the queue so it can proxy updates to its own delegates // NOTE: WILL BE RETAINED BY THE REQUEST id queue; // HTTP method to use (eg: GET / POST / PUT / DELETE / HEAD etc). Defaults to GET NSString *requestMethod; // Request body - only used when the whole body is stored in memory (shouldStreamPostDataFromDisk is false) NSMutableData *postBody; // gzipped request body used when shouldCompressRequestBody is YES NSData *compressedPostBody; // When true, post body will be streamed from a file on disk, rather than loaded into memory at once (useful for large uploads) // Automatically set to true in ASIFormDataRequests when using setFile:forKey: BOOL shouldStreamPostDataFromDisk; // Path to file used to store post body (when shouldStreamPostDataFromDisk is true) // You can set this yourself - useful if you want to PUT a file from local disk NSString *postBodyFilePath; // Path to a temporary file used to store a deflated post body (when shouldCompressPostBody is YES) NSString *compressedPostBodyFilePath; // Set to true when ASIHTTPRequest automatically created a temporary file containing the request body (when true, the file at postBodyFilePath will be deleted at the end of the request) BOOL didCreateTemporaryPostDataFile; // Used when writing to the post body when shouldStreamPostDataFromDisk is true (via appendPostData: or appendPostDataFromFile:) NSOutputStream *postBodyWriteStream; // Used for reading from the post body when sending the request NSInputStream *postBodyReadStream; // Dictionary for custom HTTP request headers NSMutableDictionary *requestHeaders; // Set to YES when the request header dictionary has been populated, used to prevent this happening more than once BOOL haveBuiltRequestHeaders; // 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 useCookiePersistence is true, network requests will present valid cookies from previous requests BOOL useCookiePersistence; // If useKeychainPersistence 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 useKeychainPersistence; // If useSessionPersistence is true, network requests will save credentials and reuse for the duration of the session (until clearSession is called) BOOL useSessionPersistence; // 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; // If shouldCompressRequestBody is true, the request body will be gzipped. Default is false. // You will probably need to enable this feature on your webserver to make this work. Tested with apache only. BOOL shouldCompressRequestBody; // 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; // If the response is gzipped and shouldWaitToInflateCompressedResponses is NO, a file will be created at this path containing the inflated response as it comes in NSString *temporaryUncompressedDataDownloadPath; // Used for writing data to a file when downloadDestinationPath is set NSOutputStream *fileDownloadOutputStream; NSOutputStream *inflatedFileDownloadOutputStream; // When the request fails or completes successfully, complete will be true BOOL complete; // external "finished" indicator, subject of KVO notifications; updates after 'complete' BOOL finished; // True if our 'cancel' selector has been called BOOL cancelled; // 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; // Username and password used for authentication NSString *username; NSString *password; // User-Agent for this request NSString *userAgentString; // Domain used for NTLM authentication NSString *domain; // Username and password used for proxy authentication NSString *proxyUsername; NSString *proxyPassword; // Domain used for NTLM proxy authentication NSString *proxyDomain; // 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; NSInputStream *readStream; // Used for authentication CFHTTPAuthenticationRef requestAuthentication; NSDictionary *requestCredentials; // Used during NTLM authentication int authenticationRetryCount; // Authentication scheme (Basic, Digest, NTLM) // If you are using Basic authentication and want to force ASIHTTPRequest to send an authorization header without waiting for a 401, you must set this to (NSString *)kCFHTTPAuthenticationSchemeBasic NSString *authenticationScheme; // Realm for authentication when credentials are required NSString *authenticationRealm; // When YES, ASIHTTPRequest will present a dialog allowing users to enter credentials when no-matching credentials were found for a server that requires authentication // The dialog will not be shown if your delegate responds to authenticationNeededForRequest: // Default is NO. BOOL shouldPresentAuthenticationDialog; // When YES, ASIHTTPRequest will present a dialog allowing users to enter credentials when no-matching credentials were found for a proxy server that requires authentication // The dialog will not be shown if your delegate responds to proxyAuthenticationNeededForRequest: // Default is YES (basically, because most people won't want the hassle of adding support for authenticating proxies to their apps) BOOL shouldPresentProxyAuthenticationDialog; // Used for proxy authentication CFHTTPAuthenticationRef proxyAuthentication; NSDictionary *proxyCredentials; // Used during authentication with an NTLM proxy int proxyAuthenticationRetryCount; // Authentication scheme for the proxy (Basic, Digest, NTLM) NSString *proxyAuthenticationScheme; // Realm for proxy authentication when credentials are required NSString *proxyAuthenticationRealm; // HTTP status code, eg: 200 = OK, 404 = Not found etc int responseStatusCode; // Description of the HTTP status code NSString *responseStatusMessage; // Size of the response unsigned long long contentLength; // Size of the partially downloaded content unsigned long long partialDownloadSize; // Size of the POST payload unsigned long long postLength; // The total amount of downloaded data unsigned long long totalBytesRead; // The total amount of uploaded data unsigned long long totalBytesSent; // 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; // This lock prevents the operation from being cancelled at an inopportune moment NSRecursiveLock *cancelledLock; // Called on the delegate (if implemented) when the request starts. Default is requestStarted: SEL didStartSelector; // Called on the delegate (if implemented) when the request receives response headers. Default is request:didReceiveResponseHeaders: SEL didReceiveResponseHeadersSelector; // Called on the delegate (if implemented) when the request receives a Location header and shouldRedirect is YES // The delegate can then change the url if needed, and can restart the request by calling [request redirectToURL:], or simply cancel it SEL willRedirectSelector; // Called on the delegate (if implemented) when the request completes successfully. Default is requestFinished: SEL didFinishSelector; // Called on the delegate (if implemented) when the request fails. Default is requestFailed: SEL didFailSelector; // Called on the delegate (if implemented) when the request receives data. Default is request:didReceiveData: // If you set this and implement the method in your delegate, you must handle the data yourself - ASIHTTPRequest will not populate responseData or write the data to downloadDestinationPath SEL didReceiveDataSelector; // 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; // Will be YES when a HEAD request will handle the content-length before this request starts BOOL shouldResetUploadProgress; BOOL shouldResetDownloadProgress; // 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; // Used internally, may reflect the size of the internal buffer used by CFNetwork // POST / PUT operations with body sizes greater than uploadBufferSize will not timeout unless more than uploadBufferSize bytes have been sent // Likely to be 32KB on iPhone 3.0, 128KB on Mac OS X Leopard and iPhone 2.2.x unsigned long long uploadBufferSize; // Text encoding for responses that do not send a Content-Type with a charset value. Defaults to NSISOLatin1StringEncoding NSStringEncoding defaultResponseEncoding; // The text encoding of the response, will be defaultResponseEncoding if the server didn't specify. Can't be set. NSStringEncoding responseEncoding; // Tells ASIHTTPRequest not to delete partial downloads, and allows it to use an existing file to resume a download. Defaults to NO. BOOL allowResumeForFileDownloads; // Custom user information associated with the request (not sent to the server) NSDictionary *userInfo; NSInteger tag; // Use HTTP 1.0 rather than 1.1 (defaults to false) BOOL useHTTPVersionOne; // When YES, requests will automatically redirect when they get a HTTP 30x header (defaults to YES) BOOL shouldRedirect; // Used internally to tell the main loop we need to stop and retry with a new url BOOL needsRedirect; // Incremented every time this request redirects. When it reaches 5, we give up int redirectCount; // When NO, requests will not check the secure certificate is valid (use for self-signed certificates during development, DO NOT USE IN PRODUCTION) Default is YES BOOL validatesSecureCertificate; // If not nil and the URL scheme is https, CFNetwork configured to supply a client certificate SecIdentityRef clientCertificateIdentity; NSArray *clientCertificates; // Details on the proxy to use - you could set these yourself, but it's probably best to let ASIHTTPRequest detect the system proxy settings NSString *proxyHost; int proxyPort; // ASIHTTPRequest will assume kCFProxyTypeHTTP if the proxy type could not be automatically determined // Set to kCFProxyTypeSOCKS if you are manually configuring a SOCKS proxy NSString *proxyType; // URL for a PAC (Proxy Auto Configuration) file. If you want to set this yourself, it's probably best if you use a local file NSURL *PACurl; // See ASIAuthenticationState values above. 0 == default == No authentication needed yet ASIAuthenticationState authenticationNeeded; // When YES, ASIHTTPRequests will present credentials from the session store for requests to the same server before being asked for them // This avoids an extra round trip for requests after authentication has succeeded, which is much for efficient for authenticated requests with large bodies, or on slower connections // Set to NO to only present credentials when explicitly asked for them // This only affects credentials stored in the session cache when useSessionPersistence is YES. Credentials from the keychain are never presented unless the server asks for them // Default is YES // For requests using Basic authentication, set authenticationScheme to (NSString *)kCFHTTPAuthenticationSchemeBasic, and credentials can be sent on the very first request when shouldPresentCredentialsBeforeChallenge is YES BOOL shouldPresentCredentialsBeforeChallenge; // YES when the request hasn't finished yet. Will still be YES even if the request isn't doing anything (eg it's waiting for delegate authentication). READ-ONLY BOOL inProgress; // Used internally to track whether the stream is scheduled on the run loop or not // Bandwidth throttling can unschedule the stream to slow things down while a request is in progress BOOL readStreamIsScheduled; // Set to allow a request to automatically retry itself on timeout // Default is zero - timeout will stop the request int numberOfTimesToRetryOnTimeout; // The number of times this request has retried (when numberOfTimesToRetryOnTimeout > 0) int retryCount; // Temporarily set to YES when a closed connection forces a retry (internally, this stops ASIHTTPRequest cleaning up a temporary post body) BOOL willRetryRequest; // When YES, requests will keep the connection to the server alive for a while to allow subsequent requests to re-use it for a substantial speed-boost // Persistent connections will not be used if the server explicitly closes the connection // Default is YES BOOL shouldAttemptPersistentConnection; // Number of seconds to keep an inactive persistent connection open on the client side // Default is 60 // If we get a keep-alive header, this is this value is replaced with how long the server told us to keep the connection around // A future date is created from this and used for expiring the connection, this is stored in connectionInfo's expires value NSTimeInterval persistentConnectionTimeoutSeconds; // Set to yes when an appropriate keep-alive header is found BOOL connectionCanBeReused; // Stores information about the persistent connection that is currently in use. // It may contain: // * The id we set for a particular connection, incremented every time we want to specify that we need a new connection // * The date that connection should expire // * A host, port and scheme for the connection. These are used to determine whether that connection can be reused by a subsequent request (all must match the new request) // * An id for the request that is currently using the connection. This is used for determining if a connection is available or not (we store a number rather than a reference to the request so we don't need to hang onto a request until the connection expires) // * A reference to the stream that is currently using the connection. This is necessary because we need to keep the old stream open until we've opened a new one. // The stream will be closed + released either when another request comes to use the connection, or when the timer fires to tell the connection to expire NSMutableDictionary *connectionInfo; // When set to YES, 301 and 302 automatic redirects will use the original method and and body, according to the HTTP 1.1 standard // Default is NO (to follow the behaviour of most browsers) BOOL shouldUseRFC2616RedirectBehaviour; // Used internally to record when a request has finished downloading data BOOL downloadComplete; // An ID that uniquely identifies this request - primarily used for debugging persistent connections NSNumber *requestID; // Will be ASIHTTPRequestRunLoopMode for synchronous requests, NSDefaultRunLoopMode for all other requests NSString *runLoopMode; // This timer checks up on the request every 0.25 seconds, and updates progress NSTimer *statusTimer; // The download cache that will be used for this request (use [ASIHTTPRequest setDefaultCache:cache] to configure a default cache id downloadCache; // The cache policy that will be used for this request - See ASICacheDelegate.h for possible values ASICachePolicy cachePolicy; // The cache storage policy that will be used for this request - See ASICacheDelegate.h for possible values ASICacheStoragePolicy cacheStoragePolicy; // Will be true when the response was pulled from the cache rather than downloaded BOOL didUseCachedResponse; // Set secondsToCache to use a custom time interval for expiring the response when it is stored in a cache NSTimeInterval secondsToCache; #if TARGET_OS_IPHONE && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_4_0 BOOL shouldContinueWhenAppEntersBackground; UIBackgroundTaskIdentifier backgroundTask; #endif // When downloading a gzipped response, the request will use this helper object to inflate the response ASIDataDecompressor *dataDecompressor; // Controls how responses with a gzipped encoding are inflated (decompressed) // When set to YES (This is the default): // * gzipped responses for requests without a downloadDestinationPath will be inflated only when [request responseData] / [request responseString] is called // * gzipped responses for requests with a downloadDestinationPath set will be inflated only when the request completes // // When set to NO // All requests will inflate the response as it comes in // * If the request has no downloadDestinationPath set, the raw (compressed) response is discarded and rawResponseData will contain the decompressed response // * If the request has a downloadDestinationPath, the raw response will be stored in temporaryFileDownloadPath as normal, the inflated response will be stored in temporaryUncompressedDataDownloadPath // Once the request completes successfully, the contents of temporaryUncompressedDataDownloadPath are moved into downloadDestinationPath // // Setting this to NO may be especially useful for users using ASIHTTPRequest in conjunction with a streaming parser, as it will allow partial gzipped responses to be inflated and passed on to the parser while the request is still running BOOL shouldWaitToInflateCompressedResponses; // Will be YES if this is a request created behind the scenes to download a PAC file - these requests do not attempt to configure their own proxies BOOL isPACFileRequest; // Used for downloading PAC files from http / https webservers ASIHTTPRequest *PACFileRequest; // Used for asynchronously reading PAC files from file:// URLs NSInputStream *PACFileReadStream; // Used for storing PAC data from file URLs as it is downloaded NSMutableData *PACFileData; // Set to YES in startSynchronous. Currently used by proxy detection to download PAC files synchronously when appropriate BOOL isSynchronous; #if NS_BLOCKS_AVAILABLE //block to execute when request starts ASIBasicBlock startedBlock; //block to execute when headers are received ASIHeadersBlock headersReceivedBlock; //block to execute when request completes successfully ASIBasicBlock completionBlock; //block to execute when request fails ASIBasicBlock failureBlock; //block for when bytes are received ASIProgressBlock bytesReceivedBlock; //block for when bytes are sent ASIProgressBlock bytesSentBlock; //block for when download size is incremented ASISizeBlock downloadSizeIncrementedBlock; //block for when upload size is incremented ASISizeBlock uploadSizeIncrementedBlock; //block for handling raw bytes received ASIDataBlock dataReceivedBlock; //block for handling authentication ASIBasicBlock authenticationNeededBlock; //block for handling proxy authentication ASIBasicBlock proxyAuthenticationNeededBlock; //block for handling redirections, if you want to ASIBasicBlock requestRedirectedBlock; #endif } #pragma mark init / dealloc // Should be an HTTP or HTTPS url, may include username and password if appropriate - (id)initWithURL:(NSURL *)newURL; // Convenience constructor + (id)requestWithURL:(NSURL *)newURL; + (id)requestWithURL:(NSURL *)newURL usingCache:(id )cache; + (id)requestWithURL:(NSURL *)newURL usingCache:(id )cache andCachePolicy:(ASICachePolicy)policy; #if NS_BLOCKS_AVAILABLE - (void)setStartedBlock:(ASIBasicBlock)aStartedBlock; - (void)setHeadersReceivedBlock:(ASIHeadersBlock)aReceivedBlock; - (void)setCompletionBlock:(ASIBasicBlock)aCompletionBlock; - (void)setFailedBlock:(ASIBasicBlock)aFailedBlock; - (void)setBytesReceivedBlock:(ASIProgressBlock)aBytesReceivedBlock; - (void)setBytesSentBlock:(ASIProgressBlock)aBytesSentBlock; - (void)setDownloadSizeIncrementedBlock:(ASISizeBlock) aDownloadSizeIncrementedBlock; - (void)setUploadSizeIncrementedBlock:(ASISizeBlock) anUploadSizeIncrementedBlock; - (void)setDataReceivedBlock:(ASIDataBlock)aReceivedBlock; - (void)setAuthenticationNeededBlock:(ASIBasicBlock)anAuthenticationBlock; - (void)setProxyAuthenticationNeededBlock:(ASIBasicBlock)aProxyAuthenticationBlock; - (void)setRequestRedirectedBlock:(ASIBasicBlock)aRedirectBlock; #endif #pragma mark setup request // Add a custom header to the request - (void)addRequestHeader:(NSString *)header value:(NSString *)value; // Called during buildRequestHeaders and after a redirect to create a cookie header from request cookies and the global store - (void)applyCookieHeader; // Populate the request headers dictionary. Called before a request is started, or by a HEAD request that needs to borrow them - (void)buildRequestHeaders; // Used to apply authorization header to a request before it is sent (when shouldPresentCredentialsBeforeChallenge is YES) - (void)applyAuthorizationHeader; // Create the post body - (void)buildPostBody; // Called to add data to the post body. Will append to postBody when shouldStreamPostDataFromDisk is false, or write to postBodyWriteStream when true - (void)appendPostData:(NSData *)data; - (void)appendPostDataFromFile:(NSString *)file; #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 running a request // Run a request synchronously, and return control when the request completes or fails - (void)startSynchronous; // Run request in the background - (void)startAsynchronous; // Clears all delegates and blocks, then cancels the request - (void)clearDelegatesAndCancel; #pragma mark HEAD request // Used by ASINetworkQueue to create a HEAD request appropriate for this request with the same headers (though you can use it yourself) - (ASIHTTPRequest *)HEADRequest; #pragma mark upload/download progress // Called approximately every 0.25 seconds to update the progress delegates - (void)updateProgressIndicators; // Updates upload progress (notifies the queue and/or uploadProgressDelegate of this request) - (void)updateUploadProgress; // Updates download progress (notifies the queue and/or uploadProgressDelegate of this request) - (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; // Called when we get a content-length header and shouldResetDownloadProgress is true - (void)incrementDownloadSizeBy:(long long)length; // Called when a request starts and shouldResetUploadProgress is true // Also called (with a negative length) to remove the size of the underlying buffer used for uploading - (void)incrementUploadSizeBy:(long long)length; // Helper method for interacting with progress indicators to abstract the details of different APIS (NSProgressIndicator and UIProgressView) + (void)updateProgressIndicator:(id *)indicator withProgress:(unsigned long long)progress ofTotal:(unsigned long long)total; // Helper method used for performing invocations on the main thread (used for progress) + (void)performSelector:(SEL)selector onTarget:(id *)target withObject:(id)object amount:(void *)amount callerToRetain:(id)caller; #pragma mark talking to delegates // Called when a request starts, lets the delegate know via didStartSelector - (void)requestStarted; // Called when a request receives response headers, lets the delegate know via didReceiveResponseHeadersSelector - (void)requestReceivedResponseHeaders:(NSDictionary *)newHeaders; // Called when a request completes successfully, lets the delegate know via didFinishSelector - (void)requestFinished; // Called when a request fails, and lets the delegate know via didFailSelector - (void)failWithError:(NSError *)theError; // Called to retry our request when our persistent connection is closed // Returns YES if we haven't already retried, and connection will be restarted // Otherwise, returns NO, and nothing will happen - (BOOL)retryUsingNewConnection; // Can be called by delegates from inside their willRedirectSelector implementations to restart the request with a new url - (void)redirectToURL:(NSURL *)newURL; #pragma mark parsing HTTP response headers // Reads the response headers to find the content length, encoding, cookies for the session // Also initiates request redirection when shouldRedirect is true // And works out if HTTP auth is required - (void)readResponseHeaders; // Attempts to set the correct encoding by looking at the Content-Type header, if this is one - (void)parseStringEncodingFromHeaders; + (void)parseMimeType:(NSString **)mimeType andResponseEncoding:(NSStringEncoding *)stringEncoding fromContentType:(NSString *)contentType; #pragma mark http authentication stuff // Apply credentials to this request - (BOOL)applyCredentials:(NSDictionary *)newCredentials; - (BOOL)applyProxyCredentials:(NSDictionary *)newCredentials; // Attempt to obtain credentials for this request from the URL, username and password or keychain - (NSMutableDictionary *)findCredentials; - (NSMutableDictionary *)findProxyCredentials; // 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)retryUsingSuppliedCredentials; // Should be called by delegates when they wish to cancel authentication and stop - (void)cancelAuthentication; // Apply authentication information and resume the request after an authentication challenge - (void)attemptToApplyCredentialsAndResume; - (void)attemptToApplyProxyCredentialsAndResume; // Attempt to show the built-in authentication dialog, returns YES if credentials were supplied, NO if user cancelled dialog / dialog is disabled / running on main thread // Currently only used on iPhone OS - (BOOL)showProxyAuthenticationDialog; - (BOOL)showAuthenticationDialog; // Construct a basic authentication header from the username and password supplied, and add it to the request headers // Used when shouldPresentCredentialsBeforeChallenge is YES - (void)addBasicAuthenticationHeaderWithUsername:(NSString *)theUsername andPassword:(NSString *)thePassword; #pragma mark stream status handlers // CFnetwork event handlers - (void)handleNetworkEvent:(CFStreamEventType)type; - (void)handleBytesAvailable; - (void)handleStreamComplete; - (void)handleStreamError; #pragma mark cleanup // Cleans up and lets the queue know this operation is finished. // Appears in this header for subclassing only, do not call this method from outside your request! - (void)markAsFinished; // Cleans up temporary files. There's normally no reason to call these yourself, they are called automatically when a request completes or fails // Clean up the temporary file used to store the downloaded data when it comes in (if downloadDestinationPath is set) - (BOOL)removeTemporaryDownloadFile; // Clean up the temporary file used to store data that is inflated (decompressed) as it comes in - (BOOL)removeTemporaryUncompressedDownloadFile; // Clean up the temporary file used to store the request body (when shouldStreamPostDataFromDisk is YES) - (BOOL)removeTemporaryUploadFile; // Clean up the temporary file used to store a deflated (compressed) request body when shouldStreamPostDataFromDisk is YES - (BOOL)removeTemporaryCompressedUploadFile; // Remove a file on disk, returning NO and populating the passed error pointer if it fails + (BOOL)removeFileAtPath:(NSString *)path error:(NSError **)err; #pragma mark persistent connections // Get the ID of the connection this request used (only really useful in tests and debugging) - (NSNumber *)connectionID; // Called automatically when a request is started to clean up any persistent connections that have expired + (void)expirePersistentConnections; #pragma mark default time out + (NSTimeInterval)defaultTimeOutSeconds; + (void)setDefaultTimeOutSeconds:(NSTimeInterval)newTimeOutSeconds; #pragma mark client certificate - (void)setClientCertificateIdentity:(SecIdentityRef)anIdentity; #pragma mark session credentials + (NSMutableArray *)sessionProxyCredentialsStore; + (NSMutableArray *)sessionCredentialsStore; + (void)storeProxyAuthenticationCredentialsInSessionStore:(NSDictionary *)credentials; + (void)storeAuthenticationCredentialsInSessionStore:(NSDictionary *)credentials; + (void)removeProxyAuthenticationCredentialsFromSessionStore:(NSDictionary *)credentials; + (void)removeAuthenticationCredentialsFromSessionStore:(NSDictionary *)credentials; - (NSDictionary *)findSessionProxyAuthenticationCredentials; - (NSDictionary *)findSessionAuthenticationCredentials; #pragma mark keychain storage // Save credentials for this request to the keychain - (void)saveCredentialsToKeychain:(NSDictionary *)newCredentials; // Save credentials to the keychain + (void)saveCredentials:(NSURLCredential *)credentials forHost:(NSString *)host port:(int)port protocol:(NSString *)protocol realm:(NSString *)realm; + (void)saveCredentials:(NSURLCredential *)credentials forProxy:(NSString *)host port:(int)port realm:(NSString *)realm; // Return credentials from the keychain + (NSURLCredential *)savedCredentialsForHost:(NSString *)host port:(int)port protocol:(NSString *)protocol realm:(NSString *)realm; + (NSURLCredential *)savedCredentialsForProxy:(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; + (void)removeCredentialsForProxy:(NSString *)host port:(int)port 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; // Adds a cookie to our list of cookies we've accepted, checking first for an old version of the same cookie and removing that + (void)addSessionCookie:(NSHTTPCookie *)newCookie; // Dump all session data (authentication and cookies) + (void)clearSession; #pragma mark get user agent // Will be used as a user agent if requests do not specify a custom user agent // Is only used when you have specified a Bundle Display Name (CFDisplayBundleName) or Bundle Name (CFBundleName) in your plist + (NSString *)defaultUserAgentString; + (void)setDefaultUserAgentString:(NSString *)agent; #pragma mark mime-type detection // Return the mime type for a file + (NSString *)mimeTypeForFileAtPath:(NSString *)path; #pragma mark bandwidth measurement / throttling // The maximum number of bytes ALL requests can send / receive in a second // This is a rough figure. The actual amount used will be slightly more, this does not include HTTP headers + (unsigned long)maxBandwidthPerSecond; + (void)setMaxBandwidthPerSecond:(unsigned long)bytes; // Get a rough average (for the last 5 seconds) of how much bandwidth is being used, in bytes + (unsigned long)averageBandwidthUsedPerSecond; - (void)performThrottling; // Will return YES is bandwidth throttling is currently in use + (BOOL)isBandwidthThrottled; // Used internally to record bandwidth use, and by ASIInputStreams when uploading. It's probably best if you don't mess with this. + (void)incrementBandwidthUsedInLastSecond:(unsigned long)bytes; // On iPhone, ASIHTTPRequest can automatically turn throttling on and off as the connection type changes between WWAN and WiFi #if TARGET_OS_IPHONE // Set to YES to automatically turn on throttling when WWAN is connected, and automatically turn it off when it isn't + (void)setShouldThrottleBandwidthForWWAN:(BOOL)throttle; // Turns on throttling automatically when WWAN is connected using a custom limit, and turns it off automatically when it isn't + (void)throttleBandwidthForWWANUsingLimit:(unsigned long)limit; #pragma mark reachability // Returns YES when an iPhone OS device is connected via WWAN, false when connected via WIFI or not connected + (BOOL)isNetworkReachableViaWWAN; #endif #pragma mark queue // Returns the shared queue + (NSOperationQueue *)sharedQueue; #pragma mark cache + (void)setDefaultCache:(id )cache; + (id )defaultCache; // Returns the maximum amount of data we can read as part of the current measurement period, and sleeps this thread if our allowance is used up + (unsigned long)maxUploadReadLength; #pragma mark network activity + (BOOL)isNetworkInUse; + (void)setShouldUpdateNetworkActivityIndicator:(BOOL)shouldUpdate; // Shows the network activity spinner thing on iOS. You may wish to override this to do something else in Mac projects + (void)showNetworkActivityIndicator; // Hides the network activity spinner thing on iOS + (void)hideNetworkActivityIndicator; #pragma mark miscellany // Used for generating Authorization header when using basic authentication when shouldPresentCredentialsBeforeChallenge is true // And also by ASIS3Request + (NSString *)base64forData:(NSData *)theData; // Returns the expiration date for the request. // Calculated from the Expires response header property, unless maxAge is non-zero or // there exists a non-zero max-age property in the Cache-Control response header. + (NSDate *)expiryDateForRequest:(ASIHTTPRequest *)request maxAge:(NSTimeInterval)maxAge; // Returns a date from a string in RFC1123 format + (NSDate *)dateFromRFC1123String:(NSString *)string; // Used for detecting multitasking support at runtime (for backgrounding requests) #if TARGET_OS_IPHONE + (BOOL)isMultitaskingSupported; #endif #pragma mark threading behaviour // In the default implementation, all requests run in a single background thread // Advanced users only: Override this method in a subclass for a different threading behaviour // Eg: return [NSThread mainThread] to run all requests in the main thread // Alternatively, you can create a thread on demand, or manage a pool of threads // Threads returned by this method will need to run the runloop in default mode (eg CFRunLoopRun()) // Requests will stop the runloop when they complete // If you have multiple requests sharing the thread you'll need to restart the runloop when this happens + (NSThread *)threadForRequest:(ASIHTTPRequest *)request; #pragma mark === @property (retain) NSString *username; @property (retain) NSString *password; @property (retain) NSString *userAgentString; @property (retain) NSString *domain; @property (retain) NSString *proxyUsername; @property (retain) NSString *proxyPassword; @property (retain) NSString *proxyDomain; @property (retain) NSString *proxyHost; @property (assign) int proxyPort; @property (retain) NSString *proxyType; @property (retain,setter=setURL:, nonatomic) NSURL *url; @property (retain) NSURL *originalURL; @property (assign, nonatomic) id delegate; @property (retain, nonatomic) id queue; @property (assign, nonatomic) id uploadProgressDelegate; @property (assign, nonatomic) id downloadProgressDelegate; @property (assign) BOOL useKeychainPersistence; @property (assign) BOOL useSessionPersistence; @property (retain) NSString *downloadDestinationPath; @property (retain) NSString *temporaryFileDownloadPath; @property (retain) NSString *temporaryUncompressedDataDownloadPath; @property (assign) SEL didStartSelector; @property (assign) SEL didReceiveResponseHeadersSelector; @property (assign) SEL willRedirectSelector; @property (assign) SEL didFinishSelector; @property (assign) SEL didFailSelector; @property (assign) SEL didReceiveDataSelector; @property (retain,readonly) NSString *authenticationRealm; @property (retain,readonly) NSString *proxyAuthenticationRealm; @property (retain) NSError *error; @property (assign,readonly) BOOL complete; @property (retain) NSDictionary *responseHeaders; @property (retain) NSMutableDictionary *requestHeaders; @property (retain) NSMutableArray *requestCookies; @property (retain,readonly) NSArray *responseCookies; @property (assign) BOOL useCookiePersistence; @property (retain) NSDictionary *requestCredentials; @property (retain) NSDictionary *proxyCredentials; @property (assign,readonly) int responseStatusCode; @property (retain,readonly) NSString *responseStatusMessage; @property (retain) NSMutableData *rawResponseData; @property (assign) NSTimeInterval timeOutSeconds; @property (retain, nonatomic) NSString *requestMethod; @property (retain) NSMutableData *postBody; @property (assign) unsigned long long contentLength; @property (assign) unsigned long long postLength; @property (assign) BOOL shouldResetDownloadProgress; @property (assign) BOOL shouldResetUploadProgress; @property (assign) ASIHTTPRequest *mainRequest; @property (assign) BOOL showAccurateProgress; @property (assign) unsigned long long totalBytesRead; @property (assign) unsigned long long totalBytesSent; @property (assign) NSStringEncoding defaultResponseEncoding; @property (assign) NSStringEncoding responseEncoding; @property (assign) BOOL allowCompressedResponse; @property (assign) BOOL allowResumeForFileDownloads; @property (retain) NSDictionary *userInfo; @property (assign) NSInteger tag; @property (retain) NSString *postBodyFilePath; @property (assign) BOOL shouldStreamPostDataFromDisk; @property (assign) BOOL didCreateTemporaryPostDataFile; @property (assign) BOOL useHTTPVersionOne; @property (assign, readonly) unsigned long long partialDownloadSize; @property (assign) BOOL shouldRedirect; @property (assign) BOOL validatesSecureCertificate; @property (assign) BOOL shouldCompressRequestBody; @property (retain) NSURL *PACurl; @property (retain) NSString *authenticationScheme; @property (retain) NSString *proxyAuthenticationScheme; @property (assign) BOOL shouldPresentAuthenticationDialog; @property (assign) BOOL shouldPresentProxyAuthenticationDialog; @property (assign, readonly) ASIAuthenticationState authenticationNeeded; @property (assign) BOOL shouldPresentCredentialsBeforeChallenge; @property (assign, readonly) int authenticationRetryCount; @property (assign, readonly) int proxyAuthenticationRetryCount; @property (assign) BOOL haveBuiltRequestHeaders; @property (assign, nonatomic) BOOL haveBuiltPostBody; @property (assign, readonly) BOOL inProgress; @property (assign) int numberOfTimesToRetryOnTimeout; @property (assign, readonly) int retryCount; @property (assign) BOOL shouldAttemptPersistentConnection; @property (assign) NSTimeInterval persistentConnectionTimeoutSeconds; @property (assign) BOOL shouldUseRFC2616RedirectBehaviour; @property (assign, readonly) BOOL connectionCanBeReused; @property (retain, readonly) NSNumber *requestID; @property (assign) id downloadCache; @property (assign) ASICachePolicy cachePolicy; @property (assign) ASICacheStoragePolicy cacheStoragePolicy; @property (assign, readonly) BOOL didUseCachedResponse; @property (assign) NSTimeInterval secondsToCache; @property (retain) NSArray *clientCertificates; #if TARGET_OS_IPHONE && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_4_0 @property (assign) BOOL shouldContinueWhenAppEntersBackground; #endif @property (retain) ASIDataDecompressor *dataDecompressor; @property (assign) BOOL shouldWaitToInflateCompressedResponses; @end