Pdf Rust Reference Documentation

Pdf

Current Version: 11.6.1
Requires Chilkat Bundle License

PDF Signing, Metadata, and Attachments

Work with PDF signatures, embedded files, metadata, and LTV information

Chilkat.Pdf provides PDF operations focused on digital signatures, embedded files, metadata, signature verification, and long-term validation support. It can load PDFs from files or memory, inspect page, signature, and attachment counts, sign PDFs with visible or invisible signatures, verify existing signatures, retrieve signer certificates, and manage DSS/LTV verification information.

Digital signatures Sign, certify, countersign, timestamp, and verify PDF signatures.
Embedded files Add attachments to PDFs or extract existing embedded files.
Metadata Read, update, or insert XMP metadata in an existing PDF.
LTV and DSS Inspect or add certificates, OCSP responses, and CRL information.

The class is commonly used for PDF signing workflows, PDF/A-3-style embedded-file scenarios, signature validation, and adding long-term validation material after signing.

For an extended overview, see Pdf Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::Pdf;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let pdf = Pdf::new();
// ... the native object is freed when `pdf` goes out of scope.
pub fn new() -> Pdf

Creates the underlying native Chilkat object (Pdf also implements Default). Every method takes &self, so the object never needs to be declared mut. A Pdf is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for Pdf

The native object is freed when the Pdf is dropped — when it goes out of scope, or explicitly with drop(pdf). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<Pdf>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match pdf.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
HasCertificationSig
// read-only
pub fn has_certification_sig(&self) -> bool
Introduced in version 9.5.0.96

Returns true if the currently open PDF has a certification signature.

PDF defines two types of signatures: approval and certification.

The differences are as follows:

  • Approval: There can be any number of approval signatures in a document.
  • Certification: There can be only one certification signature and it must be the first one in a document.

top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
NumEmbeddedFiles
// read-only
pub fn num_embedded_files(&self) -> i32
Introduced in version 9.5.0.95

The number of embedded files present in the currently open PDF.

More Information and Examples
Extract Embedded Files from PDF
top
NumPages
// read-only
pub fn num_pages(&self) -> i32
Introduced in version 9.5.0.85

The number of pages in the currently open PDF.

top
NumSignatures
// read-only
pub fn num_signatures(&self) -> i32
Introduced in version 9.5.0.85

The number of digital signatures present in the currently open PDF.

top
OwnerPassword
// read/write
pub fn owner_password(&self) -> String
pub fn set_owner_password(&self, value: &str)
Introduced in version 11.0.0

The PDF owner password, if required.

top
SigAllocateSize
// read/write
pub fn sig_allocate_size(&self) -> i32
pub fn set_sig_allocate_size(&self, value: i32)
Introduced in version 9.5.0.91

Defaults to 15000. This property should generally be left unchanged. If signing fails and the following message is in the LastErrorText: Did not allocate enough space for the PDF signature., then you should increase this value. The actual signature size will be noted in the LastErrorText, and you can use that value to set an allocation size that is somewhat larger.

top
UncommonOptions
// read/write
pub fn uncommon_options(&self) -> String
pub fn set_uncommon_options(&self, value: &str)
Introduced in version 9.5.0.85

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string. It can be set to a list of one or more of the following comma separated keywords:

  • WriteStandardXref - When writing the PDF, write the cross reference section in standard format if possible. (The standard format is the older non-compressed format.)
  • NO_VERIFY_CERT_SIGNATURES - When countersigning a PDF (i.e. adding a new signature to a PDF that already contains one or more signatures), Chilkat will automatically validate the existing signatures and their certificates. (The signing certificates are typically embedded within a signature.) If any of these validations fail, the new signature is not added. Sometimes, an existing signature is validated, but the certs in the chain of authentication, such as issuer certs or root CA certs, are not included and not available to check. In this case, you can add the NO_VERIFY_CERT_SIGNATURES to skip the existing signature certificate validations.

top
UserPassword
// read/write
pub fn user_password(&self) -> String
pub fn set_user_password(&self, value: &str)
Introduced in version 11.0.0

