source: trunk/libdjvu/ddjvuapi.h @ 15

Last change on this file since 15 was 15, checked in by Eugene Romanenko, 15 years ago

needed libs update

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