DjVuDocument Class Reference

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

#include <DjVuDocument.h>

Inheritance diagram for DjVuDocument:

[legend]

List of all members.


Classes
class	ThumbReq
class	UnnamedFile
Public Types
enum	DOC_FLAGS { DOC_TYPE_KNOWN = 1, DOC_DIR_KNOWN = 2, DOC_NDIR_KNOWN = 4, DOC_INIT_OK = 8, DOC_INIT_FAILED = 16 }
enum	DOC_TYPE { OLD_BUNDLED = 1, OLD_INDEXED, BUNDLED, INDIRECT, SINGLE_PAGE, UNKNOWN_TYPE }
enum	THREAD_FLAGS { STARTED = 1, FINISHED = 2 }
Public Member Functions
GList< GUTF8String >	get_id_list (void)
virtual GList< GURL >	get_url_names (void)
virtual GP< DjVuFile >	id_to_file (const DjVuPort *source, const GUTF8String &id)
virtual GURL	id_to_url (const DjVuPort *source, const GUTF8String &id)
void	map_ids (GMap< GUTF8String, void * > &map)
virtual void	notify_file_flags_changed (const DjVuFile *source, long set_mask, long clr_mask)
virtual GP< DataPool >	request_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
virtual	~DjVuDocument (void)
Saving document to disk
void	expand (const GURL &codebase, const GUTF8String &idx_name)
GP< DjVmDoc >	get_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< DjVuFile >	get_djvu_file (const GURL &url, bool dont_create=false)
GP< DjVuFile >	get_djvu_file (const GUTF8String &id, bool dont_create=false)
GP< DjVuFile >	get_djvu_file (int page_num, bool dont_create=false)
GP< DjVuFile >	get_djvu_file (int page_num, bool dont_create=false) const
GP< DjVuImage >	get_page (const GUTF8String &id, bool sync=true, DjVuPort *port=0)
GP< DjVuImage >	get_page (int page_num, bool sync=true, DjVuPort *port=0)
GP< DjVuImage >	get_page (int page_num, bool sync=true, DjVuPort *port=0) const
int	get_pages_num (void) const
virtual GP< DataPool >	get_thumbnail (int page_num, bool dont_decode)
float	get_thumbnails_gamma (void) const
int	id_to_page (const GUTF8String &id) const
GURL	id_to_url (const GUTF8String &id) const
GUTF8String	page_to_id (int page_num) const
GURL	page_to_url (int page_num) const
GUTF8String	url_to_id (const GURL &url) const
int	url_to_page (const GURL &url) const
Static Public Member Functions
static GP< DjVuDocument >	create (const GP< ByteStream > &bs, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)
static GP< DjVuDocument >	create (GP< DataPool > pool, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)
static GP< DjVuDocument >	create_noinit (void)
static GP< DjVuDocument >	create_wait (const GURL &url, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)
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< DjVuFile >	url_to_file (const GURL &url, bool dont_create=false) const
Static Protected Member Functions
static void	static_init_thread (void *)
Protected Attributes
DjVuFileCache *	cache
bool	can_compress_flag
GP< DjVmDir >	djvm_dir
GP< DjVmDir0 >	djvm_dir0
GP< DjVmNav >	djvm_nav
int	doc_type
GUTF8String	first_page_name
GSafeFlags	flags
bool	has_url_names
GP< DataPool >	init_data_pool
GP< DjVuDocument >	init_life_saver
bool	init_started
GThread	init_thr
GSafeFlags	init_thread_flags
GURL	init_url
GP< DjVuNavDir >	ndir
GP< DjVuFile >	ndir_file
bool	needs_compression_flag
bool	needs_rename_flag
ErrorRecoveryAction	recover_errors
GP< DjVuSimplePort >	simple_port
GPList< ThumbReq >	threqs_list
GCriticalSection	threqs_lock
GPList< UnnamedFile >	ufiles_list
GCriticalSection	ufiles_lock
GList< GURL >	url_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
DjVuDocument.h
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. Author: Andrei Erofeev <eaf@geocities.com> Version: $Id: DjVuDocument.h,v 1.10 2005/05/25 20:24:52 leonb Exp $#
bool	can_compress (void) const
DjVuFileCache *	get_cache (void) const
GP< DjVmDir >	get_djvm_dir (void) const
GP< DjVmDir0 >	get_djvm_dir0 (void) const
GP< DjVmNav >	get_djvm_nav (void) const
long	get_doc_flags (void) const
int	get_doc_type (void) const
GP< DataPool >	get_init_data_pool (void) const
GURL	get_init_url (void) const
GP< DjVuNavDir >	get_nav_dir (void) const
virtual bool	inherits (const GUTF8String &class_name) const
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< DjVuDocument >	create (const GURL &url, GP< DjVuPort > xport=0, DjVuFileCache *const xcache=0)

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 214 of file DjVuDocument.h.

