class DjVuFile: public DjVuPort

DjVuFile plays the central role in decoding DjVuImages.

Inheritance:


Public Methods

[more]void init(ByteStream & str)
Initializes a DjVuFile object.
[more]void init(const GURL & url, GP<DjVuPort> port=0)
Initializes a DjVuFile object.
[more]void disable_standard_port(void)
Disables the built-in port for accessing local files, which may have been created in the case when the port argument to the DjVuFile() constructor is ZERO
[more]GP<DjVuNavDir> find_ndir(void)
Looks for decoded navigation directory (DjVuNavDir) in this or included files.
[more]GURL get_url(void) const
Returns the URL assigned to this file
[more]GPList<DjVuFile> get_included_files(bool only_created=true)
Returns the list of included DjVuFiles.
[more]void insert_file(const char * id, int chunk_num=1)
Includes a DjVuFile with the specified This function will also insert an INCL chunk at position chunk_num.
[more]void unlink_file(const char * id)
Will get rid of included file with the given
[more]static GP<DataPool> unlink_file(const GP<DataPool> & data, const char * name)
Will find an INCL chunk containing name in input data and will remove it
[more]int get_chunks_number(void)
Returns the number of chunks in the IFF file data
[more]GString get_chunk_name(int chunk_num)
Returns the name of chunk number chunk_num
[more]bool contains_chunk(const char * chunk_name)
Returns 1 if this file contains chunk with name chunk_name
[more]GP<ByteStream> get_merged_anno(int * max_level_ptr=0)
Processes the included files hierarchy and returns merged annotations.
[more]GP<ByteStream> get_text(void)
Processes the text chunks.
[more]void remove_anno(void)
Goes down the hierarchy of DjVuFiles and merges their annotations.
[more]void remove_text(void)
Clears the hidden text.
[more]bool contains_anno(void)
Returns TRUE if the file contains annotation chunks.
[more]bool contains_text(void)
Returns TRUE if the file contains annotation chunks.
[more]void change_text(GP<DjVuTXT> txt, const bool do_reset)
Changes the value of the text annotation.
[more]void set_name(const char * name)
Internal.

Public

[more] Decoded file contents

[more]GP<IW44Image> bg44
Pointer to the background component of DjVu image (IW44 encoded).
[more]GP<GPixmap> bgpm
Pointer to the background component of DjVu image (Raw).
[more]GP<JB2Image> fgjb
Pointer to the mask of foreground component of DjVu image (JB2 encoded).
[more]GP<JB2Dict> fgjd
Pointer to the optional shape dictionary for the mask (JB2 encoded).
[more]GP<GPixmap> fgpm
Pointer to a colors layer for the foreground component of DjVu image.
[more]GP<DjVuPalette> fgbc
Pointer to a colors vector for the foreground component of DjVu image.
[more]GP<ByteStream> anno
Pointer to collected annotation chunks.
[more]GP<ByteStream> text
Pointer to collected hidden text chunks.
[more]GP<DjVuNavDir> dir
Pointer to the *old* navigation directory contained in this file
[more]GString description
Description of the file formed during decoding
[more]GString mimetype
MIME type string describing the DjVu data.
[more]int file_size
Size of the file.

[more] DjVuFile flags query functions

[more]long get_flags(void) const
Returns the DjVuFile flags.
[more]bool is_decoding(void) const
Returns TRUE if the file is being decoded.
[more]bool is_decode_ok(void) const
Returns TRUE if decoding of the file has finished successfully.
[more]bool is_decode_failed(void) const
Returns TRUE if decoding of the file has failed.
[more]bool is_decode_stopped(void) const
Returns TRUE if decoding of the file has been stopped by stop_decode() function.
[more]bool is_data_present(void) const
Returns TRUE if this file has received all data.
[more]bool is_all_data_present(void) const
Returns TRUE if this file and all included files have received all data.
[more]bool are_incl_files_created(void) const
Returns TRUE if all included files have been created.

[more] Decode control routines

[more]void start_decode(void)
Starts decode.
[more]void stop_decode(bool sync)
Stops decode.
[more]void stop(bool only_blocked)
Recursively stops all data-related operations.
[more]void wait_for_finish(void)
Wait for the decoding to finish.
[more]GP<DjVuNavDir> decode_ndir(void)
Looks for NDIR chunk (navigation directory), and decodes its contents.
[more]void reset(void)
Clears all decoded components.
[more]void process_incl_chunks(void)
Processes INCL chunks and creates included files.

