Add additional interface for filtering page contents

1 files changed, 19 insertions, 5 deletions

diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh
index f0b8f2af..1f0d550a 100644
--- a/include/qpdf/QPDFObjectHandle.hh
+++ b/include/qpdf/QPDFObjectHandle.hh
@@ -80,9 +80,10 @@ class QPDFObjectHandle
     // The TokenFilter class provides a way to filter content streams
     // in a lexically aware fashion. TokenFilters can be attached to
     // streams using the addTokenFilter or addContentTokenFilter
-    // methods. The handleToken method is called for each token,
-    // including the eof token, and then handleEOF is called at the
-    // very end. Handlers may call write (or writeToken) to pass data
+    // methods or can be applied on the spot by filterPageContents.
+    // The handleToken method is called for each token, including the
+    // eof token, and then handleEOF is called at the very end.
+    // Handlers may call write (or writeToken) to pass data
     // downstream. The finish() method must be called exactly one time
     // to ensure that any written data is flushed out. The default
     // handleEOF calls finish. If you override handleEOF, you must
@@ -91,8 +92,9 @@ class QPDFObjectHandle
     // Failure to call finish() may result in some of the data you
     // have written being lost. You should not rely on a destructor
     // for calling finish() since the destructor call may occur later
-    // than you expect. Please see examples/token-filters.cc for
-    // examples of using TokenFilters.
+    // than you expect. Please see examples/pdf-filter-tokens.cc and
+    // examples/pdf-count-strings.cc for examples of using
+    // TokenFilters.
     //
     // Please note that when you call token.getValue() on a token of
     // type tt_string, you get the string value without any
@@ -255,6 +257,18 @@ class QPDFObjectHandle
     QPDF_DLL
     void parsePageContents(ParserCallbacks* callbacks);
 
+    // Pass a page's contents through the given TokenFilter. If a
+    // pipeline is also provided, it will be the target of the write
+    // methods from the token filter. If a pipeline is not specified,
+    // any output generated by the token filter will be discarded. Use
+    // this interface if you need to pass a page's contents through
+    // filter for work purposes without having that filter
+    // automatically applied to the page's contents, as happens with
+    // addContentTokenFilter. See examples/pdf-count-strings.cc for an
+    // example.
+    QPDF_DLL
+    void filterPageContents(TokenFilter* filter, Pipeline* next = 0);
+
     // Pipe a page's contents through the given pipeline. This method
     // works whether the contents are a single stream or an array of
     // streams. Call on a page object.