{"id":1611,"url":"https://github.com/chasseurmic/TWRDownloadManager","last_synced_at":"2025-08-02T04:31:53.459Z","repository":{"id":19295987,"uuid":"22533294","full_name":"chasseurmic/TWRDownloadManager","owner":"chasseurmic","description":"A modern download manager based on NSURLSession to deal with asynchronous downloading, management and persistence of multiple files.","archived":false,"fork":false,"pushed_at":"2020-01-03T20:28:43.000Z","size":284,"stargazers_count":402,"open_issues_count":33,"forks_count":99,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-30T19:23:17.850Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chasseurmic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-01T23:26:38.000Z","updated_at":"2025-04-30T09:18:51.000Z","dependencies_parsed_at":"2022-09-22T14:24:49.907Z","dependency_job_id":null,"html_url":"https://github.com/chasseurmic/TWRDownloadManager","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/chasseurmic/TWRDownloadManager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chasseurmic%2FTWRDownloadManager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chasseurmic%2FTWRDownloadManager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chasseurmic%2FTWRDownloadManager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chasseurmic%2FTWRDownloadManager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chasseurmic","download_url":"https://codeload.github.com/chasseurmic/TWRDownloadManager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chasseurmic%2FTWRDownloadManager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268334614,"owners_count":24233793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-01-05T20:15:51.351Z","updated_at":"2025-08-02T04:31:53.161Z","avatar_url":"https://github.com/chasseurmic.png","language":"Objective-C","funding_links":[],"categories":["Networking"],"sub_categories":["Video","Other free courses"],"readme":"TWRDownloadManager\n=================\n\n## TWRDownloadManager\n\nA modern download manager for iOS (Objective C) based on NSURLSession to deal with asynchronous downloading, management and persistence of multiple files.\n\nTWRDownloadManager is a singleton instance and can thus be called in your code safely from wherever you need to. The idea of writing yet another download manager library stemmed from the fact that at the time of the writing (and yet still) there were no available open source projects based on the new `NSURLSession` APIs made available by Apple in iOS 7.\n\nTWRDownloadManager leverages the power of `NSURLSession` and `NSURLSessionDownloadTask` to make downloading of files and keeping track of their progress a breeze.\n\n- - - \n\n**09.22.2014 - UPDATE!!!**\n\n**v1.0.0** of `TWRDownloadManager` now supports background modes. The  API has changed so it’s not backwards compatible, hence its bump to v1.0.0. See the documentation below for further information.\n\nA demo project has also been added to showcase the use of the download manager in its simplest form.\n\n**v1.1.0** of `TWRDownloadManager` adds the ability to pass a block when creating the download to keep track of an estimated remaining download time. The algorithm can definitely be improved but it works. \n\nUpdated demo project.\n\n\n## Installing the library\n\nTo use the library, just add the dependency to your `Podfile`:\n\n```ruby\nplatform :ios\npod 'TWRDownloadManager'\n```\n\nRun `pod install` to install the dependencies.\n\nNext, import the header file wherever you want to use the manager:\n\n```objc\n#import \u003cTWRDownloadManager/TWRDownloadManager.h\u003e\n```\n\nSince TWRDownloadManager is a singleton you could import it in the `.pch` file of your project so that it can be accessed and used wherever you need it without worrying about importing it in each of your classes.\n\n## Usage\n\n`TWRDownloadManager` provides facilities for the following task:\n\n- downloading files;\n- persisting downloaded files and saving them to disk;\n- keeping track of download progress via block syntax;\n- being notified of the download completion via block syntax;\n- deleting downloaded files;\n- checking for file existence.\n\nAll the following instance methods can be called directly on `\n[TWRDownloadManager sharedManager]`.\n\n### Downloading files\n\n```objc \n- (void)downloadFileForURL:(NSString *)url\n                  withName:(NSString *)fileName\n          inDirectoryNamed:(NSString *)directory\n             progressBlock:(void(^)(CGFloat progress))progressBlock\n           completionBlock:(void(^)(BOOL completed))completionBlock\n      enableBackgroundMode:(BOOL)backgroundMode;\n\n- (void)downloadFileForURL:(NSString *)url\n          inDirectoryNamed:(NSString *)directory\n             progressBlock:(void(^)(CGFloat progress))progressBlock\n           completionBlock:(void(^)(BOOL completed))completionBlock\n      enableBackgroundMode:(BOOL)backgroundMode;\n\n- (void)downloadFileForURL:(NSString *)url\n             progressBlock:(void(^)(CGFloat progress))progressBlock\n           completionBlock:(void(^)(BOOL completed))completionBlock\n      enableBackgroundMode:(BOOL)backgroundMode;\n```\n\nThe easiest way to get started is by simply passing to the last of the aforementioned methods the URL string of the file that needs to be downloaded. You will get a chance to pass in two blocks that will help you keep track of the download progress (a float from 0 to 1) and of the completion of the task.\n\nAll the files, once downloaded will be moved from the `/tmp` directory of the device to the Caches directory. This is done for two reasons:\n \n- the `/tmp` directory can be cleaned once in a while to make sure that any partial, cancelled or failed downloads get properly disposed of and do not occupy space both on the device and in iTunes backups;\n- the Caches directory is not synced by default with the user's iCloud documents. This is in compliance with Apple's rules about content that – not being user-specific – can be re-downloaded from the internet and should not be synced with iCloud.\n\nIf a directory name is provided, a new sub-directory will be created in the Cached directory.\n\nOnce the file is finished downloading, if a name was provided by the user, it will be used to store the file in its final destination. If no name was provided the manager will use by default the last path component of the URL string (e.g. for `http://www.example.com/files/my_file.zip`, the final file name would be `my_file.zip`).\n\n### Checking for current downloads \n\nTo check if a file is being downloaded, you can use one of the following methods:\n\n```objc\n- (BOOL)isFileDownloadingForUrl:(NSString *)url withProgressBlock:(void(^)(CGFloat progress))block;\n- (BOOL)isFileDownloadingForUrl:(NSString *)url withProgressBlock:(void(^)(CGFloat progress))block completionBlock:(void(^)(BOOL completed))completionBlock;\n```\n\nAs with the previous download methods, you get a chance to be called back for progress and completion.\n\nTo retrieve a list of current files being downloaded, you can use the following:\n\n```objc \n- (NSArray *)currentDownloads;\n```\n\nThis method returns an array of `NSString` objects with the URLs of the current downloads being performed.\n\n### Canceling downloads\n\nThe downloads, which are uniquely referenced by the download manager by the provided URL, can either be canceled singularly or all together with a single call via one of the two following methods:\n\n```objc\n- (void)cancelAllDownloads;\n- (void)cancelDownloadForUrl:(NSString *)urlString;\n```\n\n### File management\n\nTWRDownloadManager also provides some facilities to deal with downloaded files. \n\nYou can check for existence...\n\n```objc\n- (BOOL)fileExistsForUrl:(NSString *)urlString;\n- (BOOL)fileExistsForUrl:(NSString *)urlString inDirectory:(NSString *)directoryName;\n- (BOOL)fileExistsWithName:(NSString *)fileName;\n- (BOOL)fileExistsWithName:(NSString *)fileName inDirectory:(NSString *)directoryName;\n```\n\n...and retrieve the file location with the following ones:\n\n```objc\n- (NSString *)localPathForFile:(NSString *)fileIdentifier;\n- (NSString *)localPathForFile:(NSString *)fileIdentifier inDirectory:(NSString *)directoryName;\n```\n\n### Deleting files\n\nDownloaded files can be deleted via the following methods:\n\n```objc\n- (BOOL)deleteFileForUrl:(NSString *)urlString;\n- (BOOL)deleteFileForUrl:(NSString *)urlString inDirectory:(NSString *)directoryName;\n- (BOOL)deleteFileWithName:(NSString *)fileName;\n- (BOOL)deleteFileWithName:(NSString *)fileName inDirectory:(NSString *)directoryName;\n```\n\n### Background Mode\n\nTo enable background downloads in iOS 7+, you should conform to the following steps:\n\n- enable background modes in your project. Select the project in the Project Navigator in Xcode, select your target, then select the `Capabilities` tab and finally enable Background Modes:\n\n![Enable Background modes](http://cocoahunter-blog.s3.amazonaws.com/TWRDownloadManager/bg_modes.png)\n\n- add the following method to your AppDelegate\n\n```objc\n- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)())completionHandler{\n    [TWRDownloadManager sharedManager].backgroundTransferCompletionHandler = completionHandler;   \n}\n```\n\n- register for local notifications in your `application:didFinishLaunchingWithOptions:` so that you can display a message to the user when the download completes:\n\n```objc \nif ([UIApplication instancesRespondToSelector:@selector(registerUserNotificationSettings:)]) {\n        [application registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound categories:nil]];\n}\n```\n## Using TWRDownloadManager with custom UITableViewCell\n\n`TWRDownloadManager`, being able to keep track of multiple downloads at once, could be used to show a list of current downloads inside a table view. \n\nThese are just a couple of suggestions on how it could be achieved by using `TWRDownloadManager`.\n\nIn your `UITableViewCell` subclass, import `\u003cTWRDownloadManager/TWRDownloadObject.h\u003e`. \n\nDefine your progress and completion blocks as two properties:\n\n```objc\n@property (strong, nonatomic) TWRDownloadProgressBlock progressBlock;\n@property (strong, nonatomic) TWRDownloadCompletionBlock completionBlock;\n```\n\nIn your implementation (.m) file, define their block getters:\n\n```objc\n\n- (TWRDownloadProgressBlock)progressBlock {\n    __weak typeof(self)weakSelf = self;\n    return ^void(CGFloat progress){\n        dispatch_async(dispatch_get_main_queue(), ^(void) {\n            __strong __typeof(weakSelf)strongSelf = weakSelf;\n\t\t\t\t\t\t// do something with the progress on the cell!\n        });\n    };\n}\n\n- (TWRDownloadCompletionBlock)completionBlock {\n    __weak typeof(self)weakSelf = self;\n    return ^void(BOOL completed){\n        dispatch_async(dispatch_get_main_queue(), ^(void) {\n            __strong __typeof(weakSelf)strongSelf = weakSelf;\n\t\t\t\t\t\t// do something \n        });\n    };\n}\n```\n\nFinally, don't forget to nil out the blocks before the cell can be reused:\n\n```objc\n-(void)prepareForReuse {\n    self.progressBlock = nil;\n}\n```\n\nNow in your code, whenever you set up a new cell you can get the cell's own progress and completion block and pass them to the download manager. Voilà!\n\n## Requirements\n\n`TWRDownloadManager` requires iOS 7.x or greater.\n\n\n## License\n\nUsage is provided under the [MIT License](http://opensource.org/licenses/mit-license.php).  See LICENSE for the full details.\n\n## Contributions\n\nAll contributions are welcome. Please fork the project to add functionalities and open a pull request to have them merged into the master branch in the next releases.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchasseurmic%2FTWRDownloadManager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchasseurmic%2FTWRDownloadManager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchasseurmic%2FTWRDownloadManager/lists"}