source: trunk/libdjvu/ddjvuapi.h @ 280

Last change on this file since 280 was 280, checked in by rbri, 11 years ago

DJVU plugin: djvulibre updated to version 3.5.22

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