source: trunk/libdjvu/ddjvuapi.h @ 209

Last change on this file since 209 was 206, checked in by Eugene Romanenko, 14 years ago

DJVU plugin: djvulibre updated to version 3.5.19

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