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

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

    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
    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.

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

    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
    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.

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

    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
    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.

  • 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 }
  • 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 }
  • 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 }
  • 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 }
  • 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 }
  • 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 }
  • 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 }
  • 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 }
  • 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)
  • 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.

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

  • 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 }
  • 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 }
  • 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 }
  • 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.

  • 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 }
  • 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.

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

  • 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()
  • 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.

  • Cancels all pending preview text operations.

    Note

    The previewTextHandler of cancelled operations will not be called.

    Declaration

    Objective-C

    - (void)cancelAllPreviewTextOperations;

    Swift

    func cancelAllPreviewTextOperations()
  • 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
  • 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
  • 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
  • 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 }