C API: qpdf_get_last_string_length

ChangeLog

@@ -1,3 +1,9 @@
+2021-12-02  Jay Berkenbilt  <ejb@ql.org>
+
+	* C API: Add qpdf_get_last_string_length to return the length of
+	the last string returned. This is necessary in order to fully
+	retrieve values of strings that may contain embedded null characters.
+
 2021-11-16  Jay Berkenbilt  <ejb@ql.org>
 
 	* 10.4.0: release

TODO

@@ -1,9 +1,3 @@
-Next
-====
-
-* Add a method to the C API that returns the length of tmp_str so that
-  we can handle strings with embedded null characters.
-
 Documentation
 =============
 

include/qpdf/qpdf-c.h

@@ -49,14 +49,17 @@
  *     itself, is managed by the library.  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
+ *     Many functions return char*. In all cases, the char* values
- *     returned are pointers to data inside the qpdf_data object.  As
+ *     returned are pointers to data inside the qpdf_data object. As
- *     such, they are always freed by qpdf_cleanup.  In most cases,
+ *     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
+ *     functions. If you want a string to last past the next qpdf call
- *     call or after a call to qpdf_cleanup, you should make a copy of
+ *     or after a call to qpdf_cleanup, you should make a copy of it.
- *     it.
+ *     It is possible for the internal string data to contain null
+ *     characters. To handle that case, you call
+ *     qpdf_get_last_string_length() to get the length of whatever
+ *     string was just returned.
  *
  *     Many functions defined here merely set parameters and therefore
  *     never return error conditions.  Functions that may cause PDF
@@ -126,6 +129,14 @@ extern "C" {
     QPDF_DLL
     void qpdf_cleanup(qpdf_data* qpdf);
 
+    /* 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.
+     */
+    QPDF_DLL
+    size_t qpdf_get_last_string_length(qpdf_data qpdf);
+
     /* ERROR REPORTING */
 
     /* Returns 1 if there is an error condition.  The error condition

libqpdf/qpdf-c.cc

@@ -172,6 +172,11 @@ void qpdf_cleanup(qpdf_data* qpdf)
     *qpdf = 0;
 }
 
+size_t qpdf_get_last_string_length(qpdf_data qpdf)
+{
+    return qpdf->tmp_string.length();
+}
+
 QPDF_BOOL qpdf_more_warnings(qpdf_data qpdf)
 {
     QTC::TC("qpdf", "qpdf-c called qpdf_more_warnings");

manual/qpdf-manual.xml

@@ -5116,6 +5116,28 @@ print "\n";
     </listitem>
    </varlistentry>
 -->
+   <varlistentry>
+    <term>10.5.0: XXX Month dd, YYYY</term>
+    <listitem>
+     <itemizedlist>
+      <listitem>
+       <para>
+        Library Enhancements
+       </para>
+       <itemizedlist>
+        <listitem>
+         <para>
+          Add <function>qpdf_get_last_string_length</function> to the
+          C API to get the length of the last string that was
+          returned. This is needed to handle strings that contain
+          embedded null characters.
+         </para>
+        </listitem>
+       </itemizedlist>
+      </listitem>
+     </itemizedlist>
+    </listitem>
+   </varlistentry>
    <varlistentry>
     <term>10.4.0: November 16, 2021</term>
     <listitem>

qpdf/qpdf-ctest.c

@@ -613,6 +613,13 @@ static void test24(char const* infile,
            (strcmp(qpdf_oh_get_string_value(qpdf, p_string), "3\xf7") == 0) &&
            (strcmp(qpdf_oh_get_utf8_value(qpdf, p_string), "3\xc3\xb7") == 0) &&
            (strcmp(qpdf_oh_unparse_binary(qpdf, p_string), "<33f7>") == 0));
+    qpdf_oh p_string_with_null = qpdf_oh_parse(qpdf, "<6f6e650074776f>");
+    assert(qpdf_oh_is_string(qpdf, p_string_with_null) &&
+           (strcmp(qpdf_oh_get_string_value(qpdf, p_string_with_null),
+                   "one") == 0) &&
+           (qpdf_get_last_string_length(qpdf) == 7) &&
+           (memcmp(qpdf_oh_get_string_value(qpdf, p_string_with_null),
+                   "one\000two", 7) == 0));
     assert(qpdf_oh_is_dictionary(qpdf, p_dict));
     qpdf_oh p_five = qpdf_oh_get_key(qpdf, p_dict, "/Four");
     assert(qpdf_oh_is_or_has_name(qpdf, p_five, "/Five"));