// // CPDFDocument.h // ComPDFKit // // Copyright © 2014-2022 PDF Technologies, Inc. All Rights Reserved. // // THIS SOURCE CODE AND ANY ACCOMPANYING DOCUMENTATION ARE PROTECTED BY INTERNATIONAL COPYRIGHT LAW // AND MAY NOT BE RESOLD OR REDISTRIBUTED. USAGE IS BOUND TO THE ComPDFKit LICENSE AGREEMENT. // UNAUTHORIZED REPRODUCTION OR DISTRIBUTION IS SUBJECT TO CIVIL AND CRIMINAL PENALTIES. // This notice may not be removed from this file. // #import extern NSNotificationName const CPDFDocumentDidUnlockNotification; extern NSErrorDomain const CPDFDocumentErrorDomain; NS_ERROR_ENUM(CPDFDocumentErrorDomain) { CPDFDocumentUnknownError = 1, // Unknown error. CPDFDocumentFileError = 2, // File not found or could not be opened. CPDFDocumentFormatError = 3, // File not in PDF format or corrupted. CPDFDocumentPasswordError = 4, // Password required or incorrect password. CPDFDocumentSecurityError = 5, // Unsupported security scheme. CPDFDocumentPageError = 6 // Page not found or content error. }; /** * An enumeration that specifies document permissions status. */ typedef NS_ENUM(NSInteger, CPDFDocumentPermissions) { /** The status that indicates no document permissions. */ CPDFDocumentPermissionsNone = 0, /** The status that indicates user document permissions. */ CPDFDocumentPermissionsUser, /** The status that indicates owner document permissions. */ CPDFDocumentPermissionsOwner }; typedef NS_OPTIONS(NSInteger, CPDFSearchOptions) { CPDFSearchCaseInsensitive = 0, /** If not set, it will not match case by default. */ CPDFSearchCaseSensitive = 1, /** If not set, it will not match the whole word by default. */ CPDFSearchMatchWholeWord = 2, /** If not set, it will skip past the current match to look for the next match. */ CPDFSearchConsecutive = 4 }; /** * PDF/A conformance levels. */ typedef NS_ENUM(NSInteger, CPDFType) { CPDFTypePDF = 0, /** PDF/A-1a */ CPDFTypePDFA1a, /** PDF/A-1b */ CPDFTypePDFA1b, /** PDF/A-2a */ CPDFTypePDFA2a, /** PDF/A-2u */ CPDFTypePDFA2u, /** PDF/A-2b */ CPDFTypePDFA2b, /** PDF/A-3a */ CPDFTypePDFA3a, /** PDF/A-3u */ CPDFTypePDFA3u, /** PDF/A-3b */ CPDFTypePDFA3b }; typedef NSString *CPDFDocumentAttribute NS_STRING_ENUM; extern CPDFDocumentAttribute const CPDFDocumentTitleAttribute; // NSString containing document title. extern CPDFDocumentAttribute const CPDFDocumentAuthorAttribute; // NSString containing document author. extern CPDFDocumentAttribute const CPDFDocumentSubjectAttribute; // NSString containing document title. extern CPDFDocumentAttribute const CPDFDocumentCreatorAttribute; // NSString containing name of app that created document. extern CPDFDocumentAttribute const CPDFDocumentProducerAttribute; // NSString containing name of app that produced PDF data. extern CPDFDocumentAttribute const CPDFDocumentKeywordsAttribute; // NSString containing document keywords. extern CPDFDocumentAttribute const CPDFDocumentCreationDateAttribute; // NSString representing document creation date. extern CPDFDocumentAttribute const CPDFDocumentModificationDateAttribute; // NSString representing last document modification date. typedef NSString *CPDFDocumentWriteOption NS_STRING_ENUM; extern CPDFDocumentWriteOption const CPDFDocumentOwnerPasswordOption; // NSString for the owner's password. extern CPDFDocumentWriteOption const CPDFDocumentUserPasswordOption; // NSString for the user's password. extern CPDFDocumentWriteOption const CPDFDocumentAllowsPrintingOption; extern CPDFDocumentWriteOption const CPDFDocumentAllowsHighQualityPrintingOption; extern CPDFDocumentWriteOption const CPDFDocumentAllowsCopyingOption; extern CPDFDocumentWriteOption const CPDFDocumentAllowsDocumentChangesOption; extern CPDFDocumentWriteOption const CPDFDocumentAllowsDocumentAssemblyOption; extern CPDFDocumentWriteOption const CPDFDocumentAllowsCommentingOption; extern CPDFDocumentWriteOption const CPDFDocumentAllowsFormFieldEntryOption; @class CPDFPage, CPDFOutline, CPDFBookmark, CPDFWatermark, CPDFHeaderFooter, CPDFBates, CPDFBackground, CPDFSelection; @protocol CPDFDocumentDelegate; /** * An object that represents a PDF file and defines methods for writing, searching, and selecting PDF data. * * @discussion The other utility classes are either instantiated from methods in CPDFDocument, as are CPDFPage and CPDFOutline; or support it, as do CPDFWatermark and CPDFDestination. * You initialize a CPDFDocument object with a URL to a PDF file. You can then ask for the page count, add or delete pages, perform a find, or parse selected content into an NSString object. */ @interface CPDFDocument : NSObject #pragma mark - Initializers /** * Initializes a CPDFDocument object with new PDF. */ - (instancetype)init; /** * Initializes a CPDFDocument object with the contents at the specified URL. */ - (instancetype)initWithURL:(NSURL *)url; #pragma mark - Accessors /** * The object acting as the delegate for the CPDFDocument object. * * @see CPDFDocumentDelegate */ @property (nonatomic,assign) id delegate; /** * The URL for the document. * * @discussion May return NULL if the document was created from an new object. */ @property (nonatomic,readonly) NSURL *documentURL; /** * The password for the document. * * @discussion May return NULL if the document is not an encrypted document. */ @property (nonatomic,readonly) NSString *password; /** * Error message for the document loading. * * @discussion To determine the error type, use the code to obtain error of type CPDFDocumentErrorDomain. * Except for the CPDFDocumentPasswordError error, other errors cannot open the document. * If CPDFDocumentPasswordError, reading the document requires a password. */ @property (nonatomic,readonly) NSError *error; /** * A Boolean value specifying whether the document is encrypted. * * @discussion Whether the PDF is encrypted. With the right password, a PDF can be unlocked - nonetheless, the PDF still indicates that it is encrypted - just no longer locked. * Some PDF's may be encrypted but can be unlocked with the empty string. These are unlocked automatically. */ @property (nonatomic,readonly) BOOL isEncrypted; /** * A Boolean value indicating whether the document is locked. * * @discussion Only encrypted documents can be locked. Use the unlockWithPassword: method to unlock a document using a password. */ @property (nonatomic,readonly) BOOL isLocked; /** * Attempts to unlock an encrypted document. * * @discussion If the password is correct, this method returns YES, and a CPDFDocumentDidUnlockNotification notification is sent. * Once unlocked, you cannot use this function to relock the document. * @param password The password to unlock an encrypted document (you cannot lock an unlocked PDF document by using an incorrect password). */ - (BOOL)unlockWithPassword:(NSString *)password; /** * The major version of the document. * * @discussion PDF version of the PDF file (example: major version = 1; PDF v1.4). */ @property (nonatomic,readonly) NSInteger majorVersion; /** * The minor version of the document. * * @discussion PDF version of the PDF file (example: minor version = 4; PDF v1.4). */ @property (nonatomic,readonly) NSInteger minorVersion; /** * The permissions status of the PDF document. * * @discussion Returns the permissions status of the PDF document. You have CPDFDocumentPermissionsNone 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 CPDFDocumentPermissionsUser status. * @see CPDFDocumentPermissions */ @property (nonatomic,readonly) CPDFDocumentPermissions permissionsStatus; /** * A Boolean value indicating whether the document allows printing. */ @property (nonatomic,readonly) BOOL allowsPrinting; /** * A Boolean value indicating whether the document allows printing in high fidelity. */ @property (nonatomic,readonly) BOOL allowsHighQualityPrinting; /** * A Boolean value indicating whether the document allows copying of content to the Pasteboard. */ @property (nonatomic,readonly) BOOL allowsCopying; /** * A Boolean value indicating whether you can modify the document contents except for document attributes. */ @property (nonatomic,readonly) BOOL allowsDocumentChanges; /** * A Boolean value indicating whether you can manage a document by inserting, deleting, and rotating pages. */ @property (nonatomic,readonly) BOOL allowsDocumentAssembly; /** * A Boolean value indicating whether you can create or modify document annotations, including form field entries. */ @property (nonatomic,readonly) BOOL allowsCommenting; /** * A Boolean value indicating whether you can modify form field entries even if you can't edit document annotations. */ @property (nonatomic,readonly) BOOL allowsFormFieldEntry; #pragma mark - Save /** * A Boolean value indicating whether the document has been modified. */ - (BOOL)isModified; /** * Writes the document to a location specified by the passed-in URL. */ - (BOOL)writeToURL:(NSURL *)url; /** * Writes the document to the specified URL with the specified options. * * @discussion Set the password to the document by setting options. * @param options CPDFDocumentOwnerPasswordOption, CPDFDocumentUserPasswordOption. */ - (BOOL)writeToURL:(NSURL *)url withOptions:(NSDictionary *)options; /** * Writes the document to the specified URL after flattening. */ - (BOOL)writeFlattenToURL:(NSURL *)url; /** * Writes the document to the specified URL after removing annotions and form field entries. */ - (BOOL)writeContentToURL:(NSURL *)url; /** * Writes the document to the specified URL after removing permissions. */ - (BOOL)writeDecryptToURL:(NSURL *)url; #pragma mark - Attributes /** * A dictionary of document metadata. * * @discussion Metadata is optional for PDF documents. The dictionary may be empty, or only some of the keys may have associated values. */ - (NSDictionary *)documentAttributes; - (void)setDocumentAttributes:(NSDictionary *)documentAttributes; #pragma mark - Outline /** * The document’s root outline to a PDF outline object. * * @discussion When a PDF document is saved, the outline tree structure is written out to the destination PDF file. */ - (CPDFOutline *)outlineRoot; /** * Create a root outline for the document. */ - (CPDFOutline *)setNewOutlineRoot; #pragma mark - Bookmark /** * A array of document’s bookmarks. */ - (NSArray *)bookmarks; /** * Add a bookmark at the specified index number. * * @discussion Indexes are zero based. This method raises an exception if index is out of bounds. */ - (BOOL)addBookmark:(NSString *)label forPageIndex:(NSUInteger)pageIndex; /** * Remove the bookmark at the specified index number. * * @discussion Indexes are zero based. This method raises an exception if index is out of bounds. */ - (BOOL)removeBookmarkForPageIndex:(NSUInteger)pageIndex; /** * Returns the bookmark at the specified index number. * * @discussion Indexes are zero based. This method raises an exception if index is out of bounds. */ - (CPDFBookmark *)bookmarkForPageIndex:(NSUInteger)pageIndex; #pragma mark - Watermark /** * A array of document’s watermarks. */ - (NSArray *)watermarks; /** * Add a watermark. * * @param watermark A PDF watermark object. */ - (BOOL)addWatermark:(CPDFWatermark *)watermark; /** * Remove the watermark. * * @param watermark The PDF watermark object from document’s watermarks. */ - (BOOL)removeWatermark:(CPDFWatermark *)watermark; /** * Update the watermark. * * @param watermark The PDF watermark object from document’s watermarks. */ - (BOOL)updateWatermark:(CPDFWatermark *)watermark; #pragma mark - HeaderFooter /** * Gets the header & footer of the document. */ - (CPDFHeaderFooter *)headerFooter; #pragma mark - Bates /** * Gets the bates numbers of the document. */ - (CPDFBates *)bates; #pragma mark - Background /** * Gets the background of the document. */ - (CPDFBackground *)background; #pragma mark - Pages /** * The number of pages in the document. */ @property (nonatomic,readonly) NSUInteger pageCount; /** * Returns the page size at the specified index number. * * @discussion Indexes are zero based. This method raises an exception if index is out of bounds. */ - (CGSize)pageSizeAtIndex:(NSUInteger)index; /** * Returns a CPDFPage object representing the page at index. * * @discussion Indexes are zero based. This method raises an exception if index is out of bounds. */ - (CPDFPage *)pageAtIndex:(NSUInteger)index; /** * Gets the index number for the specified page. * * @discussion Given a CPDFPage, returns the pages index within the document. Indices are zero-based. */ - (NSUInteger)indexForPage:(CPDFPage *)page; /** * Inserts a blank page at the specified index point. * * @discussion Indexes are zero based. The index must lie within bounds, or be equal to the length of bounds. */ - (BOOL)insertPage:(CGSize)pageSize atIndex:(NSUInteger)index; /** * Inserts a blank page with image at the specified index point. * * @discussion Indexes are zero based. The index must lie within bounds, or be equal to the length of bounds. */ - (BOOL)insertPage:(CGSize)pageSize withImage:(NSString *)imagePath atIndex:(NSUInteger)index; /** * Removes page(s) at the specified index set. */ - (BOOL)removePageAtIndexSet:(NSIndexSet *)indexSet; /** * Move one page to another. * * @discussion This method raises an exception if either index value is out of bounds. */ - (BOOL)movePageAtIndex:(NSUInteger)indexA withPageAtIndex:(NSUInteger)indexB; /** * Exchanges one page with another. * * @discussion This method raises an exception if either index value is out of bounds. */ - (BOOL)exchangePageAtIndex:(NSUInteger)indexA withPageAtIndex:(NSUInteger)indexB; /** * Import page(s) from another document at the specified index point. * * @discussion This method raises an exception if either index value is out of bounds. */ - (BOOL)importPages:(NSIndexSet *)indexSet fromDocument:(CPDFDocument *)document atIndex:(NSUInteger)index; #pragma mark - Annotations /** * Export annotation to XFDF document. */ - (BOOL)exportAnnotationToXFDFPath:(NSString *)xfdfPath; /** * Import annotations from XFDF document. */ - (BOOL)importAnnotationFromXFDFPath:(NSString *)xfdfPath; /** * Remove all signatures. */ - (BOOL)removeAllSignature; /** * A Boolean value indicating whether the document contains annotations. */ - (BOOL)hasAnnotations; /** * Reset all forms in PDF document. */ - (void)resetForm; #pragma mark - Extract /** * Extract image at the specified index set. */ - (NSUInteger)extractImageFromPages:(NSIndexSet *)indexSet toPath:(NSString *)path; /** * Cancels a extract initiated with extractImageFromPages:toPath:. */ - (void)cancelExtractImage; #pragma mark - Summary - (NSString *)summaryHTML; #pragma mark - PDF/A /** * Gets PDF/A conformance levels. * * @see CPDFType */ - (CPDFType)type; /** * Converts existing PDF files to PDF/A compliant documents, including PDF/A-1a and PDF/A-1b only. * * @discussion The conversion option analyzes the content of existing PDF files and performs a sequence of modifications in order to produce a PDF/A compliant document. * Features that are not suitable for long-term archiving (such as encryption, obsolete compression schemes, missing fonts, or device-dependent color) are replaced with their PDF/A compliant equivalents. * Because the conversion process applies only necessary changes to the source file, the information loss is minimal. * @see CPDFType */ - (BOOL)writePDFAToURL:(NSURL *)url withType:(CPDFType)type; #pragma mark - Find /** * Returns a Boolean value indicating whether an asynchronous find operation is in progress. */ @property (nonatomic,readonly) BOOL isFinding; /** * Synchronously finds all instances of the specified string in the document. * * @discussion Each hit gets added to an NSArray object as a CPDFSelection object. If there are no hits, this method returns an empty array. * Use this method when the complete search process will be brief and when you don’t need the flexibility or control offered by beginFindString:withOptions:. * @see CPDFSearchOptions */ - (NSArray *> *)findString:(NSString *)string withOptions:(CPDFSearchOptions)options; /** * Asynchronously finds all instances of the specified string in the document. * * @discussion This method returns immediately. It causes delegate methods to be called when searching begins and ends, on each search hit, and when the search proceeds to a new page. * @see CPDFDocumentDelegate */ - (void)beginFindString:(NSString *)string withOptions:(CPDFSearchOptions)options; /** * Cancels a search initiated with beginFindString:withOptions:. */ - (void)cancelFindString; #pragma mark - Redact /** * Applies redaction annotations in the document. */ - (void)applyRedactions; @end /** * The delegate for the CPDFDocument object. */ @protocol CPDFDocumentDelegate @optional /** * Called when the beginFindString:withOptions: or findString:withOptions: method begins finding. */ - (void)documentDidBeginDocumentFind:(CPDFDocument *)document; /** * Called when the beginFindString:withOptions: or findString:withOptions: method returns. */ - (void)documentDidEndDocumentFind:(CPDFDocument *)document; /** * Called when a find operation begins working on a new page of a document. */ - (void)documentDidBeginPageFind:(CPDFDocument *)document pageAtIndex:(NSUInteger)index; /** * Called when a find operation finishes working on a page in a document. */ - (void)documentDidEndPageFind:(CPDFDocument *)document pageAtIndex:(NSUInteger)index; /** * Called when a string match is found in a document. * * @discussion To determine the string selection found, use the selection. */ - (void)documentDidFindMatch:(CPDFSelection *)selection; @end