class DjVuDocument: public DjVuPort

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

Inheritance:


Public Classes

[more]enum DOC_FLAGS
Flags describing the document initialization state.
[more]enum DOC_TYPE
Specifies the format of DjVuDocument.

Public Methods

[more] DjVuDocument(void)
Default constructor.
[more]void start_init(const GURL & url, GP<DjVuPort> port=0, DjVuFileCache * cache=0)
Initializes the DjVuDocument object using an existing document.
[more]static GP<DjVuDocument> create( const GURL &url, GP<DjVuPort> xport=0, DjVuFileCache * const xcache=0)
Create a version of DjVuDocument which has begun initializing.
[more]static GP<DjVuDocument> create( GP<DataPool> pool, GP<DjVuPort> xport=0, DjVuFileCache * const xcache=0)
Create a version of DjVuDocument which has begun initializing.
[more]static GP<DjVuDocument> create( ByteStream &bs, GP<DjVuPort> xport=0, DjVuFileCache * const xcache=0)
Create a version of DjVuDocument which has begun initializing.
[more]void stop_init(void)
Call this function when you don't need the DjVuDocument any more.
[more]void init(const GURL & url, GP<DjVuPort> port=0, DjVuFileCache * cache=0)
Initializes the document.
[more]bool is_init_complete(void) const
Returns TRUE if the initialization thread finished (does not matter successfully or not).
[more]bool is_init_ok(void) const
Returns TRUE is the initialization thread finished successfully.
[more]void set_needs_compression(void)
Forces compression with the next save_as function.
[more]bool needs_compression(void) const
Returns TRUE if there are uncompressed pages in this document.
[more]bool needs_rename(void) const
Returns TRUE if this file must be renamed before saving.
[more]bool can_compress(void) const
Returns TRUE if this file must be renamed before saving.
[more]bool is_init_failed(void) const
Returns TRUE is the initialization thread failed.
[more]int get_doc_type(void) const
If the document has already learnt its type, the function will returns it: DjVuDocument::OLD_BUNDLED or DjVuDocument::OLD_INDEXED or DjVuDocument::SINGLE_PAGE or DjVuDocument:BUNDLED or DjVuDocument::INDIRECT.
[more]long get_doc_flags(void) const
Returns the document flags.
[more]bool is_bundled(void) const
Returns TRUE if the document is in bundled format (either in DjVuDocument::OLD_BUNDLED or DjVuDocument::BUNDLED formats).
[more]GURL get_init_url(void) const
Returns the URL passed to the init() function
[more]GP<DataPool> get_init_data_pool(void) const
Returns data corresponding to the URL passed to the init() function.
[more]bool wait_for_complete_init(void)
Waits until the document initialization process finishes.
[more]int wait_get_pages_num(void)
Wait until we known the number of pages and return.
[more]DjVuFileCache* get_cache(void) const
Returns cache being used.
[more]GP<DjVmDir> get_djvm_dir(void) const
Returns pointer to the internal directory of the document, if it is in one of the new formats: BUNDLED or INDIRECT.
[more]GP<DjVmDir0> get_djvm_dir0(void) const
Returns pointer to the internal directory of the document, if it is in obsolete OLD_BUNDLED format.
[more]GP<DjVuNavDir> get_nav_dir(void) const
Returns pointer to navigation directory of the document.
[more]virtual bool inherits(const char * class_name) const
Returns TRUE if class_name is "DjVuDocument" or "DjVuPort"

Public

[more] Accessing pages

