Networking

Objective-C

@interface PSPDFDownloadManager : NSObject

PSPDF_EMPTY_INIT_UNAVAILABLE

#pragma mark Configuration

/// The maximum number of concurrent downloads. Defaults to 2.
/// If `enableDynamicNumberOfConcurrentDownloads` is enabled, this property will change dynamically
/// and must be considered readonly.
@property (nonatomic) NSUInteger numberOfConcurrentDownloads;

/// Enable this property to let `PSPDFDownloadManager` decide what the best number of concurrent downloads
/// is depending on the network connection. Defaults to YES.
@property (nonatomic) BOOL enableDynamicNumberOfConcurrentDownloads;

/// The `PSPDFDownloadManager` delegate.
@property (nonatomic, weak) id<PSPDFDownloadManagerDelegate> delegate;

/// Controls if objects that are currently loading when the app moves to the background
/// should be completed in the background. Defaults to YES. iOS only.
@property (nonatomic) BOOL shouldFinishLoadingObjectsInBackground;

#pragma mark Enqueueing and Dequeueing Objects

/// See enqueueObject:atFront:. Enqueues the object at the end of the queue.
- (void)enqueueObject:(id<PSPDFRemoteContentObject>)object;

/// Enqueues an `PSPDFRemoteContentObject` for download. If the object is already downloading,
/// nothing is enqueued. If the object has been downloaded previously and has failed, it will be
/// removed from the failedObjects array and re-enqueued.
///
/// @param object The object to enqueue.
/// @param enqueueAtFront Set this to YES to add the object to the front of the queue.
- (void)enqueueObject:(id<PSPDFRemoteContentObject>)object atFront:(BOOL)enqueueAtFront;

/// Calls enqueueObject:atFont: multiple times. Enqueues the object at the end of the queue.
///
/// @param objects need to implement the `PSPDFRemoteContentObject` protocol.
- (void)enqueueObjects:(NSArray<id<PSPDFRemoteContentObject>> *)objects;

/// Calls enqueueObject:atFont: multiple times.
///
/// @param objects need to implement the `PSPDFRemoteContentObject` protocol.
- (void)enqueueObjects:(NSArray<id<PSPDFRemoteContentObject>> *)objects atFront:(BOOL)enqueueAtFront;

/// Cancels the download process for the given object.
///
/// @param object The object to be cancelled.
- (void)cancelObject:(id<PSPDFRemoteContentObject>)object;

/// Calls `cancelObject:` for all objects in `pendingObjects`, `loadingObjects`, and `failedObjects`.
- (void)cancelAllObjects;

#pragma mark State

/// The current reachability of the device.
@property (nonatomic, readonly) PSPDFReachability reachability;

/// Contains all objects waiting to be downloaded.
@property (nonatomic, copy, readonly) NSArray<id<PSPDFRemoteContentObject>> *waitingObjects;

/// Contains all currently loading objects.
@property (nonatomic, copy, readonly) NSArray<id<PSPDFRemoteContentObject>> *loadingObjects;

/// Contains all objects that have failed because of a network error and are scheduled for retry.
@property (nonatomic, copy, readonly) NSArray<id<PSPDFRemoteContentObject>> *failedObjects;

/// Helper that iterates loadingObjects, waitingObjects and failedObjects (in that order) and returns all matches.
- (NSArray<id<PSPDFRemoteContentObject>> *)objectsPassingTest:(BOOL (^)(id<PSPDFRemoteContentObject> obj, NSUInteger index, BOOL *stop))predicate;

/// Checks if the given object is currently handled by the download manager.
///
/// @param object The object.
/// @return YES if the download manager handles the object, that is if it is either pending, loading or failed.
- (BOOL)handlesObject:(id<PSPDFRemoteContentObject>)object;

/// Checks and returns the current state of a given object. If the object has never been enqueued,
/// `PSPDFDownloadManagerObjectStateNotHandled` will be returned.
///
/// @param object The object.
/// @return The state of the object.
- (PSPDFDownloadManagerObjectState)stateForObject:(id<PSPDFRemoteContentObject>)object;

@end

Swift

class DownloadManager : NSObject

Objective-C

@protocol PSPDFDownloadManagerPolicy<NSObject>

/// Returns YES when we're allowed to use the network.
@property (nonatomic, readonly) BOOL hasPermissionForNetworkEvent;

