/* 

//C- -------------------------------------------------------------------

//C- DjVuLibre-3.5

//C- Copyright (c) 2002  Leon Bottou and Yann Le Cun.

//C- Copyright (c) 2001  AT&T

//C-

//C- This software is subject to, and may be distributed under, the

//C- GNU General Public License, either Version 2 of the license,

//C- or (at your option) any later version. The license should have

//C- accompanied the software or you may obtain a copy of the license

//C- from the Free Software Foundation at http://www.fsf.org .

//C-

//C- This program is distributed in the hope that it will be useful,

//C- but WITHOUT ANY WARRANTY; without even the implied warranty of

//C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

//C- GNU General Public License for more details.

//C- 

//C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from

//C- Lizardtech Software.  Lizardtech Software has authorized us to

//C- replace the original DjVu(r) Reference Library notice by the following

//C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):

//C-

//C-  ------------------------------------------------------------------

//C- | DjVu (r) Reference Library (v. 3.5)

//C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.

//C- | The DjVu Reference Library is protected by U.S. Pat. No.

//C- | 6,058,214 and patents pending.

//C- |

//C- | This software is subject to, and may be distributed under, the

//C- | GNU General Public License, either Version 2 of the license,

//C- | or (at your option) any later version. The license should have

//C- | accompanied the software or you may obtain a copy of the license

//C- | from the Free Software Foundation at http://www.fsf.org .

//C- |

//C- | The computer code originally released by LizardTech under this

//C- | license and unmodified by other parties is deemed "the LIZARDTECH

//C- | ORIGINAL CODE."  Subject to any third party intellectual property

//C- | claims, LizardTech grants recipient a worldwide, royalty-free, 

//C- | non-exclusive license to make, use, sell, or otherwise dispose of 

//C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the 

//C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU 

//C- | General Public License.   This grant only confers the right to 

//C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to 

//C- | the extent such infringement is reasonably necessary to enable 

//C- | recipient to make, have made, practice, sell, or otherwise dispose 

//C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to 

//C- | any greater extent that may be necessary to utilize further 

//C- | modifications or combinations.

//C- |

//C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY

//C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED

//C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF

//C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

//C- +------------------------------------------------------------------

*/

#ifndef DDJVUAPI_H

#define DDJVUAPI_H

#ifdef __cplusplus

extern "C" { 

#endif

#if 0

}

#endif

#include <stddef.h>

#include <stdlib.h>

#include <stdio.h>

#ifndef DDJVUAPI

# ifdef _WIN32

#  ifdef DDJVUAPI_EXPORT

#   define DDJVUAPI __declspec(dllexport)

#  else

#   define DDJVUAPI __declspec(dllimport)

#  endif

# endif

#endif

#ifndef DDJVUAPI

# define DDJVUAPI /**/

#endif

#ifndef TRUE

# define TRUE  (1)

#endif

#ifndef FALSE

# define FALSE (0)

#endif

/* -------------------------------------------------- */

/* DDJVU API                                          */

/* -------------------------------------------------- */

/* The DDJVU API provides for efficiently decoding and

   displaying DjVu documents.  It provides for displaying

   images without waiting for the complete DjVu data. Images

   can be displayed as soon as sufficient data is

   available. A higher quality image might later be

   displayed when further data is available.  The DjVu

   library achieves this using a complicated scheme

   involving multiple threads. The DDJVU API hides this

   complexity with a familiar event model.

*/

/* Compiler symbol DDJVUAPI_VERSION tracks 

   backward compatible additions to the DDJVU API.

   Version   Change

   -----------------------------

     23    Added:

              miniexp_mutate()

     22    Changed

              miniexp strings accept unicode escapes

              deprecated miniexp_io_t::p_print7bits

              added miniexp_io_t::p_flags

     21    Added:

              reentrant version of miniexp input/output

     20    Added:

              ddjvu_get_version_string()

              ddjvu_format_set_white()

              ddjvu_anno_get_xmp()

     19    Added:

              ddjvu_document_create_by_filename_utf8()

     18    Added:

              ddjvu_document_get_{anno,pagedump,filedump}()

           Modifed (binary compatible):

              ddjvu_document_get_{fileinfo,pageinfo}()   

              ddjvu_document_save() [--pages, --indirect=]

           Deprecated:

              ddjvu_document_search_pageno()

              ddjvu_page_get_{short,long}_description()

     17    Added:

              ddjvu_page_get_initial_rotation(), ddjvu_code_get_version()

              ddjvu_document_{get_filenum,get_fileinfo}}()

              ddjvu_document_{search_pageno,check_pagedata}()

              ddjvu_rectmapper_t and related functions.

     16    Added:

              miniexp.h and related functions.

     15    Added:

              ddjvu_document_get_pageinfo()

              ddjvu_document_print()

     14    Initial version.

*/

