From 4630b8567c853e0a05d41f15b701c370f660250f Mon Sep 17 00:00:00 2001 From: m-holger Date: Fri, 19 Nov 2021 13:22:47 +0000 Subject: Ensure qpdf_oh handles returned by C-API functions are unique. Return new qpdf_oh from qpdf_oh_wrap_in_array when input is already an array. Update some doc comments in qpdf-c.h. --- include/qpdf/qpdf-c.h | 40 ++++++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 18 deletions(-) (limited to 'include/qpdf/qpdf-c.h') diff --git a/include/qpdf/qpdf-c.h b/include/qpdf/qpdf-c.h index e917e90a..cf32976f 100644 --- a/include/qpdf/qpdf-c.h +++ b/include/qpdf/qpdf-c.h @@ -134,7 +134,7 @@ extern "C" { /* 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_destroy. After this + * 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. @@ -201,7 +201,7 @@ extern "C" { /* 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 as the password. + * pointer or an empty string as the password. */ QPDF_DLL QPDF_ERROR_CODE qpdf_read(qpdf_data qpdf, char const* filename, @@ -489,16 +489,19 @@ extern "C" { /* Object handling. * - * These methods take and return a qpdf_oh, which is just an - * unsigned integer. The value 0 is never returned, which makes it - * usable as an uninitialized value. + * 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 argumens, the C - * method will have required arguments in those positions. For + * 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. @@ -514,25 +517,26 @@ extern "C" { * 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 methods is returned when qpdf_cleanup is called. + * of these functions is returned when qpdf_cleanup is called. * * Regarding memory, the same rules apply as the above functions. - * Specifically, if a method returns a char*, the memory is + * 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 objects returned by these - * methods. Once you are finished referencing an object, you can - * optionally release it. Releasing objects is optional since they + * The qpdf_data object keeps a cache of handles returned by these + * functions. Once you are finished referencing an 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 an object does not destroy the + * 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 simply invalidates - * the qpdf_oh handle to it. For example, if you create an object, - * add it to an existing dictionary or array, and then release it, - * the object is safely part of the dictionary or array. - * Explicitly releasing an object is essentially the same as + * 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 it's + * 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 is essentially the same as * letting a QPDFObjectHandle go out of scope in the C++ API. */ @@ -540,7 +544,7 @@ extern "C" { typedef unsigned int qpdf_oh; - /* Releasing objects -- see comments above. These methods have no + /* Releasing objects -- see comments above. These functions have no * equivalent in the C++ API. */ QPDF_DLL -- cgit v1.2.3-54-g00ecf