[more]int get_pages_num(void) const
Returns the number of pages in the document.
[more]GURL page_to_url(int page_num) const
Translates the page number to the full URL of the page.
[more]int url_to_page(const GURL & url) const
Translates the page URL back to page number.
[more]GURL id_to_url(const char * id) const
Translates the textual ID to the complete URL if possible.
[more]GP<DjVuImage> get_page(int page_num, bool sync=true, DjVuPort * port=0)
Returns GP pointer to DjVuImage corresponding to page page_num.
[more]GP<DjVuImage> get_page(const char * id, bool sync=true, DjVuPort * port=0)
Returns GP pointer to DjVuImage corresponding to the specified ID.
[more]GP<DjVuFile> get_djvu_file(int page_num, bool dont_create=false)
Returns DjVuFile corresponding to the specified page.
[more]GP<DjVuFile> get_djvu_file(const char * id, bool dont_create=false)
Returns DjVuFile corresponding to the specified ID.
[more]virtual GP<DataPool> get_thumbnail(int page_num, bool dont_decode)
Returns a DataPool containing one chunk TH44 with the encoded thumbnail for the specified page.

[more] Saving document to disk

[more]GP<DjVmDoc> get_djvm_doc(void)
Returns pointer to the DjVmDoc class, which can save the document contents on the hard disk in one of the two new formats: bundled and indirect.
[more]void write(ByteStream & str, bool force_djvm=false)
Saves the document in the new bundled format.
[more]void expand(const char * dir_name, const char * idx_name)
Saves the document in the new indirect format when every page and component are stored in separate files.
[more]virtual void save_as(const char where[], const bool bundled=0)
This function can be used instead of write() and expand().


Inherited from DjVuPort:

Public Methods

ostatic DjVuPortcaster* get_portcaster(void)
oDjVuPort& operator=(const DjVuPort & port)

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

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:

    GString file_name="/tmp/document.djvu";
    GP<DjVuDocument> doc=new DjVuDocument;
    doc->init(GOS::filename_to_url(file_name));
    int pages=doc->get_pages_num();
    for(int page=0;page<pages;page++)
    {
       GP<DjVuImage> dimg=doc->get_page(page);
       // Do something
    };
    

Comments for the code above

  1. Since the document is assumed to be stored on the hard drive, we don't have to cope with DjVuPorts 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.
  2. 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.

  3. See Also: DjVuFile, DjVuImage, GOS.

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:

  1. 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.
  2. 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.
  3. After the document type becomes known, the initializing code proceeds with learning the document structure. Gradually the flags are updated with values:
    • 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.
oenum DOC_FLAGS
Flags describing the document initialization state.
  • DOC_TYPE_KNOWN: The type of the document has been learnt.
  • 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: The initialization has completed successfully.
  • DOC_INIT_FAILED: The initialization failed.

oenum DOC_TYPE
Specifies the format of DjVuDocument. There are currently 4 DjVu multipage formats recognized by the library. Two of them are obsolete and should not be used.
  1. OLD_BUNDLED - Obsolete bundled format
  2. OLD_INDEXED - Obsolete multipage format where every page is stored in a separate file and "includes" (by means of an INCL chunk) the file with the document directory.
  3. SINGLE_PAGE - Single page document. Basically a file with either FORM:DJVU or FORM:IW44 and no multipage information. For example, OLD_INDEXED documents with document directory do not qualify even if they contain only one page.
  4. BUNDLED - Currently supported bundled format
  5. INDIRECT - Currently supported "expanded" format, where every page and component is stored in a separate file. There is also a top-level file with the document directory.

o DjVuDocument(void)
Default constructor. Please call functions init() or start_init() before you start working with the DjVuDocument.

ovoid start_init(const GURL & url, GP<DjVuPort> port=0, DjVuFileCache * cache=0)
Initializes the DjVuDocument object using an existing document. This function should be called once after creating the object. The url should point to the real data, and the creator of the document should be ready to return this data to the document if it's not stored locally (in which case DjVuDocument can access it itself).

Initializing thread In a single-threaded application, the start_init() function performs the complete initialization of the DjVuDocument before it returns. In a multi-threaded application, though, it initializes some internal variables, requests data for the document and starts a new initializing thread, which is responsible for determining the document type and structure and completing the initialization process. This additional complication is justified in the case of the DjVu plugin because performing initialization requires data and in the plugin the data can be supplied by the main thread only. Thus, if the initialization was completed by the main thread, the plugin would run out of data and block.

