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