#define DDJVUAPI_VERSION 23

typedef struct ddjvu_context_s    ddjvu_context_t;

typedef union  ddjvu_message_s    ddjvu_message_t;

typedef struct ddjvu_job_s        ddjvu_job_t;

typedef struct ddjvu_document_s   ddjvu_document_t;

typedef struct ddjvu_page_s       ddjvu_page_t;

typedef struct ddjvu_format_s     ddjvu_format_t;

typedef struct ddjvu_rect_s       ddjvu_rect_t;

typedef struct ddjvu_rectmapper_s ddjvu_rectmapper_t;

/* GENERAL CONVENTIONS:

   - all strings use locale encoding (unless specified otherwise).

   - all filenames are unencoded byte strings,

   - all errors are signaled with error event messages,

   - all functions returning a pointer might return a null pointer.

   HEADER:

   Always use the following idiom to include this file.

     #include <libdjvu/ddjvuapi.h>

     #include <libdjvu/miniexp.h>

   This file does not declare functions ddjvu_get_DjVuImage() 

   and djvu_get_DjVuDocument() unless you include files 

   "DjVuImage.h" and "DjVuDocument.h" before this file.

   PREREQUISITES:

   - Please read the djvu man page: <"tools/djvu.1">.

   - Please browse the file format specifications 

     <"doc/djvu3changes.txt"> and <"doc/djvu3spec.djvu">.

*/

/* -------------------------------------------------- */

/* DDJVU_CONTEXT_T                                    */

/* -------------------------------------------------- */

/* There is usually only one <ddjvu_context_t> object.  

   This object holds global data structures such as the 

   cache of decoded pages, or the list of pending 

   event messages.

 */

/* ddjvu_get_version_string() ---

   Returns a string that described the underlying code. */

DDJVUAPI const char*

ddjvu_get_version_string(void);

/* ddjvu_context_create ---

   Creates a <ddjvu_context_t> object.

   Argument <programname> is the name of the calling executable. */

DDJVUAPI ddjvu_context_t *

ddjvu_context_create(const char *programname);

/* ddjvu_context_release ---

   Release a reference to a <ddjvu_context_t> object.

   The calling program should no longer reference this object.

   The object itself will be destroyed as soon as no other object

   or thread needs it. */

DDJVUAPI void 

ddjvu_context_release(ddjvu_context_t *context);

/* ------- CACHE ------- */

/* ddjvu_cache_set_size ---

   Sets the maximum size of the cache of decoded page data.

   The argument is expressed in bytes. */

DDJVUAPI void

ddjvu_cache_set_size(ddjvu_context_t *context,

                     unsigned long cachesize);

/* ddjvu_cache_get_size ---

   Returns the maximum size of the cache. */

DDJVUAPI unsigned long

ddjvu_cache_get_size(ddjvu_context_t *context);

/* ddjvu_cache_clear ---

   Clears all cached data. */

DDJVUAPI void

ddjvu_cache_clear(ddjvu_context_t *context);

/* ------- MESSAGE QUEUE ------- */

/* Messages produced by the ddjvu api accumulate into

   the message queue. Processing messages is not optional!

   A typical message handling routine looks like this:

   void handle_ddjvu_messages(ddjvu_context_t *ctx, int wait)

   {

     const ddjvu_message_t *msg;

     if (wait)

       ddjvu_message_wait(ctx);

     while ((msg = ddjvu_message_peek(ctx)))

     {

       switch(msg->m_any.tag)

       { 

       case DDJVU_ERROR:      .... ; break;

       case DDJVU_INFO:       .... ; break;

       case DDJVU_NEWSTREAM:  .... ; break;

       ....

       default: break;

       }

       ddjvu_message_pop(ctx);

     }

   }

*/