Member Enumeration Documentation

enum DjVuDocument::DOC_FLAGS

Flags describing the document initialization state.

{itemize} 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. {itemize}

Enumerator:

DOC_TYPE_KNOWN
DOC_DIR_KNOWN
DOC_NDIR_KNOWN
DOC_INIT_OK
DOC_INIT_FAILED

Definition at line 229 of file DjVuDocument.h.

enum DjVuDocument::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. {enumerate} OLD_BUNDLED# - Obsolete bundled format 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. 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. BUNDLED# - Currently supported bundled format 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. {enumerate}

Enumerator:

OLD_BUNDLED
OLD_INDEXED
BUNDLED
INDIRECT
SINGLE_PAGE
UNKNOWN_TYPE

Definition at line 250 of file DjVuDocument.h.

enum DjVuDocument::THREAD_FLAGS

Enumerator:

STARTED
FINISHED

Definition at line 252 of file DjVuDocument.h.

Constructor & Destructor Documentation

DjVuDocument::DjVuDocument ( void ) [protected]

Default creator.

Please call functions {init}() or {start_init}() before you start working with the DjVuDocument#.

Definition at line 114 of file DjVuDocument.cpp.

DjVuDocument::~DjVuDocument ( void ) [virtual]

Virtual Destructor.

Definition at line 211 of file DjVuDocument.cpp.

Member Function Documentation

GP< DjVuDocument::ThumbReq > DjVuDocument::add_thumb_req ( const GP< ThumbReq > & thumb_req ) [protected]

Definition at line 1226 of file DjVuDocument.cpp.

void DjVuDocument::add_to_cache ( const GP< DjVuFile > & f ) [protected]

Definition at line 1383 of file DjVuDocument.cpp.

bool DjVuDocument::can_compress ( void ) const [inline]

Returns TRUE# if this file must be renamed before saving.

Definition at line 967 of file DjVuDocument.h.

void DjVuDocument::check ( void ) const [protected]

Definition at line 271 of file DjVuDocument.cpp.

void DjVuDocument::check_unnamed_files ( void ) [protected]

Definition at line 539 of file DjVuDocument.cpp.

GP< DjVuDocument > DjVuDocument::create	(	const GP< ByteStream > &	bs,
		GP< DjVuPort >	xport = `0`,
		DjVuFileCache *const	xcache = `0`
	)			`[static]`

Create a version of DjVuDocument which has begun initializing.

Definition at line 139 of file DjVuDocument.cpp.

GP< DjVuDocument > DjVuDocument::create	(	GP< DataPool >	pool,
		GP< DjVuPort >	xport = `0`,
		DjVuFileCache *const	xcache = `0`
	)			`[static]`

Create a version of DjVuDocument which has begun initializing.

Definition at line 128 of file DjVuDocument.cpp.

GP< DjVuDocument > DjVuDocument::create	(	const GURL &	url,
		GP< DjVuPort >	xport = `0`,
		DjVuFileCache *const	xcache = `0`
	)			`[inline, static]`

Create a version of DjVuDocument which has begun initializing.

Definition at line 927 of file DjVuDocument.h.

static GP<DjVuDocument> DjVuDocument::create_noinit ( void ) [inline, static]

This creates a DjVuDocument without initializing it.

Definition at line 343 of file DjVuDocument.h.

GP< DjVuDocument > DjVuDocument::create_wait	(	const GURL &	url,
		GP< DjVuPort >	xport = `0`,
		DjVuFileCache *const	xcache = `0`
	)			`[static]`

Create a version of DjVuDocument which has finished initializing.

Definition at line 146 of file DjVuDocument.cpp.

void DjVuDocument::expand	(	const GURL &	codebase,
		const GUTF8String &	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:

	codebase	- 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).

Definition at line 1778 of file DjVuDocument.cpp.

DjVuFileCache * DjVuDocument::get_cache ( void ) const [inline]

Returns cache being used.

Definition at line 1013 of file DjVuDocument.h.

GP< DjVmDir > DjVuDocument::get_djvm_dir ( void ) const [inline]

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.

Definition at line 1019 of file DjVuDocument.h.