Stages of initialization Immediately after the start_init() function terminates, the DjVuDocument object is ready for use. Its functionality will not be complete (until the initializing thread finishes), but the object is still very useful. Such functions as get_page() or get_djvu_file() or id_to_url() may be called before the initializing thread completes. This allows the DjVu plugin start decoding as soon as possible without waiting for all data to arrive.

To query the current stage of initialization you can use get_doc_flags() function or listen to the notify_doc_flags_changed() notifications distributed with the help of DjVuPortcaster. To wait for the initialization to complete use wait_for_complete_init(). To stop initialization call stop_init().

Querying data The query for data is done using the communication mechanism provided by DjVuPort and DjVuPortcaster. If port is not ZERO, then the request for data will be forwarded to it. If it is ZERO then DjVuDocument will create an internal instance of DjVuSimplePort and will use it to access local files and report errors to stderr. In short, if the document file is stored on the local hard disk, and you're OK about reporting errors to stderr, you may pass ZERO pointer to DjVuPort as DjVuDocument can take care of this situation by itself.

The URL Depending on the document type the url should point to:

Parameters:
url - The URL pointing to the document. If the document is in a bundled format then the URL should point to it. If the document is in the old indexed format then URL may point to any page of this document. For new indirect format the URL should point to the top-level file of the document.
port - If not ZERO, all requests and notifications will be sent to it. Otherwise DjVuDocument will create an internal instance of DjVuSimplePort for these purposes. It's OK to make it ZERO if you're writing a command line tool, which should work with files on the hard disk only because DjVuDocument can access such files itself.
cache - It's used to cache decoded DjVuFiles and is actually useful in the plugin only.

ostatic GP<DjVuDocument> create( const GURL &url, GP<DjVuPort> xport=0, DjVuFileCache * const xcache=0)
Create a version of DjVuDocument which has begun initializing.

ostatic GP<DjVuDocument> create( GP<DataPool> pool, GP<DjVuPort> xport=0, DjVuFileCache * const xcache=0)
Create a version of DjVuDocument which has begun initializing.

ostatic GP<DjVuDocument> create( ByteStream &bs, GP<DjVuPort> xport=0, DjVuFileCache * const xcache=0)
Create a version of DjVuDocument which has begun initializing.

ovoid stop_init(void)
Call this function when you don't need the DjVuDocument any more. In a multi-threaded environment it will stop initialization thread, if it is currently running. You will not be able to start the initialization again. Thus, after calling this function the document should not be used any more.

ovoid init(const GURL & url, GP<DjVuPort> port=0, DjVuFileCache * cache=0)
Initializes the document.

Contrary to start_init(), which just starts the initialization thread in a multi-threaded environment, this function does not return until the initialization completes (either successfully or not). Basically, it calls start_init() and then wait_for_complete_init().

obool is_init_complete(void) const
Returns TRUE if the initialization thread finished (does not matter successfully or not). As soon as it happens, the document becomes completely initialized and its every function should work properly. Please refer to the description of init() function and of the DjVuDocument class to learn about the initializing stages.

To wait for the initialization to complete use wait_for_complete_init() function.

To query the initialization stage use get_flags() function.

To learn whether initialization was successful or not, use is_init_ok() and is_init_failed().

Note: In a single threaded application the initialization completes before the init() function returns.

obool is_init_ok(void) const
Returns TRUE is the initialization thread finished successfully.

See is_init_complete() and wait_for_complete_init() for more details.

ovoid set_needs_compression(void)
Forces compression with the next save_as function.

obool needs_compression(void) const
Returns TRUE if there are uncompressed pages in this document.

obool needs_rename(void) const
Returns TRUE if this file must be renamed before saving.

obool can_compress(void) const
Returns TRUE if this file must be renamed before saving.

obool is_init_failed(void) const
Returns TRUE is the initialization thread failed.

See is_init_complete() and wait_for_complete_init() for more details.