The PDF user password, if required.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
// read-only
pub fn version(&self) -> String

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

AddEmbeddedFiles
pub fn add_embedded_files(&self, json: &JsonObject, out_file_path: &str) -> Result<()>
Introduced in version 9.5.0.97

Embeds one or more files in a PDF.

The json specifies the files to be attached to the PDF. See the linked example below.

The json is a JSON object containing an array of JSON objects, where each object can contain the following members.

  • localFilePath: (required) The local file to be embedded in the PDF.
  • description: (required) It is a short description of the embedded file.
  • subType: (optional) Specifies the file type, such as application/xml, text/plain, etc. If not specified, then Chilkat will automatically choose a subType based on the file extension.
  • embeddedFilename: (optional) Specifies the name of the file to be used within the PDF in the desire is for it to be different than the filename in the local filesystem. If not present, then the filename part of the localFilePath.
  • AFRelationship: (optional starting in v11.1.0) Specifies specify the nature of the relationship of the embedded file. Possible values are Source, Data, Alternative, Supplement, and Unspecified. If unset, the default is Alternative.

If successful, the updated PDF with embedded files is written to out_file_path.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add File Attachments to a PDF
top
AddEmbeddedFilesBd
pub fn add_embedded_files_bd(&self, json: &JsonObject, bd: &BinData) -> Result<()>
Introduced in version 9.5.0.97

The same as AddEmbeddedFiles, but writes the resultant PDF to the bd.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add File Attachments to a PDF
top
AddSigningCert
pub fn add_signing_cert(&self, cert: &Cert) -> Result<()>
Introduced in version 9.5.0.85

Adds a certificate to be used for PDF signing. To sign with more than one certificate, call AddSigningCert once per certificate.

Note: This method is used to provide the ability to sign once with multiple certificates. This is different than signing with one certificate, and then signing again with a different certificate.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
AddVerificationInfo
pub fn add_verification_info(&self, json_options: &JsonObject, out_file_path: &str) -> Result<()>
Introduced in version 9.5.0.93

Adds LTV verification information to the PDF, and saves the updated PDF to out_file_path. This create or update a DSS (Document Security Store) in the PDF with the needed certificates, OCSP responses, and CRL information.

Pass an empty json_options. The json_options exists as a placeholder for adding options if needed.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
GetDss
pub fn get_dss(&self, json: &JsonObject) -> Result<()>
Introduced in version 9.5.0.85

Gets the contents of the PDF's Document Security Store (/DSS) if it exists. Returns the information in JSON format (in json). If there is no /DSS then an empty JSON document {} is returned in json.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Get PDF DSS (Document Security Store)
top
GetEmbeddedFileBd
pub fn get_embedded_file_bd(&self, index: i32, bd: &BinData) -> Result<()>
Introduced in version 9.5.0.95

Loads the bd with the contents of the Nth embedded file contained in the currently open PDF. The index specifies the index of the embedded file. The 1st embedded file is at index 0. See the example linked below.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Extract Embedded Files from PDF
top
GetEmbeddedFileInfo
pub fn get_embedded_file_info(&self, index: i32, json: &JsonObject) -> Result<()>
Introduced in version 9.5.0.95

Gets information about the Nth embedded file contained in the currently open PDF. The index specifies the index of the embedded file. The 1st embedded file is at index 0. The json is filled with information about the embedded file. See the example linked below.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Extract Embedded Files from PDF
top
GetLastJsonData
pub fn get_last_json_data(&self, json: &JsonObject)
Introduced in version 11.0.0

Provides information about what transpired in the last method called. For many methods, there is no information. For some methods, details about what transpired can be obtained via LastJsonData. For example, after calling a method to verify a signature, the LastJsonData will return JSON with details about the algorithms used for signature verification.