GP< DjVmDir0 > DjVuDocument::get_djvm_dir0 ( void ) const [inline]

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.

Definition at line 1037 of file DjVuDocument.h.

GP< DjVmDoc > DjVuDocument::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.

Definition at line 1665 of file DjVuDocument.cpp.

GP< DjVmNav > DjVuDocument::get_djvm_nav ( void ) const [inline]

Returns pointer to the document bookmarks.

This applies to BUNDLED# and INDIRECT# documents.

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.

Definition at line 1029 of file DjVuDocument.h.

GP< DjVuFile > DjVuDocument::get_djvu_file	(	const GURL &	url,
		bool	dont_create = `false`
	)

Definition at line 1018 of file DjVuDocument.cpp.

GP< DjVuFile > DjVuDocument::get_djvu_file	(	const GUTF8String &	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 off, {id_to_url}() is called. If not successfull, 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.

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

Definition at line 958 of file DjVuDocument.cpp.

GP<DjVuFile> DjVuDocument::get_djvu_file	(	int	page_num,
		bool	dont_create = `false`
	)			`[inline]`

Definition at line 647 of file DjVuDocument.h.

GP< DjVuFile > DjVuDocument::get_djvu_file	(	int	page_num,
		bool	dont_create = `false`
	)			const

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.

Definition at line 879 of file DjVuDocument.cpp.

long DjVuDocument::get_doc_flags ( void ) const [inline]

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.

Definition at line 982 of file DjVuDocument.h.

int DjVuDocument::get_doc_type ( void ) const [inline]

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.

Definition at line 979 of file DjVuDocument.h.

GList< GUTF8String > DjVuDocument::get_id_list ( void )

Returns a listing of id's used by this document.

Definition at line 1243 of file DjVuDocument.cpp.

GP< DataPool > DjVuDocument::get_init_data_pool ( void ) const [inline]

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.

Definition at line 994 of file DjVuDocument.h.

GURL DjVuDocument::get_init_url ( void ) const [inline]

Returns the URL passed to the {init}() function.

Definition at line 991 of file DjVuDocument.h.

GUTF8String DjVuDocument::get_int_prefix ( void ) const [protected]

Definition at line 492 of file DjVuDocument.cpp.

GP< DjVuNavDir > DjVuDocument::get_nav_dir ( void ) const [inline]

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.

Definition at line 1045 of file DjVuDocument.h.

GP< DjVuImage > DjVuDocument::get_page	(	const GUTF8String &	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}().

Definition at line 1058 of file DjVuDocument.cpp.

GP<DjVuImage> DjVuDocument::get_page	(	int	page_num,
		bool	sync = `true`,
		DjVuPort *	port = `0`
	)			`[inline]`

Definition at line 606 of file DjVuDocument.h.

GP< DjVuImage > DjVuDocument::get_page	(	int	page_num,
		bool	sync = `true`,
		DjVuPort *	port = `0`
	)			const

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 {DjVuImage::wait_for_complete_decode}() and {DjVuFile::is_decode_ok}().
	port	A pointer to {DjVuPort}, that the created image will be connected to.

Definition at line 1036 of file DjVuDocument.cpp.

int DjVuDocument::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.

Definition at line 658 of file DjVuDocument.cpp.

GP< DataPool > DjVuDocument::get_thumbnail	(	int	page_num,
		bool	dont_decode
	)			`[virtual]`

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.

Reimplemented in DjVuDocEditor.

Definition at line 1278 of file DjVuDocument.cpp.

float DjVuDocument::get_thumbnails_gamma ( void ) const [inline]

Definition at line 1007 of file DjVuDocument.h.

GList< GURL > DjVuDocument::get_url_names ( void ) [virtual]

Definition at line 1609 of file DjVuDocument.cpp.

GP< DjVuFile > DjVuDocument::id_to_file	(	const DjVuPort *	source,
		const GUTF8String &	id
	)			`[virtual]`

This request is used to get a file corresponding to the given ID.

{DjVuDocument} is supposed to intercept it and either create a new instance of {DjVuFile} or reuse an existing one from the cache.

Reimplemented from DjVuPort.

Definition at line 1422 of file DjVuDocument.cpp.

int DjVuDocument::id_to_page ( const GUTF8String & id ) const [inline]

Find out which page this id is...

Definition at line 557 of file DjVuDocument.h.

GURL DjVuDocument::id_to_url	(	const DjVuPort *	source,
		const GUTF8String &	id
	)			`[virtual]`

Converts the specified id to a URL.

Reimplemented from DjVuPort.

Definition at line 829 of file DjVuDocument.cpp.

GURL DjVuDocument::id_to_url ( const GUTF8String & 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: {itemize} For BUNDLED# and INDIRECT# documents the function scans the {DjVmDir} (the document directory) and matches the ID against: {enumerate} File ID from the {DjVmDir} File name from the {DjVmDir} File title from the {DjVmDir} {enumerate} 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. {itemize}

If information obtained by the initialization thread is not sufficient yet, the id_to_url()# may return an empty URL. Depending on the document type, the information is sufficient when {itemize} BUNDLED# and INDIRECT#: DOC_DIR_KNOWN# flag is set. OLD_BUNDLED# and OLD_INDEXED# and SINGLE_PAGE#: DOC_TYPE_KNOWN# flag is set. {itemize}

Definition at line 775 of file DjVuDocument.cpp.

bool DjVuDocument::inherits ( const GUTF8String & class_name ) const [inline, virtual]

Returns TRUE if class_name# is #"DjVuDocument"# or #"DjVuPort"#.

Reimplemented from DjVuPort.

Reimplemented in DjVuDocEditor.

Definition at line 997 of file DjVuDocument.h.

void DjVuDocument::init	(	const GURL &	url,
		GP< DjVuPort >	port = `0`,
		DjVuFileCache *	cache = `0`
	)			`[inline]`

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}().

Definition at line 920 of file DjVuDocument.h.

void DjVuDocument::init_thread ( void ) [protected]

Definition at line 301 of file DjVuDocument.cpp.

GURL DjVuDocument::invent_url ( const GUTF8String & name ) const [protected]

Definition at line 950 of file DjVuDocument.cpp.

bool DjVuDocument::is_bundled ( void ) const [inline]

Returns TRUE# if the document is in bundled format (either in DjVuDocument::OLD_BUNDLED# or DjVuDocument::BUNDLED# formats).

Definition at line 985 of file DjVuDocument.h.

bool DjVuDocument::is_init_complete ( void ) const [inline]

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.

Definition at line 937 of file DjVuDocument.h.

bool DjVuDocument::is_init_failed ( void ) const [inline]

Returns TRUE# is the initialization thread failed.

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

Definition at line 973 of file DjVuDocument.h.

bool DjVuDocument::is_init_ok ( void ) const [inline]

Returns TRUE# is the initialization thread finished successfully.

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

Definition at line 943 of file DjVuDocument.h.

void DjVuDocument::map_ids ( GMap< GUTF8String, void * > & map )

Fill the id's into a GMap.

Definition at line 1268 of file DjVuDocument.cpp.

bool DjVuDocument::needs_compression ( void ) const [inline]

Returns TRUE# if there are uncompressed pages in this document.

Definition at line 955 of file DjVuDocument.h.

bool DjVuDocument::needs_rename ( void ) const [inline]

Returns TRUE# if this file must be renamed before saving.

Definition at line 961 of file DjVuDocument.h.

void DjVuDocument::notify_file_flags_changed	(	const DjVuFile *	source,
		long	set_mask,
		long	clr_mask
	)			`[virtual]`

Definition at line 1393 of file DjVuDocument.cpp.

GUTF8String DjVuDocument::page_to_id ( int page_num ) const [inline]

Tranlate the page number to id...

Reimplemented in DjVuDocEditor.

Definition at line 500 of file DjVuDocument.h.

GURL DjVuDocument::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: {itemize} 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. {itemize}

Definition at line 670 of file DjVuDocument.cpp.

void DjVuDocument::process_threqs ( void ) [protected]

Definition at line 1080 of file DjVuDocument.cpp.

GP< DataPool > DjVuDocument::request_data	(	const DjVuPort *	source,
		const GURL &	url
	)			`[virtual]`

This request is issued when decoder needs additional data for decoding.

Both {DjVuFile} and {DjVuDocument} are initialized with a URL, not the document data. As soon as they need the data, they call this function, whose responsibility is to locate the source of the data basing on the URL# passed and return it back in the form of the {DataPool}. If this particular receiver is unable to fullfil the request, it should return #0#.

Reimplemented from DjVuPort.

Reimplemented in DjVuDocEditor.

Definition at line 1428 of file DjVuDocument.cpp.

void DjVuDocument::save_as	(	const GURL &	where,
		const bool	bundled = `0`
	)			`[virtual]`

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: {itemize} 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.

Reimplemented in DjVuDocEditor.

Definition at line 1788 of file DjVuDocument.cpp.

static void DjVuDocument::set_compress_codec ( void(*)(GP< ByteStream > &, const GURL &where, bool bundled) codec ) [static]

void DjVuDocument::set_file_aliases ( const DjVuFile * file ) [protected]

Definition at line 505 of file DjVuDocument.cpp.

static void DjVuDocument::set_import_codec ( void(*)(GP< DataPool > &, const GURL &url, bool &, bool &) codec ) [static]

void DjVuDocument::set_needs_compression ( void ) [inline]

Forces compression with the next save_as function.

Definition at line 949 of file DjVuDocument.h.

void DjVuDocument::set_recover_errors ( ErrorRecoveryAction recover = ABORT ) [inline, virtual]

Definition at line 1051 of file DjVuDocument.h.

void DjVuDocument::set_verbose_eof ( bool verbose = true ) [inline, virtual]

Definition at line 1057 of file DjVuDocument.h.

void DjVuDocument::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: {itemize} { Old bundled} and { New bundled} formats: to the document itself. { Old indexed} format: to any page of the document. { New indirect} format: to the top-level file of the document. If (like in the {old indexed} format) you point the url# to a page, the page {will} be decoded, but it will {not} be recognized to be part of the document. {itemize}

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 {DjVuFile}s and is actually useful in the plugin only.

Definition at line 155 of file DjVuDocument.cpp.

void DjVuDocument::static_init_thread ( void * cl_data ) [static, protected]

Definition at line 278 of file DjVuDocument.cpp.

void DjVuDocument::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}.

