PSPDFLibrary


@interface PSPDFLibrary : 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 it works synchronously. 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 PSPDFFeatureMaskIndexedFTS feature flag.

  • Undocumented

    Declaration

    Objective-C

    
    @interface PSPDFLibrary : NSObject
  • Undocumented

    Declaration

    Objective-C

    
    @interface PSPDFLibrary : NSObject
  • 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

    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.

  • 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: PSPDFLibraryFTSVersion, 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.

  • 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: PSPDFLibraryIndexingPriority, ftsVersion: PSPDFLibraryFTSVersion, 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.

  • Returns the default path of the library used in PSPDFKit.sharedInstance.library.

    Declaration

    Objective-C

    + (nonnull NSString *)defaultLibraryPath;

    Swift

    class func defaultLibraryPath() -> String
  • Path to the current database.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic) 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 (assign, readwrite, atomic)
        PSPDFLibrarySpotlightIndexingType spotlightIndexingType;

    Swift

    var spotlightIndexingType: PSPDFLibrarySpotlightIndexingType { get set }
  • Specifies whether the contents of annotations in documents added to the library should be indexed by the library. Defaults to YES.

    Note

    Changing this property does not affect already indexed documents.

    Declaration

    Objective-C

    @property (assign, readwrite, atomic) BOOL shouldIndexAnnotations;

    Swift

    var shouldIndexAnnotations: Bool { get set }
  • This property shows what tokenizer is used currently. You can set it in the initializers. Defaults to nil, a PSPDFKit custom tokenizer that allows better CJK indexing. 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 (readonly, copy, nonatomic, 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 (assign, readwrite, atomic) BOOL saveReversedPageText;

    Swift

    var saveReversedPageText: Bool { get set }
  • Suspends the operations queues.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL suspended;

    Swift

    var suspended: Bool { get set }
  • See documentUIDsMatchingString:options:completionHandler:previewTextHandler:.

    Declaration

    Objective-C

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

    Swift

    func documentUIDs(matching searchString: String, options: [String : 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 PSPDFSearchResults 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.

    Note

    You can store additional metadata for an indexed document. To do so, simply enqueue documents with a set libraryMetadata dictionary. You can then query the metadata information by using the -metadataForUID: method.

    Warning

    The completion handler might be called on a different thread.

    Declaration

    Objective-C

    - (void)
    documentUIDsMatchingString:(nonnull NSString *)searchString
                       options:(nullable NSDictionary<NSString *, 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: [String : Any]? = nil, completionHandler: ((String, [String : IndexSet]) -> Void)?, previewTextHandler: ((String, [String : Set

    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 <PSPDFSearchResult *> 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

    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.

    Declaration

    Objective-C

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

    Swift

    var isIndexing: Bool { get }
  • Returns all queued and indexing UIDs.

    Declaration

    Objective-C

    @property (readonly, nonatomic) 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 (readonly, nonatomic, 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 (readonly, nonatomic) 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.

  • Returns the stored metadata for a previously enqueued document UID. If no metadata has been stored, this method will return nil.

    Declaration

    Objective-C

    - (nullable NSDictionary *)metadataForUID:(nonnull NSString *)UID;

    Swift

    func metadata(forUID UID: String) -> [AnyHashable : Any]?
  • The library’s data source. Note that this object will be retained

    Declaration

    Objective-C

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

    Swift

    var dataSource: PSPDFLibraryDataSource? { get set }
  • Updates the index based on information provided by the data source. If there is no data source set, this method will raise a PSPDFLibraryInvalidOperationException. Any currently queued documents will be removed. - warning: This method will retrieve information about documents to be indexed, which might be slow, synchronously. This is important when using the file system data source. - note: We recommend calling this on a background queue: DispatchQueue.global(qos: .background).async { library.updateIndex() } - see: dataSource

    Declaration

    Objective-C

    - (void)updateIndex;

    Swift

    func updateIndex()
  • Invalidates the search index for document with a matcing UID.

    Declaration

    Objective-C

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

    Swift

    func removeIndex(forUID UID: String)
  • Clear all database objects. Will clear ALL content in path.

    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.

  • Queue an array of PSPDFDocument objects for indexing for FTS, as well as in Spotlight, if indexToSpotlight is enabled.

    Note

    Documents that are already queued or completely indexed will be forcefully reindexed

    Warning

    This is a potentially slow operation

    Declaration

    Objective-C

    - (void)enqueueDocuments:(nonnull NSArray<PSPDFDocument *> *)documents;

    Swift

    func enqueue(_ documents: [PSPDFDocument])

    Parameters

    documents

    The array of documents to be indexed.

  • 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: PSPDFLibraryFTSVersion, 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: PSPDFLibraryIndexingPriority, ftsVersion: PSPDFLibraryFTSVersion, tokenizer: String?, error: NSErrorPointer) -> Self
  • Indicates if the library instance uses encryption.

    Declaration

    Objective-C

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

    Swift

    var isEncrypted: Bool { get }