Logo Search packages:      
Sourcecode: djvulibre version File versions

DjVuFile Class Reference

#include <DjVuFile.h>

Inheritance diagram for DjVuFile:

DjVuPort GPEnabled

List of all members.

Detailed Description

DjVuFile# plays the central role in decoding {DjVuImage}s. First of all, it represents a DjVu file whether it's part of a multipage all-in-one-file DjVu document, or part of a multipage DjVu document where every page is in a separate file, or the whole single page document. DjVuFile# can read its contents from a file and store it back when necessary.

Second, DjVuFile# does the greatest part of decoding work. In the past this was the responsibility of {DjVuImage}. Now, with the introduction of the multipage DjVu formats, the decoding routines have been extracted from the {DjVuImage} and put into this separate class DjVuFile#.

As {DjVuImage} before, DjVuFile# now contains public class variables corresponding to every component, that can ever be decoded from a DjVu file (such as INFO# chunk, BG44# chunk, SJBZ# chunk, etc.).

As before, the decoding is initiated by a single function ({start_decode}() in this case, and {DjVuImage::decode}() before). The difference is that DjVuFile# now handles threads creation itself. When you call the {start_decode}() function, it creates the decoding thread, which starts decoding, and which can create additional threads: one per each file included into this one.

{ Inclusion} is also a new feature specifically designed for a multipage document. Indeed, inside a given document there can be a lot of things shared between its pages. Examples can be the document annotation ({DjVuAnno}) and other things like shared shapes and dictionary (to be implemented). To avoid putting these chunks into every page, we have invented new chunk called INCL# which purpose is to make the decoder open the specified file and decode it.

{ Source of data.} The DjVuFile# can be initialized in two ways: {itemize} With URL# and {DjVuPort}. In this case DjVuFile# will request its data thru the communication mechanism provided by {DjVuPort} in the constructor. If this file references (includes) any other file, data for them will also be requested in the same way. With {ByteStream}. In this case the DjVuFile# will read its data directly from the passed stream. This constructor has been added to simplify creation of DjVuFile::s, which do no include anything else. In this case the {ByteStream} is enough for the DjVuFile# to initialize. {itemize}

{ Progress information.} DjVuFile# does not do decoding silently. Instead, it sends a whole set of notifications through the mechanism provided by {DjVuPort} and {DjVuPortcaster}. It tells the user of the class about the progress of the decoding, about possible errors, chunk being decoded, etc. The data is requested using this mechanism too.

{ Creating.} Depending on where you have data of the DjVu file, the DjVuFile# can be initialized in two ways: {itemize} By providing URL# and pointer to {DjVuPort}. In this case DjVuFile# will request data using communication mechanism provided by {DjVuPort}. This is useful when the data is on the web or when this file includes other files. By providing a {ByteStream} with the data for the file. Use it only when the file doesn't include other files. {itemize} There is also a bunch of functions provided for composing the desired {DjVuDocument} and modifying DjVuFile# structure. The examples are {delete_chunks}(), {insert_chunk}(), {include_file}() and {unlink_file}().

{ Caching.} In the case of plugin it's important to do the caching of decoded images or files. DjVuFile# appears to be the best candidate for caching, and that's why it supports this procedure. Whenever a DjVuFile# is successfully decoded, it's added to the cache by {DjVuDocument}. Next time somebody needs it, it will be extracted from the cache directly by {DjVuDocument} and won't be decoded again.

{ URLs.} Historically the biggest strain is put on making the decoder available for Netscape and IE plugins where the original files reside somewhere in the net. That is why DjVuFile# uses { URLs} to identify itself and other files. If you're working with files on the hard disk, you have to use the local URLs instead of file names. A good way to do two way conversion is the {GOS} class. Sometimes it happens that a given file does not reside anywhere but the memory. No problem in this case either. There is a special port {DjVuMemoryPort}, which can associate any URL with the corresponding data in the memory. All you need to do is to invent your own URL prefix for this case. "#memory:#" will do. The usage of absolute URLs has many advantages among which is the capability to cache files with their URL being the cache key.

Please note, that the DjVuFile# class has been designed to work closely with {DjVuDocument}. So please review the documentation on this class too.

Definition at line 203 of file DjVuFile.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 GP< DjVuFileid_to_file (const DjVuPort *source, const GUTF8String &id)
virtual GURL id_to_url (const DjVuPort *source, const GUTF8String &id)
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)
virtual GP< DataPoolrequest_data (const DjVuPort *source, const GURL &url)

