DjVuFile plays the central role in decoding DjVuImages.
Notifications.
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:
- 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 DjVuFiles, which do no include anything else. In this case the ByteStream is enough for the DjVuFile to initialize.
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().
- 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.
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.
GP<GPixmap> bgpm
GP<JB2Image> fgjb
GP<JB2Dict> fgjd
GP<GPixmap> fgpm
GP<DjVuPalette> fgbc
GP<ByteStream> anno
GP<ByteStream> text
GP<DjVuNavDir> dir
GString description
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.
Note. If the file includes (by means of INCL chunks) other
files then you should be ready to
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.
Depending on the value of only_blocked flag this works as follows:
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.
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.
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.
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.
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.
Summary: This function will return complete hidden text layers
only when the is_all_data_present() returns TRUE.
Note: The file stream will not have the magic
0x41,0x54,0x26,0x54
at the beginning.
void init(const GURL & url, GP<DjVuPort> port=0)
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. void disable_standard_port(void)
GP<DjVuNavDir> find_ndir(void)
DjVuFile flags query functions
long get_flags(void) const
bool is_decoding(void) const
bool is_decode_ok(void) const
bool is_decode_failed(void) const
bool is_decode_stopped(void) const
bool is_data_present(void) const
bool is_all_data_present(void) const
bool are_incl_files_created(void) const
GURL get_url(void) const
Decode control routines
void start_decode(void)
void stop_decode(bool sync)
void stop(bool only_blocked)
void wait_for_finish(void)
GP<DjVuNavDir> decode_ndir(void)
void reset(void)
void process_incl_chunks(void)
GPList<DjVuFile> get_included_files(bool only_created=true)
void insert_file(const char * id, int chunk_num=1)
void unlink_file(const char * id)
static GP<DataPool> unlink_file(const GP<DataPool> & data, const char * name)
int get_chunks_number(void)
GString get_chunk_name(int chunk_num)
bool contains_chunk(const char * chunk_name)
GP<ByteStream> get_merged_anno(int * max_level_ptr=0)
GP<ByteStream> get_text(void)
void remove_anno(void)
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. void remove_text(void)
bool contains_anno(void)
bool contains_text(void)
void change_text(GP<DjVuTXT> txt, const bool do_reset)
Encoding routines
GP<ByteStream> get_djvu_bytestream(bool included_too, bool no_ndir)
no_ndir - Get rid of NDIR chunks. GP<DataPool> get_djvu_data(bool included_too, bool no_ndir)
no_ndir - Get rid of NDIR chunks. void set_name(const char * name)
Alphabetic index HTML hierarchy of classes or Java