oint get_doc_type(void) const
If the document has already learnt its type, the function will returns it: DjVuDocument::OLD_BUNDLED or DjVuDocument::OLD_INDEXED or DjVuDocument::SINGLE_PAGE or DjVuDocument:BUNDLED or DjVuDocument::INDIRECT. The first two formats are obsolete. Otherwise (if the type is unknown yet), UNKNOWN_TYPE will be returned.

Note: To check the stage of the document initialization use get_flags() or is_init_complete() functions. To wait for the initialization to complete use wait_for_complete_init(). For single threaded applications the initialization completes before the init() function returns.

olong get_doc_flags(void) const
Returns the document flags. The flags describe the degree in which the DjVuDocument object is initialized. Every time the flags are changed, a notify_doc_flags_changed() notification is distributed using the DjVuPortcaster communication mechanism.

Note: To wait for the initialization to complete use wait_for_complete_init(). For single threaded applications the initialization completes before the init() function returns.

obool is_bundled(void) const
Returns TRUE if the document is in bundled format (either in DjVuDocument::OLD_BUNDLED or DjVuDocument::BUNDLED formats).

oGURL get_init_url(void) const
Returns the URL passed to the init() function

oGP<DataPool> get_init_data_pool(void) const
Returns data corresponding to the URL passed to the init() function.

Note: The pointer returned is guaranteed to be non-ZERO only after the DjVuDocument learns its type (passes through the first stage of initialization process). Please refer to init() for details.

o Accessing pages

oint get_pages_num(void) const
Returns the number of pages in the document. If there is still insufficient information about the document structure (initialization has not finished yet), 1 will be returned. Please refer to init() for details.

oGURL page_to_url(int page_num) const
Translates the page number to the full URL of the page. This URL is "artificial" for the bundled formats and is obtained by appending the page name to the document's URL honoring possible ; and ? in it. Negative page number has a special meaning for OLD_INDEXED documents: it points to the URL, which the DjVuDocument has been initialized with. For other formats this is the same as page 0.

The function tries it best to map the page number to the URL. Although, if the document structure has not been fully discovered yet, an empty URL will be returned. Use wait_for_complete_init() to wait until the document initialization completes. Refer to init() for details.

Depending on the document format, the function assumes, that there is enough information to complete the request when:

  • OLD_INDEXED: If page_num<0, DOC_TYPE_KNOWN flag must be set. Otherwise DOC_NDIR_KNOWN must be set.
  • OLD_BUNDLED: If page_num=0, DOC_DIR_KNOWN flag must be set. Otherwise DOC_NDIR_KNOWN flag must be set.
  • INDIRECT and BUNDLED: DOC_DIR_KNOWN flag must be set.

oint url_to_page(const GURL & url) const
Translates the page URL back to page number. Returns -1 if the page is not in the document or the document's structure has not been learnt yet.

Depending on the document format, the function starts working properly as soon as:

  • OLD_INDEXED and OLD_BUNDLED and SINGLE_PAGE: DOC_NDIR_KNOWN is set
  • INDIRECT and BUNDLED: DOC_DIR_KNOWN is set.

oGURL id_to_url(const char * id) const
Translates the textual ID to the complete URL if possible.

Depending on the document format the translation is done in the following way:

  • For BUNDLED and INDIRECT documents the function scans the DjVmDir (the document directory) and matches the ID against:
    1. File ID from the DjVmDir
    2. File name from the DjVmDir
    3. File title from the DjVmDir
    Then for BUNDLED document the URL is obtained by appending the name of the found file to the document's URL.

    For INDIRECT documents the URL is obtained by appending the name of the found file to the URL of the directory containing the document.

  • For OLD_BUNDLED documents the function compares the ID with internal name of every file inside the bundle and composes an artificial URL by appending the file name to the document's URL.
  • For OLD_INDEXED or SINGLE_PAGE documents the function composes the URL by appending the ID to the URL of the directory containing the document.

