Open Source Ecosystems

JGDownloadAcceleration is a Networking library for iOS targeted at downloading large files on to the device's hard disk.

JGDownloadAcceleration's main part is a concurrent NSOperation subclass (JGDownloadOperation) which handles the multipart download.

For managing and queuing multiple operations, JGDownloadAcceleration provides a NSOperationQueue subclass (JGOperationQueue) which handles the networking thread, activity indicator and application background task.

Q. How does the download acceleration even work?

A. Download accelerators (multipart download) use multiple network connections to download a file from a server in chunks (each connection downloads one part of the entire content). This allows to bypass bandwidth limitations set by the server and download speeds can be drastically increased.

More info: Wikipedia

Current Version: 1.2.1

##Getting started

Download JGDownloadAcceleration
Add the whole "JGDownloadAcceleration Classes" folder to your Project
Have a read through the Overview section
#import "JGDownloadAcceleration.h"
Start using JGDownloadAcceleration!

##Overview

JGDownloadAcceleration consists of 2 different classes that are available to use for networking.

###JGDownloadOperation A NSOperation subclass which does the download acceleration magic.

JGDownloadOperation is restricted to HTTP GET Requests and to writing downloaded content directly to the hard disk.

Parameters to pass: A JGDownloadOperation instance required to have the url parameter, and the destinationPath parameter set. If not the Application will terminate with an Assertion Failure.

All JGDownloadOperation instances should be initialized with the initWithURL:destinationPath:allowResume: or initWithRequest:destinationPath:allowResume: methods, where the URL or NSURLRequest, the local destination path and a BOOL to indicate whether the operation should resume (if possible) where it left of is passed. Any files located at the destination path will be removed when starting the download.

Optionally, the number of connections to use to download the resource, a tag, and the retry count can be set.

	NSUInteger tag;
	NSUInteger maximumNumberOfConnections;
	NSUInteger retryCount;

By default the tag is 0 and the number of connections is 6. The retry count it the number of connections divided by 2.

The readonly properties are:

	NSURLRequest *originalRequest;
	NSString *destinationPath;
	unsigned long long contentLength;
	NSError *error;

originalRequest and destinationPath are set in the initWithURL:destinationPath:allowResume: or initWithRequest:destinationPath:allowResume: methods and should not be changed once the operation has been initialized, therefore they are a readonly property. contentLength is the expected length (bytes) of the resource to download. This value will be 0 before the requestStartedBlock is called. error returns the failure error (it will be nil if no error occurred). The error will also be passed in the failure block. (See below for more info on the started and the failure blocks).

#####The custom init methods: JGDownloadOperation can only be initialized using either of the two custom init methods.

initWithURL:destinationPath:allowResume:: In this init method the request made will be a simple HTTP GET request from the given URL. No more customization is possible.

initWithRequest:destinationPath:allowResume:: This init method allows you to use a custom NSURLRequest with JGDownloadOperation. The HTTP Method can only be GET (default). JGDownloadOperation also supports the Range header.

#####Delegates: JGDownloadOperation uses blocks to communicate with a delegate.

    - (void)setCompletionBlockWithSuccess:(void (^)(JGDownloadOperation *operation))success failure:(void (^)(JGDownloadOperation *operation, NSError *error))failure;
    - (void)setOperationStartedBlock:(void (^)(NSUInteger tag, unsigned long long totalBytesExpectedToRead))block;
    
    - (void)setDownloadProgressBlock:(void (^)(NSUInteger bytesRead, unsigned long long totalBytesReadThisSession, unsigned long long totalBytesRead, unsigned long long totalBytesExpectedToRead, NSUInteger tag))block;

#####Cancellation: cancel will stop the download, synchronize the metadata file to allow resuming the download later and leave the partially downloaded file on the disk. The failure completion block will be called with an NSURLErrorCancelled error. cancelAndClearFiles will stop the download and remove the partially downloaded file as well as the metadata file from the disk. Neither the success completion block or the failure completion block will be called.

###JGOperationQueue A NSOperationQueue subclass which is targeted at enqueuing only JGDownloadOperation objects.

JGOperationQueue handles the shared network thread used by all JGDownloadOperation instances. Once all operations are finished the queue exits the networking thread. queue Optionally, JGOperationQueue handles the status bar NetworkActivityIndicator, according to the number of enqueued operations and the background task used for networking requests when the app runs in the background.

	BOOL handleNetworkActivityIndicator
	BOOL handleBackgroundTask

Note that when setting handleBackgroundTask to YES, the App's Info.plist file needs to have "Application uses Wi-Fi" set to YES.

##Example An example usage can be found in the Sample Project.

##Requirements In order to take advantage of multipart download, the server from which you download a content needs to support the Range HTTP header. If it doesn't then JGDownloadAcceleration will simply use 1 connection to download the content conventionally.

JGDownloadAcceleration is built for use with ARC and weak references. This means that iOS 5 or higher is required for using JGDownloadAcceleration

If your project doesn't use ARC: you must add the -fobjc-arc compiler flag to all JGDownloadAcceleration files in Target Settings > Build Phases > Compile Sources.

##Credits JGDownloadAcceleration was created by Jonas Gessner. It was created for the iOS Jailbreak tweak "ProTube Extension for YouTube" and the Jailbreak App "ProTube".

##Contact Contact me on Twitter: @JonasGessner or by email (found on my GitHub profile) if you have any questions!

Contributing to the Project is much appreciated!

##License

JGDownloadOperation is available under the Python License 2.0

An easy to understand explanation of the Python License 2.0 can be found here.