1 /* Copyright (c) 2005-2021 Jay Berkenbilt 2 * 3 * This file is part of qpdf. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 * Versions of qpdf prior to version 7 were released under the terms 18 * of version 2.0 of the Artistic License. At your option, you may 19 * continue to consider qpdf to be licensed under those terms. Please 20 * see the manual for additional information. 21 */ 22 23 #ifndef QPDF_C_H 24 #define QPDF_C_H 25 26 /* 27 * This file defines a basic "C" API for qpdf. It provides access to 28 * a subset of the QPDF library's capabilities to make them accessible 29 * to callers who can't handle calling C++ functions or working with 30 * C++ classes. This may be especially useful to Windows users who 31 * are accessing the qpdf DLL directly or to other people programming 32 * in non-C/C++ languages that can call C code but not C++ code. 33 * 34 * There are several things to keep in mind when using the C API. 35 * 36 * Error handling is tricky because the underlying C++ API uses 37 * exception handling. See "ERROR HANDLING" below for a detailed 38 * explanation. 39 * 40 * The C API is not as rich as the C++ API. For any operations 41 * that involve actually manipulating PDF objects, you must use 42 * the C++ API. The C API is primarily useful for doing basic 43 * transformations on PDF files similar to what you might do with 44 * the qpdf command-line tool. 45 * 46 * These functions store their state in a qpdf_data object. 47 * Individual instances of qpdf_data are not thread-safe: although 48 * you may access different qpdf_data objects from different 49 * threads, you may not access one qpdf_data simultaneously from 50 * multiple threads. 51 * 52 * All dynamic memory, except for that of the qpdf_data object 53 * itself, is managed by the library unless otherwise noted. You 54 * must create a qpdf_data object using qpdf_init and free it 55 * using qpdf_cleanup. 56 * 57 * Many functions return char*. In all cases, the char* values 58 * returned are pointers to data inside the qpdf_data object. As 59 * such, they are always freed by qpdf_cleanup. In most cases, 60 * strings returned by functions here may be invalidated by 61 * subsequent function calls, sometimes even to different 62 * functions. If you want a string to last past the next qpdf call 63 * or after a call to qpdf_cleanup, you should make a copy of it. 64 * 65 * Since it is possible for a PDF string to contain null 66 * characters, a function that returns data originating from a PDF 67 * string may also contain null characters. To handle that case, 68 * you call qpdf_get_last_string_length() to get the length of 69 * whatever string was just returned. See STRING FUNCTIONS below. 70 * 71 * Most functions defined here have obvious counterparts that are 72 * methods to either QPDF or QPDFWriter. Please see comments in 73 * QPDF.hh and QPDFWriter.hh for details on their use. In order 74 * to avoid duplication of information, comments here focus 75 * primarily on differences between the C and C++ API. 76 */ 77 78 /* ERROR HANDLING -- changed in qpdf 10.5 */ 79 80 /* SUMMARY: The only way to know whether a function that does not 81 * return an error code has encountered an error is to call 82 * qpdf_has_error after each function. You can do this even for 83 * functions that do return error codes. You can also call 84 * qpdf_silence_errors to prevent qpdf from writing these errors to 85 * stderr. 86 * 87 * DETAILS: 88 * 89 * The data type underlying qpdf_data maintains a list of warnings and 90 * a single error. To retrieve warnings, call qpdf_next_warning while 91 * qpdf_more_warnings is true. To retrieve the error, call 92 * qpdf_get_error when qpdf_has_error is true. 93 * 94 * There are several things that are important to understand. 95 * 96 * Some functions return an error code. The value of the error code is 97 * made up of a bitwise-OR of QPDF_WARNINGS and QPDF_ERRORS. The 98 * QPDF_ERRORS bit is set if there was an error during the *most 99 * recent call* to the API. The QPDF_WARNINGS bit is set if there are 100 * any warnings that have not yet been retrieved by calling 101 * qpdf_more_warnings. It is possible for both its or neither bit to 102 * be set. 103 * 104 * The expected mode of operation is to go through a series of 105 * operations, checking for errors after each call, but only checking 106 * for warnings at the end. This is similar to how it works in the C++ 107 * API where warnings are handled in exactly this way but errors 108 * result in exceptions being thrown. However, in both the C and C++ 109 * API, it is possible to check for and handle warnings as they arise. 110 * 111 * Some functions return values (or void) rather than an error code. 112 * This is especially true with the object handling functions. Those 113 * functions can still generate errors. To handle errors in those 114 * cases, you should explicitly call qpdf_has_error(). Note that, if 115 * you want to avoid the inconsistencies in the interface, you can 116 * always check for error conditions in this way rather than looking 117 * at status return codes. 118 * 119 * Prior to qpdf 10.5, if one of the functions that does not return an 120 * error code encountered an exception, it would cause the entire 121 * program to crash. Starting in qpdf 10.5, the default response to an 122 * error condition in these situations is to print the error to 123 * standard error, issue exactly one warning indicating that such an 124 * error occurred, and return a sensible fallback value (0 for 125 * numbers, QPDF_FALSE for booleans, "" for strings, or a null or 126 * uninitialized object handle). This is better than the old behavior 127 * but still undesirable as the best option is to explicitly check for 128 * error conditions. 129 * 130 * To prevent qpdf from writing error messages to stderr in this way, 131 * you can call qpdf_silence_errors(). This signals to the qpdf 132 * library that you intend to check the error codes yourself. 133 * 134 * If you encounter a situation where an exception from the C++ code 135 * is not properly converted to an error as described above, it is a 136 * bug in qpdf, which should be reported at 137 * https://github.com/qpdf/qpdf/issues/new. 138 */ 139 140 #include <qpdf/DLL.h> 141 #include <qpdf/Types.h> 142 #include <qpdf/Constants.h> 143 #include <string.h> 144 145 #ifdef __cplusplus 146 extern "C" { 147 #endif 148 149 typedef struct _qpdf_data* qpdf_data; 150 typedef struct _qpdf_error* qpdf_error; 151 152 /* Many functions return an integer error code. Codes are defined 153 * below. See comments at the top of the file for details. Note 154 * that the values below can be logically orred together. 155 */ 156 typedef int QPDF_ERROR_CODE; 157 # define QPDF_SUCCESS 0 158 # define QPDF_WARNINGS 1 << 0 159 # define QPDF_ERRORS 1 << 1 160 161 typedef int QPDF_BOOL; 162 # define QPDF_TRUE 1 163 # define QPDF_FALSE 0 164 165 /* From qpdf 10.5: call this method to signal to the library that 166 * you are explicitly handling errors from functions that don't 167 * return error codes. Otherwise, the library will print these 168 * error conditions to stderr and issue a warning. Prior to 10.5, 169 * the program would have crashed from an unhandled exception. 170 */ 171 QPDF_DLL 172 void qpdf_silence_errors(qpdf_data qpdf); 173 174 /* Returns the version of the qpdf software */ 175 QPDF_DLL 176 char const* qpdf_get_qpdf_version(); 177 178 /* Returns dynamically allocated qpdf_data pointer; must be freed 179 * by calling qpdf_cleanup. You must call qpdf_read or one of the 180 * other qpdf_read_* functions before calling any function that 181 * would need to operate on the PDF file. 182 */ 183 QPDF_DLL 184 qpdf_data qpdf_init(); 185 186 /* Pass a pointer to the qpdf_data pointer created by qpdf_init to 187 * clean up resources. This does not include buffers initialized 188 * by functions that return stream data but it otherwise includes 189 * all data associated with the QPDF object or any object handles. 190 */ 191 QPDF_DLL 192 void qpdf_cleanup(qpdf_data* qpdf); 193 194 /* ERROR REPORTING */ 195 196 /* Returns 1 if there is an error condition. The error condition 197 * can be retrieved by a single call to qpdf_get_error. 198 */ 199 QPDF_DLL 200 QPDF_BOOL qpdf_has_error(qpdf_data qpdf); 201 202 /* Returns the error condition, if any. The return value is a 203 * pointer to data that will become invalid after the next call to 204 * this function, qpdf_next_warning, or qpdf_cleanup. After this 205 * function is called, qpdf_has_error will return QPDF_FALSE until 206 * the next error condition occurs. If there is no error 207 * condition, this function returns a null pointer. 208 */ 209 QPDF_DLL 210 qpdf_error qpdf_get_error(qpdf_data qpdf); 211 212 /* Returns 1 if there are any unretrieved warnings, and zero 213 * otherwise. 214 */ 215 QPDF_DLL 216 QPDF_BOOL qpdf_more_warnings(qpdf_data qpdf); 217 218 /* If there are any warnings, returns a pointer to the next 219 * warning. Otherwise returns a null pointer. 220 */ 221 QPDF_DLL 222 qpdf_error qpdf_next_warning(qpdf_data qpdf); 223 224 /* Extract fields of the error. */ 225 226 /* Use this function to get a full error message suitable for 227 * showing to the user. */ 228 QPDF_DLL 229 char const* qpdf_get_error_full_text(qpdf_data q, qpdf_error e); 230 231 /* Use these functions to extract individual fields from the 232 * error; see QPDFExc.hh for details. */ 233 QPDF_DLL 234 enum qpdf_error_code_e qpdf_get_error_code(qpdf_data q, qpdf_error e); 235 QPDF_DLL 236 char const* qpdf_get_error_filename(qpdf_data q, qpdf_error e); 237 QPDF_DLL 238 unsigned long long qpdf_get_error_file_position(qpdf_data q, qpdf_error e); 239 QPDF_DLL 240 char const* qpdf_get_error_message_detail(qpdf_data q, qpdf_error e); 241 242 /* By default, warnings are written to stderr. Passing true to 243 * this function will prevent warnings from being written to 244 * stderr. They will still be available by calls to 245 * qpdf_next_warning. 246 */ 247 QPDF_DLL 248 void qpdf_set_suppress_warnings(qpdf_data qpdf, QPDF_BOOL value); 249 250 /* CHECK FUNCTIONS */ 251 252 /* Attempt to read the entire PDF file to see if there are any 253 * errors qpdf can detect. 254 */ 255 QPDF_DLL 256 QPDF_ERROR_CODE qpdf_check_pdf(qpdf_data qpdf); 257 258 /* READ FUNCTIONS */ 259 260 /* READ PARAMETER FUNCTIONS -- must be called before qpdf_read */ 261 262 QPDF_DLL 263 void qpdf_set_ignore_xref_streams(qpdf_data qpdf, QPDF_BOOL value); 264 265 QPDF_DLL 266 void qpdf_set_attempt_recovery(qpdf_data qpdf, QPDF_BOOL value); 267 268 /* Calling qpdf_read causes processFile to be called in the C++ 269 * API. Basic parsing is performed, but data from the file is 270 * only read as needed. For files without passwords, pass a null 271 * pointer or an empty string as the password. 272 */ 273 QPDF_DLL 274 QPDF_ERROR_CODE qpdf_read(qpdf_data qpdf, char const* filename, 275 char const* password); 276 277 /* Calling qpdf_read_memory causes processMemoryFile to be called 278 * in the C++ API. Otherwise, it behaves in the same way as 279 * qpdf_read. The description argument will be used in place of 280 * the file name in any error or warning messages generated by the 281 * library. 282 */ 283 QPDF_DLL 284 QPDF_ERROR_CODE qpdf_read_memory(qpdf_data qpdf, 285 char const* description, 286 char const* buffer, 287 unsigned long long size, 288 char const* password); 289 290 /* Read functions below must be called after qpdf_read or 291 * qpdf_read_memory. */ 292 293 /* 294 * NOTE: Functions that return char* are returning a pointer to an 295 * internal buffer that will be reused for each call to a function 296 * that returns a char*. You must use or copy the value before 297 * calling any other qpdf library functions. 298 */ 299 300 /* Return the version of the PDF file. See warning above about 301 * functions that return char*. */ 302 QPDF_DLL 303 char const* qpdf_get_pdf_version(qpdf_data qpdf); 304 305 /* Return the extension level of the PDF file. */ 306 QPDF_DLL 307 int qpdf_get_pdf_extension_level(qpdf_data qpdf); 308 309 /* Return the user password. If the file is opened using the 310 * owner password, the user password may be retrieved using this 311 * function. If the file is opened using the user password, this 312 * function will return that user password. See warning above 313 * about functions that return char*. 314 */ 315 QPDF_DLL 316 char const* qpdf_get_user_password(qpdf_data qpdf); 317 318 /* Return the string value of a key in the document's Info 319 * dictionary. The key parameter should include the leading 320 * slash, e.g. "/Author". If the key is not present or has a 321 * non-string value, a null pointer is returned. Otherwise, a 322 * pointer to an internal buffer is returned. See warning above 323 * about functions that return char*. 324 */ 325 QPDF_DLL 326 char const* qpdf_get_info_key(qpdf_data qpdf, char const* key); 327 328 /* Set a value in the info dictionary, possibly replacing an 329 * existing value. The key must include the leading slash 330 * (e.g. "/Author"). Passing a null pointer as a value will 331 * remove the key from the info dictionary. Otherwise, a copy 332 * will be made of the string that is passed in. 333 */ 334 QPDF_DLL 335 void qpdf_set_info_key(qpdf_data qpdf, char const* key, char const* value); 336 337 /* Indicate whether the input file is linearized. */ 338 QPDF_DLL 339 QPDF_BOOL qpdf_is_linearized(qpdf_data qpdf); 340 341 /* Indicate whether the input file is encrypted. */ 342 QPDF_DLL 343 QPDF_BOOL qpdf_is_encrypted(qpdf_data qpdf); 344 345 QPDF_DLL 346 QPDF_BOOL qpdf_allow_accessibility(qpdf_data qpdf); 347 QPDF_DLL 348 QPDF_BOOL qpdf_allow_extract_all(qpdf_data qpdf); 349 QPDF_DLL 350 QPDF_BOOL qpdf_allow_print_low_res(qpdf_data qpdf); 351 QPDF_DLL 352 QPDF_BOOL qpdf_allow_print_high_res(qpdf_data qpdf); 353 QPDF_DLL 354 QPDF_BOOL qpdf_allow_modify_assembly(qpdf_data qpdf); 355 QPDF_DLL 356 QPDF_BOOL qpdf_allow_modify_form(qpdf_data qpdf); 357 QPDF_DLL 358 QPDF_BOOL qpdf_allow_modify_annotation(qpdf_data qpdf); 359 QPDF_DLL 360 QPDF_BOOL qpdf_allow_modify_other(qpdf_data qpdf); 361 QPDF_DLL 362 QPDF_BOOL qpdf_allow_modify_all(qpdf_data qpdf); 363 364 /* WRITE FUNCTIONS */ 365 366 /* Set up for writing. No writing is actually performed until the 367 * call to qpdf_write(). 368 */ 369 370 /* Supply the name of the file to be written and initialize the 371 * qpdf_data object to handle writing operations. This function 372 * also attempts to create the file. The PDF data is not written 373 * until the call to qpdf_write. qpdf_init_write may be called 374 * multiple times for the same qpdf_data object. When 375 * qpdf_init_write is called, all information from previous calls 376 * to functions that set write parameters (qpdf_set_linearization, 377 * etc.) is lost, so any write parameter functions must be called 378 * again. 379 */ 380 QPDF_DLL 381 QPDF_ERROR_CODE qpdf_init_write(qpdf_data qpdf, char const* filename); 382 383 /* Initialize for writing but indicate that the PDF file should be 384 * written to memory. Call qpdf_get_buffer_length and 385 * qpdf_get_buffer to retrieve the resulting buffer. The memory 386 * containing the PDF file will be destroyed when qpdf_cleanup is 387 * called. 388 */ 389 QPDF_DLL 390 QPDF_ERROR_CODE qpdf_init_write_memory(qpdf_data qpdf); 391 392 /* Retrieve the buffer used if the file was written to memory. 393 * qpdf_get_buffer returns a null pointer if data was not written 394 * to memory. The memory is freed when qpdf_cleanup is called or 395 * if a subsequent call to qpdf_init_write or 396 * qpdf_init_write_memory is called. */ 397 QPDF_DLL 398 size_t qpdf_get_buffer_length(qpdf_data qpdf); 399 QPDF_DLL 400 unsigned char const* qpdf_get_buffer(qpdf_data qpdf); 401 402 QPDF_DLL 403 void qpdf_set_object_stream_mode(qpdf_data qpdf, 404 enum qpdf_object_stream_e mode); 405 406 QPDF_DLL 407 void qpdf_set_stream_data_mode(qpdf_data qpdf, 408 enum qpdf_stream_data_e mode); 409 410 QPDF_DLL 411 void qpdf_set_compress_streams(qpdf_data qpdf, QPDF_BOOL value); 412 413 414 QPDF_DLL 415 void qpdf_set_decode_level(qpdf_data qpdf, 416 enum qpdf_stream_decode_level_e level); 417 418 QPDF_DLL 419 void qpdf_set_preserve_unreferenced_objects( 420 qpdf_data qpdf, QPDF_BOOL value); 421 422 QPDF_DLL 423 void qpdf_set_newline_before_endstream(qpdf_data qpdf, QPDF_BOOL value); 424 425 QPDF_DLL 426 void qpdf_set_content_normalization(qpdf_data qpdf, QPDF_BOOL value); 427 428 QPDF_DLL 429 void qpdf_set_qdf_mode(qpdf_data qpdf, QPDF_BOOL value); 430 431 QPDF_DLL 432 void qpdf_set_deterministic_ID(qpdf_data qpdf, QPDF_BOOL value); 433 434 /* Never use qpdf_set_static_ID except in test suites to suppress 435 * generation of a random /ID. See also qpdf_set_deterministic_ID. 436 */ 437 QPDF_DLL 438 void qpdf_set_static_ID(qpdf_data qpdf, QPDF_BOOL value); 439 440 /* Never use qpdf_set_static_aes_IV except in test suites to 441 * create predictable AES encrypted output. 442 */ 443 QPDF_DLL 444 void qpdf_set_static_aes_IV(qpdf_data qpdf, QPDF_BOOL value); 445 446 QPDF_DLL 447 void qpdf_set_suppress_original_object_IDs( 448 qpdf_data qpdf, QPDF_BOOL value); 449 450 QPDF_DLL 451 void qpdf_set_preserve_encryption(qpdf_data qpdf, QPDF_BOOL value); 452 453 QPDF_DLL 454 void qpdf_set_r2_encryption_parameters( 455 qpdf_data qpdf, char const* user_password, char const* owner_password, 456 QPDF_BOOL allow_print, QPDF_BOOL allow_modify, 457 QPDF_BOOL allow_extract, QPDF_BOOL allow_annotate); 458 459 QPDF_DLL 460 void qpdf_set_r3_encryption_parameters2( 461 qpdf_data qpdf, char const* user_password, char const* owner_password, 462 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 463 QPDF_BOOL allow_assemble, QPDF_BOOL allow_annotate_and_form, 464 QPDF_BOOL allow_form_filling, QPDF_BOOL allow_modify_other, 465 enum qpdf_r3_print_e print); 466 467 QPDF_DLL 468 void qpdf_set_r4_encryption_parameters2( 469 qpdf_data qpdf, char const* user_password, char const* owner_password, 470 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 471 QPDF_BOOL allow_assemble, QPDF_BOOL allow_annotate_and_form, 472 QPDF_BOOL allow_form_filling, QPDF_BOOL allow_modify_other, 473 enum qpdf_r3_print_e print, 474 QPDF_BOOL encrypt_metadata, QPDF_BOOL use_aes); 475 476 QPDF_DLL 477 void qpdf_set_r5_encryption_parameters2( 478 qpdf_data qpdf, char const* user_password, char const* owner_password, 479 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 480 QPDF_BOOL allow_assemble, QPDF_BOOL allow_annotate_and_form, 481 QPDF_BOOL allow_form_filling, QPDF_BOOL allow_modify_other, 482 enum qpdf_r3_print_e print, QPDF_BOOL encrypt_metadata); 483 484 QPDF_DLL 485 void qpdf_set_r6_encryption_parameters2( 486 qpdf_data qpdf, char const* user_password, char const* owner_password, 487 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 488 QPDF_BOOL allow_assemble, QPDF_BOOL allow_annotate_and_form, 489 QPDF_BOOL allow_form_filling, QPDF_BOOL allow_modify_other, 490 enum qpdf_r3_print_e print, QPDF_BOOL encrypt_metadata); 491 492 /* Pre 8.4.0 encryption API */ 493 QPDF_DLL 494 void qpdf_set_r3_encryption_parameters( 495 qpdf_data qpdf, char const* user_password, char const* owner_password, 496 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 497 enum qpdf_r3_print_e print, enum qpdf_r3_modify_e modify); 498 499 QPDF_DLL 500 void qpdf_set_r4_encryption_parameters( 501 qpdf_data qpdf, char const* user_password, char const* owner_password, 502 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 503 enum qpdf_r3_print_e print, enum qpdf_r3_modify_e modify, 504 QPDF_BOOL encrypt_metadata, QPDF_BOOL use_aes); 505 506 QPDF_DLL 507 void qpdf_set_r5_encryption_parameters( 508 qpdf_data qpdf, char const* user_password, char const* owner_password, 509 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 510 enum qpdf_r3_print_e print, enum qpdf_r3_modify_e modify, 511 QPDF_BOOL encrypt_metadata); 512 513 QPDF_DLL 514 void qpdf_set_r6_encryption_parameters( 515 qpdf_data qpdf, char const* user_password, char const* owner_password, 516 QPDF_BOOL allow_accessibility, QPDF_BOOL allow_extract, 517 enum qpdf_r3_print_e print, enum qpdf_r3_modify_e modify, 518 QPDF_BOOL encrypt_metadata); 519 520 QPDF_DLL 521 void qpdf_set_linearization(qpdf_data qpdf, QPDF_BOOL value); 522 523 QPDF_DLL 524 void qpdf_set_minimum_pdf_version(qpdf_data qpdf, char const* version); 525 526 QPDF_DLL 527 void qpdf_set_minimum_pdf_version_and_extension( 528 qpdf_data qpdf, char const* version, int extension_level); 529 530 QPDF_DLL 531 void qpdf_force_pdf_version(qpdf_data qpdf, char const* version); 532 533 QPDF_DLL 534 void qpdf_force_pdf_version_and_extension( 535 qpdf_data qpdf, char const* version, int extension_level); 536 537 /* During write, your report_progress function will be called with 538 * a value between 0 and 100 representing the approximate write 539 * progress. The data object you pass to 540 * qpdf_register_progress_reporter will be handed back to your 541 * function. This function must be called after qpdf_init_write 542 * (or qpdf_init_write_memory) and before qpdf_write. The 543 * registered progress reporter applies only to a single write, so 544 * you must call it again if you perform a subsequent write with a 545 * new writer. 546 */ 547 QPDF_DLL 548 void qpdf_register_progress_reporter( 549 qpdf_data qpdf, 550 void (*report_progress)(int percent, void* data), 551 void* data); 552 553 /* Do actual write operation. */ 554 QPDF_DLL 555 QPDF_ERROR_CODE qpdf_write(qpdf_data qpdf); 556 557 /* Object handling. 558 * 559 * These functions take and return a qpdf_oh object handle, which 560 * is just an unsigned integer. The value 0 is never returned, which 561 * makes it usable as an uninitialized value. The handles returned by 562 * these functions are guaranteed to be unique, i.e. two calls to 563 * (the same of different) functions will return distinct handles 564 * even when they refer to the same object. 565 * 566 * Each function below, starting with qpdf_oh, corresponds to a 567 * specific method of QPDFObjectHandler. For example, 568 * qpdf_oh_is_bool corresponds to QPDFObjectHandle::isBool. If the 569 * C++ method is overloaded, the C function's name will be 570 * disambiguated. If the C++ method takes optional arguments, the C 571 * function will have required arguments in those positions. For 572 * details about the method, please see comments in 573 * QPDFObjectHandle.hh. Comments here only explain things that are 574 * specific to the "C" API. 575 * 576 * Only a fraction of the methods of QPDFObjectHandle are 577 * available here. Most of the basic methods for creating, 578 * accessing, and modifying most types of objects are present. 579 * Most of the higher-level functions are not implemented. 580 * Functions for dealing with content streams as well as objects 581 * that only exist in content streams (operators and inline 582 * images) are mostly not provided. 583 * 584 * To refer to a specific QPDFObjectHandle, you need a pair 585 * consisting of a qpdf_data and a qpdf_oh, which is just an index 586 * into an internal table of objects. All memory allocated by any 587 * of these functions is returned when qpdf_cleanup is called. 588 * 589 * Regarding memory, the same rules apply as the above functions. 590 * Specifically, if a function returns a char*, the memory is 591 * managed by the library and, unless otherwise specified, is not 592 * expected to be valid after the next qpdf call. 593 * 594 * The qpdf_data object keeps a cache of handles returned by these 595 * functions. Once you are finished referencing a handle, you can 596 * optionally release it. Releasing handles is optional since they 597 * will all get released by qpdf_cleanup, but it can help to 598 * reduce the memory footprint of the qpdf_data object to release 599 * them when you're done. Releasing a handle does not destroy the 600 * object. All QPDFObjectHandle objects are deleted when they are 601 * no longer referenced. Releasing an object handle simply 602 * invalidates it. For example, if you create an object, 603 * add it to an existing dictionary or array, and then release its 604 * handle, the object is safely part of the dictionary or array. 605 * Similarly, any other object handle refering to the object remains 606 * valid. Explicitly releasing an object handle is essentially the 607 * same as letting a QPDFObjectHandle go out of scope in the C++ 608 * API. 609 * 610 * Please see "ERROR HANDLING" above for details on how error 611 * conditions are handled. 612 */ 613 614 /* For examples of using this API, see examples/pdf-c-objects.c */ 615 616 typedef unsigned int qpdf_oh; 617 618 /* Releasing objects -- see comments above. These functions have no 619 * equivalent in the C++ API. 620 */ 621 QPDF_DLL 622 void qpdf_oh_release(qpdf_data qpdf, qpdf_oh oh); 623 QPDF_DLL 624 void qpdf_oh_release_all(qpdf_data qpdf); 625 626 /* Clone an object handle */ 627 QPDF_DLL 628 qpdf_oh qpdf_oh_new_object(qpdf_data qpdf, qpdf_oh oh); 629 630 /* Get trailer and root objects */ 631 QPDF_DLL 632 qpdf_oh qpdf_get_trailer(qpdf_data qpdf); 633 QPDF_DLL 634 qpdf_oh qpdf_get_root(qpdf_data qpdf); 635 636 /* Retrieve and replace indirect objects */ 637 QPDF_DLL 638 qpdf_oh qpdf_get_object_by_id(qpdf_data qpdf, int objid, int generation); 639 QPDF_DLL 640 qpdf_oh qpdf_make_indirect_object(qpdf_data qpdf, qpdf_oh oh); 641 QPDF_DLL 642 void qpdf_replace_object( 643 qpdf_data qpdf, int objid, int generation, qpdf_oh oh); 644 645 /* Wrappers around QPDFObjectHandle methods. Be sure to read 646 * corresponding comments in QPDFObjectHandle.hh to understand 647 * what each function does and what kinds of objects it applies 648 * to. 649 */ 650 651 QPDF_DLL 652 QPDF_BOOL qpdf_oh_is_initialized(qpdf_data qpdf, qpdf_oh oh); 653 QPDF_DLL 654 QPDF_BOOL qpdf_oh_is_bool(qpdf_data qpdf, qpdf_oh oh); 655 QPDF_DLL 656 QPDF_BOOL qpdf_oh_is_null(qpdf_data qpdf, qpdf_oh oh); 657 QPDF_DLL 658 QPDF_BOOL qpdf_oh_is_integer(qpdf_data qpdf, qpdf_oh oh); 659 QPDF_DLL 660 QPDF_BOOL qpdf_oh_is_real(qpdf_data qpdf, qpdf_oh oh); 661 QPDF_DLL 662 QPDF_BOOL qpdf_oh_is_name(qpdf_data qpdf, qpdf_oh oh); 663 QPDF_DLL 664 QPDF_BOOL qpdf_oh_is_string(qpdf_data qpdf, qpdf_oh oh); 665 QPDF_DLL 666 QPDF_BOOL qpdf_oh_is_operator(qpdf_data qpdf, qpdf_oh oh); 667 QPDF_DLL 668 QPDF_BOOL qpdf_oh_is_inline_image(qpdf_data qpdf, qpdf_oh oh); 669 QPDF_DLL 670 QPDF_BOOL qpdf_oh_is_array(qpdf_data qpdf, qpdf_oh oh); 671 QPDF_DLL 672 QPDF_BOOL qpdf_oh_is_dictionary(qpdf_data qpdf, qpdf_oh oh); 673 QPDF_DLL 674 QPDF_BOOL qpdf_oh_is_stream(qpdf_data qpdf, qpdf_oh oh); 675 QPDF_DLL 676 QPDF_BOOL qpdf_oh_is_indirect(qpdf_data qpdf, qpdf_oh oh); 677 QPDF_DLL 678 QPDF_BOOL qpdf_oh_is_scalar(qpdf_data qpdf, qpdf_oh oh); 679 QPDF_DLL 680 enum qpdf_object_type_e qpdf_oh_get_type_code(qpdf_data qpdf, qpdf_oh oh); 681 QPDF_DLL 682 char const* qpdf_oh_get_type_name(qpdf_data qpdf, qpdf_oh oh); 683 684 QPDF_DLL 685 qpdf_oh qpdf_oh_wrap_in_array(qpdf_data qpdf, qpdf_oh oh); 686 687 QPDF_DLL 688 qpdf_oh qpdf_oh_parse(qpdf_data qpdf, char const* object_str); 689 690 QPDF_DLL 691 QPDF_BOOL qpdf_oh_get_bool_value(qpdf_data qpdf, qpdf_oh oh); 692 693 QPDF_DLL 694 long long qpdf_oh_get_int_value(qpdf_data qpdf, qpdf_oh oh); 695 QPDF_DLL 696 int qpdf_oh_get_int_value_as_int(qpdf_data qpdf, qpdf_oh oh); 697 QPDF_DLL 698 unsigned long long qpdf_oh_get_uint_value(qpdf_data qpdf, qpdf_oh oh); 699 QPDF_DLL 700 unsigned int qpdf_oh_get_uint_value_as_uint(qpdf_data qpdf, qpdf_oh oh); 701 702 QPDF_DLL 703 char const* qpdf_oh_get_real_value(qpdf_data qpdf, qpdf_oh oh); 704 705 QPDF_DLL 706 QPDF_BOOL qpdf_oh_is_number(qpdf_data qpdf, qpdf_oh oh); 707 QPDF_DLL 708 double qpdf_oh_get_numeric_value(qpdf_data qpdf, qpdf_oh oh); 709 710 QPDF_DLL 711 char const* qpdf_oh_get_name(qpdf_data qpdf, qpdf_oh oh); 712 713 /* Return the length of the last string returned. This enables you 714 * to retrieve the entire string for cases in which a char* 715 * returned by one of the functions below points to a string with 716 * embedded null characters. The function 717 * qpdf_oh_get_binary_string_value takes a length pointer, which 718 * can be useful if you are retrieving the value of a string that 719 * is expected to contain binary data, such as a checksum or 720 * document ID. It is always valid to call 721 * qpdf_get_last_string_length, but it is usually not necessary as 722 * C strings returned by the library are only expected to be able 723 * to contain null characters if their values originate from PDF 724 * strings in the input. 725 */ 726 QPDF_DLL 727 size_t qpdf_get_last_string_length(qpdf_data qpdf); 728 729 QPDF_DLL 730 char const* qpdf_oh_get_string_value(qpdf_data qpdf, qpdf_oh oh); 731 QPDF_DLL 732 char const* qpdf_oh_get_utf8_value(qpdf_data qpdf, qpdf_oh oh); 733 QPDF_DLL 734 char const* qpdf_oh_get_binary_string_value( 735 qpdf_data qpdf, qpdf_oh oh, size_t* length); 736 737 QPDF_DLL 738 int qpdf_oh_get_array_n_items(qpdf_data qpdf, qpdf_oh oh); 739 QPDF_DLL 740 qpdf_oh qpdf_oh_get_array_item(qpdf_data qpdf, qpdf_oh oh, int n); 741 742 /* "C"-specific dictionary key iteration */ 743 744 /* Iteration is allowed on only one dictionary at a time. */ 745 QPDF_DLL 746 void qpdf_oh_begin_dict_key_iter(qpdf_data qpdf, qpdf_oh dict); 747 QPDF_DLL 748 QPDF_BOOL qpdf_oh_dict_more_keys(qpdf_data qpdf); 749 /* The memory returned by qpdf_oh_dict_next_key is owned by 750 * qpdf_data. It is good until the next call to 751 * qpdf_oh_dict_next_key with the same qpdf_data object. Calling 752 * the function again, even with a different dict, invalidates 753 * previous return values. 754 */ 755 QPDF_DLL 756 char const* qpdf_oh_dict_next_key(qpdf_data qpdf); 757 758 /* end "C"-specific dictionary key iteration */ 759 760 QPDF_DLL 761 QPDF_BOOL qpdf_oh_has_key(qpdf_data qpdf, qpdf_oh oh, char const* key); 762 QPDF_DLL 763 qpdf_oh qpdf_oh_get_key(qpdf_data qpdf, qpdf_oh oh, char const* key); 764 765 QPDF_DLL 766 QPDF_BOOL qpdf_oh_is_or_has_name( 767 qpdf_data qpdf, qpdf_oh oh, char const* key); 768 769 QPDF_DLL 770 qpdf_oh qpdf_oh_new_uninitialized(qpdf_data qpdf); 771 QPDF_DLL 772 qpdf_oh qpdf_oh_new_null(qpdf_data qpdf); 773 QPDF_DLL 774 qpdf_oh qpdf_oh_new_bool(qpdf_data qpdf, QPDF_BOOL value); 775 QPDF_DLL 776 qpdf_oh qpdf_oh_new_integer(qpdf_data qpdf, long long value); 777 QPDF_DLL 778 qpdf_oh qpdf_oh_new_real_from_string(qpdf_data qpdf, char const* value); 779 QPDF_DLL 780 qpdf_oh qpdf_oh_new_real_from_double(qpdf_data qpdf, 781 double value, int decimal_places); 782 QPDF_DLL 783 qpdf_oh qpdf_oh_new_name(qpdf_data qpdf, char const* name); 784 QPDF_DLL 785 qpdf_oh qpdf_oh_new_string(qpdf_data qpdf, char const* str); 786 QPDF_DLL 787 qpdf_oh qpdf_oh_new_unicode_string(qpdf_data qpdf, char const* utf8_str); 788 /* Use qpdf_oh_new_binary_string for creating a string that may 789 * contain atrbitary binary data including embedded null characters. 790 */ 791 QPDF_DLL 792 qpdf_oh qpdf_oh_new_binary_string( 793 qpdf_data qpdf, char const* str, size_t length); 794 QPDF_DLL 795 qpdf_oh qpdf_oh_new_array(qpdf_data qpdf); 796 QPDF_DLL 797 qpdf_oh qpdf_oh_new_dictionary(qpdf_data qpdf); 798 799 /* Create a new stream. Use qpdf_oh_get_dict to get (and 800 * subsequently modify) the stream dictionary if needed. See 801 * comments in QPDFObjectHandle.hh for newStream() for additional 802 * notes. You must call qpdf_oh_replace_stream_data to provide 803 * data for the stream. See STREAM FUNCTIONS below. 804 */ 805 QPDF_DLL 806 qpdf_oh qpdf_oh_new_stream(qpdf_data qpdf); 807 808 QPDF_DLL 809 void qpdf_oh_make_direct(qpdf_data qpdf, qpdf_oh oh); 810 811 QPDF_DLL 812 void qpdf_oh_set_array_item(qpdf_data qpdf, qpdf_oh oh, 813 int at, qpdf_oh item); 814 QPDF_DLL 815 void qpdf_oh_insert_item(qpdf_data qpdf, qpdf_oh oh, int at, qpdf_oh item); 816 QPDF_DLL 817 void qpdf_oh_append_item(qpdf_data qpdf, qpdf_oh oh, qpdf_oh item); 818 QPDF_DLL 819 void qpdf_oh_erase_item(qpdf_data qpdf, qpdf_oh oh, int at); 820 821 QPDF_DLL 822 void qpdf_oh_replace_key(qpdf_data qpdf, qpdf_oh oh, 823 char const* key, qpdf_oh item); 824 QPDF_DLL 825 void qpdf_oh_remove_key(qpdf_data qpdf, qpdf_oh oh, char const* key); 826 QPDF_DLL 827 void qpdf_oh_replace_or_remove_key(qpdf_data qpdf, qpdf_oh oh, 828 char const* key, qpdf_oh item); 829 830 QPDF_DLL 831 qpdf_oh qpdf_oh_get_dict(qpdf_data qpdf, qpdf_oh oh); 832 833 QPDF_DLL 834 int qpdf_oh_get_object_id(qpdf_data qpdf, qpdf_oh oh); 835 QPDF_DLL 836 int qpdf_oh_get_generation(qpdf_data qpdf, qpdf_oh oh); 837 838 QPDF_DLL 839 char const* qpdf_oh_unparse(qpdf_data qpdf, qpdf_oh oh); 840 QPDF_DLL 841 char const* qpdf_oh_unparse_resolved(qpdf_data qpdf, qpdf_oh oh); 842 QPDF_DLL 843 char const* qpdf_oh_unparse_binary(qpdf_data qpdf, qpdf_oh oh); 844 845 /* Note about foreign objects: the C API does not have enough 846 * information in the value of a qpdf_oh to know what QPDF object 847 * it belongs to. To uniquely specify a qpdf object handle from a 848 * specific qpdf_data instance, you always pair the qpdf_oh with 849 * the correct qpdf_data. Otherwise, you are likely to get 850 * completely the wrong object if you are not lucky enough to get 851 * an error about the object being invalid. 852 */ 853 854 /* Copy foreign object: the qpdf_oh returned belongs to `qpdf`, 855 * while `foreign_oh` belongs to `other_qpdf`. 856 */ 857 QPDF_DLL 858 qpdf_oh qpdf_oh_copy_foreign_object( 859 qpdf_data qpdf, qpdf_data other_qpdf, qpdf_oh foreign_oh); 860 861 /* STREAM FUNCTIONS */ 862 863 /* These functions provide basic access to streams and stream 864 * data. They are not as comprehensive as what is in 865 * QPDFObjectHandle, but they do allow for working with streams 866 * and stream data as caller-managed memory. 867 */ 868 869 /* Get stream data as a buffer. The buffer is allocated with 870 * malloc and must be freed by the caller. The size of the buffer 871 * is stored in *len. The arguments are similar to those in 872 * QPDFObjectHandle::pipeStreamData. To get raw stream data, pass 873 * qpdf_dl_none as decode_level. Otherwise, filtering is attempted 874 * and *filtered is set to indicate whether it was successful. If 875 * *filtered is QPDF_FALSE, then raw, unfiltered stream data was 876 * returned. You may pass a null pointer as filtered if you don't 877 * care about the result. If you pass a null pointer as bufp (and 878 * len), the value of filtered will be set to whether the stream 879 * can be filterable. 880 */ 881 QPDF_DLL 882 QPDF_ERROR_CODE qpdf_oh_get_stream_data( 883 qpdf_data qpdf, qpdf_oh stream_oh, 884 enum qpdf_stream_decode_level_e decode_level, QPDF_BOOL* filtered, 885 unsigned char** bufp, size_t* len); 886 887 /* This function returns the concatenation of all of a page's 888 * content streams as a single, dynamically allocated buffer. As 889 * with qpdf_oh_get_stream_data, the buffer is allocated with 890 * malloc and must be freed by the caller. 891 */ 892 QPDF_DLL 893 QPDF_ERROR_CODE qpdf_oh_get_page_content_data( 894 qpdf_data qpdf, qpdf_oh page_oh, 895 unsigned char** bufp, size_t* len); 896 897 /* The data pointed to by bufp will be copied by the library. It 898 * does not need to remain valid after the call returns. 899 */ 900 QPDF_DLL 901 void qpdf_oh_replace_stream_data( 902 qpdf_data qpdf, qpdf_oh stream_oh, 903 unsigned char const* buf, size_t len, 904 qpdf_oh filter, qpdf_oh decode_parms); 905 906 /* PAGE FUNCTIONS */ 907 908 /* The first time a page function is called, qpdf will traverse 909 * the /Pages tree. Subsequent calls to retrieve the number of 910 * pages or a specific page run in constant time as they are 911 * accessing the pages cache. If you manipulate the page tree 912 * outside of these functions, you should call 913 * qpdf_update_all_pages_cache. See comments for getAllPages() and 914 * updateAllPagesCache() in QPDF.hh. 915 */ 916 917 /* For each function, the corresponding method in QPDF.hh is 918 * referenced. Please see comments in QPDF.hh for details. 919 */ 920 921 /* calls getAllPages(). On error, returns -1 and sets error for 922 * qpdf_get_error. */ 923 QPDF_DLL 924 int qpdf_get_num_pages(qpdf_data qpdf); 925 /* returns uninitialized object if out of range */ 926 QPDF_DLL 927 qpdf_oh qpdf_get_page_n(qpdf_data qpdf, size_t zero_based_index); 928 929 /* updateAllPagesCache() */ 930 QPDF_DLL 931 QPDF_ERROR_CODE qpdf_update_all_pages_cache(qpdf_data qpdf); 932 933 /* findPage() -- return zero-based index. If page is not found, 934 * return -1 and save the error to be retrieved with 935 * qpdf_get_error. 936 */ 937 QPDF_DLL 938 int qpdf_find_page_by_id(qpdf_data qpdf, int objid, int generation); 939 QPDF_DLL 940 int qpdf_find_page_by_oh(qpdf_data qpdf, qpdf_oh oh); 941 942 /* pushInheritedAttributesToPage() */ 943 QPDF_DLL 944 QPDF_ERROR_CODE qpdf_push_inherited_attributes_to_page(qpdf_data qpdf); 945 946 /* Functions that add pages may add pages from other files. If 947 * adding a page from the same file, newpage_qpdf and qpdf are the 948 * same. 949 /*/ 950 951 /* addPage() */ 952 QPDF_DLL 953 QPDF_ERROR_CODE qpdf_add_page( 954 qpdf_data qpdf, 955 qpdf_data newpage_qpdf, qpdf_oh newpage, 956 QPDF_BOOL first); 957 /* addPageAt() */ 958 QPDF_DLL 959 QPDF_ERROR_CODE qpdf_add_page_at( 960 qpdf_data qpdf, 961 qpdf_data newpage_qpdf, qpdf_oh newpage, 962 QPDF_BOOL before, qpdf_oh refpage); 963 /* removePage() */ 964 QPDF_DLL 965 QPDF_ERROR_CODE qpdf_remove_page(qpdf_data qpdf, qpdf_oh page); 966 #ifdef __cplusplus 967 } 968 #endif 969 970 971 #endif /* QPDF_C_H */ 972