PSPDFInstantClient

Objective-C


@interface PSPDFInstantClient : NSObject

Swift

class InstantClient : NSObject

The entry point to Instant, representing a client that can connect to PSPDFKit Server.

The Instant client manages the descriptors of the documents that you have access to. It provides the container for your downloaded documents, and controls the communication channel to the server. By providing a delegate, you are informed of relevant events regarding the synced documents and can manage tasks like authentication in a centralized manner.

  • The URL of the directory where Instant stores its documents, which is a subdirectory of Application Support.

    It is possible to customize the directory by subclassing and overriding this method, but there should typically be no need to do so.

    To use file protection on the data that Instant stores, refer to our guide: https://pspdfkit.com/guides/ios/pspdfkit-instant/data-protection/

    Warning

    The internal structure of this directory is private!

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) NSURL *_Nonnull dataDirectory;

    Swift

    class var dataDirectory: URL { get }

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Initializes a new client object.

    Creating a new client object requires reading from, and potentially writing to permanent storage. There are a several scenarios where these operations can fail: running out of space, insufficient permissions, data corruption are just some of those.

    As such it is important that you appropriately handle the PSPDFInstantError in case of a failure.

    Declaration

    Objective-C

    - (nullable instancetype)initWithServerURL:(nonnull NSURL *)serverURL
                                     error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(serverURL: URL) throws

    Parameters

    serverURL

    The base URL of the PSPDFKit Server the client should connect to.
    error

    A pointer to be populated with an error when creating the client failed.

    Return Value

    The newly created client.

  • The base URL of the PSPDFKit Server the client connects to, as provided when creating the client;

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSURL *_Nonnull serverURL;

    Swift

    var serverURL: URL { get }

  • An object to be notified of download and authentication events for documents managed by this client.

    All delegate methods will be called on a background thread.

    Declaration

    Objective-C

    @property (nonatomic, weak) id<PSPDFInstantClientDelegate> _Nullable delegate;

    Swift

    weak var delegate: InstantClientDelegate? { get set }

  • Convenience that extracts the layer information from the given JWT.

    Extracts the document identifier and layer name from the passed JWT, ignoring the expiration date, and returns a document descriptor for the layer information. The receiver will keep a reference to the returned object and return the same instance for repeated calls with JWTs containing the same layer information.

    If the JWT is in an invalid format, this method fails. If the layer information could be extracted, the call will immediately return a document descriptor — regardless of the JWTs actual fitness. Validation of the JWTs signature and expiration date is performed asynchronously when you actually attempt to sync the returned object.

    Declaration

    Objective-C

    - (nullable id<PSPDFInstantDocumentDescriptor>)
    documentDescriptorForJWT:(nonnull NSString *)JWT
                       error:(NSError *_Nullable *_Nullable)error;

    Swift

    func documentDescriptor(forJWT JWT: String) throws -> InstantDocumentDescriptor

    Parameters

    JWT

    A JSON web token returned by your backend, identifying the document and layer you want to access.
    error

    A pointer to be populated with an error when this call fails.

  • Returns all locally available document descriptors, grouped by document identifier.

    This method gives you convenient access to the document descriptors for all locally available layers of all downloaded documents. Each key in the returned dictionary corresponds to the identifier of a downloaded document. As there is no inherent order to the layers that exist for any given document, the corresponding value is a set (rather than an array) of document descriptors for those layers.

    Note

    It is possible that a document is locally available, but we have no layers for it anymore. In those cases, the document identifier will not be contained in the dictionary. In effect, the dictionary will be empty if there are only documents left that have no local layers anymore.

    Declaration

    Objective-C

    - (nullable
       NSDictionary<NSString *, NSSet<id<PSPDFInstantDocumentDescriptor>> *> *)
    localDocumentDescriptors:(NSError *_Nullable *_Nullable)error;

    Swift

    func localDocumentDescriptors() throws -> [String : Set<AnyHashable>]

  • Purges any cache entries where we have a document, but no annotations available.

    Because there can be multiple layers for just a single document, removing the local data of a document descriptor only purges its annotation data from disk. The lion’s share of the disk space required by a document descriptor, however, is the actual PDF file. This can lead to the situation where an instant client still occupies a lot of disk space for its cache, even though most of the data it holds is no longer referenced. We call those file for which no layers are loaded “unreferenced”.

    This method uses file coordination to safely and atomically identify all unreferenced files, and purges them from disk. You can call it occasionally during app startup, or at any other point in time when you want to reclaim unneeded disk space.

    Note

    This method is not equivalent to calling removeLocalStorageForDocumentIdentifier:error: for any entry returned from listCacheEntries: where the downloadedLayerNames is empty. You can think of it as wrapping all those calls into one atomic transaction, though.

    Declaration

    Objective-C

    - (nullable NSSet<NSString *> *)removeUnreferencedCacheEntries:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func removeUnreferencedCacheEntries() throws -> Set<String>

    Parameters

    error

    A pointer to be populated in case of an error, detailing why the operation failed.

    Return Value

    On success, the (possibly empty) list of identifiers of all the documents that have been purged.

  • Returns a snapshot of the current state of the document disk cache.

    This method allows you to inspect how much disk space is currently occupied by the receiver, and decide what you might want to purge in orded to reclaim additional space.

    Note

    For ease of use, this method returns just a snapshot of the current state. In practice, this should not be an issue because the lion’s share of the space occupied by a document is the actual PDF file — and that remains untouched, no matter how many annotations you add to whichever layers.

    Declaration

    Objective-C

    - (nullable NSSet<id<PSPDFInstantDocumentCacheEntry>> *)listCacheEntries:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func listCacheEntries() throws -> Set<AnyHashable>

    Return Value

    A (possibly empty) snapshot of the disk cache metadata, or nil if the disk cache could not be queried.

  • Removes the local data for the given document identifier, invalidating any associated document descriptors.

    In order to reclaim disk space, you may want to prune the cache from time to time. If purging the data for unreferenced files is not enough, this method allows you to selectively remove all on-disk data associated with a given document identifier — regardless of that data still being referenced.

    When called, this method attempts to query the disk cache, and invalidates any related existing document descriptor. It then purges all the associated data from disk. The method will fail with a PSPDFInstantErrorCouldNotReadFromDiskCache if the disk cache cannot be queried, or with a PSPDFInstantErrorCouldNotRemoveDiskCacheEntries if the data could not be deleted.

    Declaration

    Objective-C

    - (BOOL)removeLocalStorageForDocumentIdentifier:
            (nonnull NSString *)documentIdentifier
                                          error:(NSError *_Nullable *_Nullable)
                                                    error;

    Swift

    func removeLocalStorage(forDocumentIdentifier documentIdentifier: String) throws

    Parameters

    documentIdentifier

    The identifier for the document whose cache entry should be removed from disk.
    error

    A pointer to be populated when this method fails.

  • Removes the client’s local storage from disk, including storage for all documents. This will also cancel any in-progress network operations for all the client’s documents.

    If your app has a sign out procedure, this method should be called when a user signs out.

    Errors may occur due to file system operations failing.

    Declaration

    Objective-C

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

    Swift

    func removeLocalStorage() throws