/* ddjvu_message_peek ---

   Returns a pointer to the next DDJVU message.

   This function returns 0 if no message is available.

   It does not remove the message from the queue. */

DDJVUAPI ddjvu_message_t *

ddjvu_message_peek(ddjvu_context_t *context);

/* ddjvu_message_wait ---

   Returns a pointer to the next DDJVU message.

   This function waits until a message is available.

   It does not remove the message from the queue. */

DDJVUAPI ddjvu_message_t *

ddjvu_message_wait(ddjvu_context_t *context);

/* ddjvu_message_pop ---

   Removes one message from the queue.

   This function must be called after processing the message.

   Pointers returned by previous calls to <ddjvu_message_peek> 

   or <ddjvu_message_wait> are no longer valid after 

   calling <ddjvu_message_pop>. */

DDJVUAPI void

ddjvu_message_pop(ddjvu_context_t *context);

/* ddjvu_message_set_callback ---

   Defines a callback function invoked whenever

   a new message is posted to the ddjvuapi message queue,

   and returns a pointer to the previous callback function.

   This callback function can be called at any time

   while other code is executing. Do not call ddjvuapi

   functions from this callback. It should simply signal

   the main application event loop that new ddjvuapi messages

   are available.  Under WIN32, this is usually achieved

   by posting a user window message.  Under UNIX, this is

   usually achieved using a pipe: the callback writes 

   a single byte into the pipe; the main application loop

   monitors the reading end of the pipe and detects

   the presence of data. */

typedef void 

(*ddjvu_message_callback_t)(ddjvu_context_t *context, void *closure);

DDJVUAPI void

ddjvu_message_set_callback(ddjvu_context_t *context,

                           ddjvu_message_callback_t callback,

                           void *closure);

/* -------------------------------------------------- */

/* DDJVU_JOB_T                                        */

/* -------------------------------------------------- */

/* Many essential ddjvuapi functions initiate asynchronous operations. 

   These "jobs" run in seperate threads and report their

   progress by posting messages into the ddjvu context event queue. 

   Jobs are sometimes represented by a ddjvu_job_t object. */

/* ddjvu_job_status ---

   Returns the status of the specified job. */

typedef enum {

  DDJVU_JOB_NOTSTARTED, /* operation was not even started */

  DDJVU_JOB_STARTED,    /* operation is in progress */

  DDJVU_JOB_OK,         /* operation terminated successfully */

  DDJVU_JOB_FAILED,     /* operation failed because of an error */

  DDJVU_JOB_STOPPED     /* operation was interrupted by user */

} ddjvu_status_t;

DDJVUAPI ddjvu_status_t

ddjvu_job_status(ddjvu_job_t *job);

#define ddjvu_job_done(job) \

    (ddjvu_job_status(job) >= DDJVU_JOB_OK)

#define ddjvu_job_error(job) \

    (ddjvu_job_status(job) >= DDJVU_JOB_FAILED)

/* ddjvu_job_stop ---

   Attempts to cancel the specified job.

   This is a best effort function. 

   There no guarantee that the job will 

   actually stop.

 */

DDJVUAPI void

ddjvu_job_stop(ddjvu_job_t *job);

/* ddjvu_job_set_user_data ---

   ddjvu_job_get_user_data ---

   Each job can store an arbitrary pointer

   that callers can use for any purpose. These two 

   functions provide for accessing or setting this pointer. 

   This pointer is cleared when the job is released */

DDJVUAPI void

ddjvu_job_set_user_data(ddjvu_job_t *job, void *userdata);

DDJVUAPI void *

ddjvu_job_get_user_data(ddjvu_job_t *job);

/* ddjvu_job_release ---

   Releases a reference to a job object and clears its user 

   data field.  This does not cause the job to stop executing.

   The calling program should no longer reference this object.

   The object itself will be destroyed as soon as no 

   other object or thread needs it. 

*/

DDJVUAPI void

ddjvu_job_release(ddjvu_job_t *job);

