PSPDFDocumentProvider

Objective-C


@interface PSPDFDocumentProvider : NSObject <PSPDFOverridable>

Swift

class PDFDocumentProvider : NSObject, Overridable

A Document consists of one or multiple PSPDFDocumentProvider‘s. Each document provider has exactly one data source (file/data/dataProvider)

Note

This class is used within Document and should not be instantiated externally.

  • Referenced data provider.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) id<PSPDFDataProviding> dataProvider;

  • The data provider URL, if the data provider exposes it.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *fileURL;

    Swift

    var fileURL: URL? { get }

  • Returns an NSData representation, memory-maps files, copies a data provider.

    Declaration

    Objective-C

    - (nullable NSData *)dataRepresentationWithError:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func dataRepresentation() throws -> Data

  • Returns the fileSize of this documentProvider.

    Declaration

    Objective-C

    @property (nonatomic, readonly) unsigned long long fileSize;

    Swift

    var fileSize: UInt64 { get }

  • Accesses the parent document.

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly) PSPDFDocument *_Nullable document;

    Swift

    weak var document: PSPDFDocument? { get }

  • Delegate for writing annotations. Defaults to the current set document.

    Declaration

    Objective-C

    @property (weak) id<PSPDFDocumentProviderDelegate> _Nullable delegate;

    Swift

    weak var delegate: DocumentProviderDelegate? { get set }

  • Returns the page info object for the supplied pageIndex, if it exists.

    Note

    Unlike with -[PSPDFDocument pageInfoForPageAtIndex:] here the returned PSPDFPageInfo‘s pageIndex property always equals the supplied pageIndex argument

    Declaration

    Objective-C

    - (nullable PSPDFPageInfo *)pageInfoForPageAtIndex:(PSPDFPageIndex)pageIndex;

    Swift

    func pageInfoForPage(at pageIndex: PageIndex) -> PSPDFPageInfo?

  • Number of pages in the PDF. 0 if source is invalid. Filtered by pageRange.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFPageCount pageCount;

    Swift

    var pageCount: PageCount { get }

  • Returns the page offset relative to the document.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger pageOffsetForDocument;

    Swift

    var pageOffsetForDocument: UInt { get }

  • Returns the password used to unlock the document.

    Declaration

    Objective-C

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

    Swift

    var password: String? { get }

  • The attached content signature.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSData *contentSignature;

    Swift

    var contentSignature: Data? { get }

  • Specifies what functions are allowed for a PDF document.

    Note

    This replaces allowsCopying and allowsPrinting from earlier versions of the SDK.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFDocumentPermissions permissions;

    Swift

    var permissions: DocumentPermissions { get }

  • Returns the permissions status of the PDF document. You have PSPDFDocumentPermissionsLevelNone status for an encrypted document that you have not supplied either a valid user or owner password. For a document with no encryption, you automatically have PSPDFDocumentPermissionsLevelOwner status.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFDocumentPermissionsLevel permissionsLevel;

    Swift

    var permissionsLevel: DocumentPermissionsLevel { get }

  • Was the PDF file encrypted at file creation time?

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isEncrypted;

    Swift

    var isEncrypted: Bool { get }

  • Was the PDF file encrypted with an User Password.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isEncryptedWithUserPassword;

    Swift

    var isEncryptedWithUserPassword: Bool { get }

  • Specifies if the document has been unlocked with full access.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isUnlockedWithFullAccess;

    Swift

    var isUnlockedWithFullAccess: Bool { get }

  • Specifies if the document has been unlocked with the user password.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isUnlockedWithUserPassword;

    Swift

    var isUnlockedWithUserPassword: Bool { get }

  • Has the PDF file been unlocked? (is it still locked?).

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isLocked;

    Swift

    var isLocked: Bool { get }

  • Are we able to add/change annotations in this file? Annotations can’t be added to encrypted documents or if there are parsing errors.

    Note

    If Features.annotationEditing isn’t available, this will return NO.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL canEmbedAnnotations;

    Swift

    var canEmbedAnnotations: Bool { get }

  • A flag that indicates whether changing existing annotations or creating new annotations are allowed

    Note

    Searches and checks the digital signatures on the first call (caches the result for subsequent calls)

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL allowAnnotationChanges;

    Swift

    var allowAnnotationChanges: Bool { get }

  • A file identifier.

    Note

    A permanent identifier based on the contents of the file at the time it was originally created.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSData *fileId;

    Swift

    var fileId: Data? { get }

  • Access the PDF title. (“.pdf” will be truncated)

    Note

    If there’s no title in the PDF metadata, the file name will be used.

    Declaration

    Objective-C

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

    Swift

    var title: String? { get }

  • Return a textParser for the specific document page. Page starts at 0. Will parse the page contents before returning. Might take a while.

    Declaration

    Objective-C

    - (nullable PSPDFTextParser *)textParserForPageAtIndex:
    (PSPDFPageIndex)pageIndex;

    Swift

    func textParserForPage(at pageIndex: PageIndex) -> PSPDFTextParser?

  • Outline extraction class for current PDF. Lazy initialized. Can be subclassed.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFOutlineParser *_Nonnull outlineParser;

    Swift

    var outlineParser: PSPDFOutlineParser { get }

  • Returns the AcroForm parser. Forms are a separate component and might not be enabled for your license. If forms are not enabled or not part of your license, this will return nil.

    See

    formsEnabled on the Document class.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) PSPDFFormParser *formParser;

    Swift

    var formParser: PSPDFFormParser? { get }

  • Annotation manager/coordinator for current PDF. The actual annotation parsing happens in annotation providers managed by this class.

    Lazy initialized. Can be subclassed.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFAnnotationManager *_Nonnull annotationManager;

    Swift

    var annotationManager: PSPDFAnnotationManager { get }

  • Page labels found in the current PDF.

    Lazy initialized. Can be subclassed.

    Declaration

    Objective-C

    @property (nonatomic, readonly) PSPDFLabelParser *_Nonnull labelParser;

    Swift

    var labelParser: PSPDFLabelParser { get }

  • Access the PDF metadata.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSDictionary<NSString *, id> *_Nonnull metadata;

    Swift

    var metadata: [String : Any] { get }

  • Get the XMP metadata in XML format, if there is any.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *XMPMetadata;

    Swift

    var xmpMetadata: String? { get }

  • Sets a page rotation for display without writing to the PDF.

    Warning

    There are a lot of caveats with this API. Instead we recommend using Processor or PDFDocumentEditor to perform page rotations. If you’re considering using this API, we recommend contacting us at https://pspdfkit.com/support/request/ to discuss your requirements.

    The rotation is specified clockwise relative to the rotation stored in the PDF. Therefore the final clockwise rotation of a page is the sum of the rotation stored in the PDF and any offset applied using this method.

    Values set using this method may be read using PDFPageInfo’s rotationOffset property.

    This method only works if the annotation providers for this document provider conform to the PSPDFAnnotationProviderRefreshing protocol. However that protocol is deprecated in favor of using the implementation in PDFContainerAnnotationProvider, which basically means your annotation providers must derive from that class. The default PDFFileAnnotationProvider is fine. However this method is not compatible with PSPDFKit Instant.

    This method does not work if the fileAnnotationProvider has been removed from the annotation manager’s annotationProviders.

    This method is intended for temporary rotations for display purposes. If you want a persistent rotation, you must use Processor or PDFDocumentEditor.

    Changing the page rotation means that annotation properties in the page coordinate space must be updated. Therefore a PSPDFAnnotationChanged notification may be posted many times when setting a rotation offset.

    Combining using this method with saving annotations to an external file or in a custom annotation provider may incur additional overhead when saving, and it may result in PSPDFAnnotationChanged notification being posted many times when saving.

    A call to reloadData is required if the document is currently displayed in a PDFViewController. You might also want to clear existing cache, so you don’t get a malformed image while re-rendering. [self.pspdfkit.cache invalidateImagesFromDocument:self.document pageIndex:pageIndex];

    Declaration

    Objective-C

    - (void)setRotationOffset:(PSPDFRotation)rotation
           forPageAtIndex:(PSPDFPageIndex)pageIndex;

    Swift

    func setRotationOffset(_ rotation: Rotation, forPageAt pageIndex: PageIndex)

    Parameters

    rotation

    The rotation offset. Valid rotation values are 0, 90, 180 and 270.
    pageIndex

    The index of the page to be rotated.

  • Resolves a named destination. E.g. for a PSPDFRemoteGoToAction. On success, returns a valid page index. On failure, NSNotFound.

    Declaration

    Objective-C

    - (NSUInteger)resolveNamedDestination:(nonnull NSString *)namedDestination;

    Swift

    func resolveNamedDestination(_ namedDestination: String) -> UInt

