PSPDFLibrary

Objective-C


@interface PSPDFLibrary : NSObject

Swift

class PDFLibrary : NSObject

PSPDFLibrary implements a sqlite-based full-text-search engine. You set a data source that provides the documents to be indexed by the library, and then call -updateIndex, which performs its work asynchronously. Then, you can search for keywords within that collection. Typically, you use a PSPDFLibraryFileSystemDataSource. There can be multiple libraries, although usually one is enough for the common use case. Furthermore, when using multiple libraries with spotlight indexing enabled could lead to duplicates in users’ spotlight results. See https://pspdfkit.com/guides/ios/current/features/indexed-full-text-search/ for further documentation.

Note

Requires the Features.indexedFTS feature flag.

-init
Unavailable

Not the designated initializer

Undocumented
Declaration
Objective-C

PSPDF_EMPTY_INIT_UNAVAILABLE
+new
Unavailable

Not the designated initializer

Undocumented
Declaration
Objective-C

PSPDF_EMPTY_INIT_UNAVAILABLE

Initialization


                      
                      
                      
                      
                      +libraryWithPath:error:

If no library for the given path exists yet, this method will create and return one. All subsequent calls will return the same instance. Hence there will only be one instance per path. This method will return nil for invalid paths.

Note

If a library is created, it will be with the default tokenizer and the highest version of FTS available.

Declaration

Objective-C

+ (nullable instancetype)libraryWithPath:(nonnull NSString *)path
                                   error:(NSError *_Nullable *_Nullable)error;

Swift

convenience init(path: String) throws

Parameters

`path`	The path for which the library is to be retrieved or created if it does not exist already.
`error`	A pointer to an error that will be set if the library could not be retrieved or created

Return Value

A library for the specified path


                      
                      
                      
                      
                      +libraryWithPath:tokenizer:error:

Declaration

Objective-C

+ (nullable instancetype)libraryWithPath:(nonnull NSString *)path
                               tokenizer:(nullable NSString *)tokenizer
                                   error:(NSError *_Nullable *_Nullable)error;

Swift

convenience init(path: String, tokenizer: String?) throws

Parameters

`path`	The path for which the library is to be retrieved or created if it does not exist already.
`tokenizer`	See `PSPDFLibrary.tokenizer`
`error`	A pointer to an error that will be set if the library could not be retrieved or created.

Return Value

A library for the specified path.


                      
                      
                      
                      
                      +libraryWithPath:ftsVersion:tokenizer:error:

Declaration

Objective-C

+ (nullable instancetype)libraryWithPath:(nonnull NSString *)path
                              ftsVersion:(PSPDFLibraryFTSVersion)ftsVersion
                               tokenizer:(nullable NSString *)tokenizer
                                   error:(NSError *_Nullable *_Nullable)error;

Swift

convenience init(path: String, ftsVersion: PDFLibrary.FTSVersion, tokenizer: String?) throws

Parameters

`path`	The path for which the library is to be retrieved or created if it does not exist already.
`tokenizer`	See `PSPDFLibrary.tokenizer`
`ftsVersion`	The version of FTS this library is to use. If the specified version is unavailable, the library will not be created.
`error`	A pointer to an error that will be set if the library could not be retrieved or created.

Return Value

A library for the specified path.


                      
                      
                      
                      
                      +libraryWithPath:indexingPriority:ftsVersion:tokenizer:error:

Declaration

Objective-C

+ (nullable instancetype)libraryWithPath:(nonnull NSString *)path
                        indexingPriority:(PSPDFLibraryIndexingPriority)priority
                              ftsVersion:(PSPDFLibraryFTSVersion)ftsVersion
                               tokenizer:(nullable NSString *)tokenizer
                                   error:(NSError *_Nullable *_Nullable)error;

Swift

convenience init(path: String, indexingPriority priority: PDFLibrary.IndexingPriority, ftsVersion: PDFLibrary.FTSVersion, tokenizer: String?) throws

Parameters

`path`	The path for which the library is to be retrieved or created if it does not exist already.
`priority`	The priority of the internal queue to be used for indexing.
`ftsVersion`	The version of FTS this library is to use. If the specified version is unavailable, the library will not be created.
`tokenizer`	See `PSPDFLibrary.tokenizer`
`error`	A pointer to an error that will be set if the library could not be retrieved or created.