Public Types

enum  { STARTED = 1, FINISHED = 2 }
enum  {

Public Member Functions

void change_info (GP< DjVuInfo > info, const bool do_reset=false)
void change_meta (const GUTF8String &meta, const bool do_reset=false)
void change_text (GP< DjVuTXT > txt, const bool do_reset=false)
bool contains_anno (void)
bool contains_chunk (const GUTF8String &chunk_name)
 Returns 1 if this file contains chunk with name chunk_name#.
bool contains_meta (void)
bool contains_text (void)
GP< DjVuNavDirfind_ndir (void)
GP< ByteStreamget_anno (void)
GUTF8String get_chunk_name (int chunk_num)
 Returns the name of chunk number chunk_num#.
int get_chunks_number (void)
 Returns the number of chunks in the IFF file data.
int get_count (void) const
GPList< DjVuFileget_included_files (bool only_created=true)
GP< DataPoolget_init_data_pool (void) const
unsigned int get_memory_usage (void) const
GP< ByteStreamget_merged_anno (const GList< GURL > &ignore_list, int *max_level_ptr)
GP< ByteStreamget_merged_anno (int *max_level_ptr=0)
void get_meta (ByteStream &out)
GP< ByteStreamget_meta (void)
void get_text (ByteStream &out)
GP< ByteStreamget_text (void)
void init (const GURL &url, GP< DjVuPort > port=0)
void init (const GP< ByteStream > &str)
void insert_file (const GUTF8String &id, int chunk_num=1)
void merge_anno (ByteStream &out)
void move (const GURL &dir_url)
virtual void notify_chunk_done (const DjVuPort *source, const GUTF8String &name)
virtual void notify_file_flags_changed (const DjVuFile *source, long set_mask, long clr_mask)
void rebuild_data_pool (void)
void remove_anno (void)
void remove_meta (void)
 Clears the meta data.
void remove_text (void)
virtual void report_error (const GException &ex, const bool=true)
void set_name (const GUTF8String &name)
void unlink_file (const GUTF8String &id)
 Will get rid of included file with the given id#.
#DjVuFile# flags query functions

bool are_incl_files_created (void) const
bool can_compress (void) const
long get_flags (void) const
bool is_all_data_present (void) const
bool is_data_present (void) const
 Returns TRUE# if this file has received all data.
bool is_decode_failed (void) const
 Returns TRUE# if decoding of the file has failed.
bool is_decode_ok (void) const
 Returns TRUE# if decoding of the file has finished successfully.
bool is_decode_stopped (void) const
bool is_decoding (void) const
 Returns TRUE# if the file is being decoded.
bool is_modified (void) const
bool needs_compression (void) const
void set_can_compress (bool m)
void set_modified (bool m)
void set_needs_compression (bool m)
Decode control routines

GP< DjVuNavDirdecode_ndir (void)
void process_incl_chunks (void)
void reset (void)
 Clears all decoded components.
bool resume_decode (const bool sync=false)
void start_decode (void)
void stop (bool only_blocked)
void stop_decode (bool sync)
void wait_for_finish (void)
Files #"DjVuFile.h"# and #"DjVuFile.cpp"# contain implementation of the {DjVuFile} class, which takes the leading role in decoding of {DjVuImage}s.

In the previous releases of the library the work of decoding has been entirely done in {DjVuImage}. Now, due to the introduction of multipage documents, the decoding procedure became significantly more complex and has been moved out from {DjVuImage} into {DjVuFile}.

There is not much point though in creating just {DjVuFile} alone. The maximum power of the decoder is achieved when you create the {DjVuDocument} and work with { it} when decoding the image.

Classes representing DjVu files.

Andrei Erofeev <eaf@geocities.com>
DjVuFile.h,v 1.11 2007/03/25 20:48:30 leonb Exp

void disable_standard_port (void)
GSafeFlagsget_safe_flags (void)
GURL get_url (void) const
 Returns the URL assigned to this file.
virtual bool inherits (const GUTF8String &class_name) const
virtual void set_recover_errors (const ErrorRecoveryAction=ABORT)
virtual void set_verbose_eof (const bool verbose_eof=true)
Encoding routines

GP< ByteStreamget_djvu_bytestream (const bool included_too, const bool no_ndir=true)
GP< DataPoolget_djvu_data (const bool included_too, const bool no_ndir=true)

Static Public Member Functions

static GP< DjVuFilecreate (const GURL &url, GP< DjVuPort > port=0, const ErrorRecoveryAction recover_action=ABORT, const bool verbose_eof=true)
static GP< DjVuFilecreate (const GP< ByteStream > &str, const ErrorRecoveryAction recover_action=ABORT, const bool verbose_eof=true)
static DjVuPortcasterget_portcaster (void)
static void operator delete (void *addr)
static void * operator new (size_t sz)
static void set_decode_codec (GP< GPixmap >(*codec)(ByteStream &bs))
static GP< DataPoolunlink_file (const GP< DataPool > &data, const GUTF8String &name)

Public Attributes

Decoded file contents

GP< ByteStreamanno
 Pointer to collected annotation chunks.
GP< IW44Imagebg44
 Pointer to the background component of DjVu image (IW44 encoded).
GP< GPixmapbgpm
 Pointer to the background component of DjVu image (Raw).
GUTF8String description
 Description of the file formed during decoding.
GP< DjVuNavDirdir
 Pointer to the *old* navigation directory contained in this file.
GP< DjVuPalette > fgbc
 Pointer to a colors vector for the foreground component of DjVu image.
GP< JB2Imagefgjb
 Pointer to the mask of foreground component of DjVu image (JB2 encoded).
GP< JB2Dictfgjd
 Pointer to the optional shape dictionary for the mask (JB2 encoded).
GP< GPixmapfgpm
 Pointer to a colors layer for the foreground component of DjVu image.
int file_size
 Size of the file.
GP< DjVuInfoinfo
 Pointer to the DjVu file information component.
GP< ByteStreammeta
 Pointer to meta data chunks.
GUTF8String mimetype
 MIME type string describing the DjVu data.
GP< ByteStreamtext
 Pointer to collected hiddentext chunks.

Protected Member Functions