/* -------------------------------------------------- */

/* DDJVU_MESSAGE_T                                    */

/* -------------------------------------------------- */

/* ddjvu_message_t ---

   This union type represents messages delivered by the

   DDJVU API. Each member of the union pertains to a

   specific kind of message.  Member <m_any> represents the

   information common to all kinds of messages.  Given a

   pointer 
 to a <djvu_message_t>, the message kind can

   be accessed as <"p->m_any.tag">. */

/* ddjvu_message_tag_t ---

   This enumerated type identifies each kind of 

   message delivered by the DDJVU API.  */

typedef enum {

  DDJVU_ERROR,

  DDJVU_INFO,

  DDJVU_NEWSTREAM,

  DDJVU_DOCINFO,

  DDJVU_PAGEINFO,

  DDJVU_RELAYOUT,

  DDJVU_REDISPLAY,

  DDJVU_CHUNK,

  DDJVU_THUMBNAIL,

  DDJVU_PROGRESS,

} ddjvu_message_tag_t;

/* ddjvu_message_t::m_any ---

   This structure is a member of the union <djvu_message_t>.

   It represents the information common to all kinds of

   messages.  Member <tag> indicates the kind of message.

   Members <context>, <document>, <page>, and <job> indicate 

   the origin of the message.  These fields contain null

   pointers when they are not relevant.

   These fields are also cleared when the corresponding

   object is released with <ddjvu_{job,page,document}_release>.

   If the message has not yet been passed to the user 

   with <ddjvu_message_{peek,wait}>, it is silently 

   removed from the message queue. */

typedef struct ddjvu_message_any_s {

  ddjvu_message_tag_t   tag;

  ddjvu_context_t      *context;

  ddjvu_document_t     *document;

  ddjvu_page_t         *page;

  ddjvu_job_t          *job;

} ddjvu_message_any_t; 

/* ddjvu_message_t::m_error ---

   Error messages are generated whenever the decoder or the

   DDJVU API encounters an error condition.  All errors are

   reported as error messages because they can occur

   asynchronously.  Member <message> is the error message.

   Members <function>, <filename> and <lineno>

   indicates the place where the error was detected. */

struct ddjvu_message_error_s {  /* ddjvu_message_t::m_error */

  ddjvu_message_any_t   any;

  const char           *message;

  const char           *function;

  const char           *filename;

  int                   lineno;

}; 

/* ddjvu_message_t::m_info ---

   This messages provides informational text indicating

   the progress of the decoding process. This might

   be displayed in the browser status bar. */

struct ddjvu_message_info_s {   /* ddjvu_message_t::m_info */

  ddjvu_message_any_t  any;

  const char          *message;

}; 

/* -------------------------------------------------- */

/* DDJVU_DOCUMENT_T                                    */

/* -------------------------------------------------- */

/* ddjvu_document_create ---

   Creates a decoder for a DjVu document and starts

   decoding.  This function returns immediately.  The

   decoding job then generates messages to request the raw

   data and to indicate the state of the decoding process.

   Argument <url> specifies an optional URL for the document.  

   The URL follows the usual syntax (<"protocol://machine/path">). 

   It should not end with a slash. It only serves two purposes:

   - The URL is used as a key for the cache of decoded pages.

   - The URL is used to document <m_newstream> messages.

   Setting argument <cache> to <TRUE> indicates that decoded pages

   should be cached when possible.  This only works when

   argument <url> is not the null pointer.

   It is important to understand that the URL is not used to

   access the data.  The document generates <m_newstream>

   messages to indicate which data is needed.  The caller must 

   then provide the raw data using <ddjvu_stream_write> 

   and <ddjvu_stream_close>.

   Localized characters in argument <url> should be in 

   urlencoded UTF-8 (like "%2A"). What is happening for non 

   ascii characters is unclear (probably UTF-8). */

DDJVUAPI ddjvu_document_t *

ddjvu_document_create(ddjvu_context_t *context,

                      const char *url,

                      int cache);

/* ddjvu_document_create_by_filename ---

   Creates a document for a DjVu document stored in a file.

   The document will directly access the specified DjVu file 

   or related files without generating <m_newstream> messages.

   The standard function expects the filename in locale encoding. 

   The utf8 variant expects an utf8 encoded filename. */

