From 84ec83e92589461e6da68029ed7148ba48198215 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Sun, 27 Sep 2009 14:39:04 +0000 Subject: basic implementation of C API git-svn-id: svn+q:///qpdf/trunk@725 71b93d88-0707-0410-a8cf-f5a4172ac649 --- include/qpdf/QPDF.hh | 2 +- include/qpdf/qpdf-c.h | 191 +++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 150 insertions(+), 43 deletions(-) (limited to 'include') 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 @@ -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 } -- cgit v1.2.3-54-g00ecf