Implement helpers for file attachments

3 files changed, 345 insertions, 0 deletions

diff --git a/include/qpdf/QPDFEFStreamObjectHelper.hh b/include/qpdf/QPDFEFStreamObjectHelper.hh
new file mode 100644
index 00000000..fe960785
--- /dev/null
+++ b/include/qpdf/QPDFEFStreamObjectHelper.hh
@@ -0,0 +1,122 @@
+// Copyright (c) 2005-2021 Jay Berkenbilt
+//
+// This file is part of qpdf.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Versions of qpdf prior to version 7 were released under the terms
+// of version 2.0 of the Artistic License. At your option, you may
+// continue to consider qpdf to be licensed under those terms. Please
+// see the manual for additional information.
+
+#ifndef QPDFEFSTREAMOBJECTHELPER_HH
+#define QPDFEFSTREAMOBJECTHELPER_HH
+
+#include <qpdf/QPDFObjectHelper.hh>
+
+#include <qpdf/DLL.h>
+
+#include <qpdf/QPDFObjectHandle.hh>
+#include <functional>
+
+// This class provides a higher level interface around Embedded File
+// Streams, which are discussed in section 7.11.4 of the ISO-32000 PDF
+// specification.
+
+class QPDFEFStreamObjectHelper: public QPDFObjectHelper
+{
+  public:
+    QPDF_DLL
+    QPDFEFStreamObjectHelper(QPDFObjectHandle);
+    QPDF_DLL
+    virtual ~QPDFEFStreamObjectHelper() = default;
+
+    // Date parameters are strings that comform to the PDF spec for
+    // date/time strings, which is "D:yyyymmddhhmmss<z>" where <z> is
+    // either "Z" for UTC or "-hh'mm'" or "+hh'mm'" for timezone
+    // offset. Examples: "D:20210207161528-05'00'",
+    // "D:20210207211528Z". See QUtil::qpdf_time_to_pdf_time.
+
+    QPDF_DLL
+    std::string getCreationDate();
+    QPDF_DLL
+    std::string getModDate();
+    // Get size as reported in the object; return 0 if not present.
+    QPDF_DLL
+    size_t getSize();
+    // Subtype is a mime type such as "text/plain"
+    QPDF_DLL
+    std::string getSubtype();
+    // Return the MD5 checksum as stored in the object as a binary
+    // string. This does not check consistency with the data. If not
+    // present, return an empty string.
+    QPDF_DLL
+    std::string getChecksum();
+
+    // Setters return a reference to this object so that they can be
+    // used as fluent interfaces, e.g.
+    // efsoh.setCreationDate(x).setModDate(y);
+
+    // Create a new embedded file stream with the given stream data,
+    // which can be provided in any of several ways. To get the new
+    // object back, call getObjectHandle() on the returned object. The
+    // checksum and size are computed automatically and stored. Other
+    // parameters may be supplied using setters defined below.
+    QPDF_DLL
+    static QPDFEFStreamObjectHelper
+    createEFStream(QPDF& qpdf, PointerHolder<Buffer> data);
+    QPDF_DLL
+    static QPDFEFStreamObjectHelper
+    createEFStream(QPDF& qpdf, std::string const& data);
+    // The provider function must write the data to the given
+    // pipeline. The function may be called multiple times by the qpdf
+    // library. You can pass QUtil::file_provider(filename) as the
+    // provider to have the qpdf library provide the contents of
+    // filename as a binary.
+    QPDF_DLL
+    static QPDFEFStreamObjectHelper
+    createEFStream(QPDF& qpdf, std::function<void(Pipeline*)> provider);
+
+    // Setters for other parameters
+    QPDF_DLL
+    QPDFEFStreamObjectHelper& setCreationDate(std::string const&);
+    QPDF_DLL
+    QPDFEFStreamObjectHelper& setModDate(std::string const&);
+
+    // Set subtype as a mime-type, e.g. "text/plain" or
+    // "application/pdf".
+    QPDF_DLL
+    QPDFEFStreamObjectHelper& setSubtype(std::string const&);
+
+  private:
+    QPDFObjectHandle getParam(std::string const& pkey);
+    void setParam(std::string const& pkey, QPDFObjectHandle const&);
+    static QPDFEFStreamObjectHelper newFromStream(QPDFObjectHandle stream);
+
+    class Members
+    {
+        friend class QPDFEFStreamObjectHelper;
+
+      public:
+        QPDF_DLL
+        ~Members() = default;
+
+      private:
+        Members();
+        Members(Members const&) = delete;
+    };
+
+    PointerHolder<Members> m;
+};
+
+#endif // QPDFEFSTREAMOBJECTHELPER_HH
diff --git a/include/qpdf/QPDFEmbeddedFileDocumentHelper.hh b/include/qpdf/QPDFEmbeddedFileDocumentHelper.hh
new file mode 100644
index 00000000..e850eb9c
--- /dev/null
+++ b/include/qpdf/QPDFEmbeddedFileDocumentHelper.hh
@@ -0,0 +1,97 @@
+// Copyright (c) 2005-2021 Jay Berkenbilt
+//
+// This file is part of qpdf.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Versions of qpdf prior to version 7 were released under the terms
+// of version 2.0 of the Artistic License. At your option, you may
+// continue to consider qpdf to be licensed under those terms. Please
+// see the manual for additional information.
+
+#ifndef QPDFEMBEDDEDFILEDOCUMENTHELPER_HH
+#define QPDFEMBEDDEDFILEDOCUMENTHELPER_HH
+
+#include <qpdf/QPDFDocumentHelper.hh>
+
+#include <qpdf/QPDF.hh>
+#include <qpdf/QPDFNameTreeObjectHelper.hh>
+#include <qpdf/QPDFFileSpecObjectHelper.hh>
+#include <qpdf/DLL.h>
+
+#include <memory>
+#include <map>
+
+// This class provides a higher level interface around document-level
+// file attachments, also known as embedded files. These are discussed
+// in sections 7.7.4 and 7.11 of the ISO-32000 PDF specification.
+
+class QPDFEmbeddedFileDocumentHelper: public QPDFDocumentHelper
+{
+  public:
+    QPDF_DLL
+    QPDFEmbeddedFileDocumentHelper(QPDF&);
+    QPDF_DLL
+    virtual ~QPDFEmbeddedFileDocumentHelper() = default;
+
+    QPDF_DLL
+    bool hasEmbeddedFiles() const;
+
+    QPDF_DLL
+    std::map<std::string,
+             std::shared_ptr<QPDFFileSpecObjectHelper>> getEmbeddedFiles();
+
+    // If an embedded file with the given name exists, return a
+    // (shared) pointer to it. Otherwise, return nullptr.
+    QPDF_DLL
+    std::shared_ptr<QPDFFileSpecObjectHelper>
+    getEmbeddedFile(std::string const& name);
+
+    // Add or replace an attachment
+    QPDF_DLL
+    void replaceEmbeddedFile(
+        std::string const& name, QPDFFileSpecObjectHelper const&);
+
+    // Remove an embedded file if present. Return value is true if the
+    // file was present and was removed. This method not only removes
+    // the embedded file from the embedded files name tree but also
+    // nulls out the file specification dictionary. This means that
+    // any references to this file from file attachment annotations
+    // will also stop working. This is the best way to make the
+    // attachment actually disappear from the file and not just from
+    // the list of attachments.
+    QPDF_DLL
+    bool removeEmbeddedFile(std::string const& name);
+
+  private:
+    void initEmbeddedFiles();
+
+    class Members
+    {
+        friend class QPDFEmbeddedFileDocumentHelper;
+
+      public:
+        QPDF_DLL
+        ~Members() = default;
+
+      private:
+        Members();
+        Members(Members const&) = delete;
+
+        std::shared_ptr<QPDFNameTreeObjectHelper> embedded_files;
+    };
+
+    PointerHolder<Members> m;
+};
+
+#endif // QPDFEMBEDDEDFILEDOCUMENTHELPER_HH
diff --git a/include/qpdf/QPDFFileSpecObjectHelper.hh b/include/qpdf/QPDFFileSpecObjectHelper.hh
new file mode 100644
index 00000000..28012e3d
--- /dev/null
+++ b/include/qpdf/QPDFFileSpecObjectHelper.hh
@@ -0,0 +1,126 @@
+// Copyright (c) 2005-2021 Jay Berkenbilt
+//
+// This file is part of qpdf.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Versions of qpdf prior to version 7 were released under the terms
+// of version 2.0 of the Artistic License. At your option, you may
+// continue to consider qpdf to be licensed under those terms. Please
+// see the manual for additional information.
+
+#ifndef QPDFFILESPECOBJECTHELPER_HH
+#define QPDFFILESPECOBJECTHELPER_HH
+
+#include <qpdf/QPDFObjectHelper.hh>
+
+#include <qpdf/DLL.h>
+
+#include <qpdf/QPDFObjectHandle.hh>
+#include <qpdf/QPDFEFStreamObjectHelper.hh>
+
+// This class provides a higher level interface around File
+// Specification dictionaries, which are discussed in section 7.11 of
+// the ISO-32000 PDF specification.
+
+class QPDFFileSpecObjectHelper: public QPDFObjectHelper
+{
+  public:
+    QPDF_DLL
+    QPDFFileSpecObjectHelper(QPDFObjectHandle);
+    QPDF_DLL
+    virtual ~QPDFFileSpecObjectHelper() = default;
+
+    QPDF_DLL
+    std::string getDescription();
+
+    // Get the main filename for this file specification. In priority
+    // order, check /UF, /F, /Unix, /DOS, /Mac.
+    QPDF_DLL
+    std::string getFilename();
+
+    // Return any of /UF, /F, /Unix, /DOS, /Mac filename keys that may
+    // be present in the object.
+    QPDF_DLL
+    std::map<std::string, std::string> getFilenames();
+
+    // Get the requested embedded file stream for this file
+    // specification. If key is empty, In priority order, check /UF,
+    // /F, /Unix, /DOS, /Mac. Returns a null object if not found. If
+    // this is an actual embedded file stream, its data is the content
+    // of the attachment. You can also use
+    // QPDFEFStreamObjectHelper for higher level access to
+    // the parameters.
+    QPDF_DLL
+    QPDFObjectHandle getEmbeddedFileStream(std::string const& key = "");
+
+    // Return the /EF key of the file spec, which is a map from file
+    // name key to embedded file stream.
+    QPDF_DLL
+    QPDFObjectHandle getEmbeddedFileStreams();
+
+    // Setters return a reference to this object so that they can be
+    // used as fluent interfaces, e.g.
+    // fsoh.setDescription(x).setFilename(y);
+
+    // Create a new filespec as an indirect object with the given
+    // filename, and attach the contents of the specified file as data
+    // in an embedded file stream.
+    QPDF_DLL
+    static
+    QPDFFileSpecObjectHelper createFileSpec(
+        QPDF& qpdf,
+        std::string const& filename,
+        std::string const& fullpath);
+
+    // Create a new filespec as an indirect object with the given
+    // unicode filename and embedded file stream. The file name will
+    // be used as both /UF and /F. If you need to override, call
+    // setFilename.
+    QPDF_DLL
+    static
+    QPDFFileSpecObjectHelper createFileSpec(
+        QPDF& qpdf,
+        std::string const& filename,
+        QPDFEFStreamObjectHelper);
+
+    QPDF_DLL
+    QPDFFileSpecObjectHelper& setDescription(std::string const&);
+    // setFilename sets /UF to unicode_name. If compat_name is empty,
+    // it is also set to unicode_name. unicode_name should be a UTF-8
+    // encoded string. compat_name is converted to a string
+    // QPDFObjectHandle literally, preserving whatever encoding it
+    // might happen to have.
+    QPDF_DLL
+    QPDFFileSpecObjectHelper& setFilename(
+        std::string const& unicode_name,
+        std::string const& compat_name = "");
+
+  private:
+    class Members
+    {
+        friend class QPDFFileSpecObjectHelper;
+
+      public:
+        QPDF_DLL
+        ~Members() = default;
+
+      private:
+        Members();
+        Members(Members const&) = delete;
+    };
+
+    PointerHolder<Members> m;
+};
+
+#endif // QPDFFILESPECOBJECTHELPER_HH