DDJVUAPI ddjvu_document_t *

ddjvu_document_create_by_filename(ddjvu_context_t *context,

                                  const char *filename,

                                  int cache);

DDJVUAPI ddjvu_document_t *

ddjvu_document_create_by_filename_utf8(ddjvu_context_t *context,

                                       const char *filename,

                                       int cache);

/* ddjvu_document_job ---

   Access the job object in charge of decoding the document header. 

   In fact <ddjvu_document_t> is a subclass of <ddjvu_job_t>

   and this function is a type cast. */

DDJVUAPI ddjvu_job_t *

ddjvu_document_job(ddjvu_document_t *document);

/* ddjvu_document_release ---

   Release a reference to a <ddjvu_document_t> object.

   The calling program should no longer reference this object.  

   The object itself will be destroyed as soon as no other object

   or thread needs it. */

#define ddjvu_document_release(document) \

   ddjvu_job_release(ddjvu_document_job(document))

/* ddjvu_document_set_user_data ---

   ddjvu_document_get_user_data ---

   Each <ddjvu_document_t> object can store an arbitray pointer

   that callers can use for any purpose. These two functions

   provide for accessing or setting this pointer. */

#define ddjvu_document_set_user_data(document,userdata) \

   ddjvu_job_set_user_data(ddjvu_document_job(document),userdata)

#define ddjvu_document_get_user_data(document) \

   ddjvu_job_get_user_data(ddjvu_document_job(document))

/* ddjvu_document_decoding_status ---

   ddjvu_document_decoding_done, ddjvu_document_decoding_error ---

   This function returns the status of the document header decoding job */

#define ddjvu_document_decoding_status(document) \

   ddjvu_job_status(ddjvu_document_job(document))

#define ddjvu_document_decoding_done(document) \

   (ddjvu_document_decoding_status(document) >= DDJVU_JOB_OK)

#define ddjvu_document_decoding_error(document) \

   (ddjvu_document_decoding_status(document) >= DDJVU_JOB_FAILED)

/* ------- STREAMS ------- */

/* ddjvu_message_t::m_newstream --- 

   Newstream messages are generated whenever the decoder

   needs to access raw DjVu data.  The caller must then

   provide the requested data using <ddjvu_stream_write> 

   and <ddjvu_stream_close>. 

   In the case of indirect documents, a single decoder 

   might simultaneously request several streams of data.  

   Each stream is identified by a small integer <streamid>.

   The first <m_newstream> message always has member

   <streamid> set to zero and member <name> set to the null

   pointer.  It indicates that the decoder needs to access

   the data in the main DjVu file.  In fact, data can be

   written to stream <0> as soon as the <ddjvu_document_t>

   object is created.

   Further <m_newstream> messages are generated to access

   the auxiliary files of indirect or indexed DjVu

   documents.  Member <name> then provides the basename of

   the auxiliary file.

   Member <url> is set according to the url argument

   provided to function <ddjvu_document_create>.  The first

   newstream message always contain the url passed to

   <ddjvu_document_create>.  Subsequent newstream messages

   contain the url of the auxiliary files for indirect or

   indexed DjVu documents. */

struct ddjvu_message_newstream_s { /* ddjvu_message_t::m_newstream */

  ddjvu_message_any_t  any;

  int                  streamid;

  const char          *name;

  const char          *url;

}; 

/* ddjvu_stream_write ---

   Provide raw data to the DjVu decoder.

   This function should be called as soon as the data is available,

   for instance when receiving DjVu data from a network connection.

 */

DDJVUAPI void

ddjvu_stream_write(ddjvu_document_t *document,

                   int streamid,

                   const char *data,

                   unsigned long datalen );

/* ddjvu_stream_close ---

   Indicates that no more data will be provided on a

   particular stream.  Argument <stop> most likely should be

   set to <FALSE>. Setting argument <stop> to <TRUE>

   indicates that the user has interrupted the data transfer

   (for instance by pressing the stop button of a browser)

   and that the decoding threads should be stopped as 

   soon as feasible. */

DDJVUAPI void