Definition at line 246 of file DjVuDocument.cpp.

GP< DjVuFile > DjVuDocument::url_to_file	(	const GURL &	url,
		bool	dont_create = `false`
	)			const `[protected, virtual]`

Reimplemented in DjVuDocEditor.

Definition at line 835 of file DjVuDocument.cpp.

GUTF8String DjVuDocument::url_to_id ( const GURL & url ) const [inline]

Map the specified url to it's id.

Definition at line 515 of file DjVuDocument.h.

int DjVuDocument::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: {itemize} OLD_INDEXED# and OLD_BUNDLED# and SINGLE_PAGE#: DOC_NDIR_KNOWN# is set INDIRECT# and BUNDLED#: DOC_DIR_KNOWN# is set. {itemize}

Definition at line 727 of file DjVuDocument.cpp.

bool DjVuDocument::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.

Definition at line 466 of file DjVuDocument.cpp.

int DjVuDocument::wait_get_pages_num ( void ) const

Wait until we known the number of pages and return.

Definition at line 480 of file DjVuDocument.cpp.

void DjVuDocument::write	(	const GP< ByteStream > &	str,
		const GMap< GUTF8String, void * > &	reserved
	)			`[virtual]`

Always save as bundled, renaming any files conflicting with the the names in the supplied GMap.

