Logo Search packages:      
Sourcecode: djvulibre version File versions

DjVuDocument Class Reference

#include <DjVuDocument.h>

Inheritance diagram for DjVuDocument:

DjVuPort GPEnabled DjVuDocEditor

List of all members.

Detailed Description

DjVuDocument# provides convenient interface for opening, decoding and saving back DjVu documents in single page and multi page formats.

{ Input formats} It can read multi page DjVu documents in either of the 4 formats: 2 obsolete ({old bundled} and {old indexed}) and two new ({new bundled} and {new indirect}).

{ Output formats} To encourage users to switch to the new formats, the DjVuDocument# can save documents back only in the new formats: {bundled} and {indirect}.

{ Conversion.} Since DjVuDocument# can open DjVu documents in an obsolete format and save it in any of the two new formats ({new bundled} and {new indirect}), this class can be used for conversion from obsolete formats to the new ones. Although it can also do conversion between the new two formats, it's not the best way to do it. Please refer to {DjVmDoc} for details.

{ Decoding.} DjVuDocument# provides convenient interface for obtaining {DjVuImage} corresponding to any page of the document. It uses {DjVuFileCache} to do caching thus avoiding unnecessary multiple decoding of the same page. The real decoding though is accomplished by {DjVuFile}.

{ Messenging.} Being derived from {DjVuPort}, DjVuDocument# takes an active part in exchanging messages (requests and notifications) between different parties involved in decoding. It reports (relays) errors, progress information and even handles some requests for data (when these requests deal with local files).

Typical usage of DjVuDocument# class in a threadless command line program would be the following: {verbatim} static const char file_name[]="/tmp/document.djvu"; GP<DjVuDocument> doc=DjVuDocumentcreate_wait(file_name); const int pages=doc->get_pages_num(); for(int page=0;page<pages;page++) { GP<DjVuImage> dimg=doc->get_page(page); Do something }; {verbatim}

{ Comments for the code above} {enumerate} Since the document is assumed to be stored on the hard drive, we don't have to cope with {DjVuPort}s and can pass ZERO# pointer to the {init}() function. DjVuDocument# can access local data itself. In the case of a plugin though, one would have to implement his own {DjVuPort}, which would handle requests for data arising when the document is being decoded. In a threaded program instead of calling the {init}() function one can call {start_init}() and {stop_init}() to initiate and interrupt initialization carried out in another thread. This possibility of initializing the document in another thread has been added specially for the plugin because the initialization itself requires data, which is not immediately available in the plugin. Thus, to prevent the main thread from blocking, we perform initialization in a separate thread. To check if the class is completely and successfully initialized, use {is_init_ok}(). To see if there was an error, use {is_init_failed}(). To know when initialization is over (whether successfully or not), use {is_init_complete}(). To wait for this to happen use {wait_for_complete_init}(). Once again, all these things are not required for single-threaded program.

Another difference between single-threaded and multi-threaded environments is that in a single-threaded program, the image is fully decoded before it's returned. In a multi-threaded application decoding starts in a separate thread, and the pointer to the {DjVuImage} being decoded is returned immediately. This has been done to enable progressive redisplay in the DjVu plugin. Use communication mechanism provided by {DjVuPort} and {DjVuPortcaster} to learn about progress of decoding. Or try dimg->wait_for_complete_decode()# to wait until the decoding ends. See Also: {DjVuFile}, {DjVuImage}, {GOS}. {enumerate}

{ Initialization} As mentioned above, the DjVuDocument# can go through several stages of initialization. The functionality is gradually added while it passes one stage after another: {enumerate} First of all, immediately after the object is created {init}() or {start_init}() functions must be called. { Nothing} will work until this is done. {init}() function will not return until the initialization is complete. You need to make sure, that enough data is available. { Do not call {init}() in the plugin}. {start_init}() will start initialization in another thread. Use {stop_init}() to interrupt it. Use {is_init_complete}() to check the initialization progress. Use {wait_for_complete_init}() to wait for init to finish. The first thing the initializing code learns about the document is its type (BUNDLED#, INDIRECT#, OLD_BUNDLED# or OLD_INDEXED#). As soon as it happens, document flags are changed and notify_doc_flags_changed()# request is sent through the communication mechanism provided by {DjVuPortcaster}. After the document type becomes known, the initializing code proceeds with learning the document structure. Gradually the flags are updated with values: {itemize} DOC_DIR_KNOWN#: Contents of the document became known. This is meaningful for BUNDLED#, OLD_BUNDLED# and INDIRECT# documents only. DOC_NDIR_KNOWN#: Contents of the document navigation directory became known. This is meaningful for old-style documents (OLD_BUNDLED# and OLD_INDEXED#) only DOC_INIT_OK# or DOC_INIT_FAILED#: The initializating code finished. {itemize} {enumerate}

