diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/qpdf/qpdf-c.h | 43 |
1 files changed, 31 insertions, 12 deletions
diff --git a/include/qpdf/qpdf-c.h b/include/qpdf/qpdf-c.h index e261c7c1..7369e616 100644 --- a/include/qpdf/qpdf-c.h +++ b/include/qpdf/qpdf-c.h @@ -61,10 +61,12 @@ * 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. - * 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. + * + * 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 @@ -189,14 +191,6 @@ 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 @@ -716,10 +710,29 @@ extern "C" { QPDF_DLL char const* qpdf_oh_get_name(qpdf_data qpdf, qpdf_oh oh); + /* 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); + QPDF_DLL char const* qpdf_oh_get_string_value(qpdf_data qpdf, qpdf_oh oh); QPDF_DLL char const* qpdf_oh_get_utf8_value(qpdf_data qpdf, qpdf_oh oh); + QPDF_DLL + char const* qpdf_oh_get_binary_string_value( + qpdf_data qpdf, qpdf_oh oh, size_t* length); QPDF_DLL int qpdf_oh_get_array_n_items(qpdf_data qpdf, qpdf_oh oh); @@ -772,6 +785,12 @@ 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. + */ + QPDF_DLL + qpdf_oh qpdf_oh_new_binary_string( + qpdf_data qpdf, char const* str, size_t length); QPDF_DLL qpdf_oh qpdf_oh_new_array(qpdf_data qpdf); QPDF_DLL |