1 /* 2 //C- ------------------------------------------------------------------- 3 //C- DjVuLibre-3.5 4 //C- Copyright (c) 2002 Leon Bottou and Yann Le Cun. 5 //C- Copyright (c) 2001 AT&T 6 //C- 7 //C- This software is subject to, and may be distributed under, the 8 //C- GNU General Public License, either Version 2 of the license, 9 //C- or (at your option) any later version. The license should have 10 //C- accompanied the software or you may obtain a copy of the license 11 //C- from the Free Software Foundation at http://www.fsf.org . 12 //C- 13 //C- This program is distributed in the hope that it will be useful, 14 //C- but WITHOUT ANY WARRANTY; without even the implied warranty of 15 //C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 //C- GNU General Public License for more details. 17 //C- 18 //C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from 19 //C- Lizardtech Software. Lizardtech Software has authorized us to 20 //C- replace the original DjVu(r) Reference Library notice by the following 21 //C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu): 22 //C- 23 //C- ------------------------------------------------------------------ 24 //C- | DjVu (r) Reference Library (v. 3.5) 25 //C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved. 26 //C- | The DjVu Reference Library is protected by U.S. Pat. No. 27 //C- | 6,058,214 and patents pending. 28 //C- | 29 //C- | This software is subject to, and may be distributed under, the 30 //C- | GNU General Public License, either Version 2 of the license, 31 //C- | or (at your option) any later version. The license should have 32 //C- | accompanied the software or you may obtain a copy of the license 33 //C- | from the Free Software Foundation at http://www.fsf.org . 34 //C- | 35 //C- | The computer code originally released by LizardTech under this 36 //C- | license and unmodified by other parties is deemed "the LIZARDTECH 37 //C- | ORIGINAL CODE." Subject to any third party intellectual property 38 //C- | claims, LizardTech grants recipient a worldwide, royalty-free, 39 //C- | non-exclusive license to make, use, sell, or otherwise dispose of 40 //C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the 41 //C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU 42 //C- | General Public License. This grant only confers the right to 43 //C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to 44 //C- | the extent such infringement is reasonably necessary to enable 45 //C- | recipient to make, have made, practice, sell, or otherwise dispose 46 //C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to 47 //C- | any greater extent that may be necessary to utilize further 48 //C- | modifications or combinations. 49 //C- | 50 //C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY 51 //C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 52 //C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF 53 //C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 54 //C- +------------------------------------------------------------------ 55 */ 56 57 #ifndef DDJVUAPI_H 58 #define DDJVUAPI_H 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 #if 0 64 } 65 #endif 66 67 #include <stddef.h> 68 #include <stdlib.h> 69 #include <stdio.h> 70 71 #ifndef DDJVUAPI 72 # ifdef _WIN32 73 # ifdef DDJVUAPI_EXPORT 74 # define DDJVUAPI __declspec(dllexport) 75 # else 76 # define DDJVUAPI __declspec(dllimport) 77 # endif 78 # endif 79 #endif 80 #ifndef DDJVUAPI 81 # define DDJVUAPI /**/ 82 #endif 83 84 #ifndef TRUE 85 # define TRUE (1) 86 #endif 87 88 #ifndef FALSE 89 # define FALSE (0) 90 #endif 91 92 93 94 /* -------------------------------------------------- */ 95 /* DDJVU API */ 96 /* -------------------------------------------------- */ 97 98 /* The DDJVU API provides for efficiently decoding and 99 displaying DjVu documents. It provides for displaying 100 images without waiting for the complete DjVu data. Images 101 can be displayed as soon as sufficient data is 102 available. A higher quality image might later be 103 displayed when further data is available. The DjVu 104 library achieves this using a complicated scheme 105 involving multiple threads. The DDJVU API hides this 106 complexity with a familiar event model. 107 */ 108 109 /* Compiler symbol DDJVUAPI_VERSION tracks 110 backward compatible additions to the DDJVU API. 111 112 Version Change 113 ----------------------------- 114 24 Added: 115 miniexp_lstring() 116 miniexp_to_lstr() 117 23 Added: 118 miniexp_mutate() 119 22 Changed 120 miniexp strings accept unicode escapes 121 deprecated miniexp_io_t::p_print7bits 122 added miniexp_io_t::p_flags 123 21 Added: 124 reentrant version of miniexp input/output 125 20 Added: 126 ddjvu_get_version_string() 127 ddjvu_format_set_white() 128 ddjvu_anno_get_xmp() 129 19 Added: 130 ddjvu_document_create_by_filename_utf8() 131 18 Added: 132 ddjvu_document_get_{anno,pagedump,filedump}() 133 Modifed (binary compatible): 134 ddjvu_document_get_{fileinfo,pageinfo}() 135 ddjvu_document_save() [--pages, --indirect=] 136 Deprecated: 137 ddjvu_document_search_pageno() 138 ddjvu_page_get_{short,long}_description() 139 17 Added: 140 ddjvu_page_get_initial_rotation(), ddjvu_code_get_version() 141 ddjvu_document_{get_filenum,get_fileinfo}}() 142 ddjvu_document_{search_pageno,check_pagedata}() 143 ddjvu_rectmapper_t and related functions. 144 16 Added: 145 miniexp.h and related functions. 146 15 Added: 147 ddjvu_document_get_pageinfo() 148 ddjvu_document_print() 149 14 Initial version. 150 */ 151 152 #define DDJVUAPI_VERSION 23 153 154 typedef struct ddjvu_context_s ddjvu_context_t; 155 typedef union ddjvu_message_s ddjvu_message_t; 156 typedef struct ddjvu_job_s ddjvu_job_t; 157 typedef struct ddjvu_document_s ddjvu_document_t; 158 typedef struct ddjvu_page_s ddjvu_page_t; 159 typedef struct ddjvu_format_s ddjvu_format_t; 160 typedef struct ddjvu_rect_s ddjvu_rect_t; 161 typedef struct ddjvu_rectmapper_s ddjvu_rectmapper_t; 162 163 164 /* GENERAL CONVENTIONS: 165 166 - all strings use locale encoding (unless specified otherwise). 167 - all filenames are unencoded byte strings, 168 - all errors are signaled with error event messages, 169 - all functions returning a pointer might return a null pointer. 170 171 HEADER: 172 Always use the following idiom to include this file. 173 174 #include <libdjvu/ddjvuapi.h> 175 #include <libdjvu/miniexp.h> 176 177 This file does not declare functions ddjvu_get_DjVuImage() 178 and djvu_get_DjVuDocument() unless you include files 179 "DjVuImage.h" and "DjVuDocument.h" before this file. 180 181 PREREQUISITES: 182 - Please read the djvu man page: <"tools/djvu.1">. 183 - Please browse the file format specifications 184 <"doc/djvu3changes.txt"> and <"doc/djvu3spec.djvu">. 185 */ 186 187 188 189 /* -------------------------------------------------- */ 190 /* DDJVU_CONTEXT_T */ 191 /* -------------------------------------------------- */ 192 193 /* There is usually only one <ddjvu_context_t> object. 194 This object holds global data structures such as the 195 cache of decoded pages, or the list of pending 196 event messages. 197 */ 198 199 200 201 /* ddjvu_get_version_string() --- 202 Returns a string that described the underlying code. */ 203 204 DDJVUAPI const char* 205 ddjvu_get_version_string(void); 206 207 208 /* ddjvu_context_create --- 209 Creates a <ddjvu_context_t> object. 210 Argument <programname> is the name of the calling executable. */ 211 212 DDJVUAPI ddjvu_context_t * 213 ddjvu_context_create(const char *programname); 214 215 216 /* ddjvu_context_release --- 217 Release a reference to a <ddjvu_context_t> object. 218 The calling program should no longer reference this object. 219 The object itself will be destroyed as soon as no other object 220 or thread needs it. */ 221 222 DDJVUAPI void 223 ddjvu_context_release(ddjvu_context_t *context); 224 225 226 227 228 229 /* ------- CACHE ------- */ 230 231 /* ddjvu_cache_set_size --- 232 Sets the maximum size of the cache of decoded page data. 233 The argument is expressed in bytes. */ 234 235 DDJVUAPI void 236 ddjvu_cache_set_size(ddjvu_context_t *context, 237 unsigned long cachesize); 238 239 240 /* ddjvu_cache_get_size --- 241 Returns the maximum size of the cache. */ 242 243 DDJVUAPI unsigned long 244 ddjvu_cache_get_size(ddjvu_context_t *context); 245 246 247 /* ddjvu_cache_clear --- 248 Clears all cached data. */ 249 250 DDJVUAPI void 251 ddjvu_cache_clear(ddjvu_context_t *context); 252 253 254 255 /* ------- MESSAGE QUEUE ------- */ 256 257 /* Messages produced by the ddjvu api accumulate into 258 the message queue. Processing messages is not optional! 259 A typical message handling routine looks like this: 260 261 void handle_ddjvu_messages(ddjvu_context_t *ctx, int wait) 262 { 263 const ddjvu_message_t *msg; 264 if (wait) 265 ddjvu_message_wait(ctx); 266 while ((msg = ddjvu_message_peek(ctx))) 267 { 268 switch(msg->m_any.tag) 269 { 270 case DDJVU_ERROR: .... ; break; 271 case DDJVU_INFO: .... ; break; 272 case DDJVU_NEWSTREAM: .... ; break; 273 .... 274 default: break; 275 } 276 ddjvu_message_pop(ctx); 277 } 278 } 279 */ 280 281 282 /* ddjvu_message_peek --- 283 Returns a pointer to the next DDJVU message. 284 This function returns 0 if no message is available. 285 It does not remove the message from the queue. */ 286 287 DDJVUAPI ddjvu_message_t * 288 ddjvu_message_peek(ddjvu_context_t *context); 289 290 291 /* ddjvu_message_wait --- 292 Returns a pointer to the next DDJVU message. 293 This function waits until a message is available. 294 It does not remove the message from the queue. */ 295 296 DDJVUAPI ddjvu_message_t * 297 ddjvu_message_wait(ddjvu_context_t *context); 298 299 300 /* ddjvu_message_pop --- 301 Removes one message from the queue. 302 This function must be called after processing the message. 303 Pointers returned by previous calls to <ddjvu_message_peek> 304 or <ddjvu_message_wait> are no longer valid after 305 calling <ddjvu_message_pop>. */ 306 307 DDJVUAPI void 308 ddjvu_message_pop(ddjvu_context_t *context); 309 310 311 /* ddjvu_message_set_callback --- 312 Defines a callback function invoked whenever 313 a new message is posted to the ddjvuapi message queue, 314 and returns a pointer to the previous callback function. 315 This callback function can be called at any time 316 while other code is executing. Do not call ddjvuapi 317 functions from this callback. It should simply signal 318 the main application event loop that new ddjvuapi messages 319 are available. Under WIN32, this is usually achieved 320 by posting a user window message. Under UNIX, this is 321 usually achieved using a pipe: the callback writes 322 a single byte into the pipe; the main application loop 323 monitors the reading end of the pipe and detects 324 the presence of data. */ 325 326 typedef void 327 (*ddjvu_message_callback_t)(ddjvu_context_t *context, void *closure); 328 329 DDJVUAPI void 330 ddjvu_message_set_callback(ddjvu_context_t *context, 331 ddjvu_message_callback_t callback, 332 void *closure); 333 334 335 336 /* -------------------------------------------------- */ 337 /* DDJVU_JOB_T */ 338 /* -------------------------------------------------- */ 339 340 341 /* Many essential ddjvuapi functions initiate asynchronous operations. 342 These "jobs" run in seperate threads and report their 343 progress by posting messages into the ddjvu context event queue. 344 Jobs are sometimes represented by a ddjvu_job_t object. */ 345 346 /* ddjvu_job_status --- 347 Returns the status of the specified job. */ 348 349 typedef enum { 350 DDJVU_JOB_NOTSTARTED, /* operation was not even started */ 351 DDJVU_JOB_STARTED, /* operation is in progress */ 352 DDJVU_JOB_OK, /* operation terminated successfully */ 353 DDJVU_JOB_FAILED, /* operation failed because of an error */ 354 DDJVU_JOB_STOPPED /* operation was interrupted by user */ 355 } ddjvu_status_t; 356 357 DDJVUAPI ddjvu_status_t 358 ddjvu_job_status(ddjvu_job_t *job); 359 360 #define ddjvu_job_done(job) \ 361 (ddjvu_job_status(job) >= DDJVU_JOB_OK) 362 #define ddjvu_job_error(job) \ 363 (ddjvu_job_status(job) >= DDJVU_JOB_FAILED) 364 365 366 /* ddjvu_job_stop --- 367 Attempts to cancel the specified job. 368 This is a best effort function. 369 There no guarantee that the job will 370 actually stop. 371 */ 372 373 DDJVUAPI void 374 ddjvu_job_stop(ddjvu_job_t *job); 375 376 377 /* ddjvu_job_set_user_data --- 378 ddjvu_job_get_user_data --- 379 Each job can store an arbitrary pointer 380 that callers can use for any purpose. These two 381 functions provide for accessing or setting this pointer. 382 This pointer is cleared when the job is released */ 383 384 DDJVUAPI void 385 ddjvu_job_set_user_data(ddjvu_job_t *job, void *userdata); 386 387 DDJVUAPI void * 388 ddjvu_job_get_user_data(ddjvu_job_t *job); 389 390 391 /* ddjvu_job_release --- 392 Releases a reference to a job object and clears its user 393 data field. This does not cause the job to stop executing. 394 The calling program should no longer reference this object. 395 The object itself will be destroyed as soon as no 396 other object or thread needs it. 397 */ 398 399 DDJVUAPI void 400 ddjvu_job_release(ddjvu_job_t *job); 401 402 403 404 /* -------------------------------------------------- */ 405 /* DDJVU_MESSAGE_T */ 406 /* -------------------------------------------------- */ 407 408 409 /* ddjvu_message_t --- 410 This union type represents messages delivered by the 411 DDJVU API. Each member of the union pertains to a 412 specific kind of message. Member <m_any> represents the 413 information common to all kinds of messages. Given a 414 pointer <p> to a <djvu_message_t>, the message kind can 415 be accessed as <"p->m_any.tag">. */ 416 417 418 /* ddjvu_message_tag_t --- 419 This enumerated type identifies each kind of 420 message delivered by the DDJVU API. */ 421 422 typedef enum { 423 DDJVU_ERROR, 424 DDJVU_INFO, 425 DDJVU_NEWSTREAM, 426 DDJVU_DOCINFO, 427 DDJVU_PAGEINFO, 428 DDJVU_RELAYOUT, 429 DDJVU_REDISPLAY, 430 DDJVU_CHUNK, 431 DDJVU_THUMBNAIL, 432 DDJVU_PROGRESS, 433 } ddjvu_message_tag_t; 434 435 436 /* ddjvu_message_t::m_any --- 437 This structure is a member of the union <djvu_message_t>. 438 It represents the information common to all kinds of 439 messages. Member <tag> indicates the kind of message. 440 Members <context>, <document>, <page>, and <job> indicate 441 the origin of the message. These fields contain null 442 pointers when they are not relevant. 443 These fields are also cleared when the corresponding 444 object is released with <ddjvu_{job,page,document}_release>. 445 If the message has not yet been passed to the user 446 with <ddjvu_message_{peek,wait}>, it is silently 447 removed from the message queue. */ 448 449 typedef struct ddjvu_message_any_s { 450 ddjvu_message_tag_t tag; 451 ddjvu_context_t *context; 452 ddjvu_document_t *document; 453 ddjvu_page_t *page; 454 ddjvu_job_t *job; 455 } ddjvu_message_any_t; 456 457 458 /* ddjvu_message_t::m_error --- 459 Error messages are generated whenever the decoder or the 460 DDJVU API encounters an error condition. All errors are 461 reported as error messages because they can occur 462 asynchronously. Member <message> is the error message. 463 Members <function>, <filename> and <lineno> 464 indicates the place where the error was detected. */ 465 466 struct ddjvu_message_error_s { /* ddjvu_message_t::m_error */ 467 ddjvu_message_any_t any; 468 const char *message; 469 const char *function; 470 const char *filename; 471 int lineno; 472 }; 473 474 475 /* ddjvu_message_t::m_info --- 476 This messages provides informational text indicating 477 the progress of the decoding process. This might 478 be displayed in the browser status bar. */ 479 480 struct ddjvu_message_info_s { /* ddjvu_message_t::m_info */ 481 ddjvu_message_any_t any; 482 const char *message; 483 }; 484 485 486 487 488 /* -------------------------------------------------- */ 489 /* DDJVU_DOCUMENT_T */ 490 /* -------------------------------------------------- */ 491 492 493 /* ddjvu_document_create --- 494 Creates a decoder for a DjVu document and starts 495 decoding. This function returns immediately. The 496 decoding job then generates messages to request the raw 497 data and to indicate the state of the decoding process. 498 499 Argument <url> specifies an optional URL for the document. 500 The URL follows the usual syntax (<"protocol://machine/path">). 501 It should not end with a slash. It only serves two purposes: 502 - The URL is used as a key for the cache of decoded pages. 503 - The URL is used to document <m_newstream> messages. 504 505 Setting argument <cache> to <TRUE> indicates that decoded pages 506 should be cached when possible. This only works when 507 argument <url> is not the null pointer. 508 509 It is important to understand that the URL is not used to 510 access the data. The document generates <m_newstream> 511 messages to indicate which data is needed. The caller must 512 then provide the raw data using <ddjvu_stream_write> 513 and <ddjvu_stream_close>. 514 515 Localized characters in argument <url> should be in 516 urlencoded UTF-8 (like "%2A"). What is happening for non 517 ascii characters is unclear (probably UTF-8). */ 518 519 DDJVUAPI ddjvu_document_t * 520 ddjvu_document_create(ddjvu_context_t *context, 521 const char *url, 522 int cache); 523 524 525 /* ddjvu_document_create_by_filename --- 526 Creates a document for a DjVu document stored in a file. 527 The document will directly access the specified DjVu file 528 or related files without generating <m_newstream> messages. 529 The standard function expects the filename in locale encoding. 530 The utf8 variant expects an utf8 encoded filename. */ 531 532 DDJVUAPI ddjvu_document_t * 533 ddjvu_document_create_by_filename(ddjvu_context_t *context, 534 const char *filename, 535 int cache); 536 537 DDJVUAPI ddjvu_document_t * 538 ddjvu_document_create_by_filename_utf8(ddjvu_context_t *context, 539 const char *filename, 540 int cache); 541 542 /* ddjvu_document_job --- 543 Access the job object in charge of decoding the document header. 544 In fact <ddjvu_document_t> is a subclass of <ddjvu_job_t> 545 and this function is a type cast. */ 546 547 DDJVUAPI ddjvu_job_t * 548 ddjvu_document_job(ddjvu_document_t *document); 549 550 551 /* ddjvu_document_release --- 552 Release a reference to a <ddjvu_document_t> object. 553 The calling program should no longer reference this object. 554 The object itself will be destroyed as soon as no other object 555 or thread needs it. */ 556 557 #define ddjvu_document_release(document) \ 558 ddjvu_job_release(ddjvu_document_job(document)) 559 560 561 /* ddjvu_document_set_user_data --- 562 ddjvu_document_get_user_data --- 563 Each <ddjvu_document_t> object can store an arbitray pointer 564 that callers can use for any purpose. These two functions 565 provide for accessing or setting this pointer. */ 566 567 #define ddjvu_document_set_user_data(document,userdata) \ 568 ddjvu_job_set_user_data(ddjvu_document_job(document),userdata) 569 #define ddjvu_document_get_user_data(document) \ 570 ddjvu_job_get_user_data(ddjvu_document_job(document)) 571 572 /* ddjvu_document_decoding_status --- 573 ddjvu_document_decoding_done, ddjvu_document_decoding_error --- 574 This function returns the status of the document header decoding job */ 575 576 #define ddjvu_document_decoding_status(document) \ 577 ddjvu_job_status(ddjvu_document_job(document)) 578 #define ddjvu_document_decoding_done(document) \ 579 (ddjvu_document_decoding_status(document) >= DDJVU_JOB_OK) 580 #define ddjvu_document_decoding_error(document) \ 581 (ddjvu_document_decoding_status(document) >= DDJVU_JOB_FAILED) 582 583 584 /* ------- STREAMS ------- */ 585 586 587 /* ddjvu_message_t::m_newstream --- 588 Newstream messages are generated whenever the decoder 589 needs to access raw DjVu data. The caller must then 590 provide the requested data using <ddjvu_stream_write> 591 and <ddjvu_stream_close>. 592 593 In the case of indirect documents, a single decoder 594 might simultaneously request several streams of data. 595 Each stream is identified by a small integer <streamid>. 596 597 The first <m_newstream> message always has member 598 <streamid> set to zero and member <name> set to the null 599 pointer. It indicates that the decoder needs to access 600 the data in the main DjVu file. In fact, data can be 601 written to stream <0> as soon as the <ddjvu_document_t> 602 object is created. 603 604 Further <m_newstream> messages are generated to access 605 the auxiliary files of indirect or indexed DjVu 606 documents. Member <name> then provides the basename of 607 the auxiliary file. 608 609 Member <url> is set according to the url argument 610 provided to function <ddjvu_document_create>. The first 611 newstream message always contain the url passed to 612 <ddjvu_document_create>. Subsequent newstream messages 613 contain the url of the auxiliary files for indirect or 614 indexed DjVu documents. */ 615 616 struct ddjvu_message_newstream_s { /* ddjvu_message_t::m_newstream */ 617 ddjvu_message_any_t any; 618 int streamid; 619 const char *name; 620 const char *url; 621 }; 622 623 624 /* ddjvu_stream_write --- 625 Provide raw data to the DjVu decoder. 626 This function should be called as soon as the data is available, 627 for instance when receiving DjVu data from a network connection. 628 */ 629 630 DDJVUAPI void 631 ddjvu_stream_write(ddjvu_document_t *document, 632 int streamid, 633 const char *data, 634 unsigned long datalen ); 635 636 637 /* ddjvu_stream_close --- 638 Indicates that no more data will be provided on a 639 particular stream. Argument <stop> most likely should be 640 set to <FALSE>. Setting argument <stop> to <TRUE> 641 indicates that the user has interrupted the data transfer 642 (for instance by pressing the stop button of a browser) 643 and that the decoding threads should be stopped as 644 soon as feasible. */ 645 646 DDJVUAPI void 647 ddjvu_stream_close(ddjvu_document_t *document, 648 int streamid, 649 int stop ); 650 651 652 653 /* ------- QUERIES ------- */ 654 655 656 /* ddjvu_message_t::m_docinfo --- 657 The <m_docinfo> message indicates that basic information 658 about the document has been obtained and decoded. 659 Not much can be done before this happens. 660 Call <ddjvu_document_decoding_status> to determine 661 whether the operation was successful. */ 662 663 struct ddjvu_message_docinfo_s { 664 ddjvu_message_any_t any; 665 }; 666 667 668 /* ddjvu_document_get_type --- 669 Returns the type of a DjVu document. 670 This function might return <DDJVU_DOCTYPE_UNKNOWN> 671 when called before receiving a <m_docinfo> message. */ 672 673 typedef enum { 674 DDJVU_DOCTYPE_UNKNOWN=0, 675 DDJVU_DOCTYPE_SINGLEPAGE, 676 DDJVU_DOCTYPE_BUNDLED, 677 DDJVU_DOCTYPE_INDIRECT, 678 DDJVU_DOCTYPE_OLD_BUNDLED, /* obsolete */ 679 DDJVU_DOCTYPE_OLD_INDEXED, /* obsolete */ 680 } ddjvu_document_type_t; 681 682 DDJVUAPI ddjvu_document_type_t 683 ddjvu_document_get_type(ddjvu_document_t *document); 684 685 686 /* ddjvu_document_get_pagenum --- 687 Returns the number of pages in a DjVu document. 688 This function might return 1 when called 689 before receiving a <m_docinfo> message */ 690 691 DDJVUAPI int 692 ddjvu_document_get_pagenum(ddjvu_document_t *document); 693 694 695 696 /* ------- ADVANCED ------- */ 697 698 699 /* ddjvu_document_get_filenum -- 700 Returns the number of component files. 701 This function might return 0 when called 702 before receiving a <m_docinfo> message */ 703 704 DDJVUAPI int 705 ddjvu_document_get_filenum(ddjvu_document_t *document); 706 707 708 /* ddjvu_document_get_fileinfo -- 709 Returns information about component file <fileno>. 710 This function might return <DDJVU_JOB_STARTED> when 711 called before receiving a <m_docinfo> message. 712 String pointers in the returned data structure 713 might be null. Strings are UTF8 encoded and remain 714 allocated as long as the ddjvu_document_t object exists. 715 716 Changes for ddjvuapi=18 717 - Redefined as a macro passing the structure size. 718 */ 719 720 typedef struct ddjvu_fileinfo_s { 721 char type; /* [P]age, [T]humbnails, [I]nclude. */ 722 int pageno; /* Negative when not applicable. */ 723 int size; /* Negative when unknown. */ 724 const char *id; /* File identifier. */ 725 const char *name; /* Name for indirect documents. */ 726 const char *title; /* Page title. */ 727 } ddjvu_fileinfo_t; 728 729 #define ddjvu_document_get_fileinfo(d,f,i) \ 730 ddjvu_document_get_fileinfo_imp(d,f,i,sizeof(ddjvu_fileinfo_t)) 731 732 DDJVUAPI ddjvu_status_t 733 ddjvu_document_get_fileinfo_imp(ddjvu_document_t *document, int fileno, 734 ddjvu_fileinfo_t *info, unsigned int infosz); 735 736 737 /* ddjvu_document_search_pageno --- DEPRECATED. */ 738 739 DDJVUAPI int ddjvu_document_search_pageno(ddjvu_document_t*, const char*); 740 741 742 /* ddjvu_document_check_pagedata --- 743 Returns a non zero result if the data for page <pageno> 744 is already in memory. When this is the case, functions 745 <ddjvu_document_get_pageinfo> and <ddjvu_document_get_pagetext> 746 return the information immediately. 747 This function causes the emission of <m_pageinfo> messages 748 with zero in the <m_any.page> field whenever a new file 749 is completely downloaded. */ 750 751 DDJVUAPI int 752 ddjvu_document_check_pagedata(ddjvu_document_t *document, int pageno); 753 754 755 /* ddjvu_document_get_pageinfo --- 756 Attempts to obtain information about page <pageno> 757 without decoding the page. If the information is available, 758 the function returns <DDJVU_JOB_OK> and fills the <info> structure. 759 Otherwise it starts fetching page data and returns <DDJVU_JOB_STARTED>. 760 This function causes the emission of <m_pageinfo> messages 761 with zero in the <m_any.page> field. 762 Typical synchronous usage: 763 764 ddjvu_status_t r; 765 ddjvu_pageinfo_t info; 766 while ((r=ddjvu_document_get_pageinfo(doc,pageno,&info))<DDJVU_JOB_OK) 767 handle_ddjvu_messages(ctx, TRUE); 768 if (r>=DDJVU_JOB_FAILED) 769 signal_error(); 770 771 Changes for ddjvuapi=18 772 - Redefined as a macro passing the structure size. 773 - Added fields 'rotation' and 'version'. 774 */ 775 776 typedef struct ddjvu_pageinfo_s { 777 int width; /* page width (in pixels) */ 778 int height; /* page height (in pixels) */ 779 int dpi; /* page resolution (in dots per inche) */ 780 int rotation; /* initial page orientation */ 781 int version; /* page version */ 782 } ddjvu_pageinfo_t; 783 784 #define ddjvu_document_get_pageinfo(d,p,i) \ 785 ddjvu_document_get_pageinfo_imp(d,p,i,sizeof(ddjvu_pageinfo_t)) 786 787 DDJVUAPI ddjvu_status_t 788 ddjvu_document_get_pageinfo_imp(ddjvu_document_t *document, int pageno, 789 ddjvu_pageinfo_t *info, unsigned int infosz ); 790 791 792 793 794 /* ddjvu_document_get_pagedump -- 795 This function returns a UTF8 encoded text describing the contents 796 of page <pageno> using the same format as command <djvudump>. 797 The returned string must be deallocated using <free()>. 798 It returns <0> when the information is not yet available. 799 It may then cause then the emission of <m_pageinfo> 800 messages with null <m_any.page>. 801 */ 802 803 DDJVUAPI char * 804 ddjvu_document_get_pagedump(ddjvu_document_t *document, int pageno); 805 806 807 /* ddjvu_document_get_filedump -- 808 This function returns a UTF8 encoded text describing the contents 809 of file <fileno> using the same format as command <djvudump>. 810 The returned string must be deallocated using <free()>. 811 It returns <0> when the information is not yet available. 812 It may then cause then the emission of <m_pageinfo> 813 messages with null <m_any.page>. 814 */ 815 816 DDJVUAPI char * 817 ddjvu_document_get_filedump(ddjvu_document_t *document, int fileno); 818 819 820 821 822 /* -------------------------------------------------- */ 823 /* DJVU_PAGE_T */ 824 /* -------------------------------------------------- */ 825 826 827 /* ddjvu_page_create_by_pageno --- 828 Each page of a document can be accessed by creating a 829 <ddjvu_page_t> object with this function. Argument 830 <pageno> indicates the page number, starting with page 831 <0> to <pagenum-1>. This function may return NULL 832 when called before receiving the <m_docinfo> message. 833 Calling this function also initiates the data transfer 834 and the decoding threads for the specified page. 835 Various messages will document the progress of these 836 operations. Error messages will be generated if 837 the page does not exists. */ 838 839 DDJVUAPI ddjvu_page_t * 840 ddjvu_page_create_by_pageno(ddjvu_document_t *document, 841 int pageno); 842 843 /* ddjvu_page_create_by_pageid --- 844 This function is similar to <ddjvu_page_create_by_pageno> 845 but identifies the desired page by name instead of page 846 number. */ 847 848 DDJVUAPI ddjvu_page_t * 849 ddjvu_page_create_by_pageid(ddjvu_document_t *document, 850 const char *pageid); 851 852 853 /* ddjvu_page_job --- 854 Access the job object in charge of decoding the document header. 855 In fact <ddjvu_page_t> is a subclass of <ddjvu_job_t> 856 and this function is a type cast. */ 857 858 DDJVUAPI ddjvu_job_t * 859 ddjvu_page_job(ddjvu_page_t *page); 860 861 862 /* ddjvu_page_release --- 863 Release a reference to a <ddjvu_page_t> object. 864 The calling program should no longer reference this object. 865 The object itself will be destroyed as soon as no other object 866 or thread needs it. */ 867 868 #define ddjvu_page_release(page) \ 869 ddjvu_job_release(ddjvu_page_job(page)) 870 871 872 /* ddjvu_page_set_user_data --- 873 ddjvu_page_get_user_data --- 874 Each <ddjvu_paqge_t> object can store an arbitray pointer 875 that callers can use for any purpose. These two functions 876 provide for accessing or setting this pointer. */ 877 878 #define ddjvu_page_set_user_data(page,userdata) \ 879 ddjvu_job_set_user_data(ddjvu_page_job(page),userdata) 880 #define ddjvu_page_get_user_data(page) \ 881 ddjvu_job_get_user_data(ddjvu_page_job(page)) 882 883 /* ddjvu_page_decoding_status --- 884 ddjvu_page_decoding_done --- 885 ddjvu_page_decoding_error --- 886 These calls return the status of the page decoding job. */ 887 888 #define ddjvu_page_decoding_status(page) \ 889 ddjvu_job_status(ddjvu_page_job(page)) 890 #define ddjvu_page_decoding_done(page) \ 891 (ddjvu_page_decoding_status(page) >= DDJVU_JOB_OK) 892 #define ddjvu_page_decoding_error(page) \ 893 (ddjvu_page_decoding_status(page) >= DDJVU_JOB_FAILED) 894 895 896 /* ------- MESSAGES ------- */ 897 898 899 /* ddjvu_message_t::m_pageinfo --- 900 The page decoding process generates this message 901 - when basic page information is available and 902 before any <m_relayout> or <m_redisplay> message, 903 - when the page decoding thread terminates. 904 You can distinguish both cases using 905 function ddjvu_page_decoding_status(). 906 Messages <m_pageinfo> are also generated as a consequence of 907 functions such as <ddjvu_document_get_pageinfo>. 908 The field <m_any.page> of such message is null. 909 */ 910 911 struct ddjvu_message_pageinfo_s { /* ddjvu_message_t::m_pageinfo */ 912 ddjvu_message_any_t any; 913 }; 914 915 916 /* ddjvu_message_t::m_relayout --- 917 This message is generated when a DjVu viewer 918 should recompute the layout of the page viewer 919 because the page size and resolution information has 920 been updated. */ 921 922 struct ddjvu_message_relayout_s { /* ddjvu_message_t::m_relayout */ 923 ddjvu_message_any_t any; 924 }; 925 926 927 /* ddjvu_message_t::m_redisplay --- 928 This message is generated when a DjVu viewer 929 should call <ddjvu_page_render> and redisplay 930 the page. This happens, for instance, when newly 931 decoded DjVu data provides a better image. */ 932 933 struct ddjvu_message_redisplay_s { /* ddjvu_message_t::m_redisplay */ 934 ddjvu_message_any_t any; 935 }; 936 937 938 /* ddjvu_message_t::m_chunk --- 939 This message indicates that an additional chunk 940 of DjVu data has been decoded. Member <chunkid> 941 indicates the type of the DjVu chunk. */ 942 943 struct ddjvu_message_chunk_s { /* ddjvu_message_t::m_chunk */ 944 ddjvu_message_any_t any; 945 const char *chunkid; 946 }; 947 948 /* About page messages -- 949 Both the <m_relayout> and <m_redisplay> messages are derived from the 950 <m_chunk> message. They are intended for driving a djvu image viewer. 951 When receiving <m_relayout>, the viewer should get the image size, decide 952 zoom factors, and place the image area, scrollbars, toolbars, and other gui 953 objects. When receiving <m_redisplay>, the viewer should invalidate the 954 image area so that the gui toolkit calls the repaint event handler. This 955 handler should call ddjvu_page_render() and paint the part of the 956 image that needs repainting. */ 957 958 959 960 /* ------- QUERIES ------- */ 961 962 /* ddjvu_page_get_width --- 963 Returns the page width in pixels. Calling this function 964 before receiving a <m_pageinfo> message always yields <0>. */ 965 966 DDJVUAPI int 967 ddjvu_page_get_width(ddjvu_page_t *page); 968 969 970 /* ddjvu_page_get_height--- 971 Returns the page height in pixels. Calling this function 972 before receiving a <m_pageinfo> message always yields <0>. */ 973 974 DDJVUAPI int 975 ddjvu_page_get_height(ddjvu_page_t *page); 976 977 /* ddjvu_page_get_resolution --- 978 Returns the page resolution in pixels per inch (dpi). 979 Calling this function before receiving a <m_pageinfo> 980 message yields a meaningless but plausible value. */ 981 982 DDJVUAPI int 983 ddjvu_page_get_resolution(ddjvu_page_t *page); 984 985 986 /* ddjvu_page_get_gamma --- 987 Returns the gamma of the display for which this page was designed. 988 Calling this function before receiving a <m_pageinfo> 989 message yields a meaningless but plausible value. */ 990 991 DDJVUAPI double 992 ddjvu_page_get_gamma(ddjvu_page_t *page); 993 994 995 /* ddjvu_page_get_version --- 996 Returns the version of the djvu file format. 997 Calling this function before receiving a <m_pageinfo> 998 message yields a meaningless but plausible value. */ 999 1000 DDJVUAPI int 1001 ddjvu_page_get_version(ddjvu_page_t *page); 1002 1003 /* ddjvu_code_get_version --- 1004 Returns the version of the djvu file format 1005 implemented by this library. More or less graceful 1006 degradation might arise if this is smaller than 1007 the number returned by <ddjvu_page_get_version>. */ 1008 1009 DDJVUAPI int 1010 ddjvu_code_get_version(void); 1011 1012 1013 /* ddjvu_page_get_type --- 1014 Returns the type of the page data. 1015 Calling this function before the termination of the 1016 decoding process might returns <DDJVU_PAGETYPE_UNKNOWN>. */ 1017 1018 typedef enum { 1019 DDJVU_PAGETYPE_UNKNOWN, 1020 DDJVU_PAGETYPE_BITONAL, 1021 DDJVU_PAGETYPE_PHOTO, 1022 DDJVU_PAGETYPE_COMPOUND, 1023 } ddjvu_page_type_t; 1024 1025 DDJVUAPI ddjvu_page_type_t 1026 ddjvu_page_get_type(ddjvu_page_t *page); 1027 1028 1029 /* ddjvu_page_get_{short,long}_description --- DEPRECATED */ 1030 1031 DDJVUAPI char *ddjvu_page_get_short_description(ddjvu_page_t *); 1032 DDJVUAPI char *ddjvu_page_get_long_description(ddjvu_page_t *); 1033 1034 1035 /* ddjvu_page_set_rotation --- 1036 Changes the counter-clockwise rotation angle for a DjVu page. 1037 Calling this function before receiving a <m_pageinfo> 1038 message has no good effect. */ 1039 1040 typedef enum { 1041 DDJVU_ROTATE_0 = 0, 1042 DDJVU_ROTATE_90 = 1, 1043 DDJVU_ROTATE_180 = 2, 1044 DDJVU_ROTATE_270 = 3, 1045 } ddjvu_page_rotation_t; 1046 1047 DDJVUAPI void 1048 ddjvu_page_set_rotation(ddjvu_page_t *page, 1049 ddjvu_page_rotation_t rot); 1050 1051 1052 /* ddjvu_page_get_rotation --- 1053 Returns the counter-clockwise rotation angle for the DjVu page. 1054 The rotation is automatically taken into account 1055 by <ddjvu_page_render>, <ddjvu_page_get_width> 1056 and <ddjvu_page_get_height>. */ 1057 1058 DDJVUAPI ddjvu_page_rotation_t 1059 ddjvu_page_get_rotation(ddjvu_page_t *page); 1060 1061 1062 /* ddjvu_page_get_initial_rotation --- 1063 Returns the page rotation specified by the 1064 orientation flags in the DjVu file. 1065 [brain damage warning] This is useful because 1066 maparea coordinates in the annotation chunks 1067 are expressed relative to the rotated coordinates 1068 whereas text coordinates in the hidden text data 1069 are expressed relative to the unrotated coordinates. */ 1070 1071 DDJVUAPI ddjvu_page_rotation_t 1072 ddjvu_page_get_initial_rotation(ddjvu_page_t *page); 1073 1074 1075 1076 /* ------- RENDER ------- */ 1077 1078 1079 /* ddjvu_render_mode_t --- 1080 Various ways to render a page. */ 1081 1082 typedef enum { 1083 DDJVU_RENDER_COLOR = 0, /* color page or stencil */ 1084 DDJVU_RENDER_BLACK, /* stencil or color page */ 1085 DDJVU_RENDER_COLORONLY, /* color page or fail */ 1086 DDJVU_RENDER_MASKONLY, /* stencil or fail */ 1087 DDJVU_RENDER_BACKGROUND, /* color background layer */ 1088 DDJVU_RENDER_FOREGROUND, /* color foreground layer */ 1089 } ddjvu_render_mode_t; 1090 1091 1092 /* ddjvu_rect_t --- 1093 This structure specifies the location of a rectangle. 1094 Coordinates are usually expressed in pixels relative to 1095 the BOTTOM LEFT CORNER (but see ddjvu_format_set_y_direction). 1096 Members <x> and <y> indicate the position of the bottom left 1097 corner of the rectangle Members <w> and <h> indicate the 1098 width and height of the rectangle. */ 1099 1100 struct ddjvu_rect_s { 1101 int x, y; 1102 unsigned int w, h; 1103 }; 1104 1105 1106 /* ddjvu_page_render -- 1107 Renders a segment of a page with arbitrary scale. 1108 Argument <mode> indicates what image layers 1109 should be rendered. 1110 1111 Conceptually this function renders the full page 1112 into a rectangle <pagerect> and copies the 1113 pixels specified by rectangle <renderrect> 1114 into the buffer starting at position <imagebuffer>. 1115 The actual code is much more efficient than that. 1116 1117 The final image is written into buffer <imagebuffer>. 1118 Argument <pixelformat> specifies the expected pixel format. 1119 Argument <rowsize> specifies the number of BYTES from 1120 one row to the next in the buffer. The buffer must be 1121 large enough to accomodate the desired image. 1122 1123 This function makes a best effort to compute an image 1124 that reflects the most recently decoded data. It might 1125 return <FALSE> to indicate that no image could be 1126 computed at this point, and that nothing was written into 1127 the buffer. */ 1128 1129 DDJVUAPI int 1130 ddjvu_page_render(ddjvu_page_t *page, 1131 const ddjvu_render_mode_t mode, 1132 const ddjvu_rect_t *pagerect, 1133 const ddjvu_rect_t *renderrect, 1134 const ddjvu_format_t *pixelformat, 1135 unsigned long rowsize, 1136 char *imagebuffer ); 1137 1138 1139 1140 1141 /* -------------------------------------------------- */ 1142 /* COORDINATE TRANSFORMS */ 1143 /* -------------------------------------------------- */ 1144 1145 /* ddjvu_rectmapper_create -- 1146 Creates a <ddjvu_rectmapper_t> data structure 1147 representing an affine coordinate transformation that 1148 maps points from rectangle <input> to rectangle <output>. 1149 The transformation maintains the positions relative 1150 to the coordinates of the rectangle corners. */ 1151 1152 DDJVUAPI ddjvu_rectmapper_t * 1153 ddjvu_rectmapper_create(ddjvu_rect_t *input, ddjvu_rect_t *output); 1154 1155 1156 /* ddjvu_rectmapper_modify --- 1157 Modifies the coordinate transform <mapper> by redefining 1158 which corners of the output rectangle match those of the 1159 input rectangle. This function first applies a counter-clockwise 1160 rotation of <rotation> quarter-turns, and then reverses the X 1161 (resp. Y) coordinates when <mirrorx> (resp. <mirrory>) is non zero. */ 1162 1163 DDJVUAPI void 1164 ddjvu_rectmapper_modify(ddjvu_rectmapper_t *mapper, 1165 int rotation, int mirrorx, int mirrory); 1166 1167 1168 /* ddjvu_rectmapper_release --- 1169 Destroys the <ddjvu_rect_mapper_t> structure 1170 returned by <ddjvu_rect_mapper_create>. */ 1171 1172 DDJVUAPI void 1173 ddjvu_rectmapper_release(ddjvu_rectmapper_t *mapper); 1174 1175 /* ddjvu_map_point, ddjvu_map_rect --- 1176 Applies the coordinate transform 1177 to a point or a rectangle */ 1178 1179 DDJVUAPI void 1180 ddjvu_map_point(ddjvu_rectmapper_t *mapper, int *x, int *y); 1181 1182 DDJVUAPI void 1183 ddjvu_map_rect(ddjvu_rectmapper_t *mapper, ddjvu_rect_t *rect); 1184 1185 1186 /* ddjvu_unmap_point, ddjvu_unmap_rect --- 1187 Applies the inverse coordinate transform 1188 to a point or a rectangle */ 1189 1190 DDJVUAPI void 1191 ddjvu_unmap_point(ddjvu_rectmapper_t *mapper, int *x, int *y); 1192 1193 DDJVUAPI void 1194 ddjvu_unmap_rect(ddjvu_rectmapper_t *mapper, ddjvu_rect_t *rect); 1195 1196 1197 1198 1199 /* -------------------------------------------------- */ 1200 /* DJVU_FORMAT_T */ 1201 /* -------------------------------------------------- */ 1202 1203 1204 /* ddjvu_format_style_t --- 1205 Enumerated type for pixel formats. */ 1206 1207 typedef enum { 1208 DDJVU_FORMAT_BGR24, /* truecolor 24 bits in BGR order */ 1209 DDJVU_FORMAT_RGB24, /* truecolor 24 bits in RGB order */ 1210 DDJVU_FORMAT_RGBMASK16, /* truecolor 16 bits with masks */ 1211 DDJVU_FORMAT_RGBMASK32, /* truecolor 32 bits with masks */ 1212 DDJVU_FORMAT_GREY8, /* greylevel 8 bits */ 1213 DDJVU_FORMAT_PALETTE8, /* paletized 8 bits (6x6x6 color cube) */ 1214 DDJVU_FORMAT_MSBTOLSB, /* packed bits, msb on the left */ 1215 DDJVU_FORMAT_LSBTOMSB, /* packed bits, lsb on the left */ 1216 } ddjvu_format_style_t; 1217 1218 1219 /* ddjvu_format_create --- 1220 Creates a <ddjvu_format_t> object describing a pixel format. 1221 Argument <style> describes the generic pixel format. 1222 Argument <args> is an array of <nargs> unsigned ints 1223 providing additionnal information: 1224 - When style is <RGBMASK*>, argument <nargs> must be <3> or <4>. 1225 The three first entries of array <args> are three contiguous 1226 bit masks for the red, green, and blue components of each pixel. 1227 The resulting color is then xored with the optional fourth entry. 1228 - When style is <PALETTE*>, argument <nargs> must be <216> 1229 and array <args> contains the 6*6*6 entries of a web 1230 color cube. 1231 - Otherwise <nargs> must be <0>. */ 1232 1233 DDJVUAPI ddjvu_format_t * 1234 ddjvu_format_create(ddjvu_format_style_t style, 1235 int nargs, unsigned int *args); 1236 1237 1238 /* ddjvu_format_set_row_order --- 1239 Sets a flag indicating whether the rows in the pixel buffer 1240 are stored starting from the top or the bottom of the image. 1241 Default ordering starts from the bottom of the image. 1242 This is the opposite of the X11 convention. */ 1243 1244 DDJVUAPI void 1245 ddjvu_format_set_row_order(ddjvu_format_t *format, int top_to_bottom); 1246 1247 1248 /* ddjvu_format_set_y_direction --- 1249 Sets a flag indicating whether the y coordinates in the drawing 1250 area are oriented from bottom to top, or from top to botttom. 1251 The default is bottom to top, similar to PostScript. 1252 This is the opposite of the X11 convention. */ 1253 1254 DDJVUAPI void 1255 ddjvu_format_set_y_direction(ddjvu_format_t *format, int top_to_bottom); 1256 1257 1258 /* ddjvu_format_set_ditherbits --- 1259 Specifies the final depth of the image on the screen. 1260 This is used to decide which dithering algorithm should be used. 1261 The default is usually appropriate. */ 1262 1263 DDJVUAPI void 1264 ddjvu_format_set_ditherbits(ddjvu_format_t *format, int bits); 1265 1266 1267 /* ddjvu_format_set_gamma --- 1268 Sets the gamma of the display for which the pixels are 1269 intended. This will be combined with the gamma stored in 1270 DjVu documents in order to compute a suitable color 1271 correction. The default value is 2.2. */ 1272 1273 DDJVUAPI void 1274 ddjvu_format_set_gamma(ddjvu_format_t *format, double gamma); 1275 1276 1277 /* ddjvu_format_set_white --- 1278 Sets the whitepoint of the display for which the pixels are 1279 intended. This will be combined with the gamma stored in 1280 DjVu documents in order to compute a suitable color 1281 correction. The default value is 0xff,0xff,0xff. */ 1282 1283 DDJVUAPI void 1284 ddjvu_format_set_white(ddjvu_format_t *format, 1285 unsigned char b, unsigned char g, unsigned char r); 1286 1287 /* ddjvu_format_release --- 1288 Release a reference to a <ddjvu_format_t> object. 1289 The calling program should no longer reference this object. */ 1290 1291 DDJVUAPI void 1292 ddjvu_format_release(ddjvu_format_t *format); 1293 1294 1295 1296 1297 /* -------------------------------------------------- */ 1298 /* THUMBNAILS */ 1299 /* -------------------------------------------------- */ 1300 1301 1302 /* ddjvu_thumbnail_status --- 1303 Determine whether a thumbnail is available for page <pagenum>. 1304 Calling this function with non zero argument <start> initiates 1305 a thumbnail calculation job. Regardless of its success, 1306 the completion of the job is signalled by a subsequent 1307 <m_thumbnail> message. */ 1308 1309 DDJVUAPI ddjvu_status_t 1310 ddjvu_thumbnail_status(ddjvu_document_t *document, int pagenum, int start); 1311 1312 1313 /* ddjvu_message_t::m_thumbnail --- 1314 This message is sent when additional thumbnails are available. */ 1315 1316 struct ddjvu_message_thumbnail_s { /* ddjvu_message_t::m_thumbnail */ 1317 ddjvu_message_any_t any; 1318 int pagenum; 1319 }; 1320 1321 1322 /* ddjvu_thumbnail_render --- 1323 Renders a thumbnail for page <pagenum>. 1324 Argument <imagebuffer> must be large enough to contain 1325 an image of size <*wptr> by <*hptr> using pixel format 1326 <pixelformat>. Argument <rowsize> specifies the number 1327 of BYTES from one row to the next in the buffer. 1328 This function returns <FALSE> when no thumbnail is available. 1329 Otherwise it returns <TRUE>, adjusts <*wptr> and <*hptr> to 1330 reflect the thumbnail size, and, if the pointer <imagebuffer> 1331 is non zero, writes the pixel data into the image buffer. */ 1332 1333 DDJVUAPI int 1334 ddjvu_thumbnail_render(ddjvu_document_t *document, int pagenum, 1335 int *wptr, int *hptr, 1336 const ddjvu_format_t *pixelformat, 1337 unsigned long rowsize, 1338 char *imagebuffer); 1339 1340 1341 1342 /* -------------------------------------------------- */ 1343 /* SAVE AND PRINT JOBS */ 1344 /* -------------------------------------------------- */ 1345 1346 1347 /* ddjvu_message_t::m_progress --- 1348 These messages are generated to indicate progress 1349 towards the completion of a print or save job. */ 1350 1351 struct ddjvu_message_progress_s { 1352 ddjvu_message_any_t any; 1353 ddjvu_status_t status; 1354 int percent; 1355 }; 1356 1357 /* ddjvu_document_print --- 1358 Converts specified pages of a djvu document into postscript. 1359 This function works asynchronously in a separate thread. 1360 You can use the following idiom for synchronous operation: 1361 1362 ddjvu_job_t *job = ddjvu_document_print(....); 1363 while (! ddjvu_job_done(job) ) 1364 handle_ddjvu_messages(context, TRUE); 1365 1366 The postscript data is written to stdio file <output>. 1367 Arguments <optc> and <optv> specify printing options. 1368 All options described on the <djvups> man page are 1369 recognized, except <"-help"> and <"-verbose">. 1370 */ 1371 1372 DDJVUAPI ddjvu_job_t * 1373 ddjvu_document_print(ddjvu_document_t *document, FILE *output, 1374 int optc, const char * const * optv); 1375 1376 1377 /* ddjvu_document_save --- 1378 Saves the djvu document as a bundled djvu file. 1379 This function works asynchronously in a separate thread. 1380 You can use the following idiom for synchronous operation: 1381 1382 ddjvu_job_t *job = ddjvu_document_save(....); 1383 while (! ddjvu_job_done(job) ) 1384 handle_ddjvu_messages(context, TRUE); 1385 1386 The bundled djvu data is written to file <output> 1387 which must be seekable. Arguments <optc> and <optv> 1388 can be used to pass the following options: 1389 * Option "-pages=<pagespec>" specify a subset of pages 1390 using the same syntax as program <ddjvu>. 1391 Reordering or duplicating pages is prohibited. 1392 * Option "-indirect=<filename>" causes the creation 1393 of an indirect document with index file <filename> 1394 and auxiliary files in the same directory. 1395 The file name is UTF-8 encoded. 1396 When this option is specified, the argument <output> 1397 is ignored and should be NULL. 1398 */ 1399 DDJVUAPI ddjvu_job_t * 1400 ddjvu_document_save(ddjvu_document_t *document, FILE *output, 1401 int optc, const char * const * optv); 1402 1403 1404 1405 1406 /* -------------------------------------------------- */ 1407 /* S-EXPRESSIONS */ 1408 /* -------------------------------------------------- */ 1409 1410 1411 /* DjVu files can contain ancillary information such as 1412 document outline, hidden text, hyperlinks, and metadata. 1413 Program <djvused> provides for manipulating such 1414 information. Like <djvused>, the DDJVU API represents 1415 this information using a lisp s-expressions. See file 1416 <"libdjvu/miniexp.h"> for the s-expression documentation 1417 and manipulation functions. See the <djvused> man page 1418 for the specification of the s-expressions representing 1419 outlines, hidden text and annotations. It often help 1420 to print s-expressions using function <miniexp_pprint>. 1421 1422 WARNING: All strings in s-expression are UTF-8 encoded. 1423 Strings returned by miniexp_to_str might have to be 1424 converted to the locale encoding. */ 1425 1426 1427 /* miniexp_t -- 1428 Opaque type representing s-expressions. 1429 The same definition also appears in 1430 file <"libdjvu/miniexp.h">. */ 1431 1432 #ifndef MINIEXP_H 1433 typedef struct miniexp_s* miniexp_t; 1434 #endif 1435 1436 /* ddjvu_miniexp_release -- 1437 This function controls the allocation of the 1438 s-expressions returned by functions from the DDJVU 1439 API. It indicates that the s-expression <expr> is no 1440 longer needed and can be deallocated as soon as 1441 necessary. Otherwise the s-expression remains allocated 1442 as long as the document object exists. */ 1443 1444 DDJVUAPI void 1445 ddjvu_miniexp_release(ddjvu_document_t *document, miniexp_t expr); 1446 1447 1448 /* ddjvu_document_get_outline -- 1449 This function tries to obtain the document outline. 1450 If this information is available, it returns a 1451 s-expression with the same syntax as function 1452 <print-outline> of program <djvused>. 1453 Otherwise it returns <miniexp_dummy> until 1454 the document header gets fully decoded. 1455 Typical synchronous usage: 1456 1457 miniexp_t r; 1458 while ((r=ddjvu_document_get_outline(doc))==miniexp_dummy) 1459 handle_ddjvu_messages(ctx, TRUE); 1460 1461 This function returns the empty list <miniexp_nil> when 1462 the document contains no outline information. It can also 1463 return symbols <failed> or <stopped> when an error occurs 1464 while accessing the desired information. */ 1465 1466 DDJVUAPI miniexp_t 1467 ddjvu_document_get_outline(ddjvu_document_t *document); 1468 1469 1470 /* ddjvu_document_get_anno -- 1471 This function returns the document-wide annotations. 1472 This corresponds to a proposed change in the djvu format. 1473 When no new-style document-wide annotations are available 1474 and <compat> is true, this function searches a shared 1475 annotation chunk and returns its contents. 1476 1477 This function returns <miniexp_dummy> if the information 1478 is not yet available. It may then cause the emission 1479 of <m_pageinfo> messages with null <m_any.page>. 1480 1481 This function returns the empty list <miniexp_nil> when 1482 the document does not contain page annotations. It can also 1483 return symbols <failed> or <stopped> when an error occurs 1484 while accessing the desired information. */ 1485 1486 DDJVUAPI miniexp_t 1487 ddjvu_document_get_anno(ddjvu_document_t *document, int compat); 1488 1489 1490 /* ddjvu_document_get_pagetext -- 1491 This function tries to obtain the text information for 1492 page <pageno>. If this information is available, it 1493 returns a s-expression with the same syntax as function 1494 <print-txt> of program <djvused>. Otherwise it starts 1495 fetching the page data and returns <miniexp_dummy>. 1496 This function causes the emission of <m_pageinfo> messages 1497 with zero in the <m_any.page> field. 1498 Typical synchronous usage: 1499 1500 miniexp_t r; 1501 while ((r=ddjvu_document_get_pagetext(doc,pageno,0))==miniexp_dummy) 1502 handle_ddjvu_messages(ctx, TRUE); 1503 1504 This function returns the empty list <miniexp_nil> when 1505 the page contains no text information. It can also return 1506 symbols <failed> or <stopped> when an error occurs while 1507 accessing the desired information. 1508 1509 Argument <maxdetail> controls the level of detail in the 1510 returned s-expression. Values "page", "column", "region", "para", 1511 "line", and "word" restrict the output to the specified granularity. 1512 All other values produce a s-expression that represents 1513 the hidden text data as finely as possible. */ 1514 1515 DDJVUAPI miniexp_t 1516 ddjvu_document_get_pagetext(ddjvu_document_t *document, int pageno, 1517 const char *maxdetail); 1518 1519 1520 /* ddjvu_document_get_pageanno -- 1521 This function tries to obtain the annotations for 1522 page <pageno>. If this information is available, it 1523 returns a s-expression with the same syntax as function 1524 <print-ant> of program <djvused>. Otherwise it starts 1525 fetching the page data and returns <miniexp_dummy>. 1526 This function causes the emission of <m_pageinfo> messages 1527 with zero in the <m_any.page> field. 1528 Typical synchronous usage: 1529 1530 miniexp_t r; 1531 while ((r = ddjvu_document_get_pageanno(doc,pageno))==miniexp_dummy) 1532 handle_ddjvu_messages(ctx, TRUE); 1533 1534 This function returns the empty list <miniexp_nil> when 1535 the page contains no annotations. It can also return 1536 symbols <failed> or <stopped> when an error occurs while 1537 accessing the desired information. */ 1538 1539 DDJVUAPI miniexp_t 1540 ddjvu_document_get_pageanno(ddjvu_document_t *document, int pageno); 1541 1542 1543 /* --- Helper functions to parse annotations --- */ 1544 1545 /* ddjvu_anno_get_bgcolor -- 1546 Parse the annotations and extracts the desired 1547 background color as a color string ("#FFFFFF"). 1548 See <(background ...)> in the djvused man page. 1549 Returns zero if this information is not specified. */ 1550 1551 DDJVUAPI const char * 1552 ddjvu_anno_get_bgcolor(miniexp_t annotations); 1553 1554 1555 /* ddjvu_anno_get_zoom -- 1556 Parse the annotations and extracts the desired zoom factor. 1557 See <(zoom ...)> in the djvused man page. 1558 Returns zero if this information is not specified. */ 1559 1560 DDJVUAPI const char * 1561 ddjvu_anno_get_zoom(miniexp_t annotations); 1562 1563 1564 /* ddjvu_anno_get_mode -- 1565 Parse the annotations and extracts the desired display mode. 1566 See <(mode ...)> in the djvused man page. 1567 Returns zero if this information is not specified. */ 1568 1569 DDJVUAPI const char * 1570 ddjvu_anno_get_mode(miniexp_t annotations); 1571 1572 1573 /* ddjvu_anno_get_horizalign -- 1574 Parse the annotations and extracts how the page 1575 image should be aligned horizontally. 1576 See <(align ...)> in the djvused man page. 1577 Returns zero if this information is not specified. */ 1578 1579 DDJVUAPI const char * 1580 ddjvu_anno_get_horizalign(miniexp_t annotations); 1581 1582 1583 /* ddjvu_anno_get_vertalign -- 1584 Parse the annotations and extracts how the page 1585 image should be aligned vertically. 1586 See <(align ...)> in the djvused man page. 1587 Returns zero if this information is not specified. */ 1588 1589 DDJVUAPI const char * 1590 ddjvu_anno_get_vertalign(miniexp_t annotations); 1591 1592 1593 /* ddjvu_anno_get_hyperlinks -- 1594 Parse the annotations and returns a zero terminated 1595 array of <(maparea ...)> s-expressions. 1596 The caller should free this array with function <free>. 1597 These s-expressions remain allocated as long 1598 as the annotations remain allocated. 1599 See also <(maparea ...)> in the djvused man page. */ 1600 1601 DDJVUAPI miniexp_t * 1602 ddjvu_anno_get_hyperlinks(miniexp_t annotations); 1603 1604 1605 /* ddjvu_anno_get_metadata_keys -- 1606 Parse the annotations and returns a zero terminated 1607 array of key symbols for the page metadata. 1608 The caller should free this array with function <free>. 1609 See also <(metadata ...)> in the djvused man page. */ 1610 1611 DDJVUAPI miniexp_t * 1612 ddjvu_anno_get_metadata_keys(miniexp_t annotations); 1613 1614 1615 /* ddjvu_anno_get_metadata -- 1616 Parse the annotations and returns the metadata string 1617 corresponding to the metadata key symbol <key>. 1618 The string remains allocated as long as the 1619 annotations s-expression remain allocated. 1620 Returns zero if no such key is present. */ 1621 1622 DDJVUAPI const char * 1623 ddjvu_anno_get_metadata(miniexp_t annotations, miniexp_t key); 1624 1625 1626 /* ddjvu_anno_get_xmp -- 1627 Parse the annotations and returns the xmp metadata string. 1628 The string remains allocated as long as the 1629 annotations s-expression remain allocated. 1630 Returns zero if no such key is present. */ 1631 1632 DDJVUAPI const char * 1633 ddjvu_anno_get_xmp(miniexp_t annotations); 1634 1635 1636 /* -------------------------------------------------- */ 1637 /* DJVU_MESSAGE_T */ 1638 /* -------------------------------------------------- */ 1639 1640 1641 /* We can now define the djvu_message_t union */ 1642 1643 union ddjvu_message_s { 1644 struct ddjvu_message_any_s m_any; 1645 struct ddjvu_message_error_s m_error; 1646 struct ddjvu_message_info_s m_info; 1647 struct ddjvu_message_newstream_s m_newstream; 1648 struct ddjvu_message_docinfo_s m_docinfo; 1649 struct ddjvu_message_pageinfo_s m_pageinfo; 1650 struct ddjvu_message_chunk_s m_chunk; 1651 struct ddjvu_message_relayout_s m_relayout; 1652 struct ddjvu_message_redisplay_s m_redisplay; 1653 struct ddjvu_message_thumbnail_s m_thumbnail; 1654 struct ddjvu_message_progress_s m_progress; 1655 }; 1656 1657 1658 /* -------------------------------------------------- */ 1659 /* BACKDOORS */ 1660 /* -------------------------------------------------- */ 1661 1662 #ifdef __cplusplus 1663 } // extern "C" 1664 #endif 1665 1666 /* ddjvu_get_DjVuImage --- 1667 ddjvu_get_DjVuDocument --- 1668 These functions provide an access to the libdjvu objects 1669 associated with the ddjvuapi objects. These backdoors can 1670 be useful for advanced manipulations. These two functions 1671 are declared in C++ when file <"ddjvuapi.h"> is included 1672 after the libdjvu header files <"DjVuImage.h"> and 1673 <"DjVuDocument.h">. */ 1674 1675 #ifdef __cplusplus 1676 # ifndef NOT_USING_DJVU_NAMESPACE 1677 # ifdef _DJVUIMAGE_H 1678 DDJVUAPI GP<DjVuImage> 1679 ddjvu_get_DjVuImage(ddjvu_page_t *page); 1680 # endif 1681 # ifdef _DJVUDOCUMENT_H 1682 DDJVUAPI GP<DjVuDocument> 1683 ddjvu_get_DjVuDocument(ddjvu_document_t *document); 1684 # endif 1685 # endif 1686 #endif 1687 1688 #endif /* DDJVUAPI_H */ 1689