basic implementation of C API

git-svn-id: svn+q:///qpdf/trunk@725 71b93d88-0707-0410-a8cf-f5a4172ac649

2 files changed, 150 insertions, 43 deletions

diff --git a/include/qpdf/QPDF.hh b/include/qpdf/QPDF.hh
index 6b848f63..08f82efb 100644
--- a/include/qpdf/QPDF.hh
+++ b/include/qpdf/QPDF.hh
@@ -41,7 +41,7 @@ class QPDF
     // Prior to calling this, the only methods that are allowed are
     // those that set parameters.
     DLL_EXPORT
-    void processFile(char const* filename, char const* password = "");
+    void processFile(char const* filename, char const* password = 0);
 
     // Parameter settings
 
diff --git a/include/qpdf/qpdf-c.h b/include/qpdf/qpdf-c.h
index 57a08e54..2f0096f5 100644
--- a/include/qpdf/qpdf-c.h
+++ b/include/qpdf/qpdf-c.h
@@ -6,9 +6,59 @@
  * 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 qpdflib DLL directly or to other people
- * programming in non-C/C++ languages that can call C code but not C++
- * code.
+ * 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.
+ *
+ *     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.
+ *
+ *     All dynamic memory, except for that of the qpdf_data object
+ *     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
+ *     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 defined here merely set parameters and therefore
+ *     never return error conditions.  Functions that may cause PDF
+ *     files to be read or written may return error conditions.  Such
+ *     functions return an error code.  If there were no errors or
+ *     warnings, they return QPDF_SUCCESS.  If there were warnings,
+ *     the return value has the QPDF_WARNINGS bit set.  If there
+ *     errors, the QPDF_ERRORS bit is set.  In other words, if there
+ *     are both warnings and errors, then the return status will be
+ *     QPDF_WARNINGS | QPDF_ERRORS.  You may also call the
+ *     qpdf_more_warnings and qpdf_more_errors functions to test
+ *     whether there are unseen warning or error conditions.  By
+ *     default, warnings are written to stderr when detected, but this
+ *     behavior can be suppressed.  In all cases, errors and warnings
+ *     may be retrieved by calling qpdf_next_warning and
+ *     qpdf_next_error.  All exceptions thrown by the C++ interface
+ *     are caught and converted into error messages by the C
+ *     interface.
+ *
+ *     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.
  */
 
 #include <qpdf/DLL.hh>
