Appendix 1: Inspection Mode
Introduction
This appendix provides further detail about inspection mode.
Inspection mode is primarily intended for manual investigation and analysis of PDF files. API stability is not a major concern and the details of what is and is not supported may change from version to version. Please check this section for updates with each new release of qpdf.
NOTE Updates in the release notes may not apply to inspection mode despite wording such as “unconditionally” or “always.” Look out for footnotes indicating that statements don’t apply to inspection mode.
NOTE Warning messages are not adapted for inspection mode. In particular, messages that state that an issue has been repaired may not apply.
Supported Operations
The only supported operations in inspection mode are the retrieval of
objects with methods such as QPDF::getObject, QPDF::getRoot and
QPDF::getTrailer and the use of accessor methods of
QPDFObjectHandle that do not require any modification of the object,
including the unparse and writeJSON methods.
Other operations not specifically flagged as unsupported may also work, but there are no guarantees and they may cause crashes or hang.
Unsupported Operations
The following operations are explicitly unsupported in inspection mode:
use of any document and object helper methods
use of any linearization methods, including check methods
creation of object streams
operations involving more than one
QPDFobject, such as copying objects between documents
If any of these operations are desired, inspection mode should be used to manually repair the files sufficiently to allow qpdf to successfully repair them in normal mode.
Disabled Operations
The following operations are disabled and will throw a logic error:
retrieval of a document helper using static
getmethods
Disabled Automatic Repairs
The following automatic repairs are disabled in inspection mode:
- root object:
repairing missing or incorrect
/Typeattributes