@end

Swift

protocol DownloadManagerPolicy : NSObjectProtocol

Objective-C

@protocol PSPDFRemoteContentObject<NSObject>

/// The URL request used for loading the remote content.
@property (nonatomic, readonly, nullable) NSURLRequest *URLRequestForRemoteContent;

/// The remote content of the object. This property is managed by `PSPDFDownloadManager`.
@property (nonatomic, nullable) id remoteContent;

@optional

/// The loading state of the object. This property is managed by `PSPDFDownloadManager`.
@property (nonatomic, getter=isLoadingRemoteContent) BOOL loadingRemoteContent;

/// The download progress of the object. Only meaningful if `loadingRemoteContent` is YES.
/// This property is managed by `PSPDFDownloadManager`.
@property (nonatomic) CGFloat remoteContentProgress;

/// The remote content error of the object. This property is managed by `PSPDFDownloadManager`.
@property (nonatomic, nullable) NSError *remoteContentError;

/// Return YES if you want `PSPDFDownloadManager` to cache the remote content. Defaults to NO.
@property (nonatomic, readonly) BOOL shouldCacheRemoteContent;

/// Return YES if you want `PSPDFDownloadManager` to retry downloading remote content if a connection
/// error occurred. Defaults to NO.
@property (nonatomic, readonly) BOOL shouldRetryLoadingRemoteContentOnConnectionFailure;

/// Return a block if you need to handle a authentication challenge.
@property (nonatomic, readonly) PSPDFRemoteContentObjectAuthenticationBlock remoteContentAuthenticationChallengeBlock;

/// Return a custom `PSPDFRemoteContentObjectTransformerBlock`. The passed-in `NSURL` points to the
/// file that stores the downloaded data. The return value is set to `remoteContent`. If no transformer
/// block is provided, `remoteContent` will be set to data (represented by `NSData`) of the downloaded
/// content.
///
/// @note If `shouldCacheRemoteContent` returns `true` the location of the file is not temporary.
/// @note `remoteContentTransformerBlock` will be called on a background queue, so you may perform
/// long-running tasks.
/// @warning Since this runs on a background queue, you should not access state outside of the block's
/// scope to avoid thread-safety problems.
@property (nonatomic, readonly, nullable) PSPDFRemoteContentObjectTransformerBlock remoteContentTransformerBlock;

/// Return `true` if the object actually has remote content. Since most `PSPDFRemoteContentObject`s
/// will have remote content, this method is optional. If it is not implemented, `true` will be assumed.
@property (nonatomic, readonly) BOOL hasRemoteContent;

/// The completion block, called after loading finished.
@property (nonatomic, copy, nullable) void (^completionBlock)(id<PSPDFRemoteContentObject> remoteObject);

@end

Swift

protocol RemoteContentObject : NSObjectProtocol

Objective-C

@interface PSPDFRemoteFileObject : NSObject<PSPDFRemoteContentObject>

PSPDF_EMPTY_INIT_UNAVAILABLE

/// Designated initializer.
- (instancetype)initWithRemoteURL:(NSURL *)remoteURL targetURL:(NSURL *)targetFileURL fileManager:(id<PSPDFFileManager>)fileManager NS_DESIGNATED_INITIALIZER;

/// The remote URL to fetch the content from.
@property (nonatomic, copy, readonly) NSURL *remoteURL;
@property (nonatomic, copy, readonly) NSURL *targetURL;

#pragma mark PSPDFRemoteContentObject

/// The remote content of the object. This property is managed by `PSPDFDownloadManager`.
@property (nonatomic, nullable) NSURL *remoteContent;

/// The loading state of the object. This property is managed by `PSPDFDownloadManager`.
@property (nonatomic, getter=isLoadingRemoteContent) BOOL loadingRemoteContent;

/// The download progress of the object. Only meaningful if `loadingRemoteContent` is YES.
/// This property is managed by `PSPDFDownloadManager`.
@property (nonatomic) CGFloat remoteContentProgress;

/// The remote content error of the object. This property is managed by `PSPDFDownloadManager`.
@property (nonatomic, nullable) NSError *remoteContentError;

/// The completion block.
@property (nonatomic, copy, nullable) void (^completionBlock)(id<PSPDFRemoteContentObject> remoteObject);

@end

Swift

class RemoteFileObject : NSObject, RemoteContentObject