PSPDFProcessor

Objective-C


@interface PSPDFProcessor : NSObject

Swift

class Processor : NSObject

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

  • Undocumented

    Declaration

    Objective-C

    @property (nonatomic, weak) id<PSPDFProcessorDelegate> delegate

    Swift

    weak var delegate: ProcessorDelegate? { get set }

  • 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: Processor.Configuration, securityOptions: Document.SecurityOptions?)

    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.

  • 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. There should be no file at this URL prior to calling this method. This method will throw an error in the case a file already exists.
    error

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

    Return Value

    true if generation was successful, false 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.

    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

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

    Declaration

    Objective-C

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

    Swift

    func output(to outputDataSink: DataSink) 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

    true if generation was successful, false 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()

  • Renders a PDF from a website or file, 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 types are those that can be rendered by WKWebView. This includes web pages, Pages, Keynote, Numbers, Word, PowerPoint, Excel, RTF, JPEG, PNG.

    Note

    File / office conversion will generally not yield good results with this approach. For a 1:1 office conversion, you need to convert those files on a server with a product that is specialized for this task. See Processor.generatePDF(from:, serverURL:, jwt:, completionBlock:) for more information.

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

    When a password is set, only link annotations can be added as dictionary (this does not affect flattening).

    Warning

    Don’t manually override the returned operation’s completionBlock.

    Warning

    Don’t use this for PDF files.

    Note

    Requires the Features.webKitHtmlConversion feature flag. Calls completionBlock with an error if the feature is not available in your license.

    Declaration

    Objective-C

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

    Swift

    class func generatePDF(from inputURL: URL, options: [String : Any]? = nil, completionBlock: ((Data?, Error?) -> Void)? = nil) -> PSPDFURLConversionOperation

    Parameters

    inputURL

    The URL to generate the PDF from.
    options

    Options to be considered when generating a PDF from a website or file.
    completionBlock

    Called when the PDF generation is complete. First parameter is the data of the rendered PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting URL to PDF that will be automatically enqueued.

  • This method performs the same task as +generatePDFFromURL:options:completionBlock, but the generated PDF is saved to disk.

    Note

    Requires the Features.webKitHtmlConversion feature flag. Calls completionBlock with an error if the feature is not available in your license.

    Declaration

    Objective-C

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

    Swift

    class func generatePDF(from inputURL: URL, outputFileURL: URL, options: [String : Any]? = nil, completionBlock: ((URL?, Error?) -> Void)? = nil) -> PSPDFURLConversionOperation

    Parameters

    inputURL

    The URL to generate the PDF from.
    outputFileURL

    The URL the generated PDF is going to be saved to. Needs to be a file URL. Note that the actual output file URL might be different at the end.
    options

    Options to be considered when generating a PDF from a website or file.
    completionBlock

    Called when the PDF generation is complete. First parameter is the actual output file URL of the rendered PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting URL to PDF that will be automatically enqueued.

  • Renders a PDF from a HTML string, and keeps it in memory.

    Note

    This allows for simple HTML tags but will not work with complex HTML pages. E.g. This is a <b>test</b> in <span style='color:red'>color.</span>

    Warning

    Don’t manually override the returned operation’s completionBlock.

    Note

    Requires the Features.webKitHtmlConversion feature flag. Calls completionBlock with an error if the feature is not available in your license. This feature uses UIMarkupTextPrintFormatter, which is (in contrast to the documentation) not available on Mac Catalyst: FB6823732

    Declaration

    Objective-C

    + (nonnull PSPDFHTMLConversionOperation *)
    generatePDFFromHTMLString:(nonnull NSString *)HTMLString
                      options:(nullable NSDictionary<NSString *, id> *)options
              completionBlock:
                  (nullable void (^)(NSData *_Nullable,
                                     NSError *_Nullable))completionBlock;

    Swift

    class func generatePDF(fromHTMLString HTMLString: String, options: [String : Any]? = nil, completionBlock: ((Data?, Error?) -> Void)? = nil) -> PSPDFHTMLConversionOperation

    Parameters

    HTMLString

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

    Options to be considered when generating a PDF from a HTML string.
    completionBlock

    Block that’s called on completion of the PDF generation. First parameter is the data of the rendered PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting HTML string to PDF that will be automatically enqueued.

  • This method performs the same task as +generatePDFFromHTMLString:options:completionBlock, but the generated PDF is saved to disk.

    Note

    Requires the Features.webKitHtmlConversion feature flag. Calls completionBlock with an error if the feature is not available in your license.

    Declaration

    Objective-C

    + (nonnull PSPDFHTMLConversionOperation *)
    generatePDFFromHTMLString:(nonnull NSString *)HTMLString
                outputFileURL:(nonnull NSURL *)outputFileURL
                      options:(nullable NSDictionary<NSString *, id> *)options
              completionBlock:
                  (nullable void (^)(NSURL *_Nullable,
                                     NSError *_Nullable))completionBlock;

    Swift

    class func generatePDF(fromHTMLString HTMLString: String, outputFileURL: URL, options: [String : Any]? = nil, completionBlock: ((URL?, Error?) -> Void)? = nil) -> PSPDFHTMLConversionOperation

    Parameters

    HTMLString

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

    The URL the generated PDF is going to be saved to. Needs to be a file URL. Note that the actual output file URL might be different at the end.
    options

    Options to be considered when generating a PDF from a HTML string.
    completionBlock

    Block that’s called on completion of the PDF generation. First parameter is the actual output file URL of the rendered PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting HTML string to PDF that will be automatically enqueued.

  • Renders a PDF from an attributed string, and keeps it in memory.

    Warning

    Don’t manually override the returned operation’s completionBlock.

    Note

    Requires the Features.webKitHtmlConversion feature flag. Calls completionBlock with an error if the feature is not available in your license.

    Declaration

    Objective-C

    + (nonnull PSPDFAttributedStringConversionOperation *)
    generatePDFFromAttributedString:
        (nonnull NSAttributedString *)attributedString
                            options:
                                (nullable NSDictionary<NSString *, id> *)options
                    completionBlock:
                        (nullable void (^)(NSData *_Nullable,
                                           NSError *_Nullable))completionBlock;

    Swift

    class func generatePDF(from attributedString: NSAttributedString, options: [String : Any]? = nil, completionBlock: ((Data?, Error?) -> Void)? = nil) -> PSPDFAttributedStringConversionOperation

    Parameters

    attributedString

    The attributed string that’s going to be converted to PDF.
    options

    Options to be considered when generating a PDF from an attributed string.
    completionBlock

    Block that’s called on completion of the PDF generation. First parameter is the data of the rendered PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting attributed string to PDF that will be automatically enqueued.

  • This method performs the same task as +generatePDFFromAttributedString:options:completionBlock, but the generated PDF is saved to disk.

    Note

    Requires the Features.webKitHtmlConversion feature flag. Calls completionBlock with an error if the feature is not available in your license.

    Declaration

    Objective-C

    + (nonnull PSPDFAttributedStringConversionOperation *)
    generatePDFFromAttributedString:
        (nonnull NSAttributedString *)attributedString
                      outputFileURL:(nonnull NSURL *)outputFileURL
                            options:
                                (nullable NSDictionary<NSString *, id> *)options
                    completionBlock:
                        (nullable void (^)(NSURL *_Nullable,
                                           NSError *_Nullable))completionBlock;

    Swift

    class func generatePDF(from attributedString: NSAttributedString, outputFileURL: URL, options: [String : Any]? = nil, completionBlock: ((URL?, Error?) -> Void)? = nil) -> PSPDFAttributedStringConversionOperation

    Parameters

    attributedString

    The attributed string that’s going to be converted to PDF.
    outputFileURL

    The URL the generated PDF is going to be saved to. Needs to be a file URL. Note that the actual output file URL might be different at the end.
    options

    Options to be considered when generating a PDF from an attributed string.
    completionBlock

    Block that’s called on completion of the PDF generation. First parameter is the actual output file URL of the rendered PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting attributed string to PDF that will be automatically enqueued.

  • Converts an Office file to a PDF by uploading it to a server that performs the actual conversion. Once the server completes the conversion, the resulting PDF file is downloaded and kept in memory.

    Supported document types: Word, Excel and Powerpoint.

    Note

    WARNING: This API downloads and loads the entire converted PDF file into memory.

    Declaration

    Objective-C

    + (nullable PSPDFOfficeConversionOperation *)
    generatePDFFromURL:(nonnull NSURL *)inputURL
             serverURL:(nonnull NSURL *)serverURL
                   JWT:(nonnull NSString *)JWT
       completionBlock:(nullable void (^)(NSData *_Nullable,
                                          NSError *_Nullable))completionBlock;

    Swift

    class func generatePDF(from inputURL: URL, serverURL: URL, jwt JWT: String, completionBlock: ((Data?, Error?) -> Void)? = nil) -> PSPDFOfficeConversionOperation?

    Parameters

    inputURL

    The URL of the file to generate the PDF from.
    serverURL

    The URL of the server that will perform the document conversion.
    JWT

    The JSON Web token used to authenticate access to the server.
    completionBlock

    Called when the converted PDF has finished downloading. First parameter is the data of the rendered PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting the Office file to PDF that will be automatically enqueued.

  • This method performs the same task as +generatePDFFromURL:serverURL:jwt:completionBlock, but the generated PDF is saved to disk.

    Supported document types: Word, Excel and Powerpoint.

    Note

    This API streams the converted PDF file and writes it to disk without loading it entirely into memory.

    Declaration

    Objective-C

    + (nullable PSPDFOfficeConversionOperation *)
    generatePDFFromURL:(nonnull NSURL *)inputURL
             serverURL:(nonnull NSURL *)serverURL
                   JWT:(nonnull NSString *)JWT
         outputFileURL:(nonnull NSURL *)outputFileURL
       completionBlock:(nullable void (^)(NSURL *_Nullable,
                                          NSError *_Nullable))completionBlock;

    Swift

    class func generatePDF(from inputURL: URL, serverURL: URL, jwt JWT: String, outputFileURL: URL, completionBlock: ((URL?, Error?) -> Void)? = nil) -> PSPDFOfficeConversionOperation?

    Parameters

    inputURL

    The URL of the file to generate the PDF from.
    serverURL

    The URL of the server that will perform the document conversion.
    JWT

    The JSON Web token used to authenticate access to the server.
    outputFileURL

    The URL the generated PDF is going to be saved to. Needs to be a file URL. Note that the actual output file URL might be different at the end.
    completionBlock

    Called when the converted PDF has finished downloading and has been saved to disk. First parameter is the actual output file URL of the converted PDF, second parameter is the resulting error, if any.

    Return Value

    Operation of converting the Office file to PDF that will be automatically enqueued.

  • Cancel all ongoing conversion operations.

    Declaration

    Objective-C

    + (void)cancelAllConversionOperations;

    Swift

    class func cancelAllConversionOperations()