Digital Signatures

  • Returns the hash of a particular byte range of the receiver.

    Declaration

    Objective-C

    - (nullable NSData *)
    hashDocumentProviderRange:(nonnull NSArray<NSNumber *> *)range
                hashAlgorithm:(PSPDFSignatureHashAlgorithm)hashAlgorithm
                        error:(NSError *_Nullable *_Nullable)error;

    Swift

    func hashDocumentProviderRange(_ range: [NSNumber], hashAlgorithm: PDFSignatureHashAlgorithm) throws -> Data

    Parameters

    range

    The byte range of the part of the document that will be hashed. A byte range is an array of pairs (byte offset, length in bytes) that describe the (possibly discontiguous) region of the document that should be hashed. For an already prepared PDF document with a digital signature, you can get this information from the byteRange property of the signatureInfo property of a PSPDFSignatureFormElement class.
    hashAlgorithm

    The hash algorithm that will be used to generate the hashed data.
    error

    Collects any error that occurred while hashing the data. For example, the range argument may specify offsets outside of the boundaries of the document size.

Subclassing Hooks

  • Saves changed annotations.

    Warning

    You shouldn’t call this method directly, use the high-level save method in Document instead.

    Declaration

    Objective-C

    - (BOOL)saveAnnotationsWithOptions:
            (nullable NSDictionary<NSString *, id> *)options
                             error:(NSError *_Nullable *_Nullable)error;

    Swift

    func saveAnnotations(options: [String : Any]? = nil) throws

  • Resolves a path like /localhost/Library/test.pdf into a full path. If either alwaysLocal is set or localhost is part of the path, we’ll handle this as a local URL.

    Declaration

    Objective-C

    - (nonnull NSString *)resolveTokenizedPath:(nonnull NSString *)path
                               alwaysLocal:(BOOL)alwaysLocal;

    Swift

    func resolveTokenizedPath(_ path: String, alwaysLocal: Bool) -> String