top
GetMetadata
pub fn get_metadata(&self, sb: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.92

If the PDF contains Metadata, then loads the Metadata XML into sb and returns true. If the PDF does not contain Metadata, then clears sb and returns false.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Extract Metadata XML from PDF
top
GetSignatureContent
pub fn get_signature_content(&self, index: i32, bd: &BinData) -> Result<()>
Introduced in version 9.5.0.92

Returns the CMS signature for the Nth signature contained in the PDF. The 1st signature is at index 0.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
GetSignerCert
pub fn get_signer_cert(&self, index: i32, cert: &Cert) -> Result<()>
Introduced in version 9.5.0.87

This method retrieves the signer certificate after calling VerifySignature. Use the same index for index as the one passed to VerifySignature. If successful and the signer certificate is fully available, cert will contain the certificate.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Get PDF Signer Certs
top
GetUnsignedSigFields
pub fn get_unsigned_sig_fields(&self, json: &JsonObject) -> Result<()>
Introduced in version 9.5.0.90

Returns JSON containing the name of each unsigned signature field found in the PDF.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
PDF List Unsigned Signature Fields
top
LoadBd
pub fn load_bd(&self, pdf_data: &BinData) -> Result<()>
Introduced in version 9.5.0.85

Loads the PDF file contained in pdf_data.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
LoadFile
pub fn load_file(&self, file_path: &str) -> Result<()>
Introduced in version 9.5.0.85

Load a PDF file into this object in memory.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SetHttpObj
pub fn set_http_obj(&self, http: &Http)
Introduced in version 9.5.0.85

Sets the HTTP object to be used to communicate with the timestamp authority (TSA) server for cases where long term validation (LTV) of signatures is desired. The http is used to send the requests, and it allows for connection related settings and timeouts to be set. For example, if HTTP or SOCKS proxies are required, these features can be specified on the http.

The http is also used to send OCSP requests to store OCSP responses in the PDF's document security store (DSS).

More Information and Examples
PDF LTV through HTTP Proxy or SOCKS proxy
top
SetSignatureJpeg
pub fn set_signature_jpeg(&self, jpg_data: &BinData) -> Result<()>
Introduced in version 9.5.0.85

Provides an optional JPG image to be included in the signature appearance. The JPG data is passed in jpg_data.

Note: JPG images must use the BaseLine format and not the Progressive format. (Programs typically save JPEG's using the BaseLine format as default.)

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
PDF Signature with Background Image (Seal/Stamp/etc.)
top
SetSigningCert
pub fn set_signing_cert(&self, cert: &Cert) -> Result<()>
Introduced in version 9.5.0.85

Specifies a certificate to be used when signing the PDF. Signing requires both a certificate and private key. In this case, the private key is implicitly specified if the certificate originated from a PFX that contains the corresponding private key, or if on a Windows-based computer where the certificate and corresponding private key are pre-installed.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SetSigningCert2
pub fn set_signing_cert2(&self, cert: &Cert, private_key: &PrivateKey) -> Result<()>
Introduced in version 9.5.0.85

Specifies a digital certificate and private key to be used for signing the PDF.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SignPdf
pub fn sign_pdf(&self, json_options: &JsonObject, out_file_path: &str) -> Result<()>
Introduced in version 9.5.0.85

Signs the open PDF and if successful writes the signed PDF to the ARG3. The json_options contains information and instructions about the signature. See the examples below for more detailed information about the JSON options listed here.

Summary of PDF Signing Options

  • appearance.fillUnsignedSignatureField - Can be set to true) to tell Chilkat to sign an existing unsigned signature field. Chilkat will automatically scale the visual appearance (text + graphics) to fit the pre-existing signature field. When fillUnsignedSignatureField is specified, it is not necessary to set appearance.x, appearance.y, appearance.fontScale, etc.

    Starting in v9.5.0.90, the unsignedSignatureField option (see below) can be used to specify the unsigned signature field to be used. Otherwise, the 1st available unsigned field is used.

    See PDF Unsigned Signature Fields for more information.

  • appearance.fontScale - The font scale (in pts) to be used, such as 10.0.
  • appearance.height - Optional to specify the exact height of the visible signature rectangle in points, where 72 points equals 1 inch. If the appearance.height is set, then appearance.width should be set to auto (or left unset). Chilkat will compute the font scale to achieve the desired rectangle height, and the resulting width will depend on the text.
  • appearance.image - Indicates an image will be included in the signature. Set to the keyword custom-jpg to use an image set by calling the SetSignatureJpeg method. Otherwise can be set to one of the following keywords to indicate a built-in SVG graphic. (These are graphics embedded within the Chilkat library itself.)
    • green-check-grey-circle
    • green-check-green-circle
    • application-approved
    • application-rejected
    • document-accepted
    • approved
    • blue-check-mark
    • green-check-mark
    • green-check-grey-circle
    • red-x-red-circle
    • rejected
    • result-failure
    • result-pass
    • signature
    • document-check
    • document-x
    • red-x-grey-circle
  • appearance.imageOpacity - Sets the image opacity. Can be an integer from 1 to 100.
  • appearance.imagePlacement - Sets the image placment within the signature rectangle. Can be left, right, or center. Images placed in the center typically have opacity 50% or less because the text is displayed over the image (i.e. it is a background image). Images placed left or right are not background images. The signature rectangle is divided into two sub-rectangles, one for the image, and one for the text.
  • appearance.margin_x - If the appearance.x is set to left, then this can optionally be use to specify the position from the left edge. The default margin is 10.0 (10 points, where 72 points equals 1 inch).
  • appearance.margin_y - If the appearance.y is set to top, then this can optionally be use to specify the position from the top. The default margin for y is 20.0 (20 points, where 72 points equals 1 inch).
  • appearance.text[i] - The text that should appear in the signature box. Each line is specified in a JSON array item, where i is an integer starting with 0 as the 1st line. The text can contain the following keywords which are replaced with actual values:
    • cert_country - The signing certificate's subject country (C).
    • cert_cn - The signing certificate's subject common name (CN).
    • cert_dn - The signing certificate's DN (distinguished name).
    • cert_email - The signing certificate's subject email address (E).
    • cert_issuer_cn - The signing certificate's issuer's common name (CN).
    • cert_locality - The signing certificate's subject locality (L).
    • cert_organization - The signing certificate's subject organization (O).
    • cert_org_id - The signing certificate's organization ID.
    • cert_ou - The signing certificate's subject organizational unit (OU).
    • cert_san_rfc822name - The signing certificate's RFC822 subject alternative name.
    • cert_serial_dec - The signing certificate's serial number in decimal format.
    • cert_serial_hex - The signing certificate's serial number in hex format.
    • cert_state - The signing certificate's subject state (S).
    • cert_thumbprint - The signing certificate's thumbprint (The SHA1 hash of the binary DER representation in hex format).
    • current_datetime - Current local date/time in the format such as Sep 11 2020 16:30:54.
    • current_dt - Current local date/time in PDF date/time string format, such as YYYY.MM.DD hh:mm:ss -05'00'.
    • current_rfc822_dt_gmt - Current GMT date/time in RFC822 format, such as Mon, 22 Nov 2021 15:58:41 GMT.
    • current_rfc822_dt_local - Current local date/time in RFC822 format, such as Mon, 22 Nov 2021 09:56:16 -0600.
    • current_timestamp_gmt - Current GMT date/time in timestamp format, such as 1990-12-31T23:59:60Z.
    • current_timestamp_local - Current local date/time in timestamp format, such as 2019-10-12T03:20:50.52-04:00.
  • appearance.width - Optional to specify the exact width of the visible signature rectangle in points, where 72 points equals 1 inch. If the appearance.width is set, then appearance.height should be set to auto (or left unset). Chilkat will compute the font scale to achieve the desired rectangle width, and the resulting height will depend on the text and number of lines of text.
  • appearance.x - The horizontal position on the page of the left edge of the signature box. Can be a keyword such as left, right, or middle to specify a typical placement with default margins. Otherwise can be a floating point number where 0.0 is the leftmost coordinate of a page, and 612.0 is the right most. Can also be the keyword after to place the signature just to the right of the rightmost signature on the page.
  • appearance.y - The vertical position on the page of the top edge of the signature box. Can be one of the keywords top or bottom to specify a typical placement with default margins. Otherwise can be a floating point number where 0.0 is the bottom coordinate of a page, and 792.0 is the top. Can also be the keyword under to place the signature just under the bottommost signature on the page.
  • contactInfo - Optional to provide free-form text with contact information about the signer.
  • docMDP.add - Set this boolean value to true to include the Document MDP Permissions with a certifying signature. When a certifying signature is desired, both lockAfterSigning and docMDP.add should be specified. The default Doc MDP permission level is 2.
  • docMDP.accessPermissions - Include this if the docMDP.add is specified, and a permission level different from the default value of 2 is desired. Possible values are:
    • 1: No changes to the document are permitted and any changes invalidate the signature.
    • 2: Permitted changes include filling in forms, instantiating page templates and signing.
    • 3: Same as 2, but also allow annotation creation, deletion, and modification.
  • embedCertChain - Boolean to control whether the certificate chain is included in the signature. The default is to include the certificates in the chain of authentication. Set this to false to only include the signing certificate (this is not common).
  • hashAlgorithm - If the signing certificate is RSA-based, and the signing scheme (padding scheme) is RSA-PSS, then this specifies the PSS hash algorithm. Can be sha1, sha256, sha384, or sha512. (sha256 is what should be commonly chosen.)
  • includeRootCert - Boolean to control whether the root CA certificate is included in the certificate chain (assuming the certificate chain is included). The default is to include the root CA certificate. Set this to false to exclude the root CA certificate from being included (this is not common).
  • info.* - (added in Chilkat v9.5.0.90) Provides the ability to add or update the PDF document's /Info, such as Creator, Producer, Title, etc. Any number of arbitrary member names can be specified and these will be added to the document's /Info dictionary. However, Chilkat will ignore ModDate and CreationDate because ModDate is automatically set to the current system date/time and the CreationDate should not change.
  • invisibleSignature - Set this boolean to true to create an invisible signature with no appearance.
  • legalAttestation - Set to provide a free-form text legal attestation.
  • location - Optional to provide free-form text with a description of the geographic location where the PDF was signed.
  • lockAfterSigning - Set this boolean to true to certify and lock a PDF as opposed to adding an approval signature (the default) which allows for additional countersignatures.
  • ltvOcsp - Set this boolean to true to create an LTV-enabled signature.
  • noDss - Set this boolean to true to prevent adding a /DSS (Document Security Store).
  • page - The page number where the signature will be placed. Page 1 is the 1st page.
  • reason - Optional to provide text indicating the reason for the signature.
  • signingAlgorithm - If the signing certificate is RSA-based, then chooses the RSA padding scheme. Possible values are pkcs for PKCS-v1_5 or pss for RSASSA-PSS.
  • signingCertificateV2 - Set to 1 to include the SigningCertificateV2 authenticated attribute. This is desired in most cases.
  • signingTime - Set to 1 to include the SigningTime authenticated attribute. This is desired in most cases. Note: This is not the same as time-stamping. This is a fundamental authenticated attribute that should be included with or without the addition of time-stamping.
  • sigTextLabel - Set to provide free-form text for the signatures annotation text label.
  • subFilter - Set to /ETSI.CAdES.detached, /adbe.pkcs7.detached, or something else.
  • timestampToken.enabled - Set to true to tell Chilkat to request a timestamp from a TSA server and include the timestamp token in the signature's authentication attributes
  • timestampToken.tsaUrl - The timestamp server's URL.
  • timestampToken.tsaUsername, timestampToken.tsaPassword - If the timestamp server requires a login and password.
  • timestampToken.bearerToken - Use this if the timestamp server requires a bearer token instead of a password. This feature was added in Chilkat v11.2.0.
  • timestampToken.requestTsaCert - Set to true to ask the timestamp server to include its certificate in the timestamp token.
  • unsignedSignatureField - (added in Chilkat v9.5.0.90) Can be set to specify the name of the unsigned signature field that is to be signed.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
See Examples for Signing PDFs
top
SignPdfBd
pub fn sign_pdf_bd(&self, json_options: &JsonObject, bd: &BinData) -> Result<()>
Introduced in version 9.5.0.94

Signs the open PDF and if successful writes the signed PDF to the bd. The json_options contains information and instructions about the signature. See the reference documentation for the SignPdf method for details about json_options.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
UpdateMetadata
pub fn update_metadata(&self, sb: &StringBuilder, out_file_path: &str) -> Result<()>
Introduced in version 10.1.0

Updates or adds XMP metdata to a PDF. The metadata is passed in sb. If successful, the PDF with updated or inserted metadata is written to out_file_path.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
UpdateMetadataBd
pub fn update_metadata_bd(&self, sb: &StringBuilder, bd: &BinData) -> Result<()>
Introduced in version 10.1.0

Updates or adds XMP metdata to a PDF. The metadata is passed in sb. If successful, the PDF with updated or inserted metadata is written to bd.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
VerifySignature
pub fn verify_signature(&self, index: i32, sig_info: &JsonObject) -> Result<()>
Introduced in version 9.5.0.85

Verifies the Nth signature contained in the PDF, where the 1st signature is indicated by an index of 0. Returns true if the signature valid, otherwise returns false. The sig_info is an output argument and is populated with information about the validated or unvalidated signature.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Validate PDF Signatures
top

Events

All Chilkat methods are synchronous: the call returns when the work is done. During a call, Pdf raises three events so your application can show progress and offer a way out. Implement the chilkat::EventHandler trait (every method has a do-nothing default, so implement only the events you need) and install it with set_event_handler:

use chilkat::{Pdf, EventHandler};

struct Progress;

impl EventHandler for Progress {
    fn percent_done(&mut self, pct: i32) -> bool {
        println!("{pct}%");
        false   // return true to abort the method in progress
    }
    fn progress_info(&mut self, name: &str, value: &str) {
        println!("{name}: {value}");
    }
}

let pdf = Pdf::new();
pdf.set_event_handler(Progress);
pdf.set_heartbeat_ms(250);   // raise abort_check 4 times per second during Chilkat calls

For a one-off handler the closure methods avoid writing a type; they may be combined, and each replaces the previously set closure for that one event (installing a closure removes a trait handler set earlier, and vice versa):

pdf.on_percent_done(|pct| { println!("{pct}%"); false });
pdf.on_progress_info(|name, value| println!("{name}: {value}"));
pub fn set_event_handler<H: EventHandler>(&self, handler: H)

Installs handler as the receiver of this object's events, replacing any handler or closures set earlier. The object owns the handler, which must be Send + 'static.

pub fn clear_event_handler(&self)

Removes the handler and any closures; events are no longer delivered.

AbortCheck fires at regular intervals controlled by the HeartbeatMs property (0, the default, disables it); PercentDone fires when an operation's completion percentage is known; ProgressInfo delivers named progress values. Returning true from abort_check or percent_done aborts the running method, which then returns Err.

Events fire on the thread that called the method, before that method returns. A panic inside a handler aborts the running method and is re-raised to the caller once the native library has returned, so it never unwinds through C frames. To abort a long operation from another thread, share an Arc<AtomicBool> with an abort_check handler, or set the object's AbortCurrent property to true.

AbortCheck
// EventHandler trait method; closure form: on_abort_check(FnMut() -> bool)
fn abort_check(&mut self) -> bool

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

pdf.set_heartbeat_ms(250);   // call abort_check 4 times per second

let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let flag = stop.clone();
pdf.on_abort_check(move || flag.load(std::sync::atomic::Ordering::Relaxed));
// ... another thread may now abort the method in progress with stop.store(true, Ordering::Relaxed)
top
PercentDone
// EventHandler trait method; closure form: on_percent_done(FnMut(i32) -> bool)
fn percent_done(&mut self, pct: i32) -> bool

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pct_done argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pct_done equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to true. This will cause the method to terminate and return a failure status or corresponding failure value.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

pdf.on_percent_done(|pct| {
    // pct ranges from 1 to 100.
    println!("Percent done: {pct}");
    false   // return true to abort the method in progress
});
top
ProgressInfo
// EventHandler trait method; closure form: on_progress_info(FnMut(&str, &str))
fn progress_info(&mut self, name: &str, value: &str)

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

pdf.on_progress_info(|name, value| println!("{name}: {value}"));
top