If information obtained by the initialization thread is not sufficient yet, the Depending on the document type, the information is sufficient when

  • BUNDLED and INDIRECT: DOC_DIR_KNOWN flag is set.
  • OLD_BUNDLED and OLD_INDEXED and SINGLE_PAGE: DOC_TYPE_KNOWN flag is set.

oGP<DjVuImage> get_page(int page_num, bool sync=true, DjVuPort * port=0)
Returns GP pointer to DjVuImage corresponding to page page_num. If caching is enabled, and there is a fully decoded DjVuFile in the cache, the image will be reused and will be returned fully decoded. Otherwise, if multi-threaded behavior is allowed, and sync is set to FALSE, the decoding will be started in a separate thread, which enables to do progressive redisplay. Thus, in this case the image returned may be partially decoded.

Negative page_num has a special meaning for the old indexed multipage documents: the DjVuDocument will start decoding of the URL with which it has been initialized. For other formats page -1 is the same as page 0.

DjVuDocument can also connect the created page to the specified port before starting decoding. This option will allow the future owner of DjVuImage to receive all messages and requests generated during its decoding.

If this function is called before the document's structure becomes known (the initialization process completes), the DjVuFile, which the returned image will be attached to, will be assigned a temporary artificial URL, which will be corrected as soon as enough information becomes available. The trick prevents the main thread from blocking and in some cases helps to start decoding earlier. The URL is corrected and decoding will start as soon as DjVuDocument passes some given stages of initialization and page_to_url(), id_to_url() functions start working properly. Please look through their description for details.

Note: To wait for the initialization to complete use wait_for_complete_init(). For single threaded applications the initialization completes before the init() function returns.

Parameters:
page_num - Number of the page to be decoded
sync - When set to TRUE the function will not return until the page is completely decoded. Otherwise, in a multi-threaded program, this function will start decoding in a new thread and will return a partially decoded image. Refer to wait_for_complete_decode() and is_decode_ok().
port - A pointer to DjVuPort, that the created image will be connected to.

oGP<DjVuImage> get_page(const char * id, bool sync=true, DjVuPort * port=0)
Returns GP pointer to DjVuImage corresponding to the specified ID. This function behaves exactly as the get_page() function above. The only thing worth mentioning here is how the ID parameter is treated.

First of all the function checks, if the ID contains a number. If so, it just calls the get_page() function above. If ID is ZERO or just empty, page number -1 is assumed. Otherwise the ID is translated to the URL using id_to_url().

oGP<DjVuFile> get_djvu_file(int page_num, bool dont_create=false)
Returns DjVuFile corresponding to the specified page. Normally it translates the page number to the URL using page_to_url() and then creates DjVuFile initializing it with data from the URL.

The behavior becomes different, though in the case when the document structure is unknown at the moment this function is called. In this situations it invents a temporary URL, creates a DjVuFile, initializes it with this URL and returns immediately. The caller may start decoding the file right away (if necessary). The decoding will block but will automatically continue as soon as enough information is collected about the document. This trick should be quite transparent to the user and helps to prevent the main thread from blocking. The decoding will unblock and this function will stop using this "trick" as soon as DjVuDocument passes some given stages of initialization and page_to_url(), id_to_url() functions start working properly.

If dont_create is FALSE the function will return the file only if it already exists.

Note: To wait for the initialization to complete use wait_for_complete_init(). For single threaded applications the initialization completes before the init() function returns.

oGP<DjVuFile> get_djvu_file(const char * id, bool dont_create=false)
Returns DjVuFile corresponding to the specified ID. This function behaves exactly as the get_djvu_file() function above. The only thing worth mentioning here is how the ID parameter is treated.

First of all the function checks, if the ID contains a number. If so, it just calls the get_djvu_file() function above. If ID is ZERO or just empty, page number -1 is assumed. Otherwise the ID is translated to the URL using id_to_url().

If dont_create is FALSE the function will return the file only if it already exists.

