source: trunk/libdjvu/ddjvuapi.h @ 101

Last change on this file since 101 was 17, checked in by Eugene Romanenko, 16 years ago

update makefiles, remove absolute paths, update djvulibre to version 3.5.17

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