Networking

  • Undocumented

    See more

    Declaration

    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
  • Undocumented

    See more

    Declaration

    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
  • Undocumented

    See more

    Declaration

    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 `YES` 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 `YES` if the object actually has remote content. Since most `PSPDFRemoteContentObject`s
    /// will have remote content, this method is optional. If it is not implemented, `YES` 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
  • Undocumented

    See more

    Declaration

    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