[more] Encoding routines

[more]GP<ByteStream> get_djvu_bytestream(bool included_too, bool no_ndir)
The main function that encodes data back into binary stream.
[more]GP<DataPool> get_djvu_data(bool included_too, bool no_ndir)
Same as get_djvu_bytestream(), returning a DataPool.


Inherited from DjVuPort:

Public Methods

ostatic DjVuPortcaster* get_portcaster(void)
oDjVuPort& operator=(const DjVuPort & port)
ovirtual bool inherits(const char * class_name) const

Public

Notifications.

[more]virtual GURL id_to_url(const DjVuPort * source, const char * id)
This request is issued to request translation of the ID, used in an DjVu INCL chunk to a URL, which may be used to request data associated with included file.
[more]virtual GPBase id_to_file(const DjVuPort * source, const char * id)
This request is used to get a file corresponding to the given ID.
[more]virtual GP<DataPool> request_data(const DjVuPort * source, const GURL & url)
This request is issued when decoder needs additional data for decoding.
[more]virtual bool notify_error(const DjVuPort * source, const char * msg)
This notification is sent when an error occurs and the error message should be shown to the user.
[more]virtual bool notify_status(const DjVuPort * source, const char * msg)
This notification is sent to update the decoding status.
[more]virtual void notify_redisplay(const class DjVuImage * source)
This notification is sent by DjVuImage when it should be redrawn.
[more]virtual void notify_relayout(const class DjVuImage * source)
This notification is sent by \ref{DjVuImage} when its geometry has been changed as a result of decoding.
[more]virtual void notify_chunk_done(const DjVuPort * source, const char * name)
This notification is sent when a new chunk has been decoded.
[more]virtual void notify_file_flags_changed(const class DjVuFile * source, long set_mask, long clr_mask)
This notification is sent after the DjVuFile flags have been changed.
[more]virtual void notify_doc_flags_changed(const class DjVuDocument * source, long set_mask, long clr_mask)
This notification is sent after the DjVuDocument flags have been changed.
[more]virtual void notify_decode_progress(const DjVuPort * source, float done)
This notification is sent from time to time while decoding is in progress.
[more]enum ErrorRecoveryAction
This is the standard types for defining what to do in case of errors.


Inherited from GPEnabled:

Public Methods

oint get_count(void) const

Protected Fields

ovolatile int count


Documentation

DjVuFile plays the central role in decoding DjVuImages. 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 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:

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:

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.

o Decoded file contents

oGP<IW44Image> bg44
Pointer to the background component of DjVu image (IW44 encoded).

oGP<GPixmap> bgpm
Pointer to the background component of DjVu image (Raw).

oGP<JB2Image> fgjb
Pointer to the mask of foreground component of DjVu image (JB2 encoded).

oGP<JB2Dict> fgjd
Pointer to the optional shape dictionary for the mask (JB2 encoded).

oGP<GPixmap> fgpm
Pointer to a colors layer for the foreground component of DjVu image.

oGP<DjVuPalette> fgbc
Pointer to a colors vector for the foreground component of DjVu image.

oGP<ByteStream> anno
Pointer to collected annotation chunks.

oGP<ByteStream> text
Pointer to collected hidden text chunks.

oGP<DjVuNavDir> dir
Pointer to the *old* navigation directory contained in this file

oGString description
Description of the file formed during decoding

oGString mimetype
MIME type string describing the DjVu data.

oint file_size
Size of the file.

ovoid init(ByteStream & str)
Initializes a DjVuFile object. This is a simplified initializer, which is not supposed to be used for decoding or creating DjVuFiles, which include other files.

If the file is stored on the hard drive, you may also use the other constructor and pass it the file's URL and ZERO port. The DjVuFile will read the data itself.

If you want to receive error messages and notifications, you may connect the DjVuFile to your own DjVuPort after it has been constructed.

Parameters:
str - The stream containing data for the file.

