PSPDFProcessor


@interface PSPDFProcessor : NSObject

Create, merge or modify PDF documents. Can also flatten annotation data.

  • Undocumented

    Declaration

    Objective-C

    
    @interface PSPDFProcessor : NSObject
  • Instantiates a PSPDFProcessor with the given configuration and security options.

    See

    -initWithOptions: if you want to generate a PDF from an HTML string or URL.

    Declaration

    Objective-C

    - (nonnull instancetype)
    initWithConfiguration:(nonnull PSPDFProcessorConfiguration *)configuration
          securityOptions:(nullable PSPDFDocumentSecurityOptions *)securityOptions;

    Swift

    init(configuration: PSPDFProcessorConfiguration, securityOptions: PSPDFDocumentSecurityOptions?)

    Parameters

    configuration

    The configuration you want to use for the processing.

    securityOptions

    The save options to use or nil if you want to keep the ones from the original document.

    Return Value

    PSPDFProcessor instance.

  • Generates a new document based on the configuration and security options set on the receiver, and stores it to fileURL.

    Note

    Use PSPDFProcessor‘s -writeToFileURL:error: or implement -processor:didFinishWithError: in PSPDFProcessorDelegate to retrieve the error that may be generated from the writing operation.

    Declaration

    Objective-C

    - (BOOL)writeToFileURL:(nonnull NSURL *)fileURL;

    Parameters

    fileURL

    The URL to save the generated document to. Needs to be a file URL.

    Return Value

    YES if generation was successful, NO otherwise.

  • Generates a new document based on the configuration and security options set on the receiver, and stores it to fileURL.

    Declaration

    Objective-C

    - (BOOL)writeToFileURL:(nonnull NSURL *)fileURL
                     error:(NSError *_Nullable *_Nullable)error;

    Swift

    func write(toFileURL fileURL: URL) throws

    Parameters

    fileURL

    The URL to save the generated document to. Needs to be a file URL.

    error

    On return, contains an error if one occurred while generating the document.

    Return Value

    YES if generation was successful, NO otherwise.

  • Generates a new document based on the configuration and security options set on the receiver.

    Note

    The data object will be memory-mapped if possible, however we encourage you to use the file url based variant instead.

    Note

    Use PSPDFProcessor‘s -dataWithError: or implement -processor:didFinishWithError: in PSPDFProcessorDelegate to retrieve the error that may be generated from data generation operation.

    Declaration

    Objective-C

    - (nullable NSData *)data;

    Return Value

    An NSData object containing the generated document. If possible, this object is memory-mapped.

  • Generates a new document based on the configuration and security options set on the receiver.

    Note

    The data object will be memory-mapped if possible, however we encourage you to use the file url based variant instead.

    Declaration

    Objective-C

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

    Swift

    func data() throws -> Data

    Parameters

    error

    On return, contains an error if one occurred while generating the document.

    Return Value

    An NSData object containing the generated document. If possible, this object is memory-mapped.

  • Generates a new document based on the configuration and security options set on the receiver, and writes it to the PSPDFDataSink provided.

    Note

    Use PSPDFProcessor‘s -outputToDataSink:error: or implement -processor:didFinishWithError: in PSPDFProcessorDelegate to retrieve the error that may be generated from the PDF generation operation.

    Declaration

    Objective-C

    - (BOOL)outputToDataSink:(nonnull id<PSPDFDataSink>)outputDataSink;

    Parameters

    outputDataSink

    The generated document will be written into outputDataSink.

    Return Value

    YES if generation was successful, NO otherwise.

  • Generates a new document based on the configuration and security options set on the receiver, and writes it to the PSPDFDataSink provided.

    Declaration

    Objective-C

    - (BOOL)outputToDataSink:(nonnull id<PSPDFDataSink>)outputDataSink
                       error:(NSError *_Nullable *_Nullable)error;

    Swift

    func output(to outputDataSink: PSPDFDataSink) throws

    Parameters

    outputDataSink

    The generated document will be written into outputDataSink.

    error

    On return, contains an error if one occurred while generating the document.

    Return Value

    YES if generation was successful, NO otherwise.

  • Cancels the current PDF generation process associated with the receiver.

    The cancellation is asynchronous, and only happens until the current page that’s being processes is completed.

    Declaration

    Objective-C

    - (void)cancel;

    Swift

    func cancel()
  • Instantiates a new PSPDFProcessor with the given options.

    options can contain both the PSPDF constants listed above and any kCGPDFContext constants. For example, to password protect the PDF, you can use: @{(id)kCGPDFContextUserPassword: password, (id)kCGPDFContextOwnerPassword: password, (id)kCGPDFContextEncryptionKeyLength: @128}

    Other useful properties are: - kCGPDFContextAllowsCopying - kCGPDFContextAllowsPrinting - kCGPDFContextKeywords - kCGPDFContextAuthor

    Note

    Requires the PSPDFFeatureMaskPDFCreation feature flag.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithOptions:
        (nullable NSDictionary<NSString *, id> *)options;

    Parameters

    options

    Options to be considered when converting the HTML string to PDF.

  • Generates a PDF from a string. Does allow simple html tags.

    Note

    Will not work with complex HTML pages. e.g. @"This is a <b>test</b> in <span style='color:red'>color.</span>

    Note

    Use PSPDFProcessor‘s -generatePDFFromHTMLString:outputFileURL:completionBlock or implement -processor:didFinishWithData:error: in PSPDFProcessorDelegate to retrieve the data and/or error that may be generated from the HTML-to-PDF conversion operation.

    Declaration

    Objective-C

    - (void)convertHTMLString:(nonnull NSString *)HTML
                outputFileURL:(nonnull NSURL *)fileURL;

    Parameters

    HTML

    The HTML string that’s going to be converted to PDF.

    fileURL

    The URL to save the generated document to. Needs to be a file URL.

  • Generates a PDF from a string. Does allow simple html tags.

    Note

    Will not work with complex HTML pages. e.g. @"This is a <b>test</b> in <span style='color:red'>color.</span>

    Declaration

    Objective-C

    - (void)convertHTMLString:(nonnull NSString *)HTML
                outputFileURL:(nonnull NSURL *)fileURL
              completionBlock:
                  (nullable void (^)(NSError *_Nullable))completionBlock;

    Parameters

    HTML

    The HTML string that’s going to be converted to PDF.

    fileURL

    The URL to save the generated document to. Needs to be a file URL.

    completionBlock

    Block that’s called on completion of the PDF generation. Can be NULL. Block parameter is the resulting error of the operation, nil if successful.

  • Generates a PDF from a string. Does allow simple html tags.

    Note

    Will not work with complex HTML pages. e.g. @"This is a <b>test</b> in <span style='color:red'>color.</span>

    Note

    Use PSPDFProcessor‘s -generatePDFFromHTMLString:completionBlock or implement -processor:didFinishWithData:error: in PSPDFProcessorDelegate to retrieve the data and/or error that may be generated from the HTML-to-PDF conversion operation.

    Declaration

    Objective-C

    - (void)convertHTMLString:(nonnull NSString *)HTML;

    Parameters

    HTML

    The HTML string that’s going to be converted to PDF.

  • Generates a PDF from a string. Does allow simple html tags.

    Note

    Will not work with complex HTML pages. e.g. @"This is a <b>test</b> in <span style='color:red'>color.</span>

    Declaration

    Objective-C

    - (void)convertHTMLString:(nonnull NSString *)HTML
              completionBlock:
                  (nullable void (^)(NSData *_Nullable,
                                     NSError *_Nullable))completionBlock;

    Parameters

    HTML

    The HTML string that’s going to be converted to PDF.

    completionBlock

    Block that’s called on completion of the PDF generation. Can be NULL. Block parameter (1) is the resulting PDF data, (2) is the resulting error of the operation (nil if successful).

  • This method performs the same task as -generatePDFFromURL:outputFileURL, but the generated file URL confirmation and the operation’s resulting error (if any) are passed to the PSPDFProcessor‘s delegate on the method -processor:didFinishWithFileURL:error.

    Declaration

    Objective-C

    - (nullable PSPDFConversionOperation *)
    generatePDFFromURL:(nonnull NSURL *)inputURL
         outputFileURL:(nonnull NSURL *)outputURL;
  • Renders a PDF from an URL (web or fileURL). Upon completion, the completionBlock will be called.

    Loading the URL is non-blocking, however the conversion uses the iOS printing infrastructure and only works on the main thread. Larger documents might stall your application for a while. Download the document to a temporary folder and show a blocking progress HUD while the conversion is running to mitigate the blocking.

    Supported are web pages and certain file types like pages, keynote, word, powerpoint, excel, rtf, jpg, png, … See https://developer.apple.com/library/ios/#qa/qa2008/qa1630.html for the full list.

    Note

    FILE/OFFICE CONVERSION IS AN EXPERIMENTAL FEATURE AND WE CAN’T OFFER SUPPORT FOR CONVERSION ISSUES. If you require a 1:1 conversion, you need to convert those files on a server with a product that is specialized for this task.

    Certain documents might not have the correct pagination. (Try to manually define PSPDFProcessorPageRectKey to fine-tune this.)

    @warning Don’t manually override NSOperation’s completionBlock. If this helper is used, operation will be automatically queued in conversionOperationQueue. When a password is set, only link annotations can be added as dictionary (this does not affect flattening)

    Don’t use this for PDF files!

    Declaration

    Objective-C

    - (nullable PSPDFConversionOperation *)
    generatePDFFromURL:(nonnull NSURL *)inputURL
         outputFileURL:(nonnull NSURL *)outputURL
       completionBlock:
           (nullable void (^)(NSURL *_Nullable, NSError *_Nullable))completionBlock;

    Parameters

    inputURL

    The URL to generate the PDF from.

    outputURL

    The URL the generated PDF is going to be saved to. Needs to be a file URL.

    completionBlock

    The block that’s called when the PDF generation is complete. Can be NULL. First parameter is the URL the PDF was saved to, second parameter is the resulting error, if any.

  • This method performs the same task as -generatePDFFromURL:completionBlock, but the generated data (if any) and the resulting error (if any) are passed to the PSPDFProcessor‘s delegate, on the method -processor:didFinishWithData:error.

    Declaration

    Objective-C

    - (nonnull PSPDFConversionOperation *)generatePDFFromURL:
        (nonnull NSURL *)inputURL;
  • Renders a PDF from an URL (web or fileURL), and keeps it in memory. (The generated PDF won’t be saved to disk) Upon completion, the completionBlock will be called.

    Loading the URL is non-blocking, however the conversion uses the iOS printing infrastructure and only works on the main thread. Larger documents might stall your application for a while. Download the document to a temporary folder and show a blocking progress HUD while the conversion is running to mitigate the blocking.

    Supported are web pages and certain file types like pages, keynote, word, powerpoint, excel, rtf, jpg, png, … See https://developer.apple.com/library/ios/#qa/qa2008/qa1630.html for the full list.

    Note

    FILE/OFFICE CONVERSION IS AN EXPERIMENTAL FEATURE AND WE CAN’T OFFER SUPPORT FOR CONVERSION ISSUES. If you require a 1:1 conversion, you need to convert those files on a server with a product that is specialized for this task. Read more: https://pspdfkit.com/guides/ios/current/features/document-processing/#toc_website-and-office-conversion

    Certain documents might not have the correct pagination. (Try to manually define PSPDFProcessorPageRectKey to fine-tune this.)

    @warning Don’t manually override NSOperation’s completionBlock. If this helper is used, operation will be automatically queued in conversionOperationQueue. When a password is set, only link annotations can be added as dictionary (this does not affect flattening)

    Don’t use this for PDF files!

    Declaration

    Objective-C

    - (nonnull PSPDFConversionOperation *)
    generatePDFFromURL:(nonnull NSURL *)inputURL
       completionBlock:(nullable void (^)(NSData *_Nullable,
                                          NSError *_Nullable))completionBlock;

    Parameters

    inputURL

    The URL to generate the PDF from.

    completionBlock

    The block that’s called when the PDF generation is complete. Can be NULL. First parameter is the data of the rendered PDF, second parameter is the resulting error, if any.

  • Generates a new document based on PSPDFProcessorConfiguration and stores it to fileURL.

    Declaration

    Objective-C

    + (BOOL)generatePDFFromConfiguration:
                (nonnull PSPDFProcessorConfiguration *)configuration
                         securityOptions:(nullable PSPDFDocumentSecurityOptions *)
                                             securityOptions
                           outputFileURL:(nonnull NSURL *)fileURL
                           progressBlock:(nullable PSPDFProgressBlock)progressBlock
                                   error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func generatePDF(from configuration: PSPDFProcessorConfiguration, securityOptions: PSPDFDocumentSecurityOptions?, outputFileURL fileURL: URL, progressBlock: PSPDFProgressBlock? = nil) throws

    Parameters

    configuration

    The configuration you want to use for the processing.

    securityOptions

    The save options to use or nil if you want to keep the ones from the original document.

    fileURL

    The URL to save the generated document to. Needs to be a fileURL.

    progressBlock

    The progress block to monitor progress on the generation process. Can be NULL. The progress block is called on an arbitrary queue.

    error

    On return, contains an error if one occurred while generating the document.

    Return Value

    YES if generation was successful, NO otherwise.

  • Generates a new document based on PSPDFProcessorConfiguration and returns it.

    Note

    The data object will be memory-mapped if possible, however we encourage you to use the file url based variant instead.

    See

    +generatePDFFromConfiguration:securityOptions:outputFileURL:progressBlock:error:

    Declaration

    Objective-C

    + (nullable NSData *)
    generatePDFFromConfiguration:
        (nonnull PSPDFProcessorConfiguration *)configuration
                 securityOptions:
                     (nullable PSPDFDocumentSecurityOptions *)securityOptions
                   progressBlock:(nullable PSPDFProgressBlock)progressBlock
                           error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func generatePDF(from configuration: PSPDFProcessorConfiguration, securityOptions: PSPDFDocumentSecurityOptions?, progressBlock: PSPDFProgressBlock? = nil) throws -> Data

    Parameters

    configuration

    The configuration you want to use for the processing.

    securityOptions

    The save options to use or nil if you want to keep the ones from the original document.

    progressBlock

    The progress block to monitor progress on the generation process. Can be NULL. The progress block is called on an arbitrary queue.

    error

    On return, contains an error if one occurred while generating the document.

    Return Value

    An NSData object containing the generated document. If possible, this object is memory-mapped.

  • Generates a new document based on PSPDFProcessorConfiguration and returns it.

    Declaration

    Objective-C

    + (BOOL)generatePDFFromConfiguration:
                (nonnull PSPDFProcessorConfiguration *)configuration
                         securityOptions:(nullable PSPDFDocumentSecurityOptions *)
                                             securityOptions
                          outputDataSink:(nonnull id<PSPDFDataSink>)outputDataSink
                           progressBlock:(nullable PSPDFProgressBlock)progressBlock
                                   error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func generatePDF(from configuration: PSPDFProcessorConfiguration, securityOptions: PSPDFDocumentSecurityOptions?, outputDataSink: PSPDFDataSink, progressBlock: PSPDFProgressBlock? = nil) throws

    Parameters

    configuration

    The configuration you want to use for the processing.

    securityOptions

    The save options to use or nil if you want to keep the ones from the original document.

    outputDataSink

    The generated document will be written into outputDataSink.

    progressBlock

    The progress block to monitor progress on the generation process. Can be NULL. The progress block is called on an arbitrary queue.

    error

    On return, contains an error if one occurred while generating the document.

    Return Value

    YES if generation was successful, NO otherwise.

  • Generates a PDF from a string. Does allow simple html tags.

    Note

    Will not work with complex HTML pages. e.g. @"This is a <b>test</b> in <span style='color:red'>color.</span>

    Declaration

    Objective-C

    + (void)generatePDFFromHTMLString:(nonnull NSString *)HTML
                        outputFileURL:(nonnull NSURL *)fileURL
                              options:
                                  (nullable NSDictionary<NSString *, id> *)options
                      completionBlock:
                          (nullable void (^)(NSError *_Nullable))completionBlock;
  • Like the above, but create a temporary PDF in memory.

    Declaration

    Objective-C

    + (void)generatePDFFromHTMLString:(nonnull NSString *)HTML
                              options:
                                  (nullable NSDictionary<NSString *, id> *)options
                      completionBlock:
                          (nullable void (^)(NSData *_Nonnull,
                                             NSError *_Nullable))completionBlock;
  • Renders a PDF from an URL (web or fileURL). Upon completion, the completionBlock will be called.

    Loading the URL is non-blocking, however the conversion uses the iOS printing infrastructure and only works on the main thread. Larger documents might stall your application for a while. Download the document to a temporary folder and show a blocking progress HUD while the conversion is running to mitigate the blocking.

    Supported are web pages and certain file types like pages, keynote, word, powerpoint, excel, rtf, jpg, png, … See https://developer.apple.com/library/ios/#qa/qa2008/qa1630.html for the full list.

    Note

    FILE/OFFICE CONVERSION IS AN EXPERIMENTAL FEATURE AND WE CAN’T OFFER SUPPORT FOR CONVERSION ISSUES. If you require a 1:1 conversion, you need to convert those files on a server with a product that is specialized for this task.

    Certain documents might not have the correct pagination. (Try to manually define PSPDFProcessorPageRectKey to fine-tune this.)

    options can contain both the PSPDF constants listed above and any kCGPDFContext constants. For example, to password protect the PDF, you can use: @{(id)kCGPDFContextUserPassword: password, (id)kCGPDFContextOwnerPassword: password, (id)kCGPDFContextEncryptionKeyLength: @128}

    Other useful properties are: - kCGPDFContextAllowsCopying - kCGPDFContextAllowsPrinting - kCGPDFContextKeywords - kCGPDFContextAuthor

    Note

    Requires the PSPDFFeatureMaskPDFCreation feature flag.

    @warning Don’t manually override NSOperation’s completionBlock. If this helper is used, operation will be automatically queued in conversionOperationQueue. When a password is set, only link annotations can be added as dictionary (this does not affect flattening)

    Don’t use this for PDF files!

    Declaration

    Objective-C

    + (nullable PSPDFConversionOperation *)
    generatePDFFromURL:(nonnull NSURL *)inputURL
         outputFileURL:(nonnull NSURL *)outputURL
               options:(nullable NSDictionary<NSString *, id> *)options
       completionBlock:
           (nullable void (^)(NSURL *_Nullable, NSError *_Nullable))completionBlock;
  • Will create a PDF in-memory.

    Declaration

    Objective-C

    + (nonnull PSPDFConversionOperation *)
    generatePDFFromURL:(nonnull NSURL *)inputURL
               options:(nullable NSDictionary<NSString *, id> *)options
       completionBlock:(nullable void (^)(NSData *_Nullable,
                                          NSError *_Nullable))completionBlock;