@@ -20,34 +70,26 @@ extern "C" {
     typedef struct _qpdf_data* qpdf_data;
 
     /* Many functions return an integer error code.  Codes are defined
-     * below.  See ERROR REPORTING below.
+     * 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
-#   define QPDF_WARNINGS 1
-#   define QPDF_ERRORS 2
+#   define QPDF_WARNINGS 1 << 0
+#   define QPDF_ERRORS 1 << 1
 
     typedef int QPDF_BOOL;
 #   define QPDF_TRUE 1
 #   define QPDF_FALSE 0
 
     /* Returns dynamically allocated qpdf_data pointer; must be freed
-     * by calling qpdf_cleanup.  Note that qpdf_data is 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.  Many functions
-     * defined below 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 some cases,
-     * strings returned by functions here may be overwritten by
-     * additional function calls, so if you really want a string to
-     * last past the next qpdf call, you should make a copy of it.
+     * by calling qpdf_cleanup.
      */
     DLL_EXPORT
     qpdf_data qpdf_init();
 
     /* Pass a pointer to the qpdf_data pointer created by qpdf_init to
-     * clean up resoures.
+     * clean up resources.
      */
     DLL_EXPORT
     void qpdf_cleanup(qpdf_data* qpdf);
@@ -59,40 +101,45 @@ extern "C" {
      */
     DLL_EXPORT
     QPDF_BOOL qpdf_more_errors(qpdf_data qpdf);
-
-    /* If there are any errors, returns a pointer to the next error.
-     * Otherwise returns a null pointer.  The error value returned is
-     * a pointer to data inside the qpdf_data object.  It will become
-     * valid the next time a qpdf function that returns a string is
-     * called or after a call to qpdf_cleanup.
-     */
     DLL_EXPORT
-    char const* qpdf_next_error(qpdf_data qpdf);
+    QPDF_BOOL qpdf_more_warnings(qpdf_data qpdf);
 
-    /* These functions are analogous to the "error" counterparts but
-     * apply to warnings.
+    /* If there are any errors/warnings, returns a pointer to the next
+     * error or warning.  Otherwise returns a null pointer.
      */
-
     DLL_EXPORT
-    QPDF_BOOL qpdf_more_warnings(qpdf_data qpdf);
+    char const* qpdf_next_error(qpdf_data qpdf);
     DLL_EXPORT
     char const* qpdf_next_warning(qpdf_data qpdf);
 
-    /* READ PARAMETER FUNCTIONS */
-
     /* 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.
-    */
+     * this function will prevent warnings from being written to
+     * stderr.  They will still be available by calls to
+     * qpdf_next_warning.
+     */
     DLL_EXPORT
-    void qpdf_set_suppress_warnings(qpdf_data qpdf, QPDF_BOOL val);
+    void qpdf_set_suppress_warnings(qpdf_data qpdf, QPDF_BOOL value);
 
     /* READ FUNCTIONS */
 
-    /* POST-READ QUERY FUNCTIONS */
+    /* READ PARAMETER FUNCTIONS -- must be called before qpdf_read */
 
-    /* These functions are invalid until after qpdf_read has been
-     * called. */
+    DLL_EXPORT
+    void qpdf_set_ignore_xref_streams(qpdf_data qpdf, QPDF_BOOL value);
+
+    DLL_EXPORT
+    void qpdf_set_attempt_recovery(qpdf_data qpdf, QPDF_BOOL value);
+
+    /* 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.
+     */
+    DLL_EXPORT
+    QPDF_ERROR_CODE qpdf_read(qpdf_data qpdf, char const* filename,
+			      char const* password);
+
+    /* Read functions below must be called after qpdf_read. */
 
     /* Return the version of the PDF file. */
     DLL_EXPORT
@@ -126,13 +173,73 @@ extern "C" {
      * until the call to qpdf_write.
      */
     DLL_EXPORT
-    QPDF_ERROR_CODE qpdf_init_write(qpdf_data data, char const* filename);
+    QPDF_ERROR_CODE qpdf_init_write(qpdf_data qpdf, char const* filename);
+
+#   define QPDF_OBJECT_STREAM_DISABLE 0
+#   define QPDF_OBJECT_STREAM_PRESERVE 1
+#   define QPDF_OBJECT_STREAM_GENERATE 2
+
+    /* For mode, pass one of the QPDF_OBJECT_STREAM constants. */
+    DLL_EXPORT
+    void qpdf_set_object_stream_mode(qpdf_data qpdf, int mode);
 
-    /* XXX Get public interface from QPDFWriter */
+#   define QPDF_STREAM_DATA_UNCOMPRESS 0
+#   define QPDF_STREAM_DATA_PRESERVE 1
+#   define QPDF_STREAM_DATA_COMPRESS 2
+    /* For mode, pass one of the QPDF_STREAM_DATA constants. */
+    DLL_EXPORT
+    void qpdf_set_stream_data_mode(qpdf_data qpdf, int mode);
+
+    DLL_EXPORT
+    void qpdf_set_content_normalization(qpdf_data qpdf, QPDF_BOOL value);
+
+    DLL_EXPORT
+    void qpdf_set_qdf_mode(qpdf_data qpdf, QPDF_BOOL value);
+
+    /* Never use qpdf_set_static_ID except in test suites to suppress
+     * generation of a random /ID.
+     */
+    DLL_EXPORT
+    void qpdf_set_static_ID(qpdf_data qpdf, QPDF_BOOL value);
+
+    DLL_EXPORT
+    void qpdf_set_suppress_original_object_IDs(
+	qpdf_data qpdf, QPDF_BOOL value);
+
+    DLL_EXPORT
+    void qpdf_set_preserve_encryption(qpdf_data qpdf, QPDF_BOOL value);
+
+    DLL_EXPORT
+    void qpdf_set_r2_encryption_parameters(
+	qpdf_data qpdf, char const* user_password, char const* owner_password,
+	QPDF_BOOL allow_print, QPDF_BOOL allow_modify,
+	QPDF_BOOL allow_extract, QPDF_BOOL allow_annotate);
+
+#   define QPDF_R3_PRINT_FULL 0
+#   define QPDF_R3_PRINT_LOW 1
+#   define QPDF_R3_PRINT_NONE 2
+
+#   define QPDF_R3_MODIFY_ALL 0
+#   define QPDF_R3_MODIFY_ANNOTATE 1
+#   define QPDF_R3_MODIFY_FORM 2
+#   define QPDF_R3_MODIFY_ASSEMBLY 3
+#   define QPDF_R3_MODIFY_NONE 4
+
+    /* Value of print should be one of the QPDF_R3_PRINT constants.
+     * Value of modify should be one of the QPDF_R3_MODIFY constants.
+     */
+    DLL_EXPORT
+    void qpdf_set_r3_encryption_parameters(
+	qpdf_data qpdf, char const* user_password, char const* owner_password,
+	QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract,
+	int print, int modify);
+
+    DLL_EXPORT
+    void qpdf_set_linearization(qpdf_data qpdf, QPDF_BOOL value);
 
-    /* Perform the actual write operation. */
+    /* Do actual write operation. */
     DLL_EXPORT
-    QPDF_ERROR_CODE qpdf_write();
+    QPDF_ERROR_CODE qpdf_write(qpdf_data qpdf);
 
 #ifdef __cplusplus
 }