diff options
author | Jay Berkenbilt <ejb@ql.org> | 2021-02-09 00:07:21 +0100 |
---|---|---|
committer | Jay Berkenbilt <ejb@ql.org> | 2021-02-10 12:57:37 +0100 |
commit | ad34b9c278608dfdcfdbe7402acb3a6dd04c3d0e (patch) | |
tree | 5ba96898c85ae2106b44abe5120c49e4cb7b81e5 /include | |
parent | bf0e6eb3022bf2fde5623a0a3d151c07f5e82945 (diff) | |
download | qpdf-ad34b9c278608dfdcfdbe7402acb3a6dd04c3d0e.tar.zst |
Implement helpers for file attachments
Diffstat (limited to 'include')
-rw-r--r-- | include/qpdf/QPDFEFStreamObjectHelper.hh | 122 | ||||
-rw-r--r-- | include/qpdf/QPDFEmbeddedFileDocumentHelper.hh | 97 | ||||
-rw-r--r-- | include/qpdf/QPDFFileSpecObjectHelper.hh | 126 |
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 |