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 fromlistCacheEntries:
where thedownloadedLayerNames
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 aPSPDFInstantErrorCouldNotRemoveDiskCacheEntries
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