Definition at line 213 of file DjVuDocument.h.


These virtual functions may be overridden by the subclasses of DjVuPort#. They are called by the {DjVuPortcaster} when the port is alive and when there is a route between the source of the notification and this port.

enum  ErrorRecoveryAction { ABORT = 0, SKIP_PAGES = 1, SKIP_CHUNKS = 2, KEEP_ALL = 3 }
virtual void notify_chunk_done (const DjVuPort *source, const GUTF8String &name)
virtual void notify_decode_progress (const DjVuPort *source, float done)
virtual void notify_doc_flags_changed (const class DjVuDocument *source, long set_mask, long clr_mask)
virtual bool notify_error (const DjVuPort *source, const GUTF8String &msg)
virtual void notify_file_flags_changed (const class DjVuFile *source, long set_mask, long clr_mask)
virtual void notify_redisplay (const class DjVuImage *source)
virtual void notify_relayout (const class DjVuImage *source)
virtual bool notify_status (const DjVuPort *source, const GUTF8String &msg)


Files #"DjVuDocument.h"# and #"DjVuDocument.cpp"# contain implementation of the {DjVuDocument} class - the ideal tool for opening, decoding and saving DjVu single page and multi page documents.

DjVu document class.

Andrei Erofeev <eaf@geocities.com>
DjVuDocument.h,v 1.9 2003/11/07 22:08:20 leonb Exp

bool can_compress (void) const
DjVuFileCacheget_cache (void) const
 Returns cache being used.
GP< DjVmDirget_djvm_dir (void) const
GP< DjVmDir0get_djvm_dir0 (void) const
long get_doc_flags (void) const
int get_doc_type (void) const
GP< DataPoolget_init_data_pool (void) const
GURL get_init_url (void) const
 Returns the URL passed to the {init}() function.
GP< DjVuNavDirget_nav_dir (void) const
virtual bool inherits (const GUTF8String &class_name) const
 Returns TRUE if class_name# is #"DjVuDocument"# or #"DjVuPort"#.
void init (const GURL &url, GP< DjVuPort > port=0, DjVuFileCache *cache=0)
bool is_bundled (void) const
bool is_init_complete (void) const
bool is_init_failed (void) const
bool is_init_ok (void) const
bool needs_compression (void) const
bool needs_rename (void) const
void set_needs_compression (void)
virtual void set_recover_errors (ErrorRecoveryAction=ABORT)
virtual void set_verbose_eof (bool=true)
static GP< DjVuDocumentcreate (const GURL &url, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)

Public Types

