/TCBlobDownload

Competitive large files downloads for iOS

Primary LanguageObjective-CMIT LicenseMIT

TCBlobDownload

Build Status Pod version Pod platform

TCBlobDownload uses NSOperations to download large files (typically videos, music... well: BLOBs) using NSURLConnection in background threads.

Tested with files from ~150MB to ~1.2GB, mostly videos.

I've implemented TCBlobDownloader which extends NSOperation and use TCBlobDownloadManager to execute it. You can set a delegate or use blocks (your choice) for each download to update your views etc…

Requires iOS 5.1.1 or later and ARC.

======

Features

  1. Download files in background threads
  2. Blocks or delegate style
  3. Pause and resume a download
  4. Set maximum number of concurrent downloads
  5. Custom download path and auto path creation
  6. Download speed and remaining time
  7. Download cancellation
  8. Download dependencies

Documentation 📚

Browse the documentation on Cocoadocs or add it directly to Xcode by downloading the docset and placing it into ~/Library/Developer/Shared/Documentation/DocSets/. (or use Dash)

Installation

CocoaPods

Add the following to your Podfile and run $ pod install:

pod 'TCBlobDownload'

If you don't have CocoaPods installed or integrated into your project, you can learn how to do so here.

(Also be sure the $(inherited) flag is set in your Project's Target -> Build Settings -> Other Linker Flags)

Import as a static library

  1. Drag and drop TCBlobDownload.xcodeproj from Finder to your opened project.
  2. Project's Target -> Build Phases -> Target Dependencies -> add TCBlobDownload. Then, click Link binary with libraries and add libTCBlobDownload.a (no worries if it's red).
  3. Go to build settings, switch "always search user paths" to YES and add $(PROJECT_TEMP_DIR)/../UninstalledProducts/include to "User Header Search Paths".
  4. Project's Target -> Build Settings -> Other Linker Flags -> Add -ObjC
  5. Import the lib. (no worries if no autocomplete)
#import <TCBlobDownload/TCBlobDownload.h>

Examples 👓

1. Blocks

Blocks are cool. To immediately start a download in the default TCBlobDownloadManager directory (tmp/ by default):

TCBlobDownloadManager *sharedManager = [TCBlobDownloadManager sharedInstance];

TCBlobDownloader *downloader = [sharedManager startDownloadWithURL:@"http://give.me/abigfile.avi"
                downloadPath:nil
                 firstResponse:^(NSURLResponse *response) {
		      
                 }
                 progress:^(uint64_t receivedLength, uint64_t totalLength, NSInteger remainingTime, float progress) {
                   // wow moving progress bar!
                 }
                 error:^(NSError *error) {
                  // this not cool
                 }
                 complete:^(BOOL downloadFinished, NSString *pathToFile) {
                  // okay
                 }];

If you set a custom path:

NSString *customPath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"My/Custom/Path/"];

TCBlobDownloader *downloader = [sharedManager startDownloadWithURL:@"http://give.me/abigfile.avi"
                                                            customPath:customPath // important
                                                           andDelegate:nil];

This will create the given path if needed and download the file in the Path/ directory. Please note that during the download process you have no control over the file name as explained with reasons why in the documentation. Remember that you should follow the iOS Data Storage Guidelines.

2. Delegate

You can either set a delegate which can implement those optional methods if delegates have your preference over blocks:

- (void)download:(TCBlobDownloader *)blobDownload didReceiveFirstResponse:(NSURLResponse *)response
{

}

- (void)download:(TCBlobDownloader *)blobDownload didReceiveData:(uint64_t)received onTotal:(uint64_t)total
{
  // wow moving progress bar! (bis)
  // blobDownload.remainingTime
  // blobDownload.speedRate
}

- (void)download:(TCBlobDownloader *)blobDownload didStopWithError:(NSError *)error
{
  // this is not cool
}

- (void)download:(TCBlobDownloader *)blobDownload didFinishWithSucces:(BOOL)downloadFinished atPath:(NSString *)pathToFile
{
  // okay, okay
}

3. Other things you should know

Cool thing 1: If a download has been stopped and the local file has not been deleted, when you will restart the download to the same local path, the download will start where it has stopped using the HTTP Range header (14.35).

Cool thing 2: You can also set dependencies in your downloads using the addDependentDownload: method from TCBlobDownloader.

See documentation for more details.

Change log 📝

v1.5.2 (5/08/2014)

Thanks to #26,

  • Instances of TCBlobDownloader now have a state property
  • The example project has now a multiple downloads example

v1.5.1 (4/07/2014)

  • Important fix for #21

v1.5 (3/08/2014)

  • Improved documentation and created a docset
  • Added a speedRate and remainingTime (in seconds) property on TCBlobDownloader thanks to #16
  • Updated TCBlobDownloader properties to readonly
  • Refactored code and tests for a much more maintainable code base

v1.4 (11/19/2013)

  • Unit testing
  • HTTP error status code handling #3
  • Manager returns created downloads #5
  • Cocoapods release

v1.3.1 (6/01/2013)

  • Bug fix

v1.3 (5/27/2013)

  • Removed downloadCancelled and downloadFinished blocks
  • Added a completion block : completeBlock(BOOL downloadFinished, NSString *pathToFile)
  • Updated codestyle

v1.2 (5/06/2013)

  • Now built as a static library
  • Download dependencies support
  • New block for download cancelled
  • New block for first response
  • Error localizations

v1.1 (4/26/2013)

  • Blocks support
  • Custom download path directory

v1.0 (4/18/2013)

  • Initial release

Roadmap 🚀

If you have any idea or request, please suggest it! 😃

  • Multi segmented downloads
  • Dash XML feed for documentation versioning