ddjvu_stream_close(ddjvu_document_t *document,

                   int streamid,

                   int stop );

/* ------- QUERIES ------- */

/* ddjvu_message_t::m_docinfo ---

   The <m_docinfo> message indicates that basic information

   about the document has been obtained and decoded.

   Not much can be done before this happens.

   Call <ddjvu_document_decoding_status> to determine

   whether the operation was successful. */

struct ddjvu_message_docinfo_s {

  ddjvu_message_any_t  any;

};

/* ddjvu_document_get_type ---

   Returns the type of a DjVu document.

   This function might return <DDJVU_DOCTYPE_UNKNOWN>

   when called before receiving a <m_docinfo> message. */

typedef enum {

  DDJVU_DOCTYPE_UNKNOWN=0,

  DDJVU_DOCTYPE_SINGLEPAGE,

  DDJVU_DOCTYPE_BUNDLED, 

  DDJVU_DOCTYPE_INDIRECT,

  DDJVU_DOCTYPE_OLD_BUNDLED, /* obsolete */

  DDJVU_DOCTYPE_OLD_INDEXED, /* obsolete */

} ddjvu_document_type_t;

DDJVUAPI ddjvu_document_type_t

ddjvu_document_get_type(ddjvu_document_t *document);

/* ddjvu_document_get_pagenum ---

   Returns the number of pages in a DjVu document.

   This function might return 1 when called 

   before receiving a <m_docinfo> message */

DDJVUAPI int

ddjvu_document_get_pagenum(ddjvu_document_t *document);

/* ------- ADVANCED ------- */

/* ddjvu_document_get_filenum --

   Returns the number of component files.

   This function might return 0 when called

   before receiving a <m_docinfo> message */

DDJVUAPI int

ddjvu_document_get_filenum(ddjvu_document_t *document);

/* ddjvu_document_get_fileinfo --

   Returns information about component file <fileno>.

   This function might return <DDJVU_JOB_STARTED> when

   called before receiving a <m_docinfo> message.

   String pointers in the returned data structure 

   might be null. Strings are UTF8 encoded and remain 

   allocated as long as the ddjvu_document_t object exists.

   Changes for ddjvuapi=18

   - Redefined as a macro passing the structure size.

*/

typedef struct ddjvu_fileinfo_s {

  char  type;                   /* [P]age, [T]humbnails, [I]nclude. */

  int   pageno;                 /* Negative when not applicable. */

  int   size;                   /* Negative when unknown. */

  const char *id;               /* File identifier. */

  const char *name;             /* Name for indirect documents. */

  const char *title;            /* Page title. */

} ddjvu_fileinfo_t;

#define ddjvu_document_get_fileinfo(d,f,i) \

   ddjvu_document_get_fileinfo_imp(d,f,i,sizeof(ddjvu_fileinfo_t))

DDJVUAPI ddjvu_status_t

ddjvu_document_get_fileinfo_imp(ddjvu_document_t *document, int fileno, 

                                ddjvu_fileinfo_t *info, unsigned int infosz);

/* ddjvu_document_search_pageno --- DEPRECATED. */

DDJVUAPI int ddjvu_document_search_pageno(ddjvu_document_t*, const char*);

/* ddjvu_document_check_pagedata ---

   Returns a non zero result if the data for page <pageno>

   is already in memory. When this is the case, functions 

   <ddjvu_document_get_pageinfo> and <ddjvu_document_get_pagetext> 

   return the information immediately.

   This function causes the emission of <m_pageinfo> messages 

   with zero in the <m_any.page> field whenever a new file

   is completely downloaded. */

DDJVUAPI int 

ddjvu_document_check_pagedata(ddjvu_document_t *document, int pageno);

/* ddjvu_document_get_pageinfo ---

   Attempts to obtain information about page <pageno>

   without decoding the page. If the information is available,

   the function returns <DDJVU_JOB_OK> and fills the <info> structure. 

   Otherwise it starts fetching page data and returns <DDJVU_JOB_STARTED>. 

   This function causes the emission of <m_pageinfo> messages 

   with zero in the <m_any.page> field.

   Typical synchronous usage:

   ddjvu_status_t r;

   ddjvu_pageinfo_t info;

   while ((r=ddjvu_document_get_pageinfo(doc,pageno,&info))

     handle_ddjvu_messages(ctx, TRUE);

   if (r>=DDJVU_JOB_FAILED)

     signal_error();

   Changes for ddjvuapi=18

   - Redefined as a macro passing the structure size.

   - Added fields 'rotation' and 'version'.

*/      