Return Value

A library for the specified path.

Properties

+defaultLibraryPath
Returns the default path of the library used in PSPDFKitGlobal.sharedInstance.library.
Declaration
Objective-C

+ (nonnull NSString *)defaultLibraryPath;
Swift

class func defaultLibraryPath() -> String

Path to the current database.

Declaration

Objective-C

@property (nonatomic, copy, readonly) NSString *_Nonnull path;

Swift

var path: String { get }

spotlightIndexingType
Specifies whether the documents should also be indexed to Spotlight. If Spotlight indexing is not supported on the device, that is, +[CSSearchableIndex isIndexingAvailable] returns NO, then this property is ignored. Defaults to PSPDFLibrarySpotlightIndexingTypeDisabled.
Declaration
Objective-C

@property PSPDFLibrarySpotlightIndexingType spotlightIndexingType;
Swift

var spotlightIndexingType: PDFLibrary.SpotlightIndexingType { get set }
shouldIndexAnnotations
Specifies whether the contents of annotations in documents added to the library should be indexed by the library. Defaults to true.

Note
Changing this property does not affect already indexed documents.
Declaration
Objective-C

@property BOOL shouldIndexAnnotations;
Swift

var shouldIndexAnnotations: Bool { get set }
tokenizer
This property shows what tokenizer is used currently. You can set it in the initializers. When nil (the default), a PSPDFKit custom porter tokenizer that allows better CJK indexing is used. This tokenizer also comes with a few drawbacks, like much more lax matching of words (Searching for “Dependency” will also return “Dependencies”). If that is a problem, we suggest using the ‘UNICODE61’ tokenizer. The UNICODE61 tokenizer allows searching inside text with diacritics. http://swwritings.com/post/2013-05-04-diacritics-and-fts Sadly, Apple doesn’t ship this tokenizer with their sqlite builds but there is a support article how to enable it: https://pspdfkit.com/guides/ios/current/memory-and-storage/how-to-enable-the-unicode61-tokenizer/

Warning
Once the database is created, changing the tokenizer property will assert.
Declaration
Objective-C

@property (nonatomic, copy, readonly, nullable) NSString *tokenizer;
Swift

var tokenizer: String? { get }
saveReversedPageText
Will save a reversed copy of the original page text. Defaults to YES.

Note
If enabled, the sqlite cache will be about 2x bigger, but ends-with matches will be enabled.

Note
This doesn’t change indexes that already exist.
Declaration
Objective-C

@property BOOL saveReversedPageText;
Swift

var saveReversedPageText: Bool { get set }

Suspends the operations queues.

Declaration

Objective-C

@property (nonatomic) BOOL suspended;

Swift

var suspended: Bool { get set }

automaticallyPauseLongRunningTasks
On iOS, the system watchdog automatically kills any process taking using large amounts of CPU for extended periods of time. When indexing a very large amount of documents at the same time, it is possible to go over this limit. To prevent this from happening, PSPDFLibrary periodically pauses indexing if it has been going on for a long enough period, and then resumes it after a short break. Typically, if indexing is taking longer than maximumContiguousIndexingTime, the library will pause itself (by setting suspended to true), and resume after the automaticPauseDuration.

Defaults to true on iOS devices. Set to false to disable this behavior.
Declaration
Objective-C

@property (nonatomic) BOOL automaticallyPauseLongRunningTasks;
Swift

var automaticallyPauseLongRunningTasks: Bool { get set }
maximumContiguousIndexingTime
The amount of time (in seconds) that indexing can run uninterrupted when automaticallyPauseLongRunningTasks is set to true. Defaults to 140.
Declaration
Objective-C

@property NSTimeInterval maximumContiguousIndexingTime;
Swift

var maximumContiguousIndexingTime: TimeInterval { get set }
automaticPauseDuration
The amount of time indexing should be paused when suspended automaticallyPauseLongRunningTasks is set to true. Defaults to 40 seconds.
Declaration
Objective-C

@property NSTimeInterval automaticPauseDuration;
Swift

var automaticPauseDuration: TimeInterval { get set }

Library Operations


                      
                      
                      
                      
                      -documentUIDsMatchingString:options:completionHandler:

See documentUIDsMatchingString:options:completionHandler:previewTextHandler:.

Declaration

Objective-C