ovoid init(const GURL & url, GP<DjVuPort> port=0)
Initializes a DjVuFile object. As you can notice, the data is not directly passed to this function. The DjVuFile will ask for it through the DjVuPort mechanism before the constructor finishes. If the data is stored locally on the hard disk then the pointer to DjVuPort may be set to ZERO, which will make DjVuFile read all data from the hard disk and report all errors to stderr.

Note. If the file includes (by means of INCL chunks) other files then you should be ready to

  1. Reply to requests id_to_url() issued to translate IDs (used in INCL chunks) to absolute URLs. Usually, when the file is created by DjVuDocument this job is done by it. If you construct such a file manually, be prepared to do the ID to URL translation
  2. Provide data for all included files.

Parameters:
url - The URL assigned to this file. It will be used when the DjVuFile asks for data.
port - All communication between DjVuFiles and DjVuDocuments is done through the DjVuPort mechanism. If the url is not local or the data does not reside on the hard disk, the port parameter must not be ZERO. If the port is ZERO then DjVuFile will create an internal instance of DjVuSimplePort for accessing local files and reporting errors. It can later be disabled by means of disable_standard_port() function.

ovoid disable_standard_port(void)
Disables the built-in port for accessing local files, which may have been created in the case when the port argument to the DjVuFile() constructor is ZERO

oGP<DjVuNavDir> find_ndir(void)
Looks for decoded navigation directory (DjVuNavDir) in this or included files. Returns ZERO if nothing could be found.

Note. This function does not attempt to decode NDIR chunks. It is looking for predecoded components. NDIR can be decoded either during regular decoding (initiated by start_decode() function) or by decode_ndir() function, which processes this and included files recursively in search of NDIR chunks and decodes them.

o DjVuFile flags query functions

olong get_flags(void) const
Returns the DjVuFile flags. The value returned is the result of ORing one or more of the following constants:

obool is_decoding(void) const
Returns TRUE if the file is being decoded.

obool is_decode_ok(void) const
Returns TRUE if decoding of the file has finished successfully.

obool is_decode_failed(void) const
Returns TRUE if decoding of the file has failed.

obool is_decode_stopped(void) const
Returns TRUE if decoding of the file has been stopped by stop_decode() function.

obool is_data_present(void) const
Returns TRUE if this file has received all data.

obool is_all_data_present(void) const
Returns TRUE if this file and all included files have received all data.

obool are_incl_files_created(void) const
Returns TRUE if all included files have been created. Only when this function returns 1, the get_included_files() returns the correct information.

oGURL get_url(void) const
Returns the URL assigned to this file

o Decode control routines

ovoid start_decode(void)
Starts decode. If threads are enabled, the decoding will be done in another thread. Be sure to use wait_for_finish() or listen for notifications sent through the DjVuPortcaster to remain in sync.

ovoid stop_decode(bool sync)
Stops decode. If sync is 1 then the function will not return until the decoding thread actually dies. Otherwise it will just signal the thread to stop and will return immediately. Decoding of all included files will be stopped too.

ovoid stop(bool only_blocked)
Recursively stops all data-related operations.

Depending on the value of only_blocked flag this works as follows:

  • If only_blocked is TRUE, the function will make sure, that any further access to the file's data will result in a STOP exception if the desired data is not available (and the thread would normally block).
  • If only_blocked is FALSE, then any further access to the file's data will result in immediate STOP exception.

The action of this function is recursive, meaning that any DjVuFile included into this one will also be stopped.

Use this function when you don't need the DjVuFile anymore. The results cannot be undone, and the whole idea is to make all threads working with this file exit with the STOP exception.

ovoid wait_for_finish(void)
Wait for the decoding to finish. This will wait for the termination of included files too.

oGP<DjVuNavDir> decode_ndir(void)
Looks for NDIR chunk (navigation directory), and decodes its contents. If the NDIR chunk has not been found in this file, but this file includes others, the procedure will continue recursively. This function is useful to obtain the document navigation directory before any page has been decoded. After it returns the directory can be obtained by calling find_ndir() function.

Warning. Contrary to start_decode(), this function does not return before it completely decodes the directory. Make sure, that this file and all included files have enough data.

ovoid reset(void)
Clears all decoded components.

ovoid process_incl_chunks(void)
Processes INCL chunks and creates included files. Normally you won't need to call this function because included files are created automatically when the file is being decoded. But if due to some reason you'd like to obtain the list of included files without decoding this file, this is an ideal function to call.