typedef struct ddjvu_pageinfo_s {

  int width;                    /* page width (in pixels) */

  int height;                   /* page height (in pixels) */

  int dpi;                      /* page resolution (in dots per inche) */

  int rotation;                 /* initial page orientation */

  int version;                  /* page version */

} ddjvu_pageinfo_t;

#define ddjvu_document_get_pageinfo(d,p,i) \

   ddjvu_document_get_pageinfo_imp(d,p,i,sizeof(ddjvu_pageinfo_t))

DDJVUAPI ddjvu_status_t

ddjvu_document_get_pageinfo_imp(ddjvu_document_t *document, int pageno, 

                                ddjvu_pageinfo_t *info, unsigned int infosz );

/* ddjvu_document_get_pagedump --

   This function returns a UTF8 encoded text describing the contents 

   of page <pageno> using the same format as command <djvudump>. 

   The returned string must be deallocated using <free()>.

   It returns <0> when the information is not yet available. 

   It may then cause then the emission of <m_pageinfo> 

   messages with null <m_any.page>.

*/   

DDJVUAPI char *

ddjvu_document_get_pagedump(ddjvu_document_t *document, int pageno);

/* ddjvu_document_get_filedump --

   This function returns a UTF8 encoded text describing the contents 

   of file <fileno> using the same format as command <djvudump>. 

   The returned string must be deallocated using <free()>.

   It returns <0> when the information is not yet available. 

   It may then cause then the emission of <m_pageinfo> 

   messages with null <m_any.page>.

*/   

DDJVUAPI char *

ddjvu_document_get_filedump(ddjvu_document_t *document, int fileno);

/* -------------------------------------------------- */

/* DJVU_PAGE_T                                        */

/* -------------------------------------------------- */

/* ddjvu_page_create_by_pageno ---

   Each page of a document can be accessed by creating a

   <ddjvu_page_t> object with this function.  Argument

   <pageno> indicates the page number, starting with page

   <0> to <pagenum-1>. This function may return NULL

   when called before receiving the <m_docinfo> message.

   Calling this function also initiates the data transfer 

   and the decoding threads for the specified page.  

   Various messages will document the progress of these 

   operations. Error messages will be generated if 

   the page does not exists. */

DDJVUAPI ddjvu_page_t *

ddjvu_page_create_by_pageno(ddjvu_document_t *document,

                            int pageno);

/* ddjvu_page_create_by_pageid ---

   This function is similar to <ddjvu_page_create_by_pageno>

   but identifies the desired page by name instead of page

   number. */

DDJVUAPI ddjvu_page_t *

ddjvu_page_create_by_pageid(ddjvu_document_t *document,

                            const char *pageid);

/* ddjvu_page_job ---

   Access the job object in charge of decoding the document header. 

   In fact <ddjvu_page_t> is a subclass of <ddjvu_job_t>

   and this function is a type cast. */

DDJVUAPI ddjvu_job_t *

ddjvu_page_job(ddjvu_page_t *page);

/* ddjvu_page_release ---

   Release a reference to a <ddjvu_page_t> object.

   The calling program should no longer reference this object.

   The object itself will be destroyed as soon as no other object

   or thread needs it. */

#define ddjvu_page_release(page) \

  ddjvu_job_release(ddjvu_page_job(page))

/* ddjvu_page_set_user_data ---

   ddjvu_page_get_user_data ---

   Each <ddjvu_paqge_t> object can store an arbitray pointer

   that callers can use for any purpose. These two functions

   provide for accessing or setting this pointer. */

#define ddjvu_page_set_user_data(page,userdata) \

   ddjvu_job_set_user_data(ddjvu_page_job(page),userdata)

#define ddjvu_page_get_user_data(page) \

   ddjvu_job_get_user_data(ddjvu_page_job(page))

/* ddjvu_page_decoding_status ---