- (void)documentUIDsMatchingString:(nonnull NSString *)searchString
                           options:
                               (nullable NSDictionary<PSPDFLibraryOption, id> *)
                                   options
                 completionHandler:
                     (nonnull void (^)(NSString *_Nonnull,
                                       NSDictionary<NSString *, NSIndexSet *>
                                           *_Nonnull))completionHandler;

Swift

func documentUIDs(matching searchString: String, options: [PDFLibrary.Option : Any]? = nil, completionHandler: @escaping (String, [String : IndexSet]) -> Void)


                      
                      
                      
                      
                      -documentUIDsMatchingString:options:completionHandler:previewTextHandler:

Query the database for a match of searchString. Only direct matches, begins-with and ends-with matches are supported. Returns in the completionHandler. If you provide an optional previewTextHandler, a text preview for all search results will be extracted from the matching documents and a dictionary of UID->NSSet of PSPDFLibraryPreviewResults will be returned in the previewTextHandler.

By default the number of search and preview results is limited to 500 to keep maximum search times reasonable. Use options to modify both limits.

Note

previewTextHandler is optional.

Note

Ends-with matches are only possible if saveReversedPageText has been YES while the document was indexed.

Warning

The completion handler might be called on a different thread.

Declaration

Objective-C

- (void)documentUIDsMatchingString:(nonnull NSString *)searchString
                           options:
                               (nullable NSDictionary<PSPDFLibraryOption, id> *)
                                   options
                 completionHandler:
                     (nullable void (^)(NSString *_Nonnull,
                                        NSDictionary<NSString *, NSIndexSet *>
                                            *_Nonnull))completionHandler
                previewTextHandler:
                    (nullable void (^)(
                        NSString *_Nonnull,
                        NSDictionary<NSString *,
                                     NSSet<PSPDFLibraryPreviewResult *> *>
                            *_Nonnull))previewTextHandler;

Swift

func documentUIDs(matching searchString: String, options: [PDFLibrary.Option : Any]? = nil, completionHandler: ((String, [String : IndexSet]) -> Void)?, previewTextHandler: ((String, [String : Set<AnyHashable>]) -> Void)? = nil)

Parameters

`searchString`	The string to search for in the FTS database.
`options`	The options for the search.
`completionHandler`	The block to be executed on completion of the search. It’s arguments are the input search string and a dictionary of UID->`NSIndexSet` of matching page numbers.
`previewTextHandler`	The block to execute with a text preview argument for all the search results. A dictionary of UID -> `NSSet<PSPDFLibraryPreviewResult *>` objects will be passed in as the argument.

Index Status


                      
                      
                      
                      
                      -indexStatusForUID:withProgress:

Checks the indexing status of the document. If status is PSPDFLibraryIndexStatusPartialAndIndexing progress will be set as well.

Declaration

Objective-C

- (PSPDFLibraryIndexStatus)indexStatusForUID:(nonnull NSString *)UID
                                withProgress:(nullable CGFloat *)outProgress;

Swift

func indexStatus(forUID UID: String, withProgress outProgress: UnsafeMutablePointer<CGFloat>?) -> PDFLibrary.IndexStatus

Parameters

`UID`	The UID of the document whose index status is to be retrieved.
`outProgress`	A pointer to a CGFloat that, on return, will point to the current indexing progress if the document is currently being indexed.

Return Value

The current indexing status of the document with the specified UID.

indexing
Returns YES if library is currently indexing, and is not suspended. This property will return false if indexing is suspended automatically because automaticallyPauseLongRunningTasks is set to true.
Declaration
Objective-C

@property (nonatomic, readonly, getter=isIndexing) BOOL indexing;
Swift

var isIndexing: Bool { get }

Returns all queued and indexing UIDs.

Declaration

Objective-C

@property (nonatomic, readonly) NSOrderedSet<NSString *> *_Nonnull queuedUIDs;

Swift

var queuedUIDs: NSOrderedSet { get }


                      
                      
                      
                      
                      indexedUIDs

Returns all the indexed UIDs, or nil if we were unable to fetch the data.

Declaration

Objective-C

@property (nonatomic, readonly, nullable) NSOrderedSet<NSString *> *indexedUIDs;

Swift

var indexedUIDs: NSOrderedSet? { get }