Warning. This function does not return before it reads the whole file, which may block your application under some circumstances if not all data is available.

oGPList<DjVuFile> get_included_files(bool only_created=true)
Returns the list of included DjVuFiles.

Warning. Included files are normally created during decoding. Before that they do not exist. If you call this function at that time and set only_created to FALSE then it will have to read all the data from this file in order to find INCL chunks, which may block your application, if not all data is available.

Parameters:
only_created - If TRUE, the file will not try to process INCL chunks and load referenced files. It will return just those files, which have already been created during the decoding procedure.

ovoid insert_file(const char * id, int chunk_num=1)
Includes a DjVuFile with the specified This function will also insert an INCL chunk at position chunk_num. The function will request data for the included file and will create it before returning.

ovoid unlink_file(const char * id)
Will get rid of included file with the given

ostatic GP<DataPool> unlink_file(const GP<DataPool> & data, const char * name)
Will find an INCL chunk containing name in input data and will remove it

oint get_chunks_number(void)
Returns the number of chunks in the IFF file data

oGString get_chunk_name(int chunk_num)
Returns the name of chunk number chunk_num

obool contains_chunk(const char * chunk_name)
Returns 1 if this file contains chunk with name chunk_name

oGP<ByteStream> get_merged_anno(int * max_level_ptr=0)
Processes the included files hierarchy and returns merged annotations. This function may be used even when the DjVuFile has not been decoded yet. If all data has been received for this DjVuFile and all included DjVuFiles, it will will gather annotations from them and will return the result. If no annotations have been found, ZERO will be returned. If either this DjVuFile or any of the included files do not have all the data, the function will use the results of decoding, which may have been started with the start_decode() function. Otherwise ZERO will be returned as well.

If max_level_ptr pointer is not zero, the function will use it to store the maximum level number from which annotations have been obtained. ZERO level corresponds to the top-level page file.

Summary: This function will return complete annotations only when the is_all_data_present() returns TRUE.

oGP<ByteStream> get_text(void)
Processes the text chunks. This function may be used even when the DjVuFile has not been decoded yet. If all data has been received for this DjVuFile, it will gather hidden text and return the result. If no hidden text has been found, ZERO will be returned.

Summary: This function will return complete hidden text layers only when the is_all_data_present() returns TRUE.

ovoid remove_anno(void)
Goes down the hierarchy of DjVuFiles and merges their annotations.

Parameters:
max_level_ptr - If this pointer is not ZERO, the function will use it to store the maximum level at which annotations were found. Top-level page files have ZERO level.
ignore_list - The function will not process included DjVuFiles with URLs matching those mentioned in this GP<ByteStream> get_merged_anno(const GList<GURL> & ignore_list, int * max_level_ptr); /** Clears this file of all annotations.

ovoid remove_text(void)
Clears the hidden text.

obool contains_anno(void)
Returns TRUE if the file contains annotation chunks. Known annotation chunks at the time of writing this help are: ANTa, ANTz, FORM:ANNO.

obool contains_text(void)
Returns TRUE if the file contains annotation chunks. Known annotation chunks at the time of writing this help are: TXTa, and TXTz.

ovoid change_text(GP<DjVuTXT> txt, const bool do_reset)
Changes the value of the text annotation.

o Encoding routines

oGP<ByteStream> get_djvu_bytestream(bool included_too, bool no_ndir)
The main function that encodes data back into binary stream. The data returned will reflect possible changes made into the chunk structure, annotation chunks and navigation directory chunk NDIR.

Note: The file stream will not have the magic 0x41,0x54,0x26,0x54 at the beginning.

Parameters:
included_too - Process included files too
no_ndir - Get rid of NDIR chunks.

oGP<DataPool> get_djvu_data(bool included_too, bool no_ndir)
Same as get_djvu_bytestream(), returning a DataPool.
Parameters:
included_too - Process included files too
no_ndir - Get rid of NDIR chunks.

ovoid set_name(const char * name)
Internal. Used by DjVuDocument. The name should not be encoded with encode_reserved().


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java


DjVu is a trademark of LizardTech, Inc.
All other products mentioned are registered trademarks or trademarks of their respective companies.