enum  DOC_FLAGS {
enum  DOC_TYPE {

Public Member Functions

int get_count (void) const
GList< GUTF8Stringget_id_list (void)
 Returns a listing of id's used by this document.
virtual GList< GURLget_url_names (void)
virtual GP< DjVuFileid_to_file (const DjVuPort *source, const GUTF8String &id)
virtual GURL id_to_url (const DjVuPort *source, const GUTF8String &id)
 Converts the specified id to a URL.
void map_ids (GMap< GUTF8String, void * > &map)
 Fill the id's into a GMap.
virtual void notify_file_flags_changed (const DjVuFile *source, long set_mask, long clr_mask)
virtual GP< DataPoolrequest_data (const DjVuPort *source, const GURL &url)
void start_init (const GURL &url, GP< DjVuPort > port=0, DjVuFileCache *cache=0)
void stop_init (void)
bool wait_for_complete_init (void)
int wait_get_pages_num (void) const
void writeDjVuXML (const GP< ByteStream > &gstr_out, int flags) const
 Create a complete DjVuXML file.
virtual ~DjVuDocument (void)
 Virtual Destructor.
Saving document to disk

void expand (const GURL &codebase, const GUTF8String &idx_name)
GP< DjVmDocget_djvm_doc (void)
virtual void save_as (const GURL &where, const bool bundled=0)
virtual void write (const GP< ByteStream > &str, const GMap< GUTF8String, void * > &reserved)
virtual void write (const GP< ByteStream > &str, bool force_djvm=false)
Accessing pages

GP< DjVuFileget_djvu_file (const GURL &url, bool dont_create=false)
GP< DjVuFileget_djvu_file (const GUTF8String &id, bool dont_create=false)
GP< DjVuFileget_djvu_file (int page_num, bool dont_create=false)
GP< DjVuFileget_djvu_file (int page_num, bool dont_create=false) const
GP< DjVuImageget_page (const GUTF8String &id, bool sync=true, DjVuPort *port=0)
GP< DjVuImageget_page (int page_num, bool sync=true, DjVuPort *port=0)
GP< DjVuImageget_page (int page_num, bool sync=true, DjVuPort *port=0) const
int get_pages_num (void) const
virtual GP< DataPoolget_thumbnail (int page_num, bool dont_decode)
float get_thumbnails_gamma (void) const
int id_to_page (const GUTF8String &id) const
 Find out which page this id is...
GURL id_to_url (const GUTF8String &id) const
GUTF8String page_to_id (int page_num) const
 Tranlate the page number to id...
GURL page_to_url (int page_num) const
GUTF8String url_to_id (const GURL &url) const
 Map the specified url to it's id.
int url_to_page (const GURL &url) const

Static Public Member Functions

static GP< DjVuDocumentcreate (const GP< ByteStream > &bs, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)
static GP< DjVuDocumentcreate (GP< DataPool > pool, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)
static GP< DjVuDocumentcreate_noinit (void)
static GP< DjVuDocumentcreate_wait (const GURL &url, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)
static DjVuPortcasterget_portcaster (void)
static void operator delete (void *addr)
static void * operator new (size_t sz)
static void set_compress_codec (void(*codec)(GP< ByteStream > &, const GURL &where, bool bundled))
static void set_import_codec (void(*codec)(GP< DataPool > &, const GURL &url, bool &, bool &))

Protected Member Functions

GP< ThumbReq > add_thumb_req (const GP< ThumbReq > &thumb_req)
void add_to_cache (const GP< DjVuFile > &f)
void check () const
void check_unnamed_files (void)
 DjVuDocument (void)
GUTF8String get_int_prefix (void) const
void init_thread (void)
GURL invent_url (const GUTF8String &name) const
void process_threqs (void)
void set_file_aliases (const DjVuFile *file)
virtual GP< DjVuFileurl_to_file (const GURL &url, bool dont_create=false) const

Static Protected Member Functions

static void static_init_thread (void *)

Protected Attributes

bool can_compress_flag
volatile int count
 The reference counter.
GP< DjVmDirdjvm_dir
GP< DjVmDir0djvm_dir0
int doc_type
GUTF8String first_page_name
GSafeFlags flags
bool has_url_names
GP< DataPoolinit_data_pool
GP< DjVuDocumentinit_life_saver
bool init_started
GThread init_thr
GSafeFlags init_thread_flags
GURL init_url
GP< DjVuNavDirndir
GP< DjVuFilendir_file
bool needs_compression_flag
bool needs_rename_flag
ErrorRecoveryAction recover_errors
GP< DjVuSimplePortsimple_port
GPList< ThumbReq > threqs_list
GCriticalSection threqs_lock
GPList< UnnamedFile > ufiles_list
GCriticalSection ufiles_lock
GList< GURLurl_names
GCriticalSection url_names_lock
bool verbose_eof

Static Protected Attributes

static void(* djvu_compress_codec )(GP< ByteStream > &bs, const GURL &where, bool bundled)
static void(* djvu_import_codec )(GP< DataPool > &pool, const GURL &url, bool &needs_compression, bool &needs_rename)
static const float thumb_gamma = (float)2.20


class  ThumbReq
class  UnnamedFile

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index