indexedUIDCount
Specifies the number of indexed UIDs, or -1 if it was unable to be retrieved.
Declaration
Objective-C

@property (nonatomic, readonly) NSInteger indexedUIDCount;
Swift

var indexedUIDCount: Int { get }


                      
                      
                      
                      
                      -indexedDocumentWithUID:

Retrieves a document with the specified UID from the data source, if any. Using this method is preferred to directly interacting with the data source’s PSPDFLibraryDataSource methods.

Warning

This method might be slow, as it depends on the data source’s ability to provide the document.

Declaration

Objective-C

- (nullable PSPDFDocument *)indexedDocumentWithUID:(nonnull NSString *)UID;

Swift

func indexedDocument(withUID UID: String) -> PSPDFDocument?

Parameters

UID

The UID of the document to be fetched.

Return Value

The document for the specified UID, if it exists, else nil.

Indexing Operations

The library’s data source. Note that this object will be retained

Declaration

Objective-C

@property (strong, nullable) id<PSPDFLibraryDataSource> dataSource;

Swift

var dataSource: LibraryDataSource? { get set }


                      
                      
                      
                      
                      -updateIndexWithCompletionHandler:

Updates the index based on information provided by the data source. If there is not data source set, this method will raise PSPDFLibraryInvalidOperationException. Any currently queued documents will be removed.

See

dataSource.

Declaration

Objective-C

- (void)updateIndexWithCompletionHandler:
    (nullable dispatch_block_t)completionHandler;

Swift

func updateIndex(completionHandler: (() -> Void)? = nil)

Parameters


                                  completionHandler

The block to call after all indexing operations have been completed. This may be called on a background queue.


                      
                      
                      
                      
                      -removeIndexForUID:

Removes the indexed contents for document with a matcing UID.

Warning

This method performs its work synchronously, and will block until the database call completes.

Declaration

Objective-C

- (void)removeIndexForUID:(nonnull NSString *)UID;

Swift

func removeIndex(forUID UID: String)

Parameters

UID

The UID of the document whose content is to be removed from the index.

-clearAllIndexes
Removes all indexed content by deleting the database and recreating it.

Warning
This method is synchronous and will block until the database call completes.
Declaration
Objective-C

- (void)clearAllIndexes;
Swift

func clearAllIndexes()

Spotlight Helpers


                      
                      
                      
                      
                      -fetchSpotlightIndexedDocumentForUserActivity:completionHandler:

Fetches the document specified by the user activity

Declaration

Objective-C

- (void)
    fetchSpotlightIndexedDocumentForUserActivity:
        (nonnull NSUserActivity *)userActivity
                               completionHandler:
                                   (nonnull void (^)(PSPDFDocument *_Nullable))
                                       completionHandler;

Swift

func fetchSpotlightIndexedDocument(for userActivity: NSUserActivity, completionHandler: @escaping (PSPDFDocument?) -> Void)

Parameters

`userActivity`	The userActivity received in your application delegata’s `application:continueUserActivity:restorationHandler:` as a result of the user selecting a spotlight search result.
`completionHandler`	The block to call if the document corresponding to the userActivity has been indexed in Spotlight.

Queue Operations

-cancelAllPreviewTextOperations
Cancels all pending preview text operations.

Note
The previewTextHandler of cancelled operations will not be called.
Declaration
Objective-C

- (void)cancelAllPreviewTextOperations;
Swift

func cancelAllPreviewTextOperations()

EncryptionSupport

+encryptedLibraryWithPath:encryptionKeyProvider:error:
Returns an encrypted library for this given path. The encryptionKeyProvider is used to access the encryption key when necessary. This allows us to not keep the encryption key around in memory. Your implementation of encryption key provider should therefore always load the key from secure storage, e.g. Apple’s keychain. An encryption key provider must also be side-effect free in the sense that it always returns the same encryption key on every call. This method will return nil for invalid paths.

Note

In contrast to libraryWithPath:, this method will not return the same instance when calling it with an already used path.

Warning

This method will return nil if the given encryption key provider was invalid.
Declaration
Objective-C

+ (nonnull instancetype) encryptedLibraryWithPath:(nonnull NSString *)path encryptionKeyProvider: (nullable NSData *_Nonnull (^)(void))encryptionKeyProvider error:(NSError *_Nullable *_Nullable)error;
Swift