ovirtual GP<DataPool> get_thumbnail(int page_num, bool dont_decode)
Returns a DataPool containing one chunk TH44 with the encoded thumbnail for the specified page. The function first looks for thumbnails enclosed into the document and if it fails to find one, it decodes the required page and creates the thumbnail on the fly (unless dont_decode is true).

Note: It may happen that the returned DataPool will not contain all the data you need. In this case you will need to install a trigger into the DataPool to learn when the data actually arrives.

obool wait_for_complete_init(void)
Waits until the document initialization process finishes. It can finish either successfully or not. Use is_init_ok() and is_init_failed() to learn the result code.

As described in start_init(), for multi-threaded applications the initialization is carried out in parallel with the main thread. This function blocks the calling thread until the initializing thread reads enough data, receives information about the document format and exits. This function returns true if the initialization is successful. You can use get_flags() or is_init_complete() to check more precisely the degree of initialization. Use stop_init() to interrupt initialization.

oint wait_get_pages_num(void)
Wait until we known the number of pages and return.

oDjVuFileCache* get_cache(void) const
Returns cache being used.

o Saving document to disk

oGP<DjVmDoc> get_djvm_doc(void)
Returns pointer to the DjVmDoc class, which can save the document contents on the hard disk in one of the two new formats: bundled and indirect. You may also want to look at write() and expand() if you are interested in how to save the document.

Plugin Warning. This function will read contents of the whole document. Thus, if you call it from the main thread (the thread, which transfers data from Netscape), the plugin will block.

ovoid write(ByteStream & str, bool force_djvm=false)
Saves the document in the new bundled format. All the data is "bundled" into one file and this file is written into the passed stream.

If force_djvm is TRUE then even one page documents will be saved in the DJVM BUNDLED format (inside a FORM:DJVM);

Plugin Warning. This function will read contents of the whole document. Thus, if you call it from the main thread (the thread, which transfers data from Netscape), the plugin will block.

ovoid expand(const char * dir_name, const char * idx_name)
Saves the document in the new indirect format when every page and component are stored in separate files. This format is ideal for web publishing because it allows direct access to any page and component. In addition to it, a top-level file containing the list of all components will be created. To view the document later in the plugin or in the viewer one should load the top-level file.

Plugin Warning. This function will read contents of the whole document. Thus, if you call it from the main thread (the thread, which transfers data from Netscape), the plugin will block.

Parameters:
dir_name - - Name of the directory which the document should be expanded into.
idx_name - - Name of the top-level file containing the document directory (basically, list of all files composing the document).

ovirtual void save_as(const char where[], const bool bundled=0)
This function can be used instead of write() and expand(). It allows to save the document either in the new BUNDLED format or in the new INDIRECT format depending on the value of parameter bundled.

Depending on the document's type, the meaning of where is:

  • For BUNDLED documents this is the name of the file
  • For INDIRECT documents this is the name of top-level index file. All document files will be saved into the save directory where the index file will resize.

oGP<DjVmDir> get_djvm_dir(void) const
Returns pointer to the internal directory of the document, if it is in one of the new formats: BUNDLED or INDIRECT. Otherwise (if the format of the input document is obsolete), ZERO is returned.

ZERO will also be returned if the initializing thread has not learnt enough information about the document (DOC_DIR_KNOWN has not been set yet). Check is_init_complete() and init() for details.

oGP<DjVmDir0> get_djvm_dir0(void) const
Returns pointer to the internal directory of the document, if it is in obsolete OLD_BUNDLED format.

ZERO will also be returned if the initializing thread has not learnt enough information about the document (DOC_DIR_KNOWN has not been set yet). Check is_init_complete() and init() for details.

oGP<DjVuNavDir> get_nav_dir(void) const
Returns pointer to navigation directory of the document. The navigation directory is a DjVu file containing only one chunk NDIR inside a FORM:DJVI with the list of all document pages.

ovirtual bool inherits(const char * class_name) const
Returns TRUE if class_name is "DjVuDocument" or "DjVuPort"


Direct child classes:
DjVuDocEditor

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.