PSPDFInstantDocumentDescriptor

@protocol PSPDFInstantDocumentDescriptor <NSObject>

A PSPDFInstantDocumentDescriptor represents a document managed by Instant and may be used to download a local copy of the document to show to the user.

Instant manages downloading and storing the PDF files, and synchronizes annotations automatically.

Instances must not be created directly, but instead obtained from a PSPDFInstantClient, which also keeps the instances it creates alive.

Notifications are posted for events, with the document descriptor as the object. For a convenient alternative API see PSPDFInstantClientDelegate.

  • Undocumented

    Declaration

    Objective-C

    @protocol PSPDFInstantDocumentDescriptor <NSObject>
  • Undocumented

    Declaration

    Objective-C

    @protocol PSPDFInstantDocumentDescriptor <NSObject>
  • The identifier for the document used by PSPDFKit Server.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *_Nonnull identifier;

    Swift

    var identifier: String { get }
  • A Boolean value indicating whether the PDF file for this document has been downloaded from the server.

    Declaration

    Objective-C

    @property (readonly, getter=isDownloaded, nonatomic) BOOL downloaded;

    Swift

    var isDownloaded: Bool { get }
  • Starts asynchronously downloading a the document from PSPDFKit Server. The delegate will be notified when the download finishes or fails.

    If there is already a download in progress, this method will not start a duplicate download, and will not return an error.

    Declaration

    Objective-C

    - (BOOL)
    downloadDocumentUsingAuthenticationToken:(nonnull NSString *)authenticationToken
                                       error:(NSError *_Nullable *_Nullable)error;

    Swift

    func downloadDocument(usingAuthenticationToken authenticationToken: String) throws

    Parameters

    authenticationToken

    An authentication token (JWT) that gives the user approval to access this document. This must be supplied by your own server.

  • The progress of the document download, or nil if there is no current download, either due to the download having not been started or being finished.

    This may be used to cancel an in-progress download.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) NSProgress *downloadProgress;

    Swift

    var downloadProgress: Progress? { get }
  • Returns a PDF document, in which annotations may be edited.

    This property is nil if the document has not been downloaded, but this may change in the future, and therefore using this to check if the document has been downloaded is not recommended. Instead use the downloaded property.

    To start a download, use downloadDocumentUsingAuthenticationToken:error:.

    Note

    There can only be a single editable document for a document identifier at any time! Therefore, this method can return the same instance on repeated calls. If you need to display more than one instance of the same document at a time, for example when you want mirroring on an external screen, create secondary read-only instances using readOnlyDocumentWithError:.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) PSPDFDocument *editableDocument;

    Swift

    var editableDocument: PSPDFDocument? { get }
  • Returns a read-only PDF document.

    This method returns nil if the document has not been downloaded, but this may change in the future, and therefore using this to check if the document has been downloaded is not recommended. Instead use the downloaded property.

    To start a download, use downloadDocumentUsingAuthenticationToken:error:.

    To avoid undefined behavior, there can only be a single editable Instant-enabled PSPDFDocument for a given identifier at a time. But since one PSPDFDocument should only be used by one PSPDFViewController, there will be times — like mirroring on an external display — where you need more than just one. For these situations, you can get an arbitrary number of documents that are read-only: When changes are made, these are updated as appropriate, but they will not allow you to make any edits — like adding, changing, or removing existing annotations.

    Declaration

    Objective-C

    - (nullable PSPDFDocument *)readOnlyDocument;

    Swift

    func readOnlyDocument() -> PSPDFDocument?
  • Removes the local document storage from disk.

    This will also cancel any in-progress network operations for this document.

    This must be called before authenticating the document as a different user. Providing an authentication token for a different user without calling this method first may raise an exception.

    Errors may occur due to file system operations failing.

    Declaration

    Objective-C

    - (BOOL)removeLocalStorageWithError:(NSError *_Nullable *_Nullable)error;

    Swift

    func removeLocalStorage() throws
  • Updates the token (JWT) used to authenticate access to this document with the server.

    It is only necessary to set this if the JWT used to download the document has expired which typically means following the delegate receiving documentDidFailAuthentication:.

    Declaration

    Objective-C

    - (void)updateAuthenticationToken:(nonnull NSString *)authenticationToken;

    Swift

    func updateAuthenticationToken(_ authenticationToken: String)
  • Syncs annotations with the Instant server.

    When the document has been downloaded, this method initiates a one-time sync: While Instant will push your edits to the server as they happen, there are situations where you simply want the latest state from the server without making local changes. In those situations, you can use this method to start a one-time sync. Any remaining local changes are sent in the process. - note: If the document has not been downloaded yet, this method does nothing.

    Declaration

    Objective-C

    - (void)sync;

    Swift

    func sync()
  • Tells the receiver to start listening for changes from the server as they happen.

    Once a document has been downloaded, you can use this method to begin observing the server for changes. The most common use case for this is that you are displaying the document in your custom PDF view controller, and you want to make sure that the user sees changes made on other devices in a real-time-like fashion. When you call this method, PSPDF Instant will begin monitoring the server for changes until syncing fails, or until you call stopListeningForServerUpdates — whichever happens first.

    A word of warning: Using the network, especially the cellular network, is one of the most energy intensive tasks. While we do our best to minimize the energy impact this feature has, if your app does not require (near-)real-time sync, consider using explicit user actions to call sync instead. - note: If you use PSPDFInstantViewController you get this behavior for free! This method is provided if you cannot customize that class to suit your needs, but need real-time-like updates.

    Declaration

    Objective-C

    - (void)startListeningForServerUpdates;

    Swift

    func startListeningForServerUpdates()
  • Tells the receiver to stop listening for changes from the server.

    Once you are no longer interested in real-time updates from the server, use this method to stop listening for changes. A common scenario where you would want to call this, is when you stop displaying an Instant enabled document in your custom PDF view controller. - note: If you use PSPDFInstantViewController you get this behavior for free! This method is provided if you cannot customize that class to suit your needs, but need real-time updates.

    Declaration

    Objective-C

    - (void)stopListeningForServerUpdates;

    Swift

    func stopListeningForServerUpdates()