Reimplemented in DjVuDocEditor.

Definition at line 1747 of file DjVuDocument.cpp.

void DjVuDocument::write	(	const GP< ByteStream > &	str,
		bool	force_djvm = `false`
	)			`[virtual]`

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.

Reimplemented in DjVuDocEditor.

Definition at line 1756 of file DjVuDocument.cpp.

void DjVuDocument::writeDjVuXML	(	const GP< ByteStream > &	gstr_out,
		int	flags
	)			const

Create a complete DjVuXML file.

Definition at line 1821 of file DjVuDocument.cpp.

Member Data Documentation

DjVuFileCache* DjVuDocument::cache [protected]

Definition at line 844 of file DjVuDocument.h.

bool DjVuDocument::can_compress_flag [protected]

Definition at line 827 of file DjVuDocument.h.

GP<DjVmDir> DjVuDocument::djvm_dir [protected]

Definition at line 823 of file DjVuDocument.h.

GP<DjVmDir0> DjVuDocument::djvm_dir0 [protected]

Definition at line 847 of file DjVuDocument.h.

GP<DjVmNav> DjVuDocument::djvm_nav [protected]

Definition at line 824 of file DjVuDocument.h.

void(* DjVuDocument::djvu_compress_codec)(GP< ByteStream > &doc, const GURL &where, bool bundled)=0	(	GP< ByteStream > &	bs,
		const GURL &	where,
		bool	bundled
	)			`[static, protected]`

void(* DjVuDocument::djvu_import_codec)(GP< DataPool > &pool, const GURL &url, bool &needs_compression, bool &needs_rename)=0	(	GP< DataPool > &	pool,
		const GURL &	url,
		bool &	needs_compression,
		bool &	needs_rename
	)			`[static, protected]`