class func encryptedLibrary(withPath path: String, encryptionKeyProvider: (() -> Data)?, error: NSErrorPointer) -> Self
+encryptedLibraryWithPath:encryptionKeyProvider:tokenizer:error:
Returns an encrypted library for this given path. The encryptionKeyProvider is used to access the encryption key when necessary. This allows us to not keep the encryption key around in memory. Your implementation of encryption key provider should therefore always load the key from secure storage, e.g. Apple’s keychain. An encryption key provider must also be side-effect free in the sense that it always returns the same encryption key on every call. This method will return nil for invalid paths.

You can also specify a custom tokenizer – see the tokenizer property.

Note

In contrast to libraryWithPath:, this method will not return the same instance when calling it with an already used path.

Warning

This method will return nil if the given encryption key provider was invalid.
Declaration
Objective-C

+ (nonnull instancetype) encryptedLibraryWithPath:(nonnull NSString *)path encryptionKeyProvider: (nullable NSData *_Nonnull (^)(void))encryptionKeyProvider tokenizer:(nullable NSString *)tokenizer error:(NSError *_Nullable *_Nullable)error;
Swift

class func encryptedLibrary(withPath path: String, encryptionKeyProvider: (() -> Data)?, tokenizer: String?, error: NSErrorPointer) -> Self
+encryptedLibraryWithPath:encryptionKeyProvider:ftsVersion:tokenizer:error:
Returns an encrypted library for this given path. The encryptionKeyProvider is used to access the encryption key when necessary. This allows us to not keep the encryption key around in memory. Your implementation of encryption key provider should therefore always load the key from secure storage, e.g. Apple’s keychain. An encryption key provider must also be side-effect free in the sense that it always returns the same encryption key on every call. This method will return nil for invalid paths.

You can also specify the FTS Version to use and a custom tokenizer – see the tokenizer property.

Note

In contrast to libraryWithPath:, this method will not return the same instance when calling it with an already used path.

Warning

This method will return nil if the given encryption key provider was invalid.
Declaration
Objective-C

+ (nonnull instancetype) encryptedLibraryWithPath:(nonnull NSString *)path encryptionKeyProvider: (nullable NSData *_Nonnull (^)(void))encryptionKeyProvider ftsVersion:(PSPDFLibraryFTSVersion)ftsVersion tokenizer:(nullable NSString *)tokenizer error:(NSError *_Nullable *_Nullable)error;
Swift

class func encryptedLibrary(withPath path: String, encryptionKeyProvider: (() -> Data)?, ftsVersion: PDFLibrary.FTSVersion, tokenizer: String?, error: NSErrorPointer) -> Self
+encryptedLibraryWithPath:encryptionKeyProvider:indexingPriority:ftsVersion:tokenizer:error:
Returns an encrypted library for this given path. The encryptionKeyProvider is used to access the encryption key when necessary. This allows us to not keep the encryption key around in memory. Your implementation of encryption key provider should therefore always load the key from secure storage, e.g. Apple’s keychain. An encryption key provider must also be side-effect free in the sense that it always returns the same encryption key on every call. This method will return nil for invalid paths.

You can also specify the FTS Version to use and a custom tokenizer – see the tokenizer property.

Note

In contrast to libraryWithPath:, this method will not return the same instance when calling it with an already used path.

Warning

This method will return nil if the given encryption key provider was invalid.
Declaration
Objective-C

+ (nonnull instancetype) encryptedLibraryWithPath:(nonnull NSString *)path encryptionKeyProvider: (nullable NSData *_Nonnull (^)(void))encryptionKeyProvider indexingPriority:(PSPDFLibraryIndexingPriority)priority ftsVersion:(PSPDFLibraryFTSVersion)ftsVersion tokenizer:(nullable NSString *)tokenizer error:(NSError *_Nullable *_Nullable)error;
Swift

class func encryptedLibrary(withPath path: String, encryptionKeyProvider: (() -> Data)?, indexingPriority priority: PDFLibrary.IndexingPriority, ftsVersion: PDFLibrary.FTSVersion, tokenizer: String?, error: NSErrorPointer) -> Self

Indicates if the library instance uses encryption.

Declaration

Objective-C

@property (nonatomic, readonly, getter=isEncrypted) BOOL encrypted;

Swift

var isEncrypted: Bool { get }