Added an ability to download a file and get a file path to PFFiles.

Author: nlutsenko

Parse/PFConstants.h

@@ -381,6 +381,7 @@ typedef void (^PFSetResultBlock)(NSSet *PF_NULLABLE_S channels, NSError *PF_NULL
 typedef void (^PFUserResultBlock)(PFUser *PF_NULLABLE_S user, NSError *PF_NULLABLE_S error);
 typedef void (^PFDataResultBlock)(NSData *PF_NULLABLE_S data, NSError *PF_NULLABLE_S error);
 typedef void (^PFDataStreamResultBlock)(NSInputStream *PF_NULLABLE_S stream, NSError *PF_NULLABLE_S error);
+typedef void (^PFFilePathResultBlock)(NSString *PF_NULLABLE_S filePath, NSError *PF_NULLABLE_S error);
 typedef void (^PFStringResultBlock)(NSString *PF_NULLABLE_S string, NSError *PF_NULLABLE_S error);
 typedef void (^PFIdResultBlock)(PF_NULLABLE_S id object, NSError *PF_NULLABLE_S error);
 typedef void (^PFProgressBlock)(int percentDone);

Parse/PFFile.h

@@ -374,6 +374,54 @@ PF_ASSUME_NONNULL_BEGIN
  */
 - (void)getDataInBackgroundWithTarget:(PF_NULLABLE_S id)target selector:(PF_NULLABLE_S SEL)selector;
 
+/*!
+ @abstract *Asynchronously* gets the file path for file from cache if available or fetches its contents from the network.
+ 
+ @note The file path may change between versions of SDK.
+ @note If you overwrite the contents of the file at returned path it will persist those change
+ until the file cache is cleared.
+
+ @returns The task, with the result set to `NSString` representation of a file path.
+ */
+- (BFTask PF_GENERIC(NSString *) *)getFilePathInBackground;
+
+/*!
+ @abstract *Asynchronously* gets the file path for file from cache if available or fetches its contents from the network.
+ 
+ @note The file path may change between versions of SDK.
+ @note If you overwrite the contents of the file at returned path it will persist those change
+ until the file cache is cleared.
+
+ @param progressBlock The block should have the following argument signature: `^(int percentDone)`.
+
+ @returns The task, with the result set to `NSString` representation of a file path.
+ */
+- (BFTask PF_GENERIC(NSString *) *)getFilePathInBackgroundWithProgressBlock:(PF_NULLABLE PFProgressBlock)progressBlock;
+
+/*!
+ @abstract *Asynchronously* gets the file path for file from cache if available or fetches its contents from the network.
+ 
+ @note The file path may change between versions of SDK.
+ @note If you overwrite the contents of the file at returned path it will persist those change
+ until the file cache is cleared.
+
+ @param block The block should have the following argument signature: `^(NSString *filePath, NSError *error)`.
+ */
+- (void)getFilePathInBackgroundWithBlock:(PF_NULLABLE PFFilePathResultBlock)block;
+
+/*!
+ @abstract *Asynchronously* gets the file path for file from cache if available or fetches its contents from the network.
+ 
+ @note The file path may change between versions of SDK.
+ @note If you overwrite the contents of the file at returned path it will persist those change
+ until the file cache is cleared.
+
+ @param block The block should have the following argument signature: `^(NSString *filePath, NSError *error)`.
+ @param progressBlock The block should have the following argument signature: `^(int percentDone)`.
+ */
+- (void)getFilePathInBackgroundWithBlock:(PF_NULLABLE PFFilePathResultBlock)block
+                           progressBlock:(PF_NULLABLE PFProgressBlock)progressBlock;
+
 ///--------------------------------------
 /// @name Interrupting a Transfer
 ///--------------------------------------

Parse/PFFile.m

@@ -213,6 +213,28 @@ - (void)getDataInBackgroundWithTarget:(id)target selector:(SEL)selector {
     }];
 }
 
+- (BFTask PF_GENERIC(NSString *) *)getFilePathInBackground {
+    return [self getFilePathInBackgroundWithProgressBlock:nil];
+}
+
+- (BFTask PF_GENERIC(NSString *)*)getFilePathInBackgroundWithProgressBlock:(PFProgressBlock)progressBlock {
+    return [[self _downloadAsyncWithProgressBlock:progressBlock] continueWithSuccessBlock:^id(BFTask *task) {
+        if (self.dirty) {
+            return self.stagedFilePath;
+        }
+        return [[[self class] fileController] cachedFilePathForFileState:self.state];
+    }];
+}
+
+- (void)getFilePathInBackgroundWithBlock:(PF_NULLABLE PFFilePathResultBlock)block {
+    [[self getFilePathInBackground] thenCallBackOnMainThreadAsync:block];
+}
+
+- (void)getFilePathInBackgroundWithBlock:(PF_NULLABLE PFFilePathResultBlock)block
+                           progressBlock:(PF_NULLABLE PFProgressBlock)progressBlock {
+    [[self getFilePathInBackgroundWithProgressBlock:progressBlock] thenCallBackOnMainThreadAsync:block];
+}
+
 #pragma mark Interrupting
 
 - (void)cancel {

Tests/Unit/FileUnitTests.m

@@ -415,6 +415,42 @@ - (void)testDownloading{
             return nil;
         }];
 
+    wait_next;
+    expectation = [self expectationForSelector:@selector(getFilePathInBackground)];
+    [[file getFilePathInBackground] continueWithBlock:^id(BFTask *task) {
+        NSData *data = [NSData dataWithContentsOfFile:task.result];
+        XCTAssertEqualObjects(data, expectedData);
+        [expectation fulfill];
+        return nil;
+    }];
+
+    wait_next;
+    expectation = [self expectationForSelector:@selector(getFilePathInBackgroundWithProgressBlock:)];
+    [[file getFilePathInBackgroundWithProgressBlock:[self progressValidationBlock]] continueWithBlock:^id(BFTask *task) {
+        NSData *data = [NSData dataWithContentsOfFile:task.result];
+        XCTAssertEqualObjects(data, expectedData);
+        [expectation fulfill];
+        return nil;
+    }];
+
+    wait_next;
+    expectation = [self expectationForSelector:@selector(getFilePathInBackgroundWithBlock:)];
+    [file getFilePathInBackgroundWithBlock:^(NSString *filePath, NSError *error) {
+        XCTAssertNil(error);
+        NSData *data = [NSData dataWithContentsOfFile:filePath];
+        XCTAssertEqualObjects(data, expectedData);
+        [expectation fulfill];
+    }];
+
+    wait_next;
+    expectation = [self expectationForSelector:@selector(getFilePathInBackgroundWithBlock:progressBlock:)];
+    [file getFilePathInBackgroundWithBlock:^(NSString *filePath, NSError *error) {
+        XCTAssertNil(error);
+        NSData *data = [NSData dataWithContentsOfFile:filePath];
+        XCTAssertEqualObjects(data, expectedData);
+        [expectation fulfill];
+    } progressBlock:[self progressValidationBlock]];
+
     wait_next;
 }