From 3c5700c255f4603b5df9c6d183d13dd71a083cc3 Mon Sep 17 00:00:00 2001 From: m-holger Date: Sat, 27 May 2023 18:19:52 +0100 Subject: Code tidy - reflow comments and strings --- include/qpdf/BufferInputSource.hh | 25 +- include/qpdf/ClosedFileInputSource.hh | 37 +- include/qpdf/FileInputSource.hh | 21 +- include/qpdf/InputSource.hh | 49 +- include/qpdf/PDFVersion.hh | 40 +- include/qpdf/Pipeline.hh | 3 +- include/qpdf/Pl_Buffer.hh | 4 +- include/qpdf/Pl_Concatenate.hh | 33 +- include/qpdf/Pl_Count.hh | 31 +- include/qpdf/Pl_DCT.hh | 24 +- include/qpdf/Pl_Discard.hh | 27 +- include/qpdf/Pl_Function.hh | 44 +- include/qpdf/Pl_OStream.hh | 24 +- include/qpdf/Pl_QPDFTokenizer.hh | 40 +- include/qpdf/Pl_RunLength.hh | 21 +- include/qpdf/Pl_StdioFile.hh | 24 +- include/qpdf/Pl_String.hh | 41 +- include/qpdf/QPDF.hh | 2 +- include/qpdf/QPDFAnnotationObjectHelper.hh | 81 ++-- include/qpdf/QPDFCryptoProvider.hh | 46 +- include/qpdf/QPDFDocumentHelper.hh | 38 +- include/qpdf/QPDFEFStreamObjectHelper.hh | 67 ++- include/qpdf/QPDFEmbeddedFileDocumentHelper.hh | 44 +- include/qpdf/QPDFFileSpecObjectHelper.hh | 69 ++- include/qpdf/QPDFLogger.hh | 104 ++--- include/qpdf/QPDFMatrix.hh | 35 +- include/qpdf/QPDFNameTreeObjectHelper.hh | 86 ++-- include/qpdf/QPDFNumberTreeObjectHelper.hh | 100 ++-- include/qpdf/QPDFObjGen.hh | 44 +- include/qpdf/QPDFObjectHelper.hh | 38 +- include/qpdf/QPDFOutlineDocumentHelper.hh | 38 +- include/qpdf/QPDFOutlineObjectHelper.hh | 61 ++- include/qpdf/QPDFPageDocumentHelper.hh | 113 ++--- include/qpdf/QPDFPageLabelDocumentHelper.hh | 61 +-- include/qpdf/QPDFStreamFilter.hh | 60 +-- include/qpdf/QPDFSystemError.hh | 30 +- include/qpdf/QPDFUsage.hh | 21 +- include/qpdf/QPDFWriter.hh | 455 ++++++++---------- include/qpdf/QPDFXRefEntry.hh | 28 +- include/qpdf/QTC.hh | 29 +- include/qpdf/QUtil.hh | 330 ++++++------- include/qpdf/qpdf-c.h | 620 ++++++++++--------------- include/qpdf/qpdfjob-c.h | 130 +++--- include/qpdf/qpdflogger-c.h | 51 +- 44 files changed, 1362 insertions(+), 1907 deletions(-) (limited to 'include') diff --git a/include/qpdf/BufferInputSource.hh b/include/qpdf/BufferInputSource.hh index 8e1ea484..2ef04a28 100644 --- a/include/qpdf/BufferInputSource.hh +++ b/include/qpdf/BufferInputSource.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDF_BUFFERINPUTSOURCE_HH #define QPDF_BUFFERINPUTSOURCE_HH @@ -28,8 +25,8 @@ class QPDF_DLL_CLASS BufferInputSource: public InputSource { public: - // If own_memory is true, BufferInputSource will delete the buffer - // when finished with it. Otherwise, the caller owns the memory. + // If own_memory is true, BufferInputSource will delete the buffer when finished with it. + // Otherwise, the caller owns the memory. QPDF_DLL BufferInputSource(std::string const& description, Buffer* buf, bool own_memory = false); QPDF_DLL diff --git a/include/qpdf/ClosedFileInputSource.hh b/include/qpdf/ClosedFileInputSource.hh index 467c8c03..9f7e4fce 100644 --- a/include/qpdf/ClosedFileInputSource.hh +++ b/include/qpdf/ClosedFileInputSource.hh @@ -2,31 +2,27 @@ // // 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 +// 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. +// 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. +// 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 QPDF_CLOSEDFILEINPUTSOURCE_HH #define QPDF_CLOSEDFILEINPUTSOURCE_HH -// This is an input source that reads from files, like -// FileInputSource, except that it opens and close the file -// surrounding every operation. This decreases efficiency, but it allows -// many more of these to exist at once than the maximum number of open -// file descriptors. This is used for merging large numbers of files. +// This is an input source that reads from files, like FileInputSource, except that it opens and +// close the file surrounding every operation. This decreases efficiency, but it allows many more of +// these to exist at once than the maximum number of open file descriptors. This is used for merging +// large numbers of files. #include #include // unused -- remove in qpdf 12 (see #785) @@ -57,10 +53,9 @@ class QPDF_DLL_CLASS ClosedFileInputSource: public InputSource QPDF_DLL virtual void unreadCh(char ch); - // The file stays open between calls to stayOpen(true) and - // stayOpen(false). You can use this to surround multiple - // operations on a single ClosedFileInputSource to reduce the - // overhead of a separate open/close on each call. + // The file stays open between calls to stayOpen(true) and stayOpen(false). You can use this to + // surround multiple operations on a single ClosedFileInputSource to reduce the overhead of a + // separate open/close on each call. QPDF_DLL void stayOpen(bool); diff --git a/include/qpdf/FileInputSource.hh b/include/qpdf/FileInputSource.hh index 52d4a2e8..71adad7b 100644 --- a/include/qpdf/FileInputSource.hh +++ b/include/qpdf/FileInputSource.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDF_FILEINPUTSOURCE_HH #define QPDF_FILEINPUTSOURCE_HH diff --git a/include/qpdf/InputSource.hh b/include/qpdf/InputSource.hh index 91a5c6e5..2bc57c57 100644 --- a/include/qpdf/InputSource.hh +++ b/include/qpdf/InputSource.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDF_INPUTSOURCE_HH #define QPDF_INPUTSOURCE_HH @@ -30,9 +27,8 @@ #include #include -// Remember to use QPDF_DLL_CLASS on anything derived from InputSource -// so it will work with dynamic_cast across the shared object -// boundary. +// Remember to use QPDF_DLL_CLASS on anything derived from InputSource so it will work with +// dynamic_cast across the shared object boundary. class QPDF_DLL_CLASS InputSource { public: @@ -61,12 +57,10 @@ class QPDF_DLL_CLASS InputSource QPDF_DLL std::string readLine(size_t max_line_length); - // Find first or last occurrence of a sequence of characters - // starting within the range defined by offset and len such that, - // when the input source is positioned at the beginning of that - // sequence, finder.check() returns true. If len is 0, the search - // proceeds until EOF. If a qualifying pattern is found, these - // methods return true and leave the input source positioned + // Find first or last occurrence of a sequence of characters starting within the range defined + // by offset and len such that, when the input source is positioned at the beginning of that + // sequence, finder.check() returns true. If len is 0, the search proceeds until EOF. If a + // qualifying pattern is found, these methods return true and leave the input source positioned // wherever check() left it at the end of the matching pattern. QPDF_DLL bool findFirst(char const* start_chars, qpdf_offset_t offset, size_t len, Finder& finder); @@ -80,11 +74,9 @@ class QPDF_DLL_CLASS InputSource virtual void rewind() = 0; virtual size_t read(char* buffer, size_t length) = 0; - // Note: you can only unread the character you just read. The - // specific character is ignored by some implementations, and the - // implementation doesn't check this. Use of unreadCh is - // semantically equivalent to seek(-1, SEEK_CUR) but is much more - // efficient. + // Note: you can only unread the character you just read. The specific character is ignored by + // some implementations, and the implementation doesn't check this. Use of unreadCh is + // semantically equivalent to seek(-1, SEEK_CUR) but is much more efficient. virtual void unreadCh(char ch) = 0; // The following methods are for use by QPDFTokenizer @@ -149,9 +141,8 @@ InputSource::fastTell() inline bool InputSource::fastRead(char& ch) { - // Before calling fastRead, fastTell must be called to prepare the buffer. - // Once reading is complete, fastUnread must be called to set the correct - // file position. + // Before calling fastRead, fastTell must be called to prepare the buffer. Once reading is + // complete, fastUnread must be called to set the correct file position. if (this->buf_idx < this->buf_len) { ch = this->buffer[this->buf_idx]; ++(this->buf_idx); diff --git a/include/qpdf/PDFVersion.hh b/include/qpdf/PDFVersion.hh index 03d78899..1b2c45de 100644 --- a/include/qpdf/PDFVersion.hh +++ b/include/qpdf/PDFVersion.hh @@ -2,26 +2,22 @@ // // 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 +// 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. +// 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. +// 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. -// This class implements a simple writer for saving QPDF objects to -// new PDF files. See comments through the header file for additional -// details. +// This class implements a simple writer for saving QPDF objects to new PDF files. See comments +// through the header file for additional details. #ifndef PDFVERSION_HH #define PDFVERSION_HH @@ -32,10 +28,9 @@ class PDFVersion { public: - // Represent a PDF version. PDF versions are typically - // major.minor, but PDF 1.7 has several extension levels as the - // ISO 32000 spec was in progress. This class helps with - // comparison of versions. + // Represent a PDF version. PDF versions are typically major.minor, but PDF 1.7 has several + // extension levels as the ISO 32000 spec was in progress. This class helps with comparison of + // versions. QPDF_DLL PDFVersion(); QPDF_DLL @@ -49,13 +44,12 @@ class PDFVersion QPDF_DLL bool operator==(PDFVersion const& rhs) const; - // Replace this version with the other one if the other one is - // greater. + // Replace this version with the other one if the other one is greater. QPDF_DLL void updateIfGreater(PDFVersion const& other); - // Initialize a string and integer suitable for passing to - // QPDFWriter::setMinimumPDFVersion or QPDFWriter::forcePDFVersion. + // Initialize a string and integer suitable for passing to QPDFWriter::setMinimumPDFVersion or + // QPDFWriter::forcePDFVersion. QPDF_DLL void getVersion(std::string& version, int& extension_level) const; diff --git a/include/qpdf/Pipeline.hh b/include/qpdf/Pipeline.hh index 9b5bc483..bd5a7826 100644 --- a/include/qpdf/Pipeline.hh +++ b/include/qpdf/Pipeline.hh @@ -26,8 +26,7 @@ // // The client is required to call finish() before destroying a Pipeline in order to avoid loss of // data. A Pipeline class should not throw an exception in the destructor if this hasn't been done -// though since doing so causes too much trouble when deleting -// pipelines during error conditions. +// though since doing so causes too much trouble when deleting pipelines during error conditions. // // Some pipelines are reusable (i.e., you can call write() after calling finish() and can call // finish() multiple times) while others are not. It is up to the caller to use a pipeline diff --git a/include/qpdf/Pl_Buffer.hh b/include/qpdf/Pl_Buffer.hh index b244a9f5..39ef0746 100644 --- a/include/qpdf/Pl_Buffer.hh +++ b/include/qpdf/Pl_Buffer.hh @@ -47,8 +47,8 @@ class QPDF_DLL_CLASS Pl_Buffer: public Pipeline void finish() override; // Each call to getBuffer() resets this object -- see notes above. - // The caller is responsible for deleting the returned Buffer - // object. See also getBufferSharedPointer() and getMallocBuffer(). + // The caller is responsible for deleting the returned Buffer object. See also + // getBufferSharedPointer() and getMallocBuffer(). QPDF_DLL Buffer* getBuffer(); diff --git a/include/qpdf/Pl_Concatenate.hh b/include/qpdf/Pl_Concatenate.hh index 6ddb61c9..444a7482 100644 --- a/include/qpdf/Pl_Concatenate.hh +++ b/include/qpdf/Pl_Concatenate.hh @@ -2,31 +2,27 @@ // // 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 +// 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. +// 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. +// 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 PL_CONCATENATE_HH #define PL_CONCATENATE_HH -// This pipeline will drop all regular finished calls rather than -// passing them onto next. To finish downstream streams, call -// manualFinish. This makes it possible to pipe multiple streams -// (e.g. with QPDFObjectHandle::pipeStreamData) to a downstream like -// Pl_Flate that can't handle multiple calls to finish(). +// This pipeline will drop all regular finished calls rather than passing them onto next. To finish +// downstream streams, call manualFinish. This makes it possible to pipe multiple streams (e.g. +// with QPDFObjectHandle::pipeStreamData) to a downstream like Pl_Flate that can't handle multiple +// calls to finish(). #include @@ -44,8 +40,7 @@ class QPDF_DLL_CLASS Pl_Concatenate: public Pipeline QPDF_DLL virtual void finish(); - // At the very end, call manualFinish to actually finish the rest of - // the pipeline. + // At the very end, call manualFinish to actually finish the rest of the pipeline. QPDF_DLL void manualFinish(); diff --git a/include/qpdf/Pl_Count.hh b/include/qpdf/Pl_Count.hh index 2367aae9..51338607 100644 --- a/include/qpdf/Pl_Count.hh +++ b/include/qpdf/Pl_Count.hh @@ -2,28 +2,24 @@ // // 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 +// 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. +// 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. +// 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 PL_COUNT_HH #define PL_COUNT_HH -// This pipeline is reusable; i.e., it is safe to call write() after -// calling finish(). +// This pipeline is reusable; i.e., it is safe to call write() after calling finish(). #include #include @@ -42,8 +38,8 @@ class QPDF_DLL_CLASS Pl_Count: public Pipeline // Returns the number of bytes written QPDF_DLL qpdf_offset_t getCount() const; - // Returns the last character written, or '\0' if no characters - // have been written (in which case getCount() returns 0) + // Returns the last character written, or '\0' if no characters have been written (in which case + // getCount() returns 0) QPDF_DLL unsigned char getLastChar() const; @@ -60,8 +56,7 @@ class QPDF_DLL_CLASS Pl_Count: public Pipeline Members(); Members(Members const&) = delete; - // Must be qpdf_offset_t, not size_t, to handle writing more than - // size_t can handle. + // Must be qpdf_offset_t, not size_t, to handle writing more than size_t can handle. qpdf_offset_t count; unsigned char last_char; }; diff --git a/include/qpdf/Pl_DCT.hh b/include/qpdf/Pl_DCT.hh index 9352091f..e4f6345f 100644 --- a/include/qpdf/Pl_DCT.hh +++ b/include/qpdf/Pl_DCT.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 PL_DCT_HH #define PL_DCT_HH @@ -27,8 +24,7 @@ #include #include -// jpeglib.h must be included after cstddef or else it messes up the -// definition of size_t. +// jpeglib.h must be included after cstddef or else it messes up the definition of size_t. #include class QPDF_DLL_CLASS Pl_DCT: public Pipeline diff --git a/include/qpdf/Pl_Discard.hh b/include/qpdf/Pl_Discard.hh index 1754fcab..b2733a66 100644 --- a/include/qpdf/Pl_Discard.hh +++ b/include/qpdf/Pl_Discard.hh @@ -2,31 +2,26 @@ // // 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 +// 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. +// 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. +// 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 PL_DISCARD_HH #define PL_DISCARD_HH -// This pipeline discards its output. It is an end-of-line pipeline -// (with no next). +// This pipeline discards its output. It is an end-of-line pipeline (with no next). -// This pipeline is reusable; i.e., it is safe to call write() after -// calling finish(). +// This pipeline is reusable; i.e., it is safe to call write() after calling finish(). #include diff --git a/include/qpdf/Pl_Function.hh b/include/qpdf/Pl_Function.hh index e31d497d..c9d5550d 100644 --- a/include/qpdf/Pl_Function.hh +++ b/include/qpdf/Pl_Function.hh @@ -2,38 +2,33 @@ // // 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 +// 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. +// 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. +// 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 PL_FUNCTION_HH #define PL_FUNCTION_HH -// This pipeline calls an arbitrary function with whatever data is -// passed to it. This pipeline can be reused. +// This pipeline calls an arbitrary function with whatever data is passed to it. This pipeline can +// be reused. // -// For this pipeline, "next" may be null. If a next pointer is -// provided, this pipeline will also pass the data through to it and -// will forward finish() to it. +// For this pipeline, "next" may be null. If a next pointer is provided, this pipeline will also +// pass the data through to it and will forward finish() to it. // -// It is okay to not call finish() on this pipeline if it has no -// "next". +// It is okay to not call finish() on this pipeline if it has no "next". // -// It is okay to keep calling write() after a previous write throws an -// exception as long as the delegated function allows it. +// It is okay to keep calling write() after a previous write throws an exception as long as the +// delegated function allows it. #include @@ -48,10 +43,9 @@ class QPDF_DLL_CLASS Pl_Function: public Pipeline QPDF_DLL Pl_Function(char const* identifier, Pipeline* next, writer_t fn); - // The supplied C-style function is called every time write is - // called. The udata option is passed into the function with each - // call. If the function returns a non-zero value, a runtime error - // is thrown. + // The supplied C-style function is called every time write is called. The udata option is + // passed into the function with each call. If the function returns a non-zero value, a runtime + // error is thrown. typedef int (*writer_c_t)(unsigned char const*, size_t, void*); QPDF_DLL Pl_Function(char const* identifier, Pipeline* next, writer_c_t fn, void* udata); diff --git a/include/qpdf/Pl_OStream.hh b/include/qpdf/Pl_OStream.hh index 7bb3410d..3ea21c93 100644 --- a/include/qpdf/Pl_OStream.hh +++ b/include/qpdf/Pl_OStream.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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. // End-of-line pipeline that simply writes its data to a stdio FILE* object. @@ -35,8 +32,7 @@ class QPDF_DLL_CLASS Pl_OStream: public Pipeline { public: - // os is externally maintained; this class just writes to and - // flushes it. It does not close it. + // os is externally maintained; this class just writes to and flushes it. It does not close it. QPDF_DLL Pl_OStream(char const* identifier, std::ostream& os); QPDF_DLL diff --git a/include/qpdf/Pl_QPDFTokenizer.hh b/include/qpdf/Pl_QPDFTokenizer.hh index 37e87b4d..5bc6cb87 100644 --- a/include/qpdf/Pl_QPDFTokenizer.hh +++ b/include/qpdf/Pl_QPDFTokenizer.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 PL_QPDFTOKENIZER_HH #define PL_QPDFTOKENIZER_HH @@ -31,22 +28,19 @@ #include -// Tokenize the incoming text using QPDFTokenizer and pass the tokens -// in turn to a QPDFObjectHandle::TokenFilter object. All bytes of -// incoming content will be included in exactly one token and passed -// downstream. +// Tokenize the incoming text using QPDFTokenizer and pass the tokens in turn to a +// QPDFObjectHandle::TokenFilter object. All bytes of incoming content will be included in exactly +// one token and passed downstream. -// This is a very low-level interface for working with token filters. -// Most code will want to use QPDFObjectHandle::filterPageContents or -// QPDFObjectHandle::addTokenFilter. See QPDFObjectHandle.hh for -// details. +// This is a very low-level interface for working with token filters. Most code will want to use +// QPDFObjectHandle::filterPageContents or QPDFObjectHandle::addTokenFilter. See QPDFObjectHandle.hh +// for details. class QPDF_DLL_CLASS Pl_QPDFTokenizer: public Pipeline { public: - // Whatever pipeline is provided as "next" will be set as the - // pipeline that the token filter writes to. If next is not - // provided, any output written by the filter will be discarded. + // Whatever pipeline is provided as "next" will be set as the pipeline that the token filter + // writes to. If next is not provided, any output written by the filter will be discarded. QPDF_DLL Pl_QPDFTokenizer( char const* identifier, QPDFObjectHandle::TokenFilter* filter, Pipeline* next = nullptr); diff --git a/include/qpdf/Pl_RunLength.hh b/include/qpdf/Pl_RunLength.hh index 94f9ef57..86782535 100644 --- a/include/qpdf/Pl_RunLength.hh +++ b/include/qpdf/Pl_RunLength.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 PL_RUNLENGTH_HH #define PL_RUNLENGTH_HH diff --git a/include/qpdf/Pl_StdioFile.hh b/include/qpdf/Pl_StdioFile.hh index d175d3c3..90190d2b 100644 --- a/include/qpdf/Pl_StdioFile.hh +++ b/include/qpdf/Pl_StdioFile.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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. // End-of-line pipeline that simply writes its data to a stdio FILE* object. @@ -35,8 +32,7 @@ class QPDF_DLL_CLASS Pl_StdioFile: public Pipeline { public: - // f is externally maintained; this class just writes to and - // flushes it. It does not close it. + // f is externally maintained; this class just writes to and flushes it. It does not close it. QPDF_DLL Pl_StdioFile(char const* identifier, FILE* f); QPDF_DLL diff --git a/include/qpdf/Pl_String.hh b/include/qpdf/Pl_String.hh index cd4ec0f4..8f712fbf 100644 --- a/include/qpdf/Pl_String.hh +++ b/include/qpdf/Pl_String.hh @@ -2,39 +2,34 @@ // // 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 +// 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. +// 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. +// 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 PL_STRING_HH #define PL_STRING_HH -// This pipeline accumulates the data passed to it into a std::string, -// a reference to which is passed in at construction. Each subsequent -// use of this pipeline appends to the data accumulated so far. +// This pipeline accumulates the data passed to it into a std::string, a reference to which is +// passed in at construction. Each subsequent use of this pipeline appends to the data accumulated +// so far. // -// For this pipeline, "next" may be null. If a next pointer is -// provided, this pipeline will also pass the data through to it and -// will forward finish() to it. +// For this pipeline, "next" may be null. If a next pointer is provided, this pipeline will also +// pass the data through to it and will forward finish() to it. // -// It is okay to not call finish() on this pipeline if it has no -// "next". This makes it easy to stick this in front of another -// pipeline to capture data that is written to the other pipeline -// without interfering with when finish is called on the other -// pipeline and without having to put a Pl_Concatenate after it. +// It is okay to not call finish() on this pipeline if it has no "next". This makes it easy to stick +// this in front of another pipeline to capture data that is written to the other pipeline without +// interfering with when finish is called on the other pipeline and without having to put a +// Pl_Concatenate after it. #include diff --git a/include/qpdf/QPDF.hh b/include/qpdf/QPDF.hh index 707899cd..152421ad 100644 --- a/include/qpdf/QPDF.hh +++ b/include/qpdf/QPDF.hh @@ -68,7 +68,7 @@ class QPDF // read until they are needed. A QPDF object may be associated with only one file in its // lifetime. This method must be called before any methods that potentially ask for information // about the PDF file are called. Prior to calling this, the only methods that are allowed are - // those that set parameters. If the input file is not encrypted,either a null password or an + // those that set parameters. If the input file is not encrypted, either a null password or an // empty password can be used. If the file is encrypted, either the user password or the owner // password may be supplied. The method setPasswordIsHexKey may be called prior to calling this // method or any of the other process methods to force the password to be interpreted as a raw diff --git a/include/qpdf/QPDFAnnotationObjectHelper.hh b/include/qpdf/QPDFAnnotationObjectHelper.hh index b3d57092..9da0fd39 100644 --- a/include/qpdf/QPDFAnnotationObjectHelper.hh +++ b/include/qpdf/QPDFAnnotationObjectHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFANNOTATIONOBJECTHELPER_HH #define QPDFANNOTATIONOBJECTHELPER_HH @@ -35,19 +32,16 @@ class QPDFAnnotationObjectHelper: public QPDFObjectHelper QPDF_DLL virtual ~QPDFAnnotationObjectHelper() = default; - // This class provides helper methods for annotations. More - // functionality will likely be added in the future. + // This class provides helper methods for annotations. More functionality will likely be added + // in the future. - // Some functionality for annotations is also implemented in - // QPDFAcroFormDocumentHelper and QPDFFormFieldObjectHelper. In - // some cases, functions defined there work for other annotations - // besides widget annotations, but they are implemented with form - // fields so that they can properly handle form fields when - // needed. + // Some functionality for annotations is also implemented in QPDFAcroFormDocumentHelper and + // QPDFFormFieldObjectHelper. In some cases, functions defined there work for other annotations + // besides widget annotations, but they are implemented with form fields so that they can + // properly handle form fields when needed. - // Return the subtype of the annotation as a string (e.g. - // "/Widget"). Returns the empty string if the subtype (which is - // required by the spec) is missing. + // Return the subtype of the annotation as a string (e.g. "/Widget"). Returns the empty string + // if the subtype (which is required by the spec) is missing. QPDF_DLL std::string getSubtype(); @@ -57,39 +51,32 @@ class QPDFAnnotationObjectHelper: public QPDFObjectHelper QPDF_DLL QPDFObjectHandle getAppearanceDictionary(); - // Return the appearance state as given in "/AS", or the empty - // string if none is given. + // Return the appearance state as given in "/AS", or the empty string if none is given. QPDF_DLL std::string getAppearanceState(); - // Return flags from "/F". The value is a logical or of - // pdf_annotation_flag_e as defined in qpdf/Constants.h. + // Return flags from "/F". The value is a logical or of pdf_annotation_flag_e as defined in + // qpdf/Constants.h. QPDF_DLL int getFlags(); - // Return a specific stream. "which" may be one of "/N", "/R", or - // "/D" to indicate the normal, rollover, or down appearance - // stream. (Any value may be passed to "which"; if an appearance - // stream of that name exists, it will be returned.) If the value - // associated with "which" in the appearance dictionary is a - // subdictionary, an appearance state may be specified to select - // which appearance stream is desired. If not specified, the - // appearance state in "/AS" will used. + // Return a specific stream. "which" may be one of "/N", "/R", or "/D" to indicate the normal, + // rollover, or down appearance stream. (Any value may be passed to "which"; if an appearance + // stream of that name exists, it will be returned.) If the value associated with "which" in the + // appearance dictionary is a subdictionary, an appearance state may be specified to select + // which appearance stream is desired. If not specified, the appearance state in "/AS" will + // used. QPDF_DLL QPDFObjectHandle getAppearanceStream(std::string const& which, std::string const& state = ""); - // Generate text suitable for addition to the containing page's - // content stream that draws this annotation's appearance stream - // as a form XObject. The value "name" is the resource name that - // will be used to refer to the form xobject. The value "rotate" - // should be set to the page's /Rotate value or 0 if none. The - // values of required_flags and forbidden_flags are constructed by - // logically "or"ing annotation flags of type - // pdf_annotation_flag_e defined in qpdf/Constants.h. Content will - // be returned only if all required_flags are set and no - // forbidden_flags are set. For example, including an_no_view in - // forbidden_flags could be useful for creating an on-screen view, - // and including an_print to required_flags could be useful if + // Generate text suitable for addition to the containing page's content stream that draws this + // annotation's appearance stream as a form XObject. The value "name" is the resource name that + // will be used to refer to the form xobject. The value "rotate" should be set to the page's + // /Rotate value or 0 if none. The values of required_flags and forbidden_flags are constructed + // by logically "or"ing annotation flags of type pdf_annotation_flag_e defined in + // qpdf/Constants.h. Content will be returned only if all required_flags are set and no + // forbidden_flags are set. For example, including an_no_view in forbidden_flags could be useful + // for creating an on-screen view, and including an_print to required_flags could be useful if // preparing to print. QPDF_DLL std::string getPageContentForAppearance( diff --git a/include/qpdf/QPDFCryptoProvider.hh b/include/qpdf/QPDFCryptoProvider.hh index 46a9379d..f1f7801c 100644 --- a/include/qpdf/QPDFCryptoProvider.hh +++ b/include/qpdf/QPDFCryptoProvider.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFCRYPTOPROVIDER_HH #define QPDFCRYPTOPROVIDER_HH @@ -30,35 +27,30 @@ #include #include -// This class is part of qpdf's pluggable crypto provider support. -// Most users won't need to know or care about this class, but you can -// use it if you want to supply your own crypto implementation. See -// also comments in QPDFCryptoImpl.hh. +// This class is part of qpdf's pluggable crypto provider support. Most users won't need to know or +// care about this class, but you can use it if you want to supply your own crypto implementation. +// See also comments in QPDFCryptoImpl.hh. class QPDFCryptoProvider { public: - // Methods for getting and registering crypto implementations. - // These methods are not thread-safe. + // Methods for getting and registering crypto implementations. These methods are not + // thread-safe. - // Return an instance of a crypto provider using the default - // implementation. + // Return an instance of a crypto provider using the default implementation. QPDF_DLL static std::shared_ptr getImpl(); - // Return an instance of the crypto provider registered using the - // given name. + // Return an instance of the crypto provider registered using the given name. QPDF_DLL static std::shared_ptr getImpl(std::string const& name); - // Register the given type (T) as a crypto implementation. T must - // be derived from QPDFCryptoImpl and must have a constructor that - // takes no arguments. + // Register the given type (T) as a crypto implementation. T must be derived from QPDFCryptoImpl + // and must have a constructor that takes no arguments. template QPDF_DLL static void registerImpl(std::string const& name); - // Set the crypto provider registered with the given name as the - // default crypto implementation. + // Set the crypto provider registered with the given name as the default crypto implementation. QPDF_DLL static void setDefaultProvider(std::string const& name); diff --git a/include/qpdf/QPDFDocumentHelper.hh b/include/qpdf/QPDFDocumentHelper.hh index dcdecf01..bb614843 100644 --- a/include/qpdf/QPDFDocumentHelper.hh +++ b/include/qpdf/QPDFDocumentHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFDOCUMENTHELPER_HH #define QPDFDOCUMENTHELPER_HH @@ -25,16 +22,13 @@ #include #include -// This is a base class for QPDF Document Helper classes. Document -// helpers are classes that provide a convenient, higher-level API for -// accessing document-level structures with a PDF file. Document -// helpers are always initialized with a reference to a QPDF object, -// and the object can always be retrieved. The intention is that you -// may freely intermix use of document helpers with the underlying -// QPDF object unless there is a specific comment in a specific helper -// method that says otherwise. The pattern of using helper objects was -// introduced to allow creation of higher level helper functions -// without polluting the public interface of QPDF. +// This is a base class for QPDF Document Helper classes. Document helpers are classes that provide +// a convenient, higher-level API for accessing document-level structures with a PDF file. Document +// helpers are always initialized with a reference to a QPDF object, and the object can always be +// retrieved. The intention is that you may freely intermix use of document helpers with the +// underlying QPDF object unless there is a specific comment in a specific helper method that says +// otherwise. The pattern of using helper objects was introduced to allow creation of higher level +// helper functions without polluting the public interface of QPDF. class QPDF_DLL_CLASS QPDFDocumentHelper { diff --git a/include/qpdf/QPDFEFStreamObjectHelper.hh b/include/qpdf/QPDFEFStreamObjectHelper.hh index b164dbe3..ab26b2c1 100644 --- a/include/qpdf/QPDFEFStreamObjectHelper.hh +++ b/include/qpdf/QPDFEFStreamObjectHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 @@ -29,9 +26,8 @@ #include #include -// 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. +// 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 { @@ -41,11 +37,10 @@ class QPDFEFStreamObjectHelper: public QPDFObjectHelper QPDF_DLL virtual ~QPDFEFStreamObjectHelper() = default; - // Date parameters are strings that conform to the PDF spec for - // date/time strings, which is "D:yyyymmddhhmmss" where 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. + // Date parameters are strings that conform to the PDF spec for date/time strings, which is + // "D:yyyymmddhhmmss" where 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(); @@ -57,32 +52,27 @@ class QPDFEFStreamObjectHelper: public QPDFObjectHelper // Subtype is a mime type such as "text/plain" QPDF_DLL std::string getSubtype(); - // Return the 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. The PDF spec specifies this as an MD5 - // checksum and notes that it is not to be used for security - // purposes since MD5 is known not to be secure. + // Return the 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. The PDF spec specifies + // this as an MD5 checksum and notes that it is not to be used for security purposes since MD5 + // is known not to be secure. QPDF_DLL std::string getChecksum(); - // Setters return a reference to this object so that they can be - // used as fluent interfaces, e.g. + // 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. + // 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, std::shared_ptr 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. + // 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 provider); @@ -93,8 +83,7 @@ class QPDFEFStreamObjectHelper: public QPDFObjectHelper QPDF_DLL QPDFEFStreamObjectHelper& setModDate(std::string const&); - // Set subtype as a mime-type, e.g. "text/plain" or - // "application/pdf". + // Set subtype as a mime-type, e.g. "text/plain" or "application/pdf". QPDF_DLL QPDFEFStreamObjectHelper& setSubtype(std::string const&); diff --git a/include/qpdf/QPDFEmbeddedFileDocumentHelper.hh b/include/qpdf/QPDFEmbeddedFileDocumentHelper.hh index 5ee608bd..4727feef 100644 --- a/include/qpdf/QPDFEmbeddedFileDocumentHelper.hh +++ b/include/qpdf/QPDFEmbeddedFileDocumentHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 @@ -32,9 +29,9 @@ #include #include -// 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. +// 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 { @@ -50,8 +47,8 @@ class QPDFEmbeddedFileDocumentHelper: public QPDFDocumentHelper QPDF_DLL std::map> getEmbeddedFiles(); - // If an embedded file with the given name exists, return a - // (shared) pointer to it. Otherwise, return nullptr. + // If an embedded file with the given name exists, return a (shared) pointer to it. Otherwise, + // return nullptr. QPDF_DLL std::shared_ptr getEmbeddedFile(std::string const& name); @@ -59,14 +56,11 @@ class QPDFEmbeddedFileDocumentHelper: public QPDFDocumentHelper 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. + // 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); diff --git a/include/qpdf/QPDFFileSpecObjectHelper.hh b/include/qpdf/QPDFFileSpecObjectHelper.hh index 040399bc..9b6474df 100644 --- a/include/qpdf/QPDFFileSpecObjectHelper.hh +++ b/include/qpdf/QPDFFileSpecObjectHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 @@ -29,9 +26,8 @@ #include #include -// This class provides a higher level interface around File -// Specification dictionaries, which are discussed in section 7.11 of -// the ISO-32000 PDF specification. +// 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 { @@ -44,45 +40,38 @@ class QPDFFileSpecObjectHelper: public QPDFObjectHelper QPDF_DLL std::string getDescription(); - // Get the main filename for this file specification. In priority - // order, check /UF, /F, /Unix, /DOS, /Mac. + // 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. + // Return any of /UF, /F, /Unix, /DOS, /Mac filename keys that may be present in the object. QPDF_DLL std::map 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. + // 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. + // 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. + // 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. + // 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 + // 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 @@ -90,11 +79,9 @@ class QPDFFileSpecObjectHelper: public QPDFObjectHelper 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. + // 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 = ""); diff --git a/include/qpdf/QPDFLogger.hh b/include/qpdf/QPDFLogger.hh index 2b7c7a9b..0b77d57a 100644 --- a/include/qpdf/QPDFLogger.hh +++ b/include/qpdf/QPDFLogger.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFLOGGER_HH #define QPDFLOGGER_HH @@ -33,18 +30,14 @@ class QPDFLogger QPDF_DLL static std::shared_ptr create(); - // Return the default logger. In general, you should use the - // default logger. You can also create your own loggers and use - // them QPDF and QPDFJob objects, but there are few reasons to do - // so. One reason may if you are using multiple QPDF or QPDFJob - // objects in different threads and want to capture output and - // errors to different streams. (Note that a single QPDF or - // QPDFJob can't be safely used from multiple threads, but it is - // safe to use separate QPDF and QPDFJob objects on separate - // threads.) Another possible reason would be if you are writing - // an application that uses the qpdf library directly and qpdf is - // also used by a downstream library or if you are using qpdf from - // a library and don't want to interfere with potential uses of + // Return the default logger. In general, you should use the default logger. You can also create + // your own loggers and use them QPDF and QPDFJob objects, but there are few reasons to do so. + // One reason may if you are using multiple QPDF or QPDFJob objects in different threads and + // want to capture output and errors to different streams. (Note that a single QPDF or QPDFJob + // can't be safely used from multiple threads, but it is safe to use separate QPDF and QPDFJob + // objects on separate threads.) Another possible reason would be if you are writing an + // application that uses the qpdf library directly and qpdf is also used by a downstream library + // or if you are using qpdf from a library and don't want to interfere with potential uses of // qpdf by other libraries or applications. QPDF_DLL static std::shared_ptr defaultLogger(); @@ -56,50 +49,40 @@ class QPDFLogger // error -- standard error // save -- undefined unless set // - // "info" is used for diagnostic messages, verbose messages, and - // progress messages. "warn" is used for warnings. "error" is used - // for errors. "save" is used for saving output -- see below. + // "info" is used for diagnostic messages, verbose messages, and progress messages. "warn" is + // used for warnings. "error" is used for errors. "save" is used for saving output -- see below. // - // On deletion, finish() is called for the standard output and - // standard error pipelines, which flushes output. If you supply - // any custom pipelines, you must call finish() on them yourself. - // Note that calling finish is not needed for string, stdio, or - // ostream pipelines. + // On deletion, finish() is called for the standard output and standard error pipelines, which + // flushes output. If you supply any custom pipelines, you must call finish() on them yourself. + // Note that calling finish is not needed for string, stdio, or ostream pipelines. // // NOTES ABOUT THE SAVE PIPELINE // - // The save pipeline is used by QPDFJob when some kind of binary - // output is being saved. This includes saving attachments and - // stream data and also includes when the output file is standard - // output. If you want to grab that output, you can call setSave. - // See examples/qpdfjob-save-attachment.cc and - // examples/qpdfjob-c-save-attachment.c. + // The save pipeline is used by QPDFJob when some kind of binary output is being saved. This + // includes saving attachments and stream data and also includes when the output file is + // standard output. If you want to grab that output, you can call setSave. See + // examples/qpdfjob-save-attachment.cc and examples/qpdfjob-c-save-attachment.c. // - // You should never set the save pipeline to the same destination - // as something else. Doing so will corrupt your save output. If - // you want to save to standard output, use the method - // saveToStandardOutput(). In addition to setting the save - // pipeline, that does the following extra things: + // You should never set the save pipeline to the same destination as something else. Doing so + // will corrupt your save output. If you want to save to standard output, use the method + // saveToStandardOutput(). In addition to setting the save pipeline, that does the following + // extra things: // // * If standard output has been used, a logic error is thrown - // * If info is set to standard output at the time of the set save - // call, it is switched to standard error. + // * If info is set to standard output at the time of the set save call, it is switched to + // standard error. // - // This is not a guarantee. You can still mess this up in ways - // that are not checked. Here are a few examples: + // This is not a guarantee. You can still mess this up in ways that are not checked. Here are a + // few examples: // - // * Don't set any pipeline to standard output *after* passing it - // to setSave() - // * Don't use a separate mechanism to write stdout/stderr other - // than QPDFLogger::standardOutput() - // * Don't set anything to the same custom pipeline that save is - // set to. + // * Don't set any pipeline to standard output *after* passing it to setSave() + // * Don't use a separate mechanism to write stdout/stderr other than + // QPDFLogger::standardOutput() + // * Don't set anything to the same custom pipeline that save is set to. // - // Just be sure that if you change pipelines around, you should - // avoid having the save pipeline also be used for any other - // purpose. The special case for saving to standard output allows - // you to call saveToStandardOutput() early without having to - // worry about the info pipeline. + // Just be sure that if you change pipelines around, you should avoid having the save pipeline + // also be used for any other purpose. The special case for saving to standard output allows you + // to call saveToStandardOutput() early without having to worry about the info pipeline. QPDF_DLL void info(char const*); @@ -145,9 +128,8 @@ class QPDFLogger QPDF_DLL void saveToStandardOutput(bool only_if_not_set); - // Shortcut for logic to reset output to new output/error streams. - // out_stream is used for info, err_stream is used for error, and - // warning is cleared so that it follows error. + // Shortcut for logic to reset output to new output/error streams. out_stream is used for info, + // err_stream is used for error, and warning is cleared so that it follows error. QPDF_DLL void setOutputStreams(std::ostream* out_stream, std::ostream* err_stream); diff --git a/include/qpdf/QPDFMatrix.hh b/include/qpdf/QPDFMatrix.hh index fb005e50..7abe6ec6 100644 --- a/include/qpdf/QPDFMatrix.hh +++ b/include/qpdf/QPDFMatrix.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFMATRIX_HH #define QPDFMATRIX_HH @@ -26,8 +23,7 @@ #include #include -// This class represents a PDF transformation matrix using a tuple -// such that +// This class represents a PDF transformation matrix using a tuple such that // // ┌ ┐ // │ a b 0 │ @@ -45,8 +41,7 @@ class QPDFMatrix QPDF_DLL QPDFMatrix(QPDFObjectHandle::Matrix const&); - // Returns the six values separated by spaces as real numbers with - // trimmed zeroes. + // Returns the six values separated by spaces as real numbers with trimmed zeroes. QPDF_DLL std::string unparse() const; @@ -75,14 +70,12 @@ class QPDFMatrix QPDF_DLL void transform(double x, double y, double& xp, double& yp) const; - // Transform a rectangle by creating a new rectangle that tightly - // bounds the polygon resulting from transforming the four - // corners. + // Transform a rectangle by creating a new rectangle that tightly bounds the polygon resulting + // from transforming the four corners. QPDF_DLL QPDFObjectHandle::Rectangle transformRectangle(QPDFObjectHandle::Rectangle r) const; - // operator== tests for exact equality, not considering deltas for - // floating point. + // operator== tests for exact equality, not considering deltas for floating point. QPDF_DLL bool operator==(QPDFMatrix const& rhs) const; QPDF_DLL diff --git a/include/qpdf/QPDFNameTreeObjectHelper.hh b/include/qpdf/QPDFNameTreeObjectHelper.hh index e0023013..9e59e1fb 100644 --- a/include/qpdf/QPDFNameTreeObjectHelper.hh +++ b/include/qpdf/QPDFNameTreeObjectHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFNAMETREEOBJECTHELPER_HH #define QPDFNAMETREEOBJECTHELPER_HH @@ -30,13 +27,11 @@ #include -// This is an object helper for name trees. See section 7.9.6 in the -// PDF spec (ISO 32000) for a description of name trees. When looking -// up items in the name tree, use UTF-8 strings. All names are -// normalized for lookup purposes. +// This is an object helper for name trees. See section 7.9.6 in the PDF spec (ISO 32000) for a +// description of name trees. When looking up items in the name tree, use UTF-8 strings. All names +// are normalized for lookup purposes. -// See examples/pdf-name-number-tree.cc for a demonstration of using -// QPDFNameTreeObjectHelper. +// See examples/pdf-name-number-tree.cc for a demonstration of using QPDFNameTreeObjectHelper. class NNTreeImpl; class NNTreeIterator; @@ -45,8 +40,8 @@ class NNTreeDetails; class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper { public: - // The qpdf object is required so that this class can issue - // warnings, attempt repairs, and add indirect objects. + // The qpdf object is required so that this class can issue warnings, attempt repairs, and add + // indirect objects. QPDF_DLL QPDFNameTreeObjectHelper(QPDFObjectHandle, QPDF&, bool auto_repair = true); @@ -57,13 +52,11 @@ class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper QPDF_DLL virtual ~QPDFNameTreeObjectHelper(); - // Return whether the number tree has an explicit entry for this - // number. + // Return whether the number tree has an explicit entry for this number. QPDF_DLL bool hasName(std::string const& utf8); - // Find an object by name. If found, returns true and initializes - // oh. See also find(). + // Find an object by name. If found, returns true and initializes oh. See also find(). QPDF_DLL bool findObject(std::string const& utf8, QPDFObjectHandle& oh); @@ -115,21 +108,17 @@ class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper return !operator==(other); } - // DANGER: this method can create inconsistent trees if not - // used properly! Insert a new item immediately after the - // current iterator and increment so that it points to the new - // item. If the current iterator is end(), insert at the - // beginning. This method does not check for proper ordering, - // so if you use it, you must ensure that the item you are - // inserting belongs where you are putting it. The reason for - // this method is that it is more efficient than insert() and - // can be used safely when you are creating a new tree and - // inserting items in sorted order. + // DANGER: this method can create inconsistent trees if not used properly! Insert a new item + // immediately after the current iterator and increment so that it points to the new item. + // If the current iterator is end(), insert at the beginning. This method does not check for + // proper ordering, so if you use it, you must ensure that the item you are inserting + // belongs where you are putting it. The reason for this method is that it is more efficient + // than insert() and can be used safely when you are creating a new tree and inserting items + // in sorted order. QPDF_DLL void insertAfter(std::string const& key, QPDFObjectHandle value); - // Remove the current item and advance the iterator to the - // next item. + // Remove the current item and advance the iterator to the next item. QPDF_DLL void remove(); @@ -141,10 +130,9 @@ class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper value_type ivalue; }; - // The iterator looks like map iterator, so i.first is a string - // and i.second is a QPDFObjectHandle. Incrementing end() brings - // you to the first item. Decrementing end() brings you to the - // last item. + // The iterator looks like map iterator, so i.first is a string and i.second is a + // QPDFObjectHandle. Incrementing end() brings you to the first item. Decrementing end() brings + // you to the last item. QPDF_DLL iterator begin() const; QPDF_DLL @@ -153,8 +141,8 @@ class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper QPDF_DLL iterator last() const; - // Find the entry with the given key. If return_prev_if_not_found - // is true and the item is not found, return the next lower item. + // Find the entry with the given key. If return_prev_if_not_found is true and the item is not + // found, return the next lower item. QPDF_DLL iterator find(std::string const& key, bool return_prev_if_not_found = false); @@ -162,20 +150,18 @@ class QPDF_DLL_CLASS QPDFNameTreeObjectHelper: public QPDFObjectHelper QPDF_DLL iterator insert(std::string const& key, QPDFObjectHandle value); - // Remove an item. Return true if the item was found and removed; - // otherwise return false. If value is not null, initialize it to - // the value that was removed. + // Remove an item. Return true if the item was found and removed; otherwise return false. If + // value is not null, initialize it to the value that was removed. QPDF_DLL bool remove(std::string const& key, QPDFObjectHandle* value = nullptr); - // Return the contents of the name tree as a map. Note that name - // trees may be very large, so this may use a lot of RAM. It is - // more efficient to use QPDFNameTreeObjectHelper's iterator. + // Return the contents of the name tree as a map. Note that name trees may be very large, so + // this may use a lot of RAM. It is more efficient to use QPDFNameTreeObjectHelper's iterator. QPDF_DLL std::map getAsMap() const; - // Split a node if the number of items exceeds this value. There's - // no real reason to ever set this except for testing. + // Split a node if the number of items exceeds this value. There's no real reason to ever set + // this except for testing. QPDF_DLL void setSplitThreshold(int); diff --git a/include/qpdf/QPDFNumberTreeObjectHelper.hh b/include/qpdf/QPDFNumberTreeObjectHelper.hh index 82933b21..f2a66026 100644 --- a/include/qpdf/QPDFNumberTreeObjectHelper.hh +++ b/include/qpdf/QPDFNumberTreeObjectHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFNUMBERTREEOBJECTHELPER_HH #define QPDFNUMBERTREEOBJECTHELPER_HH @@ -29,11 +26,10 @@ #include -// This is an object helper for number trees. See section 7.9.7 in the -// PDF spec (ISO 32000) for a description of number trees. +// This is an object helper for number trees. See section 7.9.7 in the PDF spec (ISO 32000) for a +// description of number trees. -// See examples/pdf-name-number-tree.cc for a demonstration of using -// QPDFNumberTreeObjectHelper. +// See examples/pdf-name-number-tree.cc for a demonstration of using QPDFNumberTreeObjectHelper. class NNTreeImpl; class NNTreeIterator; @@ -42,8 +38,8 @@ class NNTreeDetails; class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper { public: - // The qpdf object is required so that this class can issue - // warnings, attempt repairs, and add indirect objects. + // The qpdf object is required so that this class can issue warnings, attempt repairs, and add + // indirect objects. QPDF_DLL QPDFNumberTreeObjectHelper(QPDFObjectHandle, QPDF&, bool auto_repair = true); @@ -62,24 +58,20 @@ class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper QPDF_DLL numtree_number getMax(); - // Return whether the number tree has an explicit entry for this - // number. + // Return whether the number tree has an explicit entry for this number. QPDF_DLL bool hasIndex(numtree_number idx); - // Find an object with a specific index. If found, returns true - // and initializes oh. See also find(). + // Find an object with a specific index. If found, returns true and initializes oh. See also + // find(). QPDF_DLL bool findObject(numtree_number idx, QPDFObjectHandle& oh); - // Find the object at the index or, if not found, the object whose - // index is the highest index less than the requested index. If - // the requested index is less than the minimum, return false. - // Otherwise, return true, initialize oh to the object, and set - // offset to the difference between the requested index and the - // actual index. For example, if a number tree has values for 3 - // and 6 and idx is 5, this method would return true, initialize - // oh to the value with index 3, and set offset to 2 (5 - 3). See - // also find(). + // Find the object at the index or, if not found, the object whose index is the highest index + // less than the requested index. If the requested index is less than the minimum, return false. + // Otherwise, return true, initialize oh to the object, and set offset to the difference between + // the requested index and the actual index. For example, if a number tree has values for 3 and + // 6 and idx is 5, this method would return true, initialize oh to the value with index 3, and + // set offset to 2 (5 - 3). See also find(). QPDF_DLL bool findObjectAtOrBelow(numtree_number idx, QPDFObjectHandle& oh, numtree_number& offset); @@ -131,21 +123,17 @@ class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper return !operator==(other); } - // DANGER: this method can create inconsistent trees if not - // used properly! Insert a new item immediately after the - // current iterator and increment so that it points to the new - // item. If the current iterator is end(), insert at the - // beginning. This method does not check for proper ordering, - // so if you use it, you must ensure that the item you are - // inserting belongs where you are putting it. The reason for - // this method is that it is more efficient than insert() and - // can be used safely when you are creating a new tree and - // inserting items in sorted order. + // DANGER: this method can create inconsistent trees if not used properly! Insert a new item + // immediately after the current iterator and increment so that it points to the new item. + // If the current iterator is end(), insert at the beginning. This method does not check for + // proper ordering, so if you use it, you must ensure that the item you are inserting + // belongs where you are putting it. The reason for this method is that it is more efficient + // than insert() and can be used safely when you are creating a new tree and inserting items + // in sorted order. QPDF_DLL void insertAfter(numtree_number key, QPDFObjectHandle value); - // Remove the current item and advance the iterator to the - // next item. + // Remove the current item and advance the iterator to the next item. QPDF_DLL void remove(); @@ -157,10 +145,9 @@ class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper value_type ivalue; }; - // The iterator looks like map iterator, so i.first is a string - // and i.second is a QPDFObjectHandle. Incrementing end() brings - // you to the first item. Decrementing end() brings you to the - // last item. + // The iterator looks like map iterator, so i.first is a string and i.second is a + // QPDFObjectHandle. Incrementing end() brings you to the first item. Decrementing end() brings + // you to the last item. QPDF_DLL iterator begin() const; QPDF_DLL @@ -169,8 +156,8 @@ class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper QPDF_DLL iterator last() const; - // Find the entry with the given key. If return_prev_if_not_found - // is true and the item is not found, return the next lower item. + // Find the entry with the given key. If return_prev_if_not_found is true and the item is not + // found, return the next lower item. QPDF_DLL iterator find(numtree_number key, bool return_prev_if_not_found = false); @@ -178,22 +165,19 @@ class QPDF_DLL_CLASS QPDFNumberTreeObjectHelper: public QPDFObjectHelper QPDF_DLL iterator insert(numtree_number key, QPDFObjectHandle value); - // Remove an item. Return true if the item was found and removed; - // otherwise return false. If value is not null, initialize it to - // the value that was removed. + // Remove an item. Return true if the item was found and removed; otherwise return false. If + // value is not null, initialize it to the value that was removed. QPDF_DLL bool remove(numtree_number key, QPDFObjectHandle* value = nullptr); - // Return the contents of the number tree as a map. Note that - // number trees may be very large, so this may use a lot of RAM. - // It is more efficient to use QPDFNumberTreeObjectHelper's - // iterator. + // Return the contents of the number tree as a map. Note that number trees may be very large, so + // this may use a lot of RAM. It is more efficient to use QPDFNumberTreeObjectHelper's iterator. typedef std::map idx_map; QPDF_DLL idx_map getAsMap() const; - // Split a node if the number of items exceeds this value. There's - // no real reason to ever set this except for testing. + // Split a node if the number of items exceeds this value. There's no real reason to ever set + // this except for testing. QPDF_DLL void setSplitThreshold(int); diff --git a/include/qpdf/QPDFObjGen.hh b/include/qpdf/QPDFObjGen.hh index 851e8d11..0f22b481 100644 --- a/include/qpdf/QPDFObjGen.hh +++ b/include/qpdf/QPDFObjGen.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFOBJGEN_HH #define QPDFOBJGEN_HH @@ -29,8 +26,8 @@ class QPDFObjectHandle; class QPDFObjectHelper; -// This class represents an object ID and generation pair. It is -// suitable to use as a key in a map or set. +// This class represents an object ID and generation pair. It is suitable to use as a key in a map +// or set. class QPDFObjGen { @@ -91,13 +88,11 @@ class QPDFObjGen // Convenience class for loop detection when processing objects. // - // The class adds 'add' methods to a std::set which allows - // to test whether an QPDFObjGen is present in the set and to insert it in - // a single operation. The 'add' method is overloaded to take a QPDFObjGen, - // QPDFObjectHandle or an QPDFObjectHelper as parameter. + // The class adds 'add' methods to a std::set which allows to test whether an + // QPDFObjGen is present in the set and to insert it in a single operation. The 'add' method is + // overloaded to take a QPDFObjGen, QPDFObjectHandle or an QPDFObjectHelper as parameter. // - // The erase method is modified to ignore requests to erase - // QPDFObjGen(0, 0). + // The erase method is modified to ignore requests to erase QPDFObjGen(0, 0). // // Usage example: // @@ -112,8 +107,8 @@ class QPDFObjGen class QPDF_DLL_CLASS set: public std::set { public: - // Add 'og' to the set. Return false if 'og' is already present in - // the set. Attempts to insert QPDFObjGen(0, 0) are ignored. + // Add 'og' to the set. Return false if 'og' is already present in the set. Attempts to + // insert QPDFObjGen(0, 0) are ignored. QPDF_DLL bool add(QPDFObjGen og) @@ -150,9 +145,8 @@ class QPDFObjGen }; private: - // This class does not use the Members pattern to avoid a memory - // allocation for every one of these. A lot of these get created - // and destroyed. + // This class does not use the Members pattern to avoid a memory allocation for every one of + // these. A lot of these get created and destroyed. int obj{0}; int gen{0}; }; diff --git a/include/qpdf/QPDFObjectHelper.hh b/include/qpdf/QPDFObjectHelper.hh index e79eff9d..30853a74 100644 --- a/include/qpdf/QPDFObjectHelper.hh +++ b/include/qpdf/QPDFObjectHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFOBJECTHELPER_HH #define QPDFOBJECTHELPER_HH @@ -26,16 +23,13 @@ #include -// This is a base class for QPDF Object Helper classes. Object helpers -// are classes that provide a convenient, higher-level API for working -// with specific types of QPDF objects. Object helpers are always -// initialized with a QPDFObjectHandle, and the underlying object -// handle can always be retrieved. The intention is that you may -// freely intermix use of document helpers with the underlying QPDF -// objects unless there is a specific comment in a specific helper -// method that says otherwise. The pattern of using helper objects was -// introduced to allow creation of higher level helper functions -// without polluting the public interface of QPDFObjectHandle. +// This is a base class for QPDF Object Helper classes. Object helpers are classes that provide a +// convenient, higher-level API for working with specific types of QPDF objects. Object helpers are +// always initialized with a QPDFObjectHandle, and the underlying object handle can always be +// retrieved. The intention is that you may freely intermix use of document helpers with the +// underlying QPDF objects unless there is a specific comment in a specific helper method that says +// otherwise. The pattern of using helper objects was introduced to allow creation of higher level +// helper functions without polluting the public interface of QPDFObjectHandle. class QPDF_DLL_CLASS QPDFObjectHelper { diff --git a/include/qpdf/QPDFOutlineDocumentHelper.hh b/include/qpdf/QPDFOutlineDocumentHelper.hh index 38310302..23e4902c 100644 --- a/include/qpdf/QPDFOutlineDocumentHelper.hh +++ b/include/qpdf/QPDFOutlineDocumentHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFOUTLINEDOCUMENTHELPER_HH #define QPDFOUTLINEDOCUMENTHELPER_HH @@ -33,11 +30,10 @@ #include -// This is a document helper for outlines, also known as bookmarks. -// Outlines are discussed in section 12.3.3 of the PDF spec -// (ISO-32000). With the help of QPDFOutlineObjectHelper, the outlines -// tree is traversed, and a bidirectional map is made between pages -// and outlines. See also QPDFOutlineObjectHelper. +// This is a document helper for outlines, also known as bookmarks. Outlines are discussed in +// section 12.3.3 of the PDF spec (ISO-32000). With the help of QPDFOutlineObjectHelper, the +// outlines tree is traversed, and a bidirectional map is made between pages and outlines. See also +// QPDFOutlineObjectHelper. class QPDFOutlineDocumentHelper: public QPDFDocumentHelper { @@ -53,15 +49,13 @@ class QPDFOutlineDocumentHelper: public QPDFDocumentHelper QPDF_DLL std::vector getTopLevelOutlines(); - // If the name is a name object, look it up in the /Dests key of - // the document catalog. If the name is a string, look it up in - // the name tree pointed to by the /Dests key of the names + // If the name is a name object, look it up in the /Dests key of the document catalog. If the + // name is a string, look it up in the name tree pointed to by the /Dests key of the names // dictionary. QPDF_DLL QPDFObjectHandle resolveNamedDest(QPDFObjectHandle name); - // Return a list outlines that are known to target the specified - // page + // Return a list outlines that are known to target the specified page QPDF_DLL std::vector getOutlinesForPage(QPDFObjGen const&); diff --git a/include/qpdf/QPDFOutlineObjectHelper.hh b/include/qpdf/QPDFOutlineObjectHelper.hh index 0ecbdd54..8a0b10c9 100644 --- a/include/qpdf/QPDFOutlineObjectHelper.hh +++ b/include/qpdf/QPDFOutlineObjectHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFOUTLINEOBJECTHELPER_HH #define QPDFOUTLINEOBJECTHELPER_HH @@ -30,9 +27,8 @@ class QPDFOutlineDocumentHelper; #include -// This is an object helper for outline items. Outlines, also known as -// bookmarks, are described in section 12.3.3 of the PDF spec -// (ISO-32000). See comments below for details. +// This is an object helper for outline items. Outlines, also known as bookmarks, are described in +// section 12.3.3 of the PDF spec (ISO-32000). See comments below for details. class QPDFOutlineObjectHelper: public QPDFObjectHelper { @@ -40,16 +36,15 @@ class QPDFOutlineObjectHelper: public QPDFObjectHelper QPDF_DLL virtual ~QPDFOutlineObjectHelper() { - // This must be cleared explicitly to avoid circular references - // that prevent cleanup of pointer holders. + // This must be cleared explicitly to avoid circular references that prevent cleanup of + // pointer holders. m->parent = nullptr; } - // All constructors are private. You can only create one of these - // using QPDFOutlineDocumentHelper. + // All constructors are private. You can only create one of these using + // QPDFOutlineDocumentHelper. - // Return parent pointer. Returns a null pointer if this is a - // top-level outline. + // Return parent pointer. Returns a null pointer if this is a top-level outline. QPDF_DLL std::shared_ptr getParent(); @@ -57,29 +52,25 @@ class QPDFOutlineObjectHelper: public QPDFObjectHelper QPDF_DLL std::vector getKids(); - // Return the destination, regardless of whether it is named or - // explicit and whether it is directly provided or in a GoTo - // action. Returns a null object if the destination can't be - // determined. Named destinations can be resolved using the older - // root /Dest dictionary or the current names tree. + // Return the destination, regardless of whether it is named or explicit and whether it is + // directly provided or in a GoTo action. Returns a null object if the destination can't be + // determined. Named destinations can be resolved using the older root /Dest dictionary or the + // current names tree. QPDF_DLL QPDFObjectHandle getDest(); - // Return the page that the outline points to. Returns a null - // object if the destination page can't be determined. + // Return the page that the outline points to. Returns a null object if the destination page + // can't be determined. QPDF_DLL QPDFObjectHandle getDestPage(); - // Returns the value of /Count as present in the object, or 0 if - // not present. If count is positive, the outline is open. If - // negative, it is closed. Either way, the absolute value is the - // number descendant items that would be visible if this were - // open. + // Returns the value of /Count as present in the object, or 0 if not present. If count is + // positive, the outline is open. If negative, it is closed. Either way, the absolute value is + // the number descendant items that would be visible if this were open. QPDF_DLL int getCount(); - // Returns the title as a UTF-8 string. Returns the empty string - // if there is no title. + // Returns the title as a UTF-8 string. Returns the empty string if there is no title. QPDF_DLL std::string getTitle(); diff --git a/include/qpdf/QPDFPageDocumentHelper.hh b/include/qpdf/QPDFPageDocumentHelper.hh index 2cabbbb0..351a04f0 100644 --- a/include/qpdf/QPDFPageDocumentHelper.hh +++ b/include/qpdf/QPDFPageDocumentHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFPAGEDOCUMENTHELPER_HH #define QPDFPAGEDOCUMENTHELPER_HH @@ -42,67 +39,53 @@ class QPDFPageDocumentHelper: public QPDFDocumentHelper QPDF_DLL virtual ~QPDFPageDocumentHelper() = default; - // Traverse page tree, and return all /Page objects wrapped in - // QPDFPageObjectHelper objects. Unlike with - // QPDF::getAllPages, the vector of pages returned by - // this call is not affected by additions or removals of pages. If - // you manipulate pages, you will have to call this again to get a - // new copy. Please see comments in QPDF.hh for getAllPages() for - // additional details. + // Traverse page tree, and return all /Page objects wrapped in QPDFPageObjectHelper objects. + // Unlike with QPDF::getAllPages, the vector of pages returned by this call is not affected by + // additions or removals of pages. If you manipulate pages, you will have to call this again to + // get a new copy. Please see comments in QPDF.hh for getAllPages() for additional details. QPDF_DLL std::vector getAllPages(); - // The PDF /Pages tree allows inherited values. Working with the - // pages of a pdf is much easier when the inheritance is resolved - // by explicitly setting the values in each /Page. + // The PDF /Pages tree allows inherited values. Working with the pages of a pdf is much easier + // when the inheritance is resolved by explicitly setting the values in each /Page. QPDF_DLL void pushInheritedAttributesToPage(); - // This calls QPDFPageObjectHelper::removeUnreferencedResources - // for every page in the document. See comments in - // QPDFPageObjectHelper.hh for details. + // This calls QPDFPageObjectHelper::removeUnreferencedResources for every page in the document. + // See comments in QPDFPageObjectHelper.hh for details. QPDF_DLL void removeUnreferencedResources(); - // Add new page at the beginning or the end of the current pdf. - // The newpage parameter may be either a direct object, an - // indirect object from this QPDF, or an indirect object from - // another QPDF. If it is a direct object, it will be made - // indirect. If it is an indirect object from another QPDF, this - // method will call pushInheritedAttributesToPage on the other - // file and then copy the page to this QPDF using the same - // underlying code as copyForeignObject. At this stage, if the - // indirect object is already in the pages tree, a shallow copy is - // made to avoid adding the same page more than once. In version - // 10.3.1 and earlier, adding a page that already existed would - // throw an exception and could cause qpdf to crash on subsequent - // page insertions in some cases. Note that this means that, in - // some cases, the page actually added won't be exactly the same - // object as the one passed in. If you want to do subsequent + // Add new page at the beginning or the end of the current pdf. The newpage parameter may be + // either a direct object, an indirect object from this QPDF, or an indirect object from another + // QPDF. If it is a direct object, it will be made indirect. If it is an indirect object from + // another QPDF, this method will call pushInheritedAttributesToPage on the other file and then + // copy the page to this QPDF using the same underlying code as copyForeignObject. At this + // stage, if the indirect object is already in the pages tree, a shallow copy is made to avoid + // adding the same page more than once. In version 10.3.1 and earlier, adding a page that + // already existed would throw an exception and could cause qpdf to crash on subsequent page + // insertions in some cases. Note that this means that, in some cases, the page actually added + // won't be exactly the same object as the one passed in. If you want to do subsequent // modification on the page, you should retrieve it again. // - // Note that you can call copyForeignObject directly to copy a - // page from a different file, but the resulting object will not - // be a page in the new file. You could do this, for example, to - // convert a page into a form XObject, though for that, you're - // better off using QPDFPageObjectHelper::getFormXObjectForPage. + // Note that you can call copyForeignObject directly to copy a page from a different file, but + // the resulting object will not be a page in the new file. You could do this, for example, to + // convert a page into a form XObject, though for that, you're better off using + // QPDFPageObjectHelper::getFormXObjectForPage. // - // This method does not have any specific awareness of annotations - // or form fields, so if you just add a page without thinking - // about it, you might end up with two pages that share form - // fields or annotations. While the page may look fine, it will - // probably not function properly with regard to interactive - // features. To work around this, you should called - // QPDFAcroFormDocumentHelper::fixCopiedAnnotations. A future - // version of qpdf will likely provide a higher-level interface - // for copying pages around that will handle document-level + // This method does not have any specific awareness of annotations or form fields, so if you + // just add a page without thinking about it, you might end up with two pages that share form + // fields or annotations. While the page may look fine, it will probably not function properly + // with regard to interactive features. To work around this, you should called + // QPDFAcroFormDocumentHelper::fixCopiedAnnotations. A future version of qpdf will likely + // provide a higher-level interface for copying pages around that will handle document-level // constructs in a less error-prone fashion. QPDF_DLL void addPage(QPDFPageObjectHelper newpage, bool first); - // Add new page before or after refpage. See comments for addPage - // for details about what newpage should be. + // Add new page before or after refpage. See comments for addPage for details about what newpage + // should be. QPDF_DLL void addPageAt(QPDFPageObjectHelper newpage, bool before, QPDFPageObjectHelper refpage); @@ -110,17 +93,13 @@ class QPDFPageDocumentHelper: public QPDFDocumentHelper QPDF_DLL void removePage(QPDFPageObjectHelper page); - // For every annotation, integrate the annotation's appearance - // stream into the containing page's content streams, merge the - // annotation's resources with the page's resources, and remove - // the annotation from the page. Handles widget annotations - // associated with interactive form fields as a special case, - // including removing the /AcroForm key from the document catalog. - // The values passed to required_flags and forbidden_flags are - // passed along to - // QPDFAnnotationObjectHelper::getPageContentForAppearance. See - // comments there in QPDFAnnotationObjectHelper.hh for meanings of - // those flags. + // For every annotation, integrate the annotation's appearance stream into the containing page's + // content streams, merge the annotation's resources with the page's resources, and remove the + // annotation from the page. Handles widget annotations associated with interactive form fields + // as a special case, including removing the /AcroForm key from the document catalog. The values + // passed to required_flags and forbidden_flags are passed along to + // QPDFAnnotationObjectHelper::getPageContentForAppearance. See comments there in + // QPDFAnnotationObjectHelper.hh for meanings of those flags. QPDF_DLL void flattenAnnotations(int required_flags = 0, int forbidden_flags = an_invisible | an_hidden); diff --git a/include/qpdf/QPDFPageLabelDocumentHelper.hh b/include/qpdf/QPDFPageLabelDocumentHelper.hh index dbb0a07e..64e85869 100644 --- a/include/qpdf/QPDFPageLabelDocumentHelper.hh +++ b/include/qpdf/QPDFPageLabelDocumentHelper.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFPAGELABELDOCUMENTHELPER_HH #define QPDFPAGELABELDOCUMENTHELPER_HH @@ -30,18 +27,15 @@ #include -// Page labels are discussed in the PDF spec (ISO-32000) in section -// 12.4.2. +// Page labels are discussed in the PDF spec (ISO-32000) in section 12.4.2. // -// Page labels are implemented as a number tree. Each key is a page -// index, numbered from 0. The values are dictionaries with the -// following keys, all optional: +// Page labels are implemented as a number tree. Each key is a page index, numbered from 0. The +// values are dictionaries with the following keys, all optional: // // * /Type: if present, must be /PageLabel -// * /S: one of /D, /R, /r, /A, or /a for decimal, upper-case and -// lower-case Roman numeral, or upper-case and lower-case alphabetic -// * /P: if present, a fixed prefix string that is prepended to each -// page number +// * /S: one of /D, /R, /r, /A, or /a for decimal, upper-case and lower-case Roman numeral, or +// upper-case and lower-case alphabetic +// * /P: if present, a fixed prefix string that is prepended to each page number // * /St: the starting number, or 1 if not specified class QPDFPageLabelDocumentHelper: public QPDFDocumentHelper @@ -55,25 +49,20 @@ class QPDFPageLabelDocumentHelper: public QPDFDocumentHelper QPDF_DLL bool hasPageLabels(); - // Return a page label dictionary representing the page label for - // the given page. The page does not need to appear explicitly in - // the page label dictionary. This method will adjust /St as + // Return a page label dictionary representing the page label for the given page. The page does + // not need to appear explicitly in the page label dictionary. This method will adjust /St as // needed to produce a label that is suitable for the page. QPDF_DLL QPDFObjectHandle getLabelForPage(long long page_idx); - // Append to the incoming vector a list of objects suitable for - // inclusion in a /PageLabels dictionary's /Nums field. start_idx - // and end_idx are the indexes to the starting and ending pages - // (inclusive) in the original file, and new_start_idx is the - // index to the first page in the new file. For example, if pages - // 10 through 12 of one file are being copied to a new file as - // pages 6 through 8, you would call getLabelsForPageRange(10, 12, - // 6), which would return as many entries as are required to add - // to the new file's PageLabels. This method fabricates a suitable - // entry even if the original document has no page labels. This - // behavior facilitates using this function to incrementally build - // up a page labels tree when merging files. + // Append to the incoming vector a list of objects suitable for inclusion in a /PageLabels + // dictionary's /Nums field. start_idx and end_idx are the indexes to the starting and ending + // pages (inclusive) in the original file, and new_start_idx is the index to the first page in + // the new file. For example, if pages 10 through 12 of one file are being copied to a new file + // as pages 6 through 8, you would call getLabelsForPageRange(10, 12, 6), which would return as + // many entries as are required to add to the new file's PageLabels. This method fabricates a + // suitable entry even if the original document has no page labels. This behavior facilitates + // using this function to incrementally build up a page labels tree when merging files. QPDF_DLL void getLabelsForPageRange( long long start_idx, diff --git a/include/qpdf/QPDFStreamFilter.hh b/include/qpdf/QPDFStreamFilter.hh index fec12851..4664f213 100644 --- a/include/qpdf/QPDFStreamFilter.hh +++ b/include/qpdf/QPDFStreamFilter.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFSTREAMFILTER_HH #define QPDFSTREAMFILTER_HH @@ -35,36 +32,29 @@ class QPDF_DLL_CLASS QPDFStreamFilter QPDF_DLL virtual ~QPDFStreamFilter() = default; - // A QPDFStreamFilter class must implement, at a minimum, - // setDecodeParms() and getDecodePipeline(). QPDF will always call - // setDecodeParms() before calling getDecodePipeline(). It is - // expected that you will store any needed information from - // decode_parms (or the decode_parms object itself) in your - // instance so that it can be used to construct the decode - // pipeline. + // A QPDFStreamFilter class must implement, at a minimum, setDecodeParms() and + // getDecodePipeline(). QPDF will always call setDecodeParms() before calling + // getDecodePipeline(). It is expected that you will store any needed information from + // decode_parms (or the decode_parms object itself) in your instance so that it can be used to + // construct the decode pipeline. - // Return a boolean indicating whether your filter can proceed - // with the given /DecodeParms. The default implementation accepts - // a null object and rejects everything else. + // Return a boolean indicating whether your filter can proceed with the given /DecodeParms. The + // default implementation accepts a null object and rejects everything else. QPDF_DLL virtual bool setDecodeParms(QPDFObjectHandle decode_parms); - // Return a pipeline that will decode data encoded with your - // filter. Your implementation must ensure that the pipeline is - // deleted when the instance of your class is destroyed. + // Return a pipeline that will decode data encoded with your filter. Your implementation must + // ensure that the pipeline is deleted when the instance of your class is destroyed. QPDF_DLL virtual Pipeline* getDecodePipeline(Pipeline* next) = 0; - // If your filter implements "specialized" compression or lossy - // compression, override one or both of these methods. The default - // implementations return false. See comments in QPDFWriter for - // details. QPDF defines specialized compression as non-lossy - // compression not intended for general-purpose data. qpdf, by - // default, doesn't mess with streams that are compressed with - // specialized compression, the idea being that the decision to - // use that compression scheme would fall outside of what - // QPDFWriter would know anything about, so any attempt to decode - // and re-encode would probably be undesirable. + // If your filter implements "specialized" compression or lossy compression, override one or + // both of these methods. The default implementations return false. See comments in QPDFWriter + // for details. QPDF defines specialized compression as non-lossy compression not intended for + // general-purpose data. qpdf, by default, doesn't mess with streams that are compressed with + // specialized compression, the idea being that the decision to use that compression scheme + // would fall outside of what QPDFWriter would know anything about, so any attempt to decode and + // re-encode would probably be undesirable. QPDF_DLL virtual bool isSpecializedCompression(); QPDF_DLL diff --git a/include/qpdf/QPDFSystemError.hh b/include/qpdf/QPDFSystemError.hh index fe75b272..7833b070 100644 --- a/include/qpdf/QPDFSystemError.hh +++ b/include/qpdf/QPDFSystemError.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFSYSTEMERROR_HH #define QPDFSYSTEMERROR_HH @@ -37,9 +34,8 @@ class QPDF_DLL_CLASS QPDFSystemError: public std::runtime_error QPDF_DLL virtual ~QPDFSystemError() noexcept = default; - // To get a complete error string, call what(), provided by - // std::exception. The accessors below return the original values - // used to create the exception. + // To get a complete error string, call what(), provided by std::exception. The accessors below + // return the original values used to create the exception. QPDF_DLL std::string const& getDescription() const; @@ -50,8 +46,8 @@ class QPDF_DLL_CLASS QPDFSystemError: public std::runtime_error QPDF_DLL_PRIVATE static std::string createWhat(std::string const& description, int system_errno); - // This class does not use the Members pattern to avoid needless - // memory allocations during exception handling. + // This class does not use the Members pattern to avoid needless memory allocations during + // exception handling. std::string description; int system_errno; diff --git a/include/qpdf/QPDFUsage.hh b/include/qpdf/QPDFUsage.hh index e1cadc10..538392a0 100644 --- a/include/qpdf/QPDFUsage.hh +++ b/include/qpdf/QPDFUsage.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFUSAGE_HH #define QPDFUSAGE_HH diff --git a/include/qpdf/QPDFWriter.hh b/include/qpdf/QPDFWriter.hh index d14d907f..63fba056 100644 --- a/include/qpdf/QPDFWriter.hh +++ b/include/qpdf/QPDFWriter.hh @@ -2,26 +2,22 @@ // // 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 +// 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. +// 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. +// 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. -// This class implements a simple writer for saving QPDF objects to -// new PDF files. See comments through the header file for additional -// details. +// This class implements a simple writer for saving QPDF objects to new PDF files. See comments +// through the header file for additional details. #ifndef QPDFWRITER_HH #define QPDFWRITER_HH @@ -57,21 +53,19 @@ class Pl_MD5; class QPDFWriter { public: - // Construct a QPDFWriter object without specifying output. You - // must call one of the output setting routines defined below. + // Construct a QPDFWriter object without specifying output. You must call one of the output + // setting routines defined below. QPDF_DLL QPDFWriter(QPDF& pdf); - // Create a QPDFWriter object that writes its output to a file or - // to stdout. This is equivalent to using the previous - // constructor and then calling setOutputFilename(). See + // Create a QPDFWriter object that writes its output to a file or to stdout. This is equivalent + // to using the previous constructor and then calling setOutputFilename(). See // setOutputFilename() for details. QPDF_DLL QPDFWriter(QPDF& pdf, char const* filename); - // Create a QPDFWriter object that writes its output to an already - // open FILE*. This is equivalent to calling the first - // constructor and then calling setOutputFile(). See + // Create a QPDFWriter object that writes its output to an already open FILE*. This is + // equivalent to calling the first constructor and then calling setOutputFile(). See // setOutputFile() for details. QPDF_DLL QPDFWriter(QPDF& pdf, char const* description, FILE* file, bool close_file); @@ -85,15 +79,13 @@ class QPDFWriter QPDF_DLL virtual ~ProgressReporter(); - // This method is called with a value from 0 to 100 to - // indicate approximate progress through the write process. - // See registerProgressReporter. + // This method is called with a value from 0 to 100 to indicate approximate progress through + // the write process. See registerProgressReporter. virtual void reportProgress(int) = 0; }; - // This is a progress reporter that takes a function. It is used - // by the C APIs, but it is available if you want to just register - // a C function as a handler. + // This is a progress reporter that takes a function. It is used by the C APIs, but it is + // available if you want to just register a C function as a handler. class QPDF_DLL_CLASS FunctionProgressReporter: public ProgressReporter { public: @@ -108,39 +100,31 @@ class QPDFWriter std::function handler; }; - // Setting Output. Output may be set only one time. If you don't - // use the filename version of the QPDFWriter constructor, you - // must call exactly one of these methods. + // Setting Output. Output may be set only one time. If you don't use the filename version of + // the QPDFWriter constructor, you must call exactly one of these methods. - // Passing null as filename means write to stdout. QPDFWriter - // will create a zero-length output file upon construction. If - // write fails, the empty or partially written file will not be - // deleted. This is by design: sometimes the partial file may be - // useful for tracking down problems. If your application doesn't - // want the partially written file to be left behind, you should - // delete it the eventual call to write fails. + // Passing null as filename means write to stdout. QPDFWriter will create a zero-length output + // file upon construction. If write fails, the empty or partially written file will not be + // deleted. This is by design: sometimes the partial file may be useful for tracking down + // problems. If your application doesn't want the partially written file to be left behind, you + // should delete it the eventual call to write fails. QPDF_DLL void setOutputFilename(char const* filename); - // Write to the given FILE*, which must be opened by the caller. - // If close_file is true, QPDFWriter will close the file. - // Otherwise, the caller must close the file. The file does not - // need to be seekable; it will be written to in a single pass. - // It must be open in binary mode. + // Write to the given FILE*, which must be opened by the caller. If close_file is true, + // QPDFWriter will close the file. Otherwise, the caller must close the file. The file does not + // need to be seekable; it will be written to in a single pass. It must be open in binary mode. QPDF_DLL void setOutputFile(char const* description, FILE* file, bool close_file); - // Indicate that QPDFWriter should create a memory buffer to - // contain the final PDF file. Obtain the memory by calling - // getBuffer(). + // Indicate that QPDFWriter should create a memory buffer to contain the final PDF file. Obtain + // the memory by calling getBuffer(). QPDF_DLL void setOutputMemory(); - // Return the buffer object containing the PDF file. If - // setOutputMemory() has been called, this method may be called - // exactly one time after write() has returned. The caller is - // responsible for deleting the buffer when done. See also - // getBufferSharedPointer(). + // Return the buffer object containing the PDF file. If setOutputMemory() has been called, this + // method may be called exactly one time after write() has returned. The caller is responsible + // for deleting the buffer when done. See also getBufferSharedPointer(). QPDF_DLL Buffer* getBuffer(); @@ -148,33 +132,27 @@ class QPDFWriter QPDF_DLL std::shared_ptr getBufferSharedPointer(); - // Supply your own pipeline object. Output will be written to - // this pipeline, and QPDFWriter will call finish() on the - // pipeline. It is the caller's responsibility to manage the - // memory for the pipeline. The pipeline is never deleted by - // QPDFWriter, which makes it possible for you to call additional - // methods on the pipeline after the writing is finished. + // Supply your own pipeline object. Output will be written to this pipeline, and QPDFWriter + // will call finish() on the pipeline. It is the caller's responsibility to manage the memory + // for the pipeline. The pipeline is never deleted by QPDFWriter, which makes it possible for + // you to call additional methods on the pipeline after the writing is finished. QPDF_DLL void setOutputPipeline(Pipeline*); // Setting Parameters - // Set the value of object stream mode. In disable mode, we never - // generate any object streams. In preserve mode, we preserve - // object stream structure from the original file. In generate - // mode, we generate our own object streams. In all cases, we - // generate a conventional cross-reference table if there are no - // object streams and a cross-reference stream if there are object - // streams. The default is o_preserve. + // Set the value of object stream mode. In disable mode, we never generate any object streams. + // In preserve mode, we preserve object stream structure from the original file. In generate + // mode, we generate our own object streams. In all cases, we generate a conventional + // cross-reference table if there are no object streams and a cross-reference stream if there + // are object streams. The default is o_preserve. QPDF_DLL void setObjectStreamMode(qpdf_object_stream_e); - // Set value of stream data mode. This is an older interface. - // Instead of using this, prefer setCompressStreams() and - // setDecodeLevel(). This method is retained for compatibility, - // but it does not cover the full range of available - // configurations. The mapping between this and the new methods is - // as follows: + // Set value of stream data mode. This is an older interface. Instead of using this, prefer + // setCompressStreams() and setDecodeLevel(). This method is retained for compatibility, but it + // does not cover the full range of available configurations. The mapping between this and the + // new methods is as follows: // // qpdf_s_uncompress: // setCompressStreams(false) @@ -190,205 +168,161 @@ class QPDFWriter QPDF_DLL void setStreamDataMode(qpdf_stream_data_e); - // If true, compress any uncompressed streams when writing them. - // Metadata streams are a special case and are not compressed even - // if this is true. This is true by default for QPDFWriter. If you - // want QPDFWriter to leave uncompressed streams uncompressed, - // pass false to this method. + // If true, compress any uncompressed streams when writing them. Metadata streams are a special + // case and are not compressed even if this is true. This is true by default for QPDFWriter. If + // you want QPDFWriter to leave uncompressed streams uncompressed, pass false to this method. QPDF_DLL void setCompressStreams(bool); - // When QPDFWriter encounters streams, this parameter controls the - // behavior with respect to attempting to apply any filters to the - // streams when copying to the output. The decode levels are as - // follows: + // When QPDFWriter encounters streams, this parameter controls the behavior with respect to + // attempting to apply any filters to the streams when copying to the output. The decode levels + // are as follows: // - // qpdf_dl_none: Do not attempt to apply any filters. Streams - // remain as they appear in the original file. Note that - // uncompressed streams may still be compressed on output. You can + // qpdf_dl_none: Do not attempt to apply any filters. Streams remain as they appear in the + // original file. Note that uncompressed streams may still be compressed on output. You can // disable that by calling setCompressStreams(false). // - // qpdf_dl_generalized: This is the default. QPDFWriter will apply - // LZWDecode, ASCII85Decode, ASCIIHexDecode, and FlateDecode - // filters on the input. When combined with - // setCompressStreams(true), which the default, the effect of this - // is that streams filtered with these older and less efficient - // filters will be recompressed with the Flate filter. By default, - // as a special case, if a stream is already compressed with - // FlateDecode and setCompressStreams is enabled, the original - // compressed data will be preserved. This behavior can be - // overridden by calling setRecompressFlate(true). + // qpdf_dl_generalized: This is the default. QPDFWriter will apply LZWDecode, ASCII85Decode, + // ASCIIHexDecode, and FlateDecode filters on the input. When combined with + // setCompressStreams(true), which the default, the effect of this is that streams filtered with + // these older and less efficient filters will be recompressed with the Flate filter. By + // default, as a special case, if a stream is already compressed with FlateDecode and + // setCompressStreams is enabled, the original compressed data will be preserved. This behavior + // can be overridden by calling setRecompressFlate(true). // - // qpdf_dl_specialized: In addition to uncompressing the - // generalized compression formats, supported non-lossy - // compression will also be decoded. At present, this includes - // the RunLengthDecode filter. + // qpdf_dl_specialized: In addition to uncompressing the generalized compression formats, + // supported non-lossy compression will also be decoded. At present, this includes the + // RunLengthDecode filter. // - // qpdf_dl_all: In addition to generalized and non-lossy - // specialized filters, supported lossy compression filters will - // be applied. At present, this includes DCTDecode (JPEG) - // compression. Note that compressing the resulting data with - // DCTDecode again will accumulate loss, so avoid multiple - // compression and decompression cycles. This is mostly useful for - // retrieving image data. + // qpdf_dl_all: In addition to generalized and non-lossy specialized filters, supported lossy + // compression filters will be applied. At present, this includes DCTDecode (JPEG) compression. + // Note that compressing the resulting data with DCTDecode again will accumulate loss, so avoid + // multiple compression and decompression cycles. This is mostly useful for retrieving image + // data. QPDF_DLL void setDecodeLevel(qpdf_stream_decode_level_e); - // By default, when both the input and output contents of a stream - // are compressed with Flate, qpdf does not uncompress and - // recompress the stream. Passing true here causes it to do so. - // This can be useful if recompressing all streams with a higher - // compression level, which can be set by calling the static - // method Pl_Flate::setCompressionLevel. + // By default, when both the input and output contents of a stream are compressed with Flate, + // qpdf does not uncompress and recompress the stream. Passing true here causes it to do so. + // This can be useful if recompressing all streams with a higher compression level, which can be + // set by calling the static method Pl_Flate::setCompressionLevel. QPDF_DLL void setRecompressFlate(bool); - // Set value of content stream normalization. The default is - // "false". If true, we attempt to normalize newlines inside of - // content streams. Some constructs such as inline images may - // thwart our efforts. There may be some cases where this can - // damage the content stream. This flag should be used only for - // debugging and experimenting with PDF content streams. Never - // use it for production files. + // Set value of content stream normalization. The default is "false". If true, we attempt to + // normalize newlines inside of content streams. Some constructs such as inline images may + // thwart our efforts. There may be some cases where this can damage the content stream. This + // flag should be used only for debugging and experimenting with PDF content streams. Never use + // it for production files. QPDF_DLL void setContentNormalization(bool); - // Set QDF mode. QDF mode causes special "pretty printing" of - // PDF objects, adds comments for easier perusing of files. - // Resulting PDF files can be edited in a text editor and then run - // through fix-qdf to update cross reference tables and stream - // lengths. + // Set QDF mode. QDF mode causes special "pretty printing" of PDF objects, adds comments for + // easier perusing of files. Resulting PDF files can be edited in a text editor and then run + // through fix-qdf to update cross reference tables and stream lengths. QPDF_DLL void setQDFMode(bool); - // Preserve unreferenced objects. The default behavior is to - // discard any object that is not visited during a traversal of - // the object structure from the trailer. + // Preserve unreferenced objects. The default behavior is to discard any object that is not + // visited during a traversal of the object structure from the trailer. QPDF_DLL void setPreserveUnreferencedObjects(bool); - // Always write a newline before the endstream keyword. This helps - // with PDF/A compliance, though it is not sufficient for it. + // Always write a newline before the endstream keyword. This helps with PDF/A compliance, though + // it is not sufficient for it. QPDF_DLL void setNewlineBeforeEndstream(bool); - // Set the minimum PDF version. If the PDF version of the input - // file (or previously set minimum version) is less than the - // version passed to this method, the PDF version of the output - // file will be set to this value. If the original PDF file's - // version or previously set minimum version is already this - // version or later, the original file's version will be used. - // QPDFWriter automatically sets the minimum version to 1.4 when - // R3 encryption parameters are used, and to 1.5 when object - // streams are used. + // Set the minimum PDF version. If the PDF version of the input file (or previously set minimum + // version) is less than the version passed to this method, the PDF version of the output file + // will be set to this value. If the original PDF file's version or previously set minimum + // version is already this version or later, the original file's version will be used. + // QPDFWriter automatically sets the minimum version to 1.4 when R3 encryption parameters are + // used, and to 1.5 when object streams are used. QPDF_DLL void setMinimumPDFVersion(std::string const&, int extension_level = 0); QPDF_DLL void setMinimumPDFVersion(PDFVersion const&); - // Force the PDF version of the output file to be a given version. - // Use of this function may create PDF files that will not work - // properly with older PDF viewers. When a PDF version is set - // using this function, qpdf will use this version even if the - // file contains features that are not supported in that version - // of PDF. In other words, you should only use this function if - // you are sure the PDF file in question has no features of newer - // versions of PDF or if you are willing to create files that old - // viewers may try to open but not be able to properly interpret. - // If any encryption has been applied to the document either - // explicitly or by preserving the encryption of the source - // document, forcing the PDF version to a value too low to support - // that type of encryption will explicitly disable decryption. - // Additionally, forcing to a version below 1.5 will disable - // object streams. + // Force the PDF version of the output file to be a given version. Use of this function may + // create PDF files that will not work properly with older PDF viewers. When a PDF version is + // set using this function, qpdf will use this version even if the file contains features that + // are not supported in that version of PDF. In other words, you should only use this function + // if you are sure the PDF file in question has no features of newer versions of PDF or if you + // are willing to create files that old viewers may try to open but not be able to properly + // interpret. If any encryption has been applied to the document either explicitly or by + // preserving the encryption of the source document, forcing the PDF version to a value too low + // to support that type of encryption will explicitly disable decryption. Additionally, forcing + // to a version below 1.5 will disable object streams. QPDF_DLL void forcePDFVersion(std::string const&, int extension_level = 0); - // Provide additional text to insert in the PDF file somewhere - // near the beginning of the file. This can be used to add - // comments to the beginning of a PDF file, for example, if those - // comments are to be consumed by some other application. No - // checks are performed to ensure that the text inserted here is - // valid PDF. If you want to insert multiline comments, you will - // need to include \n in the string yourself and start each line - // with %. An extra newline will be appended if one is not - // already present at the end of your text. + // Provide additional text to insert in the PDF file somewhere near the beginning of the file. + // This can be used to add comments to the beginning of a PDF file, for example, if those + // comments are to be consumed by some other application. No checks are performed to ensure + // that the text inserted here is valid PDF. If you want to insert multiline comments, you will + // need to include \n in the string yourself and start each line with %. An extra newline will + // be appended if one is not already present at the end of your text. QPDF_DLL void setExtraHeaderText(std::string const&); - // Causes a deterministic /ID value to be generated. When this is - // set, the current time and output file name are not used as part - // of /ID generation. Instead, a digest of all significant parts - // of the output file's contents is included in the /ID - // calculation. Use of a deterministic /ID can be handy when it is - // desirable for a repeat of the same qpdf operation on the same - // inputs being written to the same outputs with the same - // parameters to generate exactly the same results. This feature - // is incompatible with encrypted files because, for encrypted - // files, the /ID is generated before any part of the file is - // written since it is an input to the encryption process. + // Causes a deterministic /ID value to be generated. When this is set, the current time and + // output file name are not used as part of /ID generation. Instead, a digest of all significant + // parts of the output file's contents is included in the /ID calculation. Use of a + // deterministic /ID can be handy when it is desirable for a repeat of the same qpdf operation + // on the same inputs being written to the same outputs with the same parameters to generate + // exactly the same results. This feature is incompatible with encrypted files because, for + // encrypted files, the /ID is generated before any part of the file is written since it is an + // input to the encryption process. QPDF_DLL void setDeterministicID(bool); - // Cause a static /ID value to be generated. Use only in test - // suites. See also setDeterministicID. + // Cause a static /ID value to be generated. Use only in test suites. See also + // setDeterministicID. QPDF_DLL void setStaticID(bool); - // Use a fixed initialization vector for AES-CBC encryption. This - // is not secure. It should be used only in test suites for - // creating predictable encrypted output. + // Use a fixed initialization vector for AES-CBC encryption. This is not secure. It should be + // used only in test suites for creating predictable encrypted output. QPDF_DLL void setStaticAesIV(bool); - // Suppress inclusion of comments indicating original object IDs - // when writing QDF files. This can also be useful for testing, - // particularly when using comparison of two qdf files to + // Suppress inclusion of comments indicating original object IDs when writing QDF files. This + // can also be useful for testing, particularly when using comparison of two qdf files to // determine whether two PDF files have identical content. QPDF_DLL void setSuppressOriginalObjectIDs(bool); - // Preserve encryption. The default is true unless prefilering, - // content normalization, or qdf mode has been selected in which - // case encryption is never preserved. Encryption is also not + // Preserve encryption. The default is true unless prefilering, content normalization, or qdf + // mode has been selected in which case encryption is never preserved. Encryption is also not // preserved if we explicitly set encryption parameters. QPDF_DLL void setPreserveEncryption(bool); - // Copy encryption parameters from another QPDF object. If you - // want to copy encryption from the object you are writing, call - // setPreserveEncryption(true) instead. + // Copy encryption parameters from another QPDF object. If you want to copy encryption from the + // object you are writing, call setPreserveEncryption(true) instead. QPDF_DLL void copyEncryptionParameters(QPDF&); - // Set up for encrypted output. User and owner password both must - // be specified. Either or both may be the empty string. Note - // that qpdf does not apply any special treatment to the empty - // string, which makes it possible to create encrypted files with - // empty owner passwords and non-empty user passwords or with the - // same password for both user and owner. Some PDF reading - // products don't handle such files very well. Enabling - // encryption disables stream prefiltering and content - // normalization. Note that setting R2 encryption parameters sets - // the PDF version to at least 1.3, setting R3 encryption - // parameters pushes the PDF version number to at least 1.4, - // setting R4 parameters pushes the version to at least 1.5, or if - // AES is used, 1.6, and setting R5 or R6 parameters pushes the - // version to at least 1.7 with extension level 3. + // Set up for encrypted output. User and owner password both must be specified. Either or both + // may be the empty string. Note that qpdf does not apply any special treatment to the empty + // string, which makes it possible to create encrypted files with empty owner passwords and + // non-empty user passwords or with the same password for both user and owner. Some PDF reading + // products don't handle such files very well. Enabling encryption disables stream prefiltering + // and content normalization. Note that setting R2 encryption parameters sets the PDF version + // to at least 1.3, setting R3 encryption parameters pushes the PDF version number to at + // least 1.4, setting R4 parameters pushes the version to at least 1.5, or if AES is used, 1.6, + // and setting R5 or R6 parameters pushes the version to at least 1.7 with extension level 3. // - // Note about Unicode passwords: the PDF specification requires - // passwords to be encoded with PDF Doc encoding for R <= 4 and - // UTF-8 for R >= 5. In all cases, these methods take strings of - // bytes as passwords. It is up to the caller to ensure that - // passwords are properly encoded. The qpdf command-line tool - // tries to do this, as discussed in the manual. If you are doing - // this from your own application, QUtil contains many transcoding - // functions that could be useful to you, most notably - // utf8_to_pdf_doc. - - // R2 uses RC4, which is a weak cryptographic algorithm. Don't use - // it unless you have to. See "Weak Cryptography" in the manual. - // This encryption format is deprecated in the PDF 2.0 + // Note about Unicode passwords: the PDF specification requires passwords to be encoded with PDF + // Doc encoding for R <= 4 and UTF-8 for R >= 5. In all cases, these methods take strings of + // bytes as passwords. It is up to the caller to ensure that passwords are properly encoded. The + // qpdf command-line tool tries to do this, as discussed in the manual. If you are doing this + // from your own application, QUtil contains many transcoding functions that could be useful to + // you, most notably utf8_to_pdf_doc. + + // R2 uses RC4, which is a weak cryptographic algorithm. Don't use it unless you have to. See + // "Weak Cryptography" in the manual. This encryption format is deprecated in the PDF 2.0 // specification. QPDF_DLL void setR2EncryptionParametersInsecure( @@ -398,9 +332,8 @@ class QPDFWriter bool allow_modify, bool allow_extract, bool allow_annotate); - // R3 uses RC4, which is a weak cryptographic algorithm. Don't use - // it unless you have to. See "Weak Cryptography" in the manual. - // This encryption format is deprecated in the PDF 2.0 + // R3 uses RC4, which is a weak cryptographic algorithm. Don't use it unless you have to. See + // "Weak Cryptography" in the manual. This encryption format is deprecated in the PDF 2.0 // specification. QPDF_DLL void setR3EncryptionParametersInsecure( @@ -413,11 +346,10 @@ class QPDFWriter bool allow_form_filling, bool allow_modify_other, qpdf_r3_print_e print); - // When use_aes=false, this call enables R4 with RC4, which is a - // weak cryptographic algorithm. Even with use_aes=true, the - // overall encryption scheme is weak. Don't use it unless you have - // to. See "Weak Cryptography" in the manual. This encryption - // format is deprecated in the PDF 2.0 specification. + // When use_aes=false, this call enables R4 with RC4, which is a weak cryptographic algorithm. + // Even with use_aes=true, the overall encryption scheme is weak. Don't use it unless you have + // to. See "Weak Cryptography" in the manual. This encryption format is deprecated in the + // PDF 2.0 specification. QPDF_DLL void setR4EncryptionParametersInsecure( char const* user_password, @@ -431,9 +363,8 @@ class QPDFWriter qpdf_r3_print_e print, bool encrypt_metadata, bool use_aes); - // R5 is deprecated. Do not use it for production use. Writing - // R5 is supported by qpdf primarily to generate test files for - // applications that may need to test R5 support. + // R5 is deprecated. Do not use it for production use. Writing R5 is supported by qpdf + // primarily to generate test files for applications that may need to test R5 support. QPDF_DLL void setR5EncryptionParameters( char const* user_password, @@ -446,8 +377,7 @@ class QPDFWriter bool allow_modify_other, qpdf_r3_print_e print, bool encrypt_metadata); - // This is the only password-based encryption format supported by - // the PDF specification. + // This is the only password-based encryption format supported by the PDF specification. QPDF_DLL void setR6EncryptionParameters( char const* user_password, @@ -461,57 +391,49 @@ class QPDFWriter qpdf_r3_print_e print, bool encrypt_metadata_aes); - // Create linearized output. Disables qdf mode, content - // normalization, and stream prefiltering. + // Create linearized output. Disables qdf mode, content normalization, and stream prefiltering. QPDF_DLL void setLinearization(bool); - // For debugging QPDF: provide the name of a file to write pass1 - // of linearization to. The only reason to use this is to debug - // QPDF. To linearize, QPDF writes out the file in two passes. - // Usually the first pass is discarded, but lots of computations - // are made in pass 1. If a linearized file comes out wrong, it - // can be helpful to look at the first pass. + // For debugging QPDF: provide the name of a file to write pass1 of linearization to. The only + // reason to use this is to debug QPDF. To linearize, QPDF writes out the file in two passes. + // Usually the first pass is discarded, but lots of computations are made in pass 1. If a + // linearized file comes out wrong, it can be helpful to look at the first pass. QPDF_DLL void setLinearizationPass1Filename(std::string const&); - // Create PCLm output. This is only useful for clients that know - // how to create PCLm files. If a file is structured exactly as - // PCLm requires, this call will tell QPDFWriter to write the PCLm - // header, create certain unreferenced streams required by the - // standard, and write the objects in the required order. Calling - // this on an ordinary PDF serves no purpose. There is no + // Create PCLm output. This is only useful for clients that know how to create PCLm files. If a + // file is structured exactly as PCLm requires, this call will tell QPDFWriter to write the PCLm + // header, create certain unreferenced streams required by the standard, and write the objects + // in the required order. Calling this on an ordinary PDF serves no purpose. There is no // command-line argument that causes this method to be called. QPDF_DLL void setPCLm(bool); - // If you want to be notified of progress, derive a class from - // ProgressReporter and override the reportProgress method. + // If you want to be notified of progress, derive a class from ProgressReporter and override the + // reportProgress method. QPDF_DLL void registerProgressReporter(std::shared_ptr); - // Return the PDF version that will be written into the header. - // Calling this method does all the preparation for writing, so it - // is an error to call any methods that may cause a change to the - // version. Adding new objects to the original file after calling - // this may also cause problems. It is safe to update existing - // objects or stream contents after calling this method, e.g., to + // Return the PDF version that will be written into the header. Calling this method does all the + // preparation for writing, so it is an error to call any methods that may cause a change to the + // version. Adding new objects to the original file after calling this may also cause problems. + // It is safe to update existing objects or stream contents after calling this method, e.g., to // include the final version number in metadata. QPDF_DLL std::string getFinalVersion(); - // Write the final file. There is no expectation of being able to - // call write() more than once. + // Write the final file. There is no expectation of being able to call write() more than once. QPDF_DLL void write(); - // Return renumbered ObjGen that was written into the final file. - // This method can be used after calling write(). + // Return renumbered ObjGen that was written into the final file. This method can be used after + // calling write(). QPDF_DLL QPDFObjGen getRenumberedObjGen(QPDFObjGen); - // Return XRef entry that was written into the final file. - // This method can be used after calling write(). + // Return XRef entry that was written into the final file. This method can be used after calling + // write(). QPDF_DLL std::map getWrittenXRefTable(); @@ -525,15 +447,12 @@ class QPDFWriter enum trailer_e { t_normal, t_lin_first, t_lin_second }; - // An reference to a PipelinePopper instance is passed into - // activatePipelineStack. When the PipelinePopper goes out of - // scope, the pipeline stack is popped. PipelinePopper's - // destructor calls finish on the current pipeline and pops the - // pipeline stack until the top of stack is a previous active top - // of stack, and restores the pipeline to that point. It deletes - // any pipelines that it pops. If the bp argument is non-null and - // any of the stack items are of type Pl_Buffer, the buffer is - // retrieved. + // An reference to a PipelinePopper instance is passed into activatePipelineStack. When the + // PipelinePopper goes out of scope, the pipeline stack is popped. PipelinePopper's destructor + // calls finish on the current pipeline and pops the pipeline stack until the top of stack is a + // previous active top of stack, and restores the pipeline to that point. It deletes any + // pipelines that it pops. If the bp argument is non-null and any of the stack items are of type + // Pl_Buffer, the buffer is retrieved. class PipelinePopper { friend class QPDFWriter; @@ -672,10 +591,9 @@ class QPDFWriter int linearization_pass); size_t calculateXrefStreamPadding(qpdf_offset_t xref_bytes); - // When filtering subsections, push additional pipelines to the - // stack. When ready to switch, activate the pipeline stack. When - // the passed in PipelinePopper goes out of scope, the stack is - // popped. + // When filtering subsections, push additional pipelines to the stack. When ready to switch, + // activate the pipeline stack. When the passed in PipelinePopper goes out of scope, the stack + // is popped. Pipeline* pushPipeline(Pipeline*); void activatePipelineStack(PipelinePopper&); void initializePipelineStack(Pipeline*); @@ -779,9 +697,8 @@ class QPDFWriter int next_progress_report{0}; }; - // Keep all member variables inside the Members object, which we - // dynamically allocate. This makes it possible to add new private - // members without breaking binary compatibility. + // Keep all member variables inside the Members object, which we dynamically allocate. This + // makes it possible to add new private members without breaking binary compatibility. std::shared_ptr m; }; diff --git a/include/qpdf/QPDFXRefEntry.hh b/include/qpdf/QPDFXRefEntry.hh index afdca768..0593c02d 100644 --- a/include/qpdf/QPDFXRefEntry.hh +++ b/include/qpdf/QPDFXRefEntry.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QPDFXREFENTRY_HH #define QPDFXREFENTRY_HH @@ -28,8 +25,7 @@ class QPDFXRefEntry { public: - // Type constants are from the PDF spec section - // "Cross-Reference Streams": + // Type constants are from the PDF spec section "Cross-Reference Streams": // 0 = free entry; not used // 1 = "uncompressed"; field 1 = offset // 2 = "compressed"; field 1 = object stream number, field 2 = index @@ -65,8 +61,8 @@ class QPDFXRefEntry int getObjStreamIndex() const; // only for type 2 private: - // This class does not use the Members pattern to avoid a memory - // allocation for every one of these. A lot of these get created. + // This class does not use the Members pattern to avoid a memory allocation for every one of + // these. A lot of these get created. int type{0}; qpdf_offset_t field1{0}; int field2{0}; diff --git a/include/qpdf/QTC.hh b/include/qpdf/QTC.hh index 46d65607..030d4d97 100644 --- a/include/qpdf/QTC.hh +++ b/include/qpdf/QTC.hh @@ -2,33 +2,28 @@ // // 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 +// 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. +// 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. +// 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 QTC_HH #define QTC_HH #include -// Defining QPDF_DISABLE_QTC will effectively compile out any QTC::TC -// calls in any code that includes this file, but QTC will still be -// built into the library. That way, it is possible to build and -// package qpdf with QPDF_DISABLE_QTC while still making QTC::TC -// available to end users. +// Defining QPDF_DISABLE_QTC will effectively compile out any QTC::TC calls in any code that +// includes this file, but QTC will still be built into the library. That way, it is possible to +// build and package qpdf with QPDF_DISABLE_QTC while still making QTC::TC available to end users. namespace QTC { diff --git a/include/qpdf/QUtil.hh b/include/qpdf/QUtil.hh index 85e7f907..47ecf6bf 100644 --- a/include/qpdf/QUtil.hh +++ b/include/qpdf/QUtil.hh @@ -2,22 +2,19 @@ // // 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 +// 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. +// 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. +// 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 QUTIL_HH #define QUTIL_HH @@ -40,8 +37,7 @@ class Pipeline; namespace QUtil { - // This is a collection of useful utility functions that don't - // really go anywhere else. + // This is a collection of useful utility functions that don't really go anywhere else. QPDF_DLL std::string int_to_string(long long, int length = 0); QPDF_DLL @@ -53,8 +49,7 @@ namespace QUtil QPDF_DLL std::string double_to_string(double, int decimal_places = 0, bool trim_trailing_zeroes = true); - // These string to number methods throw std::runtime_error on - // underflow/overflow. + // These string to number methods throw std::runtime_error on underflow/overflow. QPDF_DLL long long string_to_ll(char const* str); QPDF_DLL @@ -64,63 +59,53 @@ namespace QUtil QPDF_DLL unsigned int string_to_uint(char const* str); - // Returns true if this exactly represents a long long. The - // determination is made by converting the string to a long long, - // then converting the result back to a string, and then comparing + // Returns true if this exactly represents a long long. The determination is made by converting + // the string to a long long, then converting the result back to a string, and then comparing // that result with the original string. QPDF_DLL bool is_long_long(char const* str); - // Pipeline's write method wants unsigned char*, but we often have - // some other type of string. These methods do combinations of - // const_cast and reinterpret_cast to give us an unsigned char*. - // They should only be used when it is known that it is safe. - // None of the pipelines in qpdf modify the data passed to them, - // so within qpdf, it should always be safe. + // Pipeline's write method wants unsigned char*, but we often have some other type of string. + // These methods do combinations of const_cast and reinterpret_cast to give us an unsigned + // char*. They should only be used when it is known that it is safe. None of the pipelines in + // qpdf modify the data passed to them, so within qpdf, it should always be safe. QPDF_DLL unsigned char* unsigned_char_pointer(std::string const& str); QPDF_DLL unsigned char* unsigned_char_pointer(char const* str); - // Throw QPDFSystemError, which is derived from - // std::runtime_error, with a string formed by appending to - // "description: " the standard string corresponding to the - // current value of errno. You can retrieve the value of errno by - // calling getErrno() on the QPDFSystemError. Prior to qpdf 8.2.0, - // this method threw system::runtime_error directly, but since - // QPDFSystemError is derived from system::runtime_error, old code - // that specifically catches std::runtime_error will still work. + // Throw QPDFSystemError, which is derived from std::runtime_error, with a string formed by + // appending to "description: " the standard string corresponding to the current value of errno. + // You can retrieve the value of errno by calling getErrno() on the QPDFSystemError. Prior to + // qpdf 8.2.0, this method threw system::runtime_error directly, but since QPDFSystemError is + // derived from system::runtime_error, old code that specifically catches std::runtime_error + // will still work. QPDF_DLL void throw_system_error(std::string const& description); - // The status argument is assumed to be the return value of a - // standard library call that sets errno when it fails. If status - // is -1, convert the current value of errno to a - // std::runtime_error that includes the standard error string. - // Otherwise, return status. + // The status argument is assumed to be the return value of a standard library call that sets + // errno when it fails. If status is -1, convert the current value of errno to a + // std::runtime_error that includes the standard error string. Otherwise, return status. QPDF_DLL int os_wrapper(std::string const& description, int status); - // If the open fails, throws std::runtime_error. Otherwise, the - // FILE* is returned. The filename should be UTF-8 encoded, even - // on Windows. It will be converted as needed on Windows. + // If the open fails, throws std::runtime_error. Otherwise, the FILE* is returned. The filename + // should be UTF-8 encoded, even on Windows. It will be converted as needed on Windows. QPDF_DLL FILE* safe_fopen(char const* filename, char const* mode); - // The FILE* argument is assumed to be the return of fopen. If - // null, throw std::runtime_error. Otherwise, return the FILE* - // argument. + // The FILE* argument is assumed to be the return of fopen. If null, throw std::runtime_error. + // Otherwise, return the FILE* argument. QPDF_DLL FILE* fopen_wrapper(std::string const&, FILE*); - // This is a little class to help with automatic closing files. - // You can do something like + // This is a little class to help with automatic closing files. You can do something like // // QUtil::FileCloser fc(QUtil::safe_fopen(filename, "rb")); // - // and then use fc.f to the file. Be sure to actually declare a - // variable of type FileCloser. Using it as a temporary won't work - // because it will close the file as soon as it goes out of scope. + // and then use fc.f to the file. Be sure to actually declare a variable of type FileCloser. + // Using it as a temporary won't work because it will close the file as soon as it goes out of + // scope. class FileCloser { public: @@ -160,28 +145,24 @@ namespace QUtil QPDF_DLL void rename_file(char const* oldname, char const* newname); - // Write the contents of filename as a binary file to the - // pipeline. + // Write the contents of filename as a binary file to the pipeline. QPDF_DLL void pipe_file(char const* filename, Pipeline* p); - // Return a function that will send the contents of the given file - // through the given pipeline as binary data. + // Return a function that will send the contents of the given file through the given pipeline as + // binary data. QPDF_DLL std::function file_provider(std::string const& filename); - // Return the last path element. On Windows, either / or \ are - // path separators. Otherwise, only / is a path separator. Strip - // any trailing path separators. Then, if any path separators - // remain, return everything after the last path separator. - // Otherwise, return the whole string. As a special case, if a - // string consists entirely of path separators, the first - // character is returned. + // Return the last path element. On Windows, either / or \ are path separators. Otherwise, only + // / is a path separator. Strip any trailing path separators. Then, if any path separators + // remain, return everything after the last path separator. Otherwise, return the whole string. + // As a special case, if a string consists entirely of path separators, the first character is + // returned. QPDF_DLL std::string path_basename(std::string const& filename); - // Returns a dynamically allocated copy of a string that the - // caller has to delete with delete[]. + // Returns a dynamically allocated copy of a string that the caller has to delete with delete[]. QPDF_DLL char* copy_string(std::string const&); @@ -193,8 +174,7 @@ namespace QUtil QPDF_DLL std::unique_ptr make_unique_cstr(std::string const&); - // Create a shared pointer to an array. From c++20, - // std::make_shared(n) does this. + // Create a shared pointer to an array. From c++20, std::make_shared(n) does this. template std::shared_ptr make_shared_array(size_t n) @@ -202,27 +182,24 @@ namespace QUtil return std::shared_ptr(new T[n], std::default_delete()); } - // Returns lower-case hex-encoded version of the string, treating - // each character in the input string as unsigned. The output - // string will be twice as long as the input string. + // Returns lower-case hex-encoded version of the string, treating each character in the input + // string as unsigned. The output string will be twice as long as the input string. QPDF_DLL std::string hex_encode(std::string const&); - // Returns lower-case hex-encoded version of the char including a leading - // "#". + // Returns lower-case hex-encoded version of the char including a leading "#". QPDF_DLL inline std::string hex_encode_char(char); - // Returns a string that is the result of decoding the input - // string. The input string may consist of mixed case hexadecimal - // digits. Any characters that are not hexadecimal digits will be - // silently ignored. If there are an odd number of hexadecimal - // digits, a trailing 0 will be assumed. + // Returns a string that is the result of decoding the input string. The input string may + // consist of mixed case hexadecimal digits. Any characters that are not hexadecimal digits will + // be silently ignored. If there are an odd number of hexadecimal digits, a trailing 0 will be + // assumed. QPDF_DLL std::string hex_decode(std::string const&); - // Decode a single hex digit into a char in the range 0 <= char < 16. Return - // a char >= 16 if digit is not a valid hex digit. + // Decode a single hex digit into a char in the range 0 <= char < 16. Return a char >= 16 if + // digit is not a valid hex digit. QPDF_DLL inline constexpr char hex_decode_char(char digit) noexcept; @@ -239,17 +216,15 @@ namespace QUtil QPDF_DLL char* getWhoami(char* argv0); - // Get the value of an environment variable in a portable fashion. - // Returns true iff the variable is defined. If `value' is - // non-null, initializes it with the value of the variable. + // Get the value of an environment variable in a portable fashion. Returns true iff the variable + // is defined. If `value' is non-null, initializes it with the value of the variable. QPDF_DLL bool get_env(std::string const& var, std::string* value = nullptr); QPDF_DLL time_t get_current_time(); - // Portable structure representing a point in time with second - // granularity and time zone offset + // Portable structure representing a point in time with second granularity and time zone offset struct QPDFTime { QPDFTime() = default; @@ -277,12 +252,11 @@ namespace QUtil QPDF_DLL QPDFTime get_current_qpdf_time(); - // Convert a QPDFTime structure to a PDF timestamp string, which - // is "D:yyyymmddhhmmss" where is either "Z" for UTC or - // "-hh'mm'" or "+hh'mm'" for timezone offset. may also be - // omitted. Examples: "D:20210207161528-05'00'", - // "D:20210207211528Z", "D:20210207211528". See - // get_current_qpdf_time and the QPDFTime structure above. + // Convert a QPDFTime structure to a PDF timestamp string, which is "D:yyyymmddhhmmss" where + // is either "Z" for UTC or "-hh'mm'" or "+hh'mm'" for timezone offset. may also be + // omitted. + // Examples: "D:20210207161528-05'00'", "D:20210207211528Z", "D:20210207211528". + // See get_current_qpdf_time and the QPDFTime structure above. QPDF_DLL std::string qpdf_time_to_pdf_time(QPDFTime const&); @@ -290,63 +264,53 @@ namespace QUtil QPDF_DLL std::string qpdf_time_to_iso8601(QPDFTime const&); - // Convert a PDF timestamp string to a QPDFTime. If syntactically - // valid, return true and fill in qtm. If not valid, return false, - // and do not modify qtm. If qtm is null, just check the validity - // of the string. + // Convert a PDF timestamp string to a QPDFTime. If syntactically valid, return true and fill in + // qtm. If not valid, return false, and do not modify qtm. If qtm is null, just check the + // validity of the string. QPDF_DLL bool pdf_time_to_qpdf_time(std::string const&, QPDFTime* qtm = nullptr); - // Convert PDF timestamp to a second-granularity ISO-8601 - // timestamp. If syntactically valid, return true and initialize - // iso8601. Otherwise, return false. + // Convert PDF timestamp to a second-granularity ISO-8601 timestamp. If syntactically valid, + // return true and initialize iso8601. Otherwise, return false. bool pdf_time_to_iso8601(std::string const& pdf_time, std::string& iso8601); - // Return a string containing the byte representation of the UTF-8 - // encoding for the unicode value passed in. + // Return a string containing the byte representation of the UTF-8 encoding for the unicode + // value passed in. QPDF_DLL std::string toUTF8(unsigned long uval); - // Return a string containing the byte representation of the - // UTF-16 big-endian encoding for the unicode value passed in. - // Unrepresentable code points are converted to U+FFFD. + // Return a string containing the byte representation of the UTF-16 big-endian encoding for the + // unicode value passed in. Unrepresentable code points are converted to U+FFFD. QPDF_DLL std::string toUTF16(unsigned long uval); - // If utf8_val.at(pos) points to the beginning of a valid - // UTF-8-encoded character, return the codepoint of the character - // and set error to false. Otherwise, return 0xfffd and set error - // to true. In all cases, pos is advanced to the next position - // that may begin a valid character. When the string has been - // consumed, pos will be set to the string length. It is an error - // to pass a value of pos that is greater than or equal to the - // length of the string. + // If utf8_val.at(pos) points to the beginning of a valid UTF-8-encoded character, return the + // codepoint of the character and set error to false. Otherwise, return 0xfffd and set error to + // true. In all cases, pos is advanced to the next position that may begin a valid character. + // When the string has been consumed, pos will be set to the string length. It is an error to + // pass a value of pos that is greater than or equal to the length of the string. QPDF_DLL unsigned long get_next_utf8_codepoint(std::string const& utf8_val, size_t& pos, bool& error); - // Test whether this is a UTF-16 string. This is indicated by - // first two bytes being 0xFE 0xFF (big-endian) or 0xFF 0xFE - // (little-endian), each of which is the encoding of U+FEFF, the - // Unicode marker. Starting in qpdf 10.6.2, this detects - // little-endian as well as big-endian. Even though the PDF spec - // doesn't allow little-endian, most readers seem to accept it. + // Test whether this is a UTF-16 string. This is indicated by first two bytes being 0xFE 0xFF + // (big-endian) or 0xFF 0xFE (little-endian), each of which is the encoding of U+FEFF, the + // Unicode marker. Starting in qpdf 10.6.2, this detects little-endian as well as big-endian. + // Even though the PDF spec doesn't allow little-endian, most readers seem to accept it. QPDF_DLL bool is_utf16(std::string const&); - // Test whether this is an explicit UTF-8 string as allowed by the - // PDF 2.0 spec. This is indicated by first three bytes being 0xEF - // 0xBB 0xBF, which is the UTF-8 encoding of U+FEFF. + // Test whether this is an explicit UTF-8 string as allowed by the PDF 2.0 spec. This is + // indicated by first three bytes being 0xEF 0xBB 0xBF, which is the UTF-8 encoding of U+FEFF. QPDF_DLL bool is_explicit_utf8(std::string const&); - // Convert a UTF-8 encoded string to UTF-16 big-endian. - // Unrepresentable code points are converted to U+FFFD. + // Convert a UTF-8 encoded string to UTF-16 big-endian. Unrepresentable code points are + // converted to U+FFFD. QPDF_DLL std::string utf8_to_utf16(std::string const& utf8); - // Convert a UTF-8 encoded string to the specified single-byte - // encoding system by replacing all unsupported characters with - // the given unknown_char. + // Convert a UTF-8 encoded string to the specified single-byte encoding system by replacing all + // unsupported characters with the given unknown_char. QPDF_DLL std::string utf8_to_ascii(std::string const& utf8, char unknown_char = '?'); QPDF_DLL @@ -356,9 +320,8 @@ namespace QUtil QPDF_DLL std::string utf8_to_pdf_doc(std::string const& utf8, char unknown_char = '?'); - // These versions return true if the conversion was successful and - // false if any unrepresentable characters were found and had to - // be substituted with the unknown character. + // These versions return true if the conversion was successful and false if any unrepresentable + // characters were found and had to be substituted with the unknown character. QPDF_DLL bool utf8_to_ascii(std::string const& utf8, std::string& ascii, char unknown_char = '?'); QPDF_DLL @@ -373,9 +336,8 @@ namespace QUtil QPDF_DLL std::string utf16_to_utf8(std::string const& utf16); - // Convert from the specified single-byte encoding system to - // UTF-8. There is no ascii_to_utf8 because all ASCII strings are - // already valid UTF-8. + // Convert from the specified single-byte encoding system to UTF-8. There is no ascii_to_utf8 + // because all ASCII strings are already valid UTF-8. QPDF_DLL std::string win_ansi_to_utf8(std::string const& win); QPDF_DLL @@ -383,39 +345,33 @@ namespace QUtil QPDF_DLL std::string pdf_doc_to_utf8(std::string const& pdfdoc); - // Analyze a string for encoding. We can't tell the difference - // between any single-byte encodings, and we can't tell for sure - // whether a string that happens to be valid UTF-8 isn't a - // different encoding, but we can at least tell a few things to - // help us guess. If there are no characters with the high bit - // set, has_8bit_chars is false, and the other values are also - // false, even though ASCII strings are valid UTF-8. is_valid_utf8 - // means that the string is non-trivially valid UTF-8. Although - // the PDF spec requires UTF-16 to be UTF-16BE, qpdf (and just - // about everything else) accepts UTF-16LE (as of 10.6.2). + // Analyze a string for encoding. We can't tell the difference between any single-byte + // encodings, and we can't tell for sure whether a string that happens to be valid UTF-8 isn't a + // different encoding, but we can at least tell a few things to help us guess. If there are no + // characters with the high bit set, has_8bit_chars is false, and the other values are also + // false, even though ASCII strings are valid UTF-8. is_valid_utf8 means that the string is + // non-trivially valid UTF-8. Although the PDF spec requires UTF-16 to be UTF-16BE, qpdf (and + // just about everything else) accepts UTF-16LE (as of 10.6.2). QPDF_DLL void analyze_encoding( std::string const& str, bool& has_8bit_chars, bool& is_valid_utf8, bool& is_utf16); - // Try to compensate for previously incorrectly encoded strings. - // We want to compensate for the following errors: + // Try to compensate for previously incorrectly encoded strings. We want to compensate for the + // following errors: // - // * The string was supposed to be UTF-8 but was one of the - // single-byte encodings - // * The string was supposed to be PDF Doc but was either UTF-8 or - // one of the other single-byte encodings + // * The string was supposed to be UTF-8 but was one of the single-byte encodings + // * The string was supposed to be PDF Doc but was either UTF-8 or one of the other single-byte + // encodings // - // The returned vector always contains the original string first, - // and then it contains what the correct string would be in the - // event that the original string was the result of any of the + // The returned vector always contains the original string first, and then it contains what the + // correct string would be in the event that the original string was the result of any of the // above errors. // - // This method is useful for attempting to recover a password that - // may have been previously incorrectly encoded. For example, the - // password was supposed to be UTF-8 but the previous application - // used a password encoded in WinAnsi, or if the previous password - // was supposed to be PDFDoc but was actually given as UTF-8 or - // WinAnsi, this method would find the correct password. + // This method is useful for attempting to recover a password that may have been previously + // incorrectly encoded. For example, the password was supposed to be UTF-8 but the previous + // application used a password encoded in WinAnsi, or if the previous password was supposed to + // be PDFDoc but was actually given as UTF-8 or WinAnsi, this method would find the correct + // password. QPDF_DLL std::vector possible_repaired_encodings(std::string); @@ -427,30 +383,25 @@ namespace QUtil QPDF_DLL void initializeWithRandomBytes(unsigned char* data, size_t len); - // Supply a random data provider. Starting in qpdf 10.0.0, qpdf - // uses the crypto provider as its source of random numbers. If - // you are using the native crypto provider, then qpdf will either - // use the operating system's secure random number source or, only - // if enabled at build time, an insecure random source from - // stdlib. The caller is responsible for managing the memory for - // the RandomDataProvider. This method modifies a static variable. - // If you are providing your own random data provider, you should - // call this at the beginning of your program before creating any - // QPDF objects. Passing a null to this method will reset the - // library back to its default random data provider. + // Supply a random data provider. Starting in qpdf 10.0.0, qpdf uses the crypto provider as its + // source of random numbers. If you are using the native crypto provider, then qpdf will either + // use the operating system's secure random number source or, only if enabled at build time, an + // insecure random source from stdlib. The caller is responsible for managing the memory for the + // RandomDataProvider. This method modifies a static variable. If you are providing your own + // random data provider, you should call this at the beginning of your program before creating + // any QPDF objects. Passing a null to this method will reset the library back to its default + // random data provider. QPDF_DLL void setRandomDataProvider(RandomDataProvider*); - // This returns the random data provider that would be used the - // next time qpdf needs random data. It will never return null. - // If no random data provider has been provided and the library - // was not compiled with any random data provider available, an - // exception will be thrown. + // This returns the random data provider that would be used the next time qpdf needs random + // data. It will never return null. If no random data provider has been provided and the + // library was not compiled with any random data provider available, an exception will be + // thrown. QPDF_DLL RandomDataProvider* getRandomDataProvider(); - // Filename is UTF-8 encoded, even on Windows, as described in the - // comments for safe_fopen. + // Filename is UTF-8 encoded, even on Windows, as described in the comments for safe_fopen. QPDF_DLL std::list read_lines_from_file(char const* filename, bool preserve_eol = false); QPDF_DLL @@ -471,15 +422,13 @@ namespace QUtil QPDF_DLL std::string read_file_into_string(FILE* f, std::string_view filename = ""); - // This used to be called strcasecmp, but that is a macro on some - // platforms, so we have to give it a name that is not likely to - // be a macro anywhere. + // This used to be called strcasecmp, but that is a macro on some platforms, so we have to give + // it a name that is not likely to be a macro anywhere. QPDF_DLL int str_compare_nocase(char const*, char const*); - // These routines help the tokenizer recognize certain character - // classes without using ctype, which we avoid because of locale - // considerations. + // These routines help the tokenizer recognize certain character classes without using ctype, + // which we avoid because of locale considerations. QPDF_DLL inline bool is_hex_digit(char); @@ -492,21 +441,19 @@ namespace QUtil QPDF_DLL inline bool is_number(char const*); - // This method parses the numeric range syntax used by the qpdf - // command-line tool. May throw std::runtime_error. + // This method parses the numeric range syntax used by the qpdf command-line tool. May throw + // std::runtime_error. QPDF_DLL std::vector parse_numrange(char const* range, int max); #ifndef QPDF_NO_WCHAR_T - // If you are building qpdf on a stripped down system that doesn't - // have wchar_t, such as may be the case in some embedded - // environments, you may define QPDF_NO_WCHAR_T in your build. - // This symbol is never defined automatically. Search for wchar_t - // in qpdf's top-level README.md file for details. + // If you are building qpdf on a stripped down system that doesn't have wchar_t, such as may be + // the case in some embedded environments, you may define QPDF_NO_WCHAR_T in your build. This + // symbol is never defined automatically. Search for wchar_t in qpdf's top-level README.md file + // for details. - // Take an argv array consisting of wchar_t, as when wmain is - // invoked, convert all UTF-16 encoded strings to UTF-8, and call - // another main. + // Take an argv array consisting of wchar_t, as when wmain is invoked, convert all UTF-16 + // encoded strings to UTF-8, and call another main. QPDF_DLL int call_main_from_wmain(int argc, wchar_t* argv[], std::function realmain); QPDF_DLL @@ -516,13 +463,10 @@ namespace QUtil std::function realmain); #endif // QPDF_NO_WCHAR_T - // Try to return the maximum amount of memory allocated by the - // current process and its threads. Return 0 if unable to - // determine. This is Linux-specific and not implemented to be - // completely reliable. It is used during development for - // performance testing to detect changes that may significantly - // change memory usage. It is not recommended for use for other - // purposes. + // Try to return the maximum amount of memory allocated by the current process and its threads. + // Return 0 if unable to determine. This is Linux-specific and not implemented to be completely + // reliable. It is used during development for performance testing to detect changes that may + // significantly change memory usage. It is not recommended for use for other purposes. QPDF_DLL size_t get_max_memory_usage(); }; // namespace QUtil diff --git a/include/qpdf/qpdf-c.h b/include/qpdf/qpdf-c.h index 4e258e9a..e3639a43 100644 --- a/include/qpdf/qpdf-c.h +++ b/include/qpdf/qpdf-c.h @@ -2,138 +2,113 @@ * * 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 + * 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. + * 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. + * 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 QPDF_C_H #define QPDF_C_H /* - * This file defines a basic "C" API for qpdf. It provides access to - * a subset of the QPDF library's capabilities to make them accessible - * to callers who can't handle calling C++ functions or working with - * C++ classes. This may be especially useful to Windows users who - * are accessing the qpdf DLL directly or to other people programming - * in non-C/C++ languages that can call C code but not C++ code. + * This file defines a basic "C" API for qpdf. It provides access to a subset of the QPDF library's + * capabilities to make them accessible to callers who can't handle calling C++ functions or working + * with C++ classes. This may be especially useful to Windows users who are accessing the qpdf DLL + * directly or to other people programming in non-C/C++ languages that can call C code but not C++ + * code. * * There are several things to keep in mind when using the C API. * - * Error handling is tricky because the underlying C++ API uses - * exception handling. See "ERROR HANDLING" below for a detailed - * explanation. + * Error handling is tricky because the underlying C++ API uses exception handling. See "ERROR + * HANDLING" below for a detailed explanation. * - * The C API is not as rich as the C++ API. For any operations - * that involve actually manipulating PDF objects, you must use - * the C++ API. The C API is primarily useful for doing basic - * transformations on PDF files similar to what you might do with - * the qpdf command-line tool. + * The C API is not as rich as the C++ API. For any operations that involve actually + * manipulating PDF objects, you must use the C++ API. The C API is primarily useful for doing + * basic transformations on PDF files similar to what you might do with the qpdf command-line + * tool. * - * These functions store their state in a qpdf_data object. - * Individual instances of qpdf_data are not thread-safe: although - * you may access different qpdf_data objects from different - * threads, you may not access one qpdf_data simultaneously from - * multiple threads. + * These functions store their state in a qpdf_data object. Individual instances of qpdf_data + * are not thread-safe: although you may access different qpdf_data objects from different + * threads, you may not access one qpdf_data simultaneously from multiple threads. * - * All dynamic memory, except for that of the qpdf_data object - * itself, is managed by the library unless otherwise noted. You - * must create a qpdf_data object using qpdf_init and free it - * using qpdf_cleanup. + * All dynamic memory, except for that of the qpdf_data object itself, is managed by the library + * unless otherwise noted. You must create a qpdf_data object using qpdf_init and free it using + * qpdf_cleanup. * - * Many functions return char*. In all cases, the char* values - * returned are pointers to data inside the qpdf_data object. As - * such, they are always freed by qpdf_cleanup. In most cases, - * strings returned by functions here may be invalidated by - * subsequent function calls, sometimes even to different - * functions. If you want a string to last past the next qpdf call - * or after a call to qpdf_cleanup, you should make a copy of it. + * Many functions return char*. In all cases, the char* values returned are pointers to data + * inside the qpdf_data object. As such, they are always freed by qpdf_cleanup. In most cases, + * strings returned by functions here may be invalidated by subsequent function calls, sometimes + * even to different functions. If you want a string to last past the next qpdf call or after a + * call to qpdf_cleanup, you should make a copy of it. * - * Since it is possible for a PDF string to contain null - * characters, a function that returns data originating from a PDF - * string may also contain null characters. To handle that case, - * you call qpdf_get_last_string_length() to get the length of - * whatever string was just returned. See STRING FUNCTIONS below. + * Since it is possible for a PDF string to contain null characters, a function that returns + * data originating from a PDF string may also contain null characters. To handle that case, you + * call qpdf_get_last_string_length() to get the length of whatever string was just returned. + * See STRING FUNCTIONS below. * - * Most functions defined here have obvious counterparts that are - * methods to either QPDF or QPDFWriter. Please see comments in - * QPDF.hh and QPDFWriter.hh for details on their use. In order - * to avoid duplication of information, comments here focus - * primarily on differences between the C and C++ API. + * Most functions defined here have obvious counterparts that are methods to either QPDF or + * QPDFWriter. Please see comments in QPDF.hh and QPDFWriter.hh for details on their use. In + * order to avoid duplication of information, comments here focus primarily on differences + * between the C and C++ API. */ /* ERROR HANDLING -- changed in qpdf 10.5 */ -/* SUMMARY: The only way to know whether a function that does not - * return an error code has encountered an error is to call - * qpdf_has_error after each function. You can do this even for - * functions that do return error codes. You can also call - * qpdf_silence_errors to prevent qpdf from writing these errors to - * stderr. +/* SUMMARY: The only way to know whether a function that does not return an error code has + * encountered an error is to call qpdf_has_error after each function. You can do this even for + * functions that do return error codes. You can also call qpdf_silence_errors to prevent qpdf from + * writing these errors to stderr. * * DETAILS: * - * The data type underlying qpdf_data maintains a list of warnings and - * a single error. To retrieve warnings, call qpdf_next_warning while - * qpdf_more_warnings is true. To retrieve the error, call + * The data type underlying qpdf_data maintains a list of warnings and a single error. To retrieve + * warnings, call qpdf_next_warning while qpdf_more_warnings is true. To retrieve the error, call * qpdf_get_error when qpdf_has_error is true. * * There are several things that are important to understand. * - * Some functions return an error code. The value of the error code is - * made up of a bitwise-OR of QPDF_WARNINGS and QPDF_ERRORS. The - * QPDF_ERRORS bit is set if there was an error during the *most - * recent call* to the API. The QPDF_WARNINGS bit is set if there are - * any warnings that have not yet been retrieved by calling - * qpdf_more_warnings. It is possible for both its or neither bit to - * be set. + * Some functions return an error code. The value of the error code is made up of a bitwise-OR of + * QPDF_WARNINGS and QPDF_ERRORS. The QPDF_ERRORS bit is set if there was an error during the *most + * recent call* to the API. The QPDF_WARNINGS bit is set if there are any warnings that have not yet + * been retrieved by calling qpdf_more_warnings. It is possible for both its or neither bit to be + * set. * - * The expected mode of operation is to go through a series of - * operations, checking for errors after each call, but only checking - * for warnings at the end. This is similar to how it works in the C++ - * API where warnings are handled in exactly this way but errors - * result in exceptions being thrown. However, in both the C and C++ - * API, it is possible to check for and handle warnings as they arise. + * The expected mode of operation is to go through a series of operations, checking for errors after + * each call, but only checking for warnings at the end. This is similar to how it works in the C++ + * API where warnings are handled in exactly this way but errors result in exceptions being thrown. + * However, in both the C and C++ API, it is possible to check for and handle warnings as they + * arise. * - * Some functions return values (or void) rather than an error code. - * This is especially true with the object handling functions. Those - * functions can still generate errors. To handle errors in those - * cases, you should explicitly call qpdf_has_error(). Note that, if - * you want to avoid the inconsistencies in the interface, you can - * always check for error conditions in this way rather than looking - * at status return codes. + * Some functions return values (or void) rather than an error code. This is especially true with + * the object handling functions. Those functions can still generate errors. To handle errors in + * those cases, you should explicitly call qpdf_has_error(). Note that, if you want to avoid the + * inconsistencies in the interface, you can always check for error conditions in this way rather + * than looking at status return codes. * - * Prior to qpdf 10.5, if one of the functions that does not return an - * error code encountered an exception, it would cause the entire - * program to crash. Starting in qpdf 10.5, the default response to an - * error condition in these situations is to print the error to - * standard error, issue exactly one warning indicating that such an - * error occurred, and return a sensible fallback value (0 for - * numbers, QPDF_FALSE for booleans, "" for strings, or a null or - * uninitialized object handle). This is better than the old behavior - * but still undesirable as the best option is to explicitly check for - * error conditions. + * Prior to qpdf 10.5, if one of the functions that does not return an error code encountered an + * exception, it would cause the entire program to crash. Starting in qpdf 10.5, the default + * response to an error condition in these situations is to print the error to standard error, issue + * exactly one warning indicating that such an error occurred, and return a sensible fallback value + * (0 for numbers, QPDF_FALSE for booleans, "" for strings, or a null or uninitialized object + * handle). This is better than the old behavior but still undesirable as the best option is to + * explicitly check for error conditions. * - * To prevent qpdf from writing error messages to stderr in this way, - * you can call qpdf_silence_errors(). This signals to the qpdf - * library that you intend to check the error codes yourself. + * To prevent qpdf from writing error messages to stderr in this way, you can call + * qpdf_silence_errors(). This signals to the qpdf library that you intend to check the error codes + * yourself. * - * If you encounter a situation where an exception from the C++ code - * is not properly converted to an error as described above, it is a - * bug in qpdf, which should be reported at + * If you encounter a situation where an exception from the C++ code is not properly converted to an + * error as described above, it is a bug in qpdf, which should be reported at * https://github.com/qpdf/qpdf/issues/new. */ @@ -150,9 +125,8 @@ extern "C" { typedef struct _qpdf_data* qpdf_data; typedef struct _qpdf_error* qpdf_error; - /* Many functions return an integer error code. Codes are defined - * below. See comments at the top of the file for details. Note - * that the values below can be logically orred together. + /* Many functions return an integer error code. Codes are defined below. See comments at the + * top of the file for details. Note that the values below can be logically orred together. */ typedef int QPDF_ERROR_CODE; #define QPDF_SUCCESS 0 @@ -163,76 +137,68 @@ extern "C" { #define QPDF_TRUE 1 #define QPDF_FALSE 0 - /* From qpdf 10.5: call this method to signal to the library that - * you are explicitly handling errors from functions that don't - * return error codes. Otherwise, the library will print these - * error conditions to stderr and issue a warning. Prior to 10.5, - * the program would have crashed from an unhandled exception. + /* From qpdf 10.5: call this method to signal to the library that you are explicitly handling + * errors from functions that don't return error codes. Otherwise, the library will print these + * error conditions to stderr and issue a warning. Prior to 10.5, the program would have + * crashed from an unhandled exception. */ QPDF_DLL void qpdf_silence_errors(qpdf_data qpdf); - /* Returns the version of the qpdf software. This is guaranteed to - * be a static value. + /* Returns the version of the qpdf software. This is guaranteed to be a static value. */ QPDF_DLL char const* qpdf_get_qpdf_version(); - /* Returns dynamically allocated qpdf_data pointer; must be freed - * by calling qpdf_cleanup. You must call qpdf_read, one of the - * other qpdf_read_* functions, or qpdf_empty_pdf before calling + /* Returns dynamically allocated qpdf_data pointer; must be freed by calling qpdf_cleanup. You + * must call qpdf_read, one of the other qpdf_read_* functions, or qpdf_empty_pdf before calling * any function that would need to operate on the PDF file. */ QPDF_DLL qpdf_data qpdf_init(); - /* Pass a pointer to the qpdf_data pointer created by qpdf_init to - * clean up resources. This does not include buffers initialized - * by functions that return stream data but it otherwise includes - * all data associated with the QPDF object or any object handles. + /* Pass a pointer to the qpdf_data pointer created by qpdf_init to clean up resources. This does + * not include buffers initialized by functions that return stream data but it otherwise + * includes all data associated with the QPDF object or any object handles. */ QPDF_DLL void qpdf_cleanup(qpdf_data* qpdf); /* ERROR REPORTING */ - /* Returns 1 if there is an error condition. The error condition - * can be retrieved by a single call to qpdf_get_error. + /* Returns 1 if there is an error condition. The error condition can be retrieved by a single + * call to qpdf_get_error. */ QPDF_DLL QPDF_BOOL qpdf_has_error(qpdf_data qpdf); - /* Returns the error condition, if any. The return value is a - * pointer to data that will become invalid after the next call to - * this function, qpdf_next_warning, or qpdf_cleanup. After this - * function is called, qpdf_has_error will return QPDF_FALSE until - * the next error condition occurs. If there is no error - * condition, this function returns a null pointer. + /* Returns the error condition, if any. The return value is a pointer to data that will become + * invalid after the next call to this function, qpdf_next_warning, or qpdf_cleanup. After this + * function is called, qpdf_has_error will return QPDF_FALSE until the next error condition + * occurs. If there is no error condition, this function returns a null pointer. */ QPDF_DLL qpdf_error qpdf_get_error(qpdf_data qpdf); - /* Returns 1 if there are any unretrieved warnings, and zero - * otherwise. + /* Returns 1 if there are any unretrieved warnings, and zero otherwise. */ QPDF_DLL QPDF_BOOL qpdf_more_warnings(qpdf_data qpdf); - /* If there are any warnings, returns a pointer to the next - * warning. Otherwise returns a null pointer. + /* If there are any warnings, returns a pointer to the next warning. Otherwise returns a null + * pointer. */ QPDF_DLL qpdf_error qpdf_next_warning(qpdf_data qpdf); /* Extract fields of the error. */ - /* Use this function to get a full error message suitable for - * showing to the user. */ + /* Use this function to get a full error message suitable for showing to the user. */ QPDF_DLL char const* qpdf_get_error_full_text(qpdf_data q, qpdf_error e); - /* Use these functions to extract individual fields from the - * error; see QPDFExc.hh for details. */ + /* Use these functions to extract individual fields from the error; see QPDFExc.hh for details. + */ QPDF_DLL enum qpdf_error_code_e qpdf_get_error_code(qpdf_data q, qpdf_error e); QPDF_DLL @@ -242,9 +208,8 @@ extern "C" { QPDF_DLL char const* qpdf_get_error_message_detail(qpdf_data q, qpdf_error e); - /* By default, warnings are written to stderr. Passing true to - * this function will prevent warnings from being written to - * stderr. They will still be available by calls to + /* By default, warnings are written to stderr. Passing true to this function will prevent + * warnings from being written to stderr. They will still be available by calls to * qpdf_next_warning. */ QPDF_DLL @@ -252,11 +217,9 @@ extern "C" { /* LOG FUNCTIONS */ - /* Set or get the current logger. You need to call - * qpdflogger_cleanup on the logger handles when you are done with - * the handles. The underlying logger is cleaned up automatically - * and persists if needed after the logger handle is destroyed. - * See comments in qpdflogger-c.h for details. + /* Set or get the current logger. You need to call qpdflogger_cleanup on the logger handles when + * you are done with the handles. The underlying logger is cleaned up automatically and persists + * if needed after the logger handle is destroyed. See comments in qpdflogger-c.h for details. */ QPDF_DLL @@ -266,8 +229,7 @@ extern "C" { /* CHECK FUNCTIONS */ - /* Attempt to read the entire PDF file to see if there are any - * errors qpdf can detect. + /* Attempt to read the entire PDF file to see if there are any errors qpdf can detect. */ QPDF_DLL QPDF_ERROR_CODE qpdf_check_pdf(qpdf_data qpdf); @@ -284,20 +246,17 @@ extern "C" { /* This functions process a PDF or JSON input source. */ - /* Calling qpdf_read causes processFile to be called in the C++ - * API. Basic parsing is performed, but data from the file is - * only read as needed. For files without passwords, pass a null - * pointer or an empty string as the password. + /* Calling qpdf_read causes processFile to be called in the C++ API. Basic parsing is + * performed, but data from the file is only read as needed. For files without passwords, pass + * a null pointer or an empty string as the password. */ QPDF_DLL QPDF_ERROR_CODE qpdf_read(qpdf_data qpdf, char const* filename, char const* password); - /* Calling qpdf_read_memory causes processMemoryFile to be called - * in the C++ API. Otherwise, it behaves in the same way as - * qpdf_read. The description argument will be used in place of - * the file name in any error or warning messages generated by the - * library. + /* Calling qpdf_read_memory causes processMemoryFile to be called in the C++ API. Otherwise, it + * behaves in the same way as qpdf_read. The description argument will be used in place of the + * file name in any error or warning messages generated by the library. */ QPDF_DLL QPDF_ERROR_CODE qpdf_read_memory( @@ -307,22 +266,20 @@ extern "C" { unsigned long long size, char const* password); - /* Calling qpdf_empty_pdf initializes this qpdf object with an - * empty PDF, making it possible to create a PDF from scratch - * using the C API. Added in 10.6. + /* Calling qpdf_empty_pdf initializes this qpdf object with an empty PDF, making it possible to + * create a PDF from scratch using the C API. Added in 10.6. */ QPDF_DLL QPDF_ERROR_CODE qpdf_empty_pdf(qpdf_data qpdf); - /* Create a PDF from a JSON file. This calls createFromJSON in the - * C++ API. + /* Create a PDF from a JSON file. This calls createFromJSON in the C++ API. */ QPDF_DLL QPDF_ERROR_CODE qpdf_create_from_json_file(qpdf_data qpdf, char const* filename); - /* Create a PDF from JSON data in a null-terminated string. This - * calls createFromJSON in the C++ API. + /* Create a PDF from JSON data in a null-terminated string. This calls createFromJSON in the C++ + * API. */ QPDF_DLL QPDF_ERROR_CODE @@ -330,10 +287,9 @@ extern "C" { /* JSON UPDATE FUNCTIONS */ - /* Update a QPDF object from a JSON file or buffer. These - * functions call updateFromJSON. One of the other processing - * functions has to be called first so that the QPDF object is - * initialized with PDF data. + /* Update a QPDF object from a JSON file or buffer. These functions call updateFromJSON. One of + * the other processing functions has to be called first so that the QPDF object is initialized + * with PDF data. */ QPDF_DLL QPDF_ERROR_CODE @@ -344,18 +300,16 @@ extern "C" { /* READ FUNCTIONS */ - /* Read functions below must be called after qpdf_read or any of - * the other functions that process a PDF. */ + /* Read functions below must be called after qpdf_read or any of the other functions that + * process a PDF. */ /* - * NOTE: Functions that return char* are returning a pointer to an - * internal buffer that will be reused for each call to a function - * that returns a char*. You must use or copy the value before - * calling any other qpdf library functions. + * NOTE: Functions that return char* are returning a pointer to an internal buffer that will be + * reused for each call to a function that returns a char*. You must use or copy the value + * before calling any other qpdf library functions. */ - /* Return the version of the PDF file. See warning above about - * functions that return char*. */ + /* Return the version of the PDF file. See warning above about functions that return char*. */ QPDF_DLL char const* qpdf_get_pdf_version(qpdf_data qpdf); @@ -363,30 +317,26 @@ extern "C" { QPDF_DLL int qpdf_get_pdf_extension_level(qpdf_data qpdf); - /* Return the user password. If the file is opened using the - * owner password, the user password may be retrieved using this - * function. If the file is opened using the user password, this - * function will return that user password. See warning above - * about functions that return char*. + /* Return the user password. If the file is opened using the owner password, the user password + * may be retrieved using this function. If the file is opened using the user password, this + * function will return that user password. See warning above about functions that return + * char*. */ QPDF_DLL char const* qpdf_get_user_password(qpdf_data qpdf); - /* Return the string value of a key in the document's Info - * dictionary. The key parameter should include the leading - * slash, e.g. "/Author". If the key is not present or has a - * non-string value, a null pointer is returned. Otherwise, a - * pointer to an internal buffer is returned. See warning above - * about functions that return char*. + /* Return the string value of a key in the document's Info dictionary. The key parameter should + * include the leading slash, e.g. "/Author". If the key is not present or has a non-string + * value, a null pointer is returned. Otherwise, a pointer to an internal buffer is returned. + * See warning above about functions that return char*. */ QPDF_DLL char const* qpdf_get_info_key(qpdf_data qpdf, char const* key); - /* Set a value in the info dictionary, possibly replacing an - * existing value. The key must include the leading slash - * (e.g. "/Author"). Passing a null pointer as a value will - * remove the key from the info dictionary. Otherwise, a copy - * will be made of the string that is passed in. + /* Set a value in the info dictionary, possibly replacing an existing value. The key must + * include the leading slash (e.g. "/Author"). Passing a null pointer as a value will remove + * the key from the info dictionary. Otherwise, a copy will be made of the string that is + * passed in. */ QPDF_DLL void qpdf_set_info_key(qpdf_data qpdf, char const* key, char const* value); @@ -420,21 +370,16 @@ extern "C" { /* JSON WRITE FUNCTIONS */ - /* This function serializes the PDF to JSON. This calls writeJSON - * from the C++ API. + /* This function serializes the PDF to JSON. This calls writeJSON from the C++ API. * * - version: the JSON version, currently must be 2 - * - fn: a function that will be called with blocks of JSON data; - * will be called with data, a length, and the value of the - * udata parameter to this function - * - udata: will be passed as the third argument to fn with each - * call; use this for your own tracking or pass a null pointer - * if you don't need it - * - For decode_level, json_stream_data, file_prefix, and - * wanted_objects, see comments in QPDF.hh. For this API, - * wanted_objects should be a null-terminated array of - * null-terminated strings. Pass a null pointer if you want all - * objects. + * - fn: a function that will be called with blocks of JSON data; will be called with data, a + * length, and the value of the udata parameter to this function + * - udata: will be passed as the third argument to fn with each call; use this for your own + * tracking or pass a null pointer if you don't need it + * - For decode_level, json_stream_data, file_prefix, and wanted_objects, see comments in + * QPDF.hh. For this API, wanted_objects should be a null-terminated array of null-terminated + * strings. Pass a null pointer if you want all objects. */ /* Function should return 0 on success. */ @@ -453,37 +398,29 @@ extern "C" { /* WRITE FUNCTIONS */ - /* Set up for writing. No writing is actually performed until the - * call to qpdf_write(). + /* Set up for writing. No writing is actually performed until the call to qpdf_write(). */ - /* Supply the name of the file to be written and initialize the - * qpdf_data object to handle writing operations. This function - * also attempts to create the file. The PDF data is not written - * until the call to qpdf_write. qpdf_init_write may be called - * multiple times for the same qpdf_data object. When - * qpdf_init_write is called, all information from previous calls - * to functions that set write parameters (qpdf_set_linearization, - * etc.) is lost, so any write parameter functions must be called - * again. + /* Supply the name of the file to be written and initialize the qpdf_data object to handle + * writing operations. This function also attempts to create the file. The PDF data is not + * written until the call to qpdf_write. qpdf_init_write may be called multiple times for the + * same qpdf_data object. When qpdf_init_write is called, all information from previous calls + * to functions that set write parameters (qpdf_set_linearization, etc.) is lost, so any write + * parameter functions must be called again. */ QPDF_DLL QPDF_ERROR_CODE qpdf_init_write(qpdf_data qpdf, char const* filename); - /* Initialize for writing but indicate that the PDF file should be - * written to memory. Call qpdf_get_buffer_length and - * qpdf_get_buffer to retrieve the resulting buffer. The memory - * containing the PDF file will be destroyed when qpdf_cleanup is - * called. + /* Initialize for writing but indicate that the PDF file should be written to memory. Call + * qpdf_get_buffer_length and qpdf_get_buffer to retrieve the resulting buffer. The memory + * containing the PDF file will be destroyed when qpdf_cleanup is called. */ QPDF_DLL QPDF_ERROR_CODE qpdf_init_write_memory(qpdf_data qpdf); - /* Retrieve the buffer used if the file was written to memory. - * qpdf_get_buffer returns a null pointer if data was not written - * to memory. The memory is freed when qpdf_cleanup is called or - * if a subsequent call to qpdf_init_write or - * qpdf_init_write_memory is called. */ + /* Retrieve the buffer used if the file was written to memory. qpdf_get_buffer returns a null + * pointer if data was not written to memory. The memory is freed when qpdf_cleanup is called + * or if a subsequent call to qpdf_init_write or qpdf_init_write_memory is called. */ QPDF_DLL size_t qpdf_get_buffer_length(qpdf_data qpdf); QPDF_DLL @@ -516,14 +453,14 @@ extern "C" { QPDF_DLL void qpdf_set_deterministic_ID(qpdf_data qpdf, QPDF_BOOL value); - /* Never use qpdf_set_static_ID except in test suites to suppress - * generation of a random /ID. See also qpdf_set_deterministic_ID. + /* Never use qpdf_set_static_ID except in test suites to suppress generation of a random /ID. + * See also qpdf_set_deterministic_ID. */ QPDF_DLL void qpdf_set_static_ID(qpdf_data qpdf, QPDF_BOOL value); - /* Never use qpdf_set_static_aes_IV except in test suites to - * create predictable AES encrypted output. + /* Never use qpdf_set_static_aes_IV except in test suites to create predictable AES encrypted + * output. */ QPDF_DLL void qpdf_set_static_aes_IV(qpdf_data qpdf, QPDF_BOOL value); @@ -534,9 +471,8 @@ extern "C" { QPDF_DLL void qpdf_set_preserve_encryption(qpdf_data qpdf, QPDF_BOOL value); - /* The *_insecure functions are identical to the old versions but - * have been renamed as a an alert to the caller that they are - * insecure. See "Weak Cryptographic" in the manual for + /* The *_insecure functions are identical to the old versions but have been renamed as a an + * alert to the caller that they are insecure. See "Weak Cryptographic" in the manual for * details. */ QPDF_DLL @@ -622,15 +558,12 @@ extern "C" { void qpdf_force_pdf_version_and_extension(qpdf_data qpdf, char const* version, int extension_level); - /* During write, your report_progress function will be called with - * a value between 0 and 100 representing the approximate write - * progress. The data object you pass to - * qpdf_register_progress_reporter will be handed back to your - * function. This function must be called after qpdf_init_write - * (or qpdf_init_write_memory) and before qpdf_write. The - * registered progress reporter applies only to a single write, so - * you must call it again if you perform a subsequent write with a - * new writer. + /* During write, your report_progress function will be called with a value between 0 and 100 + * representing the approximate write progress. The data object you pass to + * qpdf_register_progress_reporter will be handed back to your function. This function must be + * called after qpdf_init_write (or qpdf_init_write_memory) and before qpdf_write. The + * registered progress reporter applies only to a single write, so you must call it again if you + * perform a subsequent write with a new writer. */ QPDF_DLL void qpdf_register_progress_reporter( @@ -642,67 +575,51 @@ extern "C" { /* Object handling. * - * These functions take and return a qpdf_oh object handle, which - * is just an unsigned integer. The value 0 is never returned, which - * makes it usable as an uninitialized value. The handles returned by - * these functions are guaranteed to be unique, i.e. two calls to - * (the same of different) functions will return distinct handles - * even when they refer to the same object. + * These functions take and return a qpdf_oh object handle, which is just an unsigned integer. + * The value 0 is never returned, which makes it usable as an uninitialized value. The handles + * returned by these functions are guaranteed to be unique, i.e. two calls to (the same of + * different) functions will return distinct handles even when they refer to the same object. * - * Each function below, starting with qpdf_oh, corresponds to a - * specific method of QPDFObjectHandler. For example, - * qpdf_oh_is_bool corresponds to QPDFObjectHandle::isBool. If the - * C++ method is overloaded, the C function's name will be - * disambiguated. If the C++ method takes optional arguments, the C - * function will have required arguments in those positions. For - * details about the method, please see comments in - * QPDFObjectHandle.hh. Comments here only explain things that are - * specific to the "C" API. + * Each function below, starting with qpdf_oh, corresponds to a specific method of + * QPDFObjectHandler. For example, qpdf_oh_is_bool corresponds to QPDFObjectHandle::isBool. If + * the C++ method is overloaded, the C function's name will be disambiguated. If the C++ method + * takes optional arguments, the C function will have required arguments in those positions. For + * details about the method, please see comments in QPDFObjectHandle.hh. Comments here only + * explain things that are specific to the "C" API. * - * Only a fraction of the methods of QPDFObjectHandle are - * available here. Most of the basic methods for creating, - * accessing, and modifying most types of objects are present. - * Most of the higher-level functions are not implemented. - * Functions for dealing with content streams as well as objects - * that only exist in content streams (operators and inline - * images) are mostly not provided. + * Only a fraction of the methods of QPDFObjectHandle are available here. Most of the basic + * methods for creating, accessing, and modifying most types of objects are present. Most of the + * higher-level functions are not implemented. Functions for dealing with content streams as + * well as objects that only exist in content streams (operators and inline images) are mostly + * not provided. * - * To refer to a specific QPDFObjectHandle, you need a pair - * consisting of a qpdf_data and a qpdf_oh, which is just an index - * into an internal table of objects. All memory allocated by any - * of these functions is returned when qpdf_cleanup is called. + * To refer to a specific QPDFObjectHandle, you need a pair consisting of a qpdf_data and a + * qpdf_oh, which is just an index into an internal table of objects. All memory allocated by + * any of these functions is returned when qpdf_cleanup is called. * - * Regarding memory, the same rules apply as the above functions. - * Specifically, if a function returns a char*, the memory is - * managed by the library and, unless otherwise specified, is not + * Regarding memory, the same rules apply as the above functions. Specifically, if a function + * returns a char*, the memory is managed by the library and, unless otherwise specified, is not * expected to be valid after the next qpdf call. * - * The qpdf_data object keeps a cache of handles returned by these - * functions. Once you are finished referencing a handle, you can - * optionally release it. Releasing handles is optional since they - * will all get released by qpdf_cleanup, but it can help to - * reduce the memory footprint of the qpdf_data object to release - * them when you're done. Releasing a handle does not destroy the - * object. All QPDFObjectHandle objects are deleted when they are - * no longer referenced. Releasing an object handle simply - * invalidates it. For example, if you create an object, - * add it to an existing dictionary or array, and then release its - * handle, the object is safely part of the dictionary or array. - * Similarly, any other object handle refering to the object remains - * valid. Explicitly releasing an object handle is essentially the - * same as letting a QPDFObjectHandle go out of scope in the C++ - * API. + * The qpdf_data object keeps a cache of handles returned by these functions. Once you are + * finished referencing a handle, you can optionally release it. Releasing handles is optional + * since they will all get released by qpdf_cleanup, but it can help to reduce the memory + * footprint of the qpdf_data object to release them when you're done. Releasing a handle does + * not destroy the object. All QPDFObjectHandle objects are deleted when they are no longer + * referenced. Releasing an object handle simply invalidates it. For example, if you create an + * object, add it to an existing dictionary or array, and then release its handle, the object is + * safely part of the dictionary or array. Similarly, any other object handle refering to the + * object remains valid. Explicitly releasing an object handle is essentially the same as + * letting a QPDFObjectHandle go out of scope in the C++ API. * - * Please see "ERROR HANDLING" above for details on how error - * conditions are handled. + * Please see "ERROR HANDLING" above for details on how error conditions are handled. */ /* For examples of using this API, see examples/pdf-c-objects.c */ typedef unsigned int qpdf_oh; - /* Releasing objects -- see comments above. These functions have no - * equivalent in the C++ API. + /* Releasing objects -- see comments above. These functions have no equivalent in the C++ API. */ QPDF_DLL void qpdf_oh_release(qpdf_data qpdf, qpdf_oh oh); @@ -727,13 +644,11 @@ extern "C" { QPDF_DLL void qpdf_replace_object(qpdf_data qpdf, int objid, int generation, qpdf_oh oh); - /* Wrappers around QPDFObjectHandle methods. Be sure to read - * corresponding comments in QPDFObjectHandle.hh to understand - * what each function does and what kinds of objects it applies - * to. Note that names are to appear in a canonicalized form - * starting with a leading slash and with all PDF escaping - * resolved. See comments for getName() in QPDFObjectHandle.hh for - * details. + /* Wrappers around QPDFObjectHandle methods. Be sure to read corresponding comments in + * QPDFObjectHandle.hh to understand what each function does and what kinds of objects it + * applies to. Note that names are to appear in a canonicalized form starting with a leading + * slash and with all PDF escaping resolved. See comments for getName() in QPDFObjectHandle.hh + * for details. */ QPDF_DLL @@ -829,18 +744,14 @@ extern "C" { QPDF_BOOL qpdf_oh_get_value_as_name(qpdf_data qpdf, qpdf_oh oh, char const** value, size_t* length); - /* Return the length of the last string returned. This enables you - * to retrieve the entire string for cases in which a char* - * returned by one of the functions below points to a string with - * embedded null characters. The function - * qpdf_oh_get_binary_string_value takes a length pointer, which - * can be useful if you are retrieving the value of a string that - * is expected to contain binary data, such as a checksum or - * document ID. It is always valid to call - * qpdf_get_last_string_length, but it is usually not necessary as - * C strings returned by the library are only expected to be able - * to contain null characters if their values originate from PDF - * strings in the input. + /* Return the length of the last string returned. This enables you to retrieve the entire string + * for cases in which a char* returned by one of the functions below points to a string with + * embedded null characters. The function qpdf_oh_get_binary_string_value takes a length + * pointer, which can be useful if you are retrieving the value of a string that is expected to + * contain binary data, such as a checksum or document ID. It is always valid to call + * qpdf_get_last_string_length, but it is usually not necessary as C strings returned by the + * library are only expected to be able to contain null characters if their values originate + * from PDF strings in the input. */ QPDF_DLL size_t qpdf_get_last_string_length(qpdf_data qpdf); @@ -865,10 +776,9 @@ extern "C" { QPDF_DLL qpdf_oh qpdf_oh_get_array_item(qpdf_data qpdf, qpdf_oh oh, int n); - /* In all dictionary APIs, keys are specified/represented as - * canonicalized name strings starting with / and with all PDF - * escaping resolved. See comments for getName() in - * QPDFObjectHandle for details. + /* In all dictionary APIs, keys are specified/represented as canonicalized name strings starting + * with / and with all PDF escaping resolved. See comments for getName() in QPDFObjectHandle for + * details. */ /* "C"-specific dictionary key iteration */ @@ -878,11 +788,9 @@ extern "C" { void qpdf_oh_begin_dict_key_iter(qpdf_data qpdf, qpdf_oh dict); QPDF_DLL QPDF_BOOL qpdf_oh_dict_more_keys(qpdf_data qpdf); - /* The memory returned by qpdf_oh_dict_next_key is owned by - * qpdf_data. It is good until the next call to - * qpdf_oh_dict_next_key with the same qpdf_data object. Calling - * the function again, even with a different dict, invalidates - * previous return values. + /* The memory returned by qpdf_oh_dict_next_key is owned by qpdf_data. It is good until the next + * call to qpdf_oh_dict_next_key with the same qpdf_data object. Calling the function again, + * even with a different dict, invalidates previous return values. */ QPDF_DLL char const* qpdf_oh_dict_next_key(qpdf_data qpdf); @@ -918,8 +826,8 @@ extern "C" { qpdf_oh qpdf_oh_new_string(qpdf_data qpdf, char const* str); QPDF_DLL qpdf_oh qpdf_oh_new_unicode_string(qpdf_data qpdf, char const* utf8_str); - /* Use qpdf_oh_new_binary_string for creating a string that may - * contain atrbitary binary data including embedded null characters. + /* Use qpdf_oh_new_binary_string for creating a string that may contain atrbitary binary data + * including embedded null characters. */ QPDF_DLL qpdf_oh qpdf_oh_new_binary_string(qpdf_data qpdf, char const* str, size_t length); @@ -930,11 +838,10 @@ extern "C" { QPDF_DLL qpdf_oh qpdf_oh_new_dictionary(qpdf_data qpdf); - /* Create a new stream. Use qpdf_oh_get_dict to get (and - * subsequently modify) the stream dictionary if needed. See - * comments in QPDFObjectHandle.hh for newStream() for additional - * notes. You must call qpdf_oh_replace_stream_data to provide - * data for the stream. See STREAM FUNCTIONS below. + /* Create a new stream. Use qpdf_oh_get_dict to get (and subsequently modify) the stream + * dictionary if needed. See comments in QPDFObjectHandle.hh for newStream() for additional + * notes. You must call qpdf_oh_replace_stream_data to provide data for the stream. See STREAM + * FUNCTIONS below. */ QPDF_DLL qpdf_oh qpdf_oh_new_stream(qpdf_data qpdf); @@ -973,40 +880,33 @@ extern "C" { QPDF_DLL char const* qpdf_oh_unparse_binary(qpdf_data qpdf, qpdf_oh oh); - /* Note about foreign objects: the C API does not have enough - * information in the value of a qpdf_oh to know what QPDF object - * it belongs to. To uniquely specify a qpdf object handle from a - * specific qpdf_data instance, you always pair the qpdf_oh with - * the correct qpdf_data. Otherwise, you are likely to get - * completely the wrong object if you are not lucky enough to get - * an error about the object being invalid. + /* Note about foreign objects: the C API does not have enough information in the value of a + * qpdf_oh to know what QPDF object it belongs to. To uniquely specify a qpdf object handle from + * a specific qpdf_data instance, you always pair the qpdf_oh with the correct qpdf_data. + * Otherwise, you are likely to get completely the wrong object if you are not lucky enough to + * get an error about the object being invalid. */ - /* Copy foreign object: the qpdf_oh returned belongs to `qpdf`, - * while `foreign_oh` belongs to `other_qpdf`. + /* Copy foreign object: the qpdf_oh returned belongs to `qpdf`, while `foreign_oh` belongs to + * `other_qpdf`. */ QPDF_DLL qpdf_oh qpdf_oh_copy_foreign_object(qpdf_data qpdf, qpdf_data other_qpdf, qpdf_oh foreign_oh); /* STREAM FUNCTIONS */ - /* These functions provide basic access to streams and stream - * data. They are not as comprehensive as what is in - * QPDFObjectHandle, but they do allow for working with streams - * and stream data as caller-managed memory. + /* These functions provide basic access to streams and stream data. They are not as + * comprehensive as what is in QPDFObjectHandle, but they do allow for working with streams and + * stream data as caller-managed memory. */ - /* Get stream data as a buffer. The buffer is allocated with - * malloc and must be freed by the caller. The size of the buffer - * is stored in *len. The arguments are similar to those in - * QPDFObjectHandle::pipeStreamData. To get raw stream data, pass - * qpdf_dl_none as decode_level. Otherwise, filtering is attempted - * and *filtered is set to indicate whether it was successful. If - * *filtered is QPDF_FALSE, then raw, unfiltered stream data was - * returned. You may pass a null pointer as filtered if you don't - * care about the result. If you pass a null pointer as bufp (and - * len), the value of filtered will be set to whether the stream - * can be filterable. + /* Get stream data as a buffer. The buffer is allocated with malloc and must be freed by the + * caller. The size of the buffer is stored in *len. The arguments are similar to those in + * QPDFObjectHandle::pipeStreamData. To get raw stream data, pass qpdf_dl_none as decode_level. + * Otherwise, filtering is attempted and *filtered is set to indicate whether it was successful. + * If *filtered is QPDF_FALSE, then raw, unfiltered stream data was returned. You may pass a + * null pointer as filtered if you don't care about the result. If you pass a null pointer as + * bufp (and len), the value of filtered will be set to whether the stream can be filterable. */ QPDF_DLL QPDF_ERROR_CODE qpdf_oh_get_stream_data( @@ -1017,17 +917,16 @@ extern "C" { unsigned char** bufp, size_t* len); - /* This function returns the concatenation of all of a page's - * content streams as a single, dynamically allocated buffer. As - * with qpdf_oh_get_stream_data, the buffer is allocated with + /* This function returns the concatenation of all of a page's content streams as a single, + * dynamically allocated buffer. As with qpdf_oh_get_stream_data, the buffer is allocated with * malloc and must be freed by the caller. */ QPDF_DLL QPDF_ERROR_CODE qpdf_oh_get_page_content_data( qpdf_data qpdf, qpdf_oh page_oh, unsigned char** bufp, size_t* len); - /* The data pointed to by bufp will be copied by the library. It - * does not need to remain valid after the call returns. + /* The data pointed to by bufp will be copied by the library. It does not need to remain valid + * after the call returns. */ QPDF_DLL void qpdf_oh_replace_stream_data( @@ -1040,21 +939,18 @@ extern "C" { /* PAGE FUNCTIONS */ - /* The first time a page function is called, qpdf will traverse - * the /Pages tree. Subsequent calls to retrieve the number of - * pages or a specific page run in constant time as they are - * accessing the pages cache. If you manipulate the page tree - * outside of these functions, you should call - * qpdf_update_all_pages_cache. See comments for getAllPages() and + /* The first time a page function is called, qpdf will traverse the /Pages tree. Subsequent + * calls to retrieve the number of pages or a specific page run in constant time as they are + * accessing the pages cache. If you manipulate the page tree outside of these functions, you + * should call qpdf_update_all_pages_cache. See comments for getAllPages() and * updateAllPagesCache() in QPDF.hh. */ - /* For each function, the corresponding method in QPDF.hh is - * referenced. Please see comments in QPDF.hh for details. + /* For each function, the corresponding method in QPDF.hh is referenced. Please see comments in + * QPDF.hh for details. */ - /* calls getAllPages(). On error, returns -1 and sets error for - * qpdf_get_error. */ + /* calls getAllPages(). On error, returns -1 and sets error for qpdf_get_error. */ QPDF_DLL int qpdf_get_num_pages(qpdf_data qpdf); /* returns uninitialized object if out of range */ @@ -1065,9 +961,8 @@ extern "C" { QPDF_DLL QPDF_ERROR_CODE qpdf_update_all_pages_cache(qpdf_data qpdf); - /* findPage() -- return zero-based index. If page is not found, - * return -1 and save the error to be retrieved with - * qpdf_get_error. + /* findPage() -- return zero-based index. If page is not found, return -1 and save the error to + * be retrieved with qpdf_get_error. */ QPDF_DLL int qpdf_find_page_by_id(qpdf_data qpdf, int objid, int generation); @@ -1078,10 +973,9 @@ extern "C" { QPDF_DLL QPDF_ERROR_CODE qpdf_push_inherited_attributes_to_page(qpdf_data qpdf); - /* Functions that add pages may add pages from other files. If - * adding a page from the same file, newpage_qpdf and qpdf are the - * same. - /*/ + /* Functions that add pages may add pages from other files. If adding a page from the same file, + newpage_qpdf and qpdf are the same. + */ /* addPage() */ QPDF_DLL diff --git a/include/qpdf/qpdfjob-c.h b/include/qpdf/qpdfjob-c.h index c41dbeee..3db41d3e 100644 --- a/include/qpdf/qpdfjob-c.h +++ b/include/qpdf/qpdfjob-c.h @@ -2,33 +2,29 @@ * * 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 + * 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. + * 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. + * 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 QPDFJOB_C_H #define QPDFJOB_C_H /* - * This file defines a basic "C" API for QPDFJob. See also qpdf-c.h, - * which defines an API that exposes more of the library's API. This - * API is primarily intended to make it simpler for programs in - * languages other than C++ to incorporate functionality that could be - * run directly from the command-line. + * This file defines a basic "C" API for QPDFJob. See also qpdf-c.h, which defines an API that + * exposes more of the library's API. This API is primarily intended to make it simpler for programs + * in languages other than C++ to incorporate functionality that could be run directly from the + * command-line. */ #include @@ -40,52 +36,46 @@ #endif /* - * This file provides a minimal wrapper around QPDFJob. See - * examples/qpdfjob-c.c for an example of its use. + * This file provides a minimal wrapper around QPDFJob. See examples/qpdfjob-c.c for an example of + * its use. */ #ifdef __cplusplus extern "C" { #endif - /* SHORT INTERFACE -- These functions are single calls that take - * care of the whole life cycle of QPDFJob. They can be used for - * one-shot operations where no additional configuration is + /* SHORT INTERFACE -- These functions are single calls that take care of the whole life cycle of + * QPDFJob. They can be used for one-shot operations where no additional configuration is * needed. See FULL INTERFACE below. */ - /* This function does the equivalent of running the qpdf - * command-line with the given arguments and returns the exit code - * that qpdf would use. argv must be a null-terminated array of - * null-terminated UTF8-encoded strings. If calling this from - * wmain on Windows, use qpdfjob_run_from_wide_argv instead. Exit - * code values are defined in Constants.h in the qpdf_exit_code_e - * type. + /* This function does the equivalent of running the qpdf command-line with the given arguments + * and returns the exit code that qpdf would use. argv must be a null-terminated array of + * null-terminated UTF8-encoded strings. If calling this from wmain on Windows, use + * qpdfjob_run_from_wide_argv instead. Exit code values are defined in Constants.h in the + * qpdf_exit_code_e type. */ QPDF_DLL int qpdfjob_run_from_argv(char const* const argv[]); #ifndef QPDF_NO_WCHAR_T - /* This function is the same as qpdfjob_run_from_argv except argv - * is encoded with wide characters. This would be suitable for - * calling from a Windows wmain function. + /* This function is the same as qpdfjob_run_from_argv except argv is encoded with wide + * characters. This would be suitable for calling from a Windows wmain function. */ QPDF_DLL int qpdfjob_run_from_wide_argv(wchar_t const* const argv[]); #endif /* QPDF_NO_WCHAR_T */ - /* This function runs QPDFJob from a job JSON file. See the "QPDF - * Job" section of the manual for details. The JSON string must be - * UTF8-encoded. It returns the error code that qpdf would return - * with the equivalent command-line invocation. Exit code values - * are defined in Constants.h in the qpdf_exit_code_e type. + /* This function runs QPDFJob from a job JSON file. See the "QPDF Job" section of the manual for + * details. The JSON string must be UTF8-encoded. It returns the error code that qpdf would + * return with the equivalent command-line invocation. Exit code values are defined in + * Constants.h in the qpdf_exit_code_e type. */ QPDF_DLL int qpdfjob_run_from_json(char const* json); - /* FULL INTERFACE -- new in qpdf11. Similar to the qpdf-c.h API, - * you must call qpdfjob_init to get a qpdfjob_handle and, when - * done, call qpdfjob_cleanup to free resources. Remaining methods - * take qpdfjob_handle as an argument. This interface requires - * more calls but also offers greater flexibility. + /* FULL INTERFACE -- new in qpdf11. Similar to the qpdf-c.h API, you must call qpdfjob_init to + * get a qpdfjob_handle and, when done, call qpdfjob_cleanup to free resources. Remaining + * methods take qpdfjob_handle as an argument. This interface requires more calls but also + * offers greater flexibility. */ typedef struct _qpdfjob_handle* qpdfjob_handle; QPDF_DLL @@ -94,11 +84,9 @@ extern "C" { QPDF_DLL void qpdfjob_cleanup(qpdfjob_handle* j); - /* Set or get the current logger. You need to call - * qpdflogger_cleanup on the logger handles when you are done with - * the handles. The underlying logger is cleaned up automatically - * and persists if needed after the logger handle is destroyed. - * See comments in qpdflogger-c.h for details. + /* Set or get the current logger. You need to call qpdflogger_cleanup on the logger handles when + * you are done with the handles. The underlying logger is cleaned up automatically and persists + * if needed after the logger handle is destroyed. See comments in qpdflogger-c.h for details. */ QPDF_DLL @@ -106,62 +94,54 @@ extern "C" { QPDF_DLL qpdflogger_handle qpdfjob_get_logger(qpdfjob_handle j); - /* This function wraps QPDFJob::initializeFromArgv. The return - * value is the same as qpdfjob_run. If this returns an error, it - * is invalid to call any other functions this job handle. + /* This function wraps QPDFJob::initializeFromArgv. The return value is the same as qpdfjob_run. + * If this returns an error, it is invalid to call any other functions this job handle. */ QPDF_DLL int qpdfjob_initialize_from_argv(qpdfjob_handle j, char const* const argv[]); #ifndef QPDF_NO_WCHAR_T - /* This function is the same as qpdfjob_initialize_from_argv - * except argv is encoded with wide characters. This would be - * suitable for calling from a Windows wmain function. + /* This function is the same as qpdfjob_initialize_from_argv except argv is encoded with wide + * characters. This would be suitable for calling from a Windows wmain function. */ QPDF_DLL int qpdfjob_initialize_from_wide_argv(qpdfjob_handle j, wchar_t const* const argv[]); #endif /* QPDF_NO_WCHAR_T */ - /* This function wraps QPDFJob::initializeFromJson. The return - * value is the same as qpdfjob_run. If this returns an error, it - * is invalid to call any other functions this job handle. + /* This function wraps QPDFJob::initializeFromJson. The return value is the same as qpdfjob_run. + * If this returns an error, it is invalid to call any other functions this job handle. */ QPDF_DLL int qpdfjob_initialize_from_json(qpdfjob_handle j, char const* json); - /* This function wraps QPDFJob::run. It returns the error code - * that qpdf would return with the equivalent command-line - * invocation. Exit code values are defined in Constants.h in the + /* This function wraps QPDFJob::run. It returns the error code that qpdf would return with the + * equivalent command-line invocation. Exit code values are defined in Constants.h in the * qpdf_exit_code_e type. */ QPDF_DLL int qpdfjob_run(qpdfjob_handle j); - /* The following two functions allow a job to be run in two stages - - * creation of a qpdf_data object and writing of the qpdf_data object. This - * allows the qpdf_data object to be modified prior to writing it out. See - * examples/qpdfjob-remove-annotations for a C++ illustration of its use. + /* The following two functions allow a job to be run in two stages - creation of a qpdf_data + * object and writing of the qpdf_data object. This allows the qpdf_data object to be modified + * prior to writing it out. See examples/qpdfjob-remove-annotations for a C++ illustration of + * its use. * - * This function wraps QPDFJob::createQPDF. It runs the first stage of the - * job. A nullptr is returned if the job did not produce any pdf file to be - * written. + * This function wraps QPDFJob::createQPDF. It runs the first stage of the job. A nullptr is + * returned if the job did not produce any pdf file to be written. */ QPDF_DLL qpdf_data qpdfjob_create_qpdf(qpdfjob_handle j); - /* This function wraps QPDFJob::writeQPDF. It returns the error code that - * qpdf would return with the equivalent command-line invocation. Exit code - * values are defined in Constants.h in the qpdf_exit_code_e type. NOTE it - * is the callers responsibility to clean up the resources associated - * qpdf_data object by calling qpdf_cleanup after the call to - * qpdfjob_write_qpdf. + /* This function wraps QPDFJob::writeQPDF. It returns the error code that qpdf would return with + * the equivalent command-line invocation. Exit code values are defined in Constants.h in the + * qpdf_exit_code_e type. NOTE it is the callers responsibility to clean up the resources + * associated qpdf_data object by calling qpdf_cleanup after the call to qpdfjob_write_qpdf. */ QPDF_DLL int qpdfjob_write_qpdf(qpdfjob_handle j, qpdf_data qpdf); - /* Allow specification of a custom progress reporter. The progress - * reporter is only used if progress is otherwise requested (with - * the --progress option or "progress": "" in the JSON). + /* Allow specification of a custom progress reporter. The progress reporter is only used if + * progress is otherwise requested (with the --progress option or "progress": "" in the JSON). */ QPDF_DLL void qpdfjob_register_progress_reporter( diff --git a/include/qpdf/qpdflogger-c.h b/include/qpdf/qpdflogger-c.h index 966c47f1..ce3d87a4 100644 --- a/include/qpdf/qpdflogger-c.h +++ b/include/qpdf/qpdflogger-c.h @@ -2,30 +2,26 @@ * * 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 + * 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. + * 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. + * 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 QPDFLOGGER_H #define QPDFLOGGER_H /* - * This file provides a C API for QPDFLogger. See QPDFLogger.hh for - * information about the logger and + * This file provides a C API for QPDFLogger. See QPDFLogger.hh for information about the logger and * examples/qpdfjob-c-save-attachment.c for an example. */ @@ -36,26 +32,21 @@ extern "C" { #endif - /* To operate on a logger, you need a handle to it. call - * qpdflogger_default_logger to get a handle for the default - * logger. There are functions in qpdf-c.h and qpdfjob-c.h that - * also take or return logger handles. When you're done with the - * logger handler, call qpdflogger_cleanup. This cleans up the - * handle but leaves the underlying log object intact. (It uses a - * shared pointer and will be cleaned up automatically when it is - * no longer in use.) That means you can create a logger with - * qpdflogger_create(), pass the logger handle to a function in - * qpdf-c.h or qpdfjob-c.h, and then clean it up, subject to - * constraints imposed by the other function. + /* To operate on a logger, you need a handle to it. call qpdflogger_default_logger to get a + * handle for the default logger. There are functions in qpdf-c.h and qpdfjob-c.h that also take + * or return logger handles. When you're done with the logger handler, call qpdflogger_cleanup. + * This cleans up the handle but leaves the underlying log object intact. (It uses a shared + * pointer and will be cleaned up automatically when it is no longer in use.) That means you can + * create a logger with qpdflogger_create(), pass the logger handle to a function in qpdf-c.h or + * qpdfjob-c.h, and then clean it up, subject to constraints imposed by the other function. */ typedef struct _qpdflogger_handle* qpdflogger_handle; QPDF_DLL qpdflogger_handle qpdflogger_default_logger(); - /* Calling cleanup on the handle returned by qpdflogger_create - * destroys the handle but not the underlying logger. See comments - * above. + /* Calling cleanup on the handle returned by qpdflogger_create destroys the handle but not the + * underlying logger. See comments above. */ QPDF_DLL qpdflogger_handle qpdflogger_create(); @@ -84,8 +75,8 @@ extern "C" { void qpdflogger_set_error( qpdflogger_handle l, enum qpdf_log_dest_e dest, qpdf_log_fn_t fn, void* udata); - /* A non-zero value for only_if_not_set means that the save - * pipeline will only be changed if it is not already set. + /* A non-zero value for only_if_not_set means that the save pipeline will only be changed if it + * is not already set. */ QPDF_DLL void qpdflogger_set_save( -- cgit v1.2.3-54-g00ecf