 DjVuFile (void)

Protected Attributes

GCriticalSection anno_lock
int chunks_number
volatile int count
 The reference counter.
GP< DataPooldata_pool
GPList< DjVuFileinc_files_list
GCriticalSection inc_files_lock
GCriticalSection meta_lock
ErrorRecoveryAction recover_errors
GCriticalSection text_lock
GURL url
bool verbose_eof

Private Member Functions

void add_djvu_data (IFFByteStream &str, GMap< GURL, void * > &map, const bool included_too, const bool no_ndir=true)
void check () const
void decode (const GP< ByteStream > &str)
GUTF8String decode_chunk (const GUTF8String &chkid, const GP< ByteStream > &str, bool djvi, bool djvu, bool iw44)
void decode_func (void)
GP< DjVuNavDirdecode_ndir (GMap< GURL, void * > &map)
GP< DjVuNavDirfind_ndir (GMap< GURL, void * > &map)
int get_dpi (int w, int h)
GP< JB2Dictget_fgjd (int block=0)
void move (GMap< GURL, void * > &map, const GURL &dir_url)
GP< DjVuFileprocess_incl_chunk (ByteStream &str, int file_num=-1)
void trigger_cb (void)
void wait_for_chunk (void)
bool wait_for_finish (bool self)

Static Private Member Functions

static void decode (ByteStream *)
static GUTF8String decode_chunk (const GUTF8String &, ByteStream *, bool, bool, bool)
static void get_anno (const GP< DjVuFile > &file, const GP< ByteStream > &str_out)
static void get_merged_anno (const GP< DjVuFile > &, ByteStream *, const GList< GURL > &, int, int &, GMap< GURL, void * > &)
static void get_merged_anno (const GP< DjVuFile > &file, const GP< ByteStream > &str_out, const GList< GURL > &ignore_list, int level, int &max_level, GMap< GURL, void * > &map)
static void get_meta (const GP< DjVuFile > &, ByteStream *)
static void get_meta (const GP< DjVuFile > &file, const GP< ByteStream > &str_out)
static void get_text (const GP< DjVuFile > &, ByteStream *)
static void get_text (const GP< DjVuFile > &file, const GP< ByteStream > &str_out)
static void progress_cb (int pos, void *)
static void static_decode_func (void *)
static GP< JB2Dictstatic_get_fgjd (void *)
static void static_trigger_cb (void *)

Private Attributes

GMonitor chunk_mon
GP< DataPooldecode_data_pool
GP< DjVuFiledecode_life_saver
GMonitor finish_mon
GSafeFlags flags
bool initialized
GP< DjVuPortsimple_port

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

Generated by  Doxygen 1.6.0   Back to index