## File: DjVmDir.h

package info (click to toggle)
djvulibre 3.5.27.1-14
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460 //C- -*- C++ -*- //C- ------------------------------------------------------------------- //C- DjVuLibre-3.5 //C- Copyright (c) 2002 Leon Bottou and Yann Le Cun. //C- Copyright (c) 2001 AT&T //C- //C- This software is subject to, and may be distributed under, the //C- GNU General Public License, either Version 2 of the license, //C- or (at your option) any later version. The license should have //C- accompanied the software or you may obtain a copy of the license //C- from the Free Software Foundation at http://www.fsf.org . //C- //C- This program is distributed in the hope that it will be useful, //C- but WITHOUT ANY WARRANTY; without even the implied warranty of //C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //C- GNU General Public License for more details. //C- //C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from //C- Lizardtech Software. Lizardtech Software has authorized us to //C- replace the original DjVu(r) Reference Library notice by the following //C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu): //C- //C- ------------------------------------------------------------------ //C- | DjVu (r) Reference Library (v. 3.5) //C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved. //C- | The DjVu Reference Library is protected by U.S. Pat. No. //C- | 6,058,214 and patents pending. //C- | //C- | This software is subject to, and may be distributed under, the //C- | GNU General Public License, either Version 2 of the license, //C- | or (at your option) any later version. The license should have //C- | accompanied the software or you may obtain a copy of the license //C- | from the Free Software Foundation at http://www.fsf.org . //C- | //C- | The computer code originally released by LizardTech under this //C- | license and unmodified by other parties is deemed "the LIZARDTECH //C- | ORIGINAL CODE." Subject to any third party intellectual property //C- | claims, LizardTech grants recipient a worldwide, royalty-free, //C- | non-exclusive license to make, use, sell, or otherwise dispose of //C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the //C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU //C- | General Public License. This grant only confers the right to //C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to //C- | the extent such infringement is reasonably necessary to enable //C- | recipient to make, have made, practice, sell, or otherwise dispose //C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to //C- | any greater extent that may be necessary to utilize further //C- | modifications or combinations. //C- | //C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY //C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED //C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF //C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. //C- +------------------------------------------------------------------ #ifndef _DJVMDIR_H #define _DJVMDIR_H #ifdef HAVE_CONFIG_H #include "config.h" #endif #if NEED_GNUG_PRAGMAS # pragma interface #endif /** @name DjVmDir.h Files #"DjVmDir.h"# and #"DjVmDir.cpp"# implement class \Ref{DjVmDir} for representing the directory of a DjVu multipage document. {\bf Bundled vs. Indirect format} --- There are currently two multipage DjVu formats supported: {\em bundled} and {\em indirect}. In the first format all component files composing a given document are packaged (or bundled) into one file, in the second one every page and component is stored in a separate file and there is one more file, which contains the list of all others. {\bf Multipage DjVu format} --- Multipage DjVu documents follow the EA IFF85 format (cf. \Ref{IFFByteStream.h}.) A document is composed of a #"FORM:DJVM"# whose first chunk is a #"DIRM"# chunk containing the {\em document directory}. This directory lists all component files composing the given document, helps to access every component file and identify the pages of the document. \begin{itemize} \item In a {\em bundled} multipage file, the component files are stored immediately after the #"DIRM"# chunk, within the #"FORM:DJVU"# composite chunk. \item In an {\em indirect} multipage file, the component files are stored in different files whose URLs are composed using information stored in the #"DIRM"# chunk. \end{itemize} Most of the component files represent pages of a document. Some files however represent data shared by several pages. The pages refer to these supporting files by means of an inclusion chunk (#"INCL"# chunks) identifying the supporting file. {\bf Document Directory} --- Every directory record describes a component file. Each component file is identified by a small string named the identifier (ID). Each component file also contains a file name and a title. The format of the #"DIRM"# chunk is described in section \Ref{Format of the DIRM chunk.}. Theoretically, IDs are used to uniquely identify each component file in #"INCL"# chunks, names are used to compose the the URLs of the component files in an indirect multipage DjVu file, and titles are cosmetic names possibly displayed when viewing a page of a document. There are however many problems with this scheme, and we {\em strongly suggest}, with the current implementation to always make the file ID, the file name and the file title identical. @memo Implements DjVu multipage document directory @author Andrei Erofeev */ //@{ #include "GString.h" #include "GThreads.h" #ifdef HAVE_NAMESPACES namespace DJVU { # ifdef NOT_DEFINED // Just to fool emacs c++ mode } #endif #endif class ByteStream; /** Implements DjVu multipage document directory. There are currently two multipage DjVu formats supported: {\em bundled} and {\em indirect}. In the first format all component files composing a given document are packaged (or bundled) into one file, in the second one every page and component is stored in a separate file and there is one more file, which contains the list of all others. The multipage document directory lists all component files composing the given document, helps to access every file, identify pages and maintain user-specified shortcuts. Every directory record describes a file composing the document. Each file is identified by a small string named the identifier (ID). Each file may also contain a file name and a title. The #DjVmDir# class represents a multipage document directory. Its main purpose is to encode and decode the document directory when writing or reading the #DIRM# chunk. Normally you don't have to create this class yourself. It's done automatically when \Ref{DjVmDoc} class initializes itself. It may be useful though to be able to access records in the directory because some classes (like \Ref{DjVuDocument} and \Ref{DjVmDoc}) return a pointer to #DjVmDir# in some cases. */ class DJVUAPI DjVmDir : public GPEnabled { protected: /** Class \Ref{DjVmDir::File} represents the directory records managed by class \Ref{DjVmDir}. */ DjVmDir(void) { } ; public: class File; static const int version; /** Class \Ref{DjVmDir::File} represents the directory records managed by class \Ref{DjVmDir}. */ static GP create(void) {return new DjVmDir; } ; /** Decodes the directory from the specified stream. */ void decode(const GP &stream); /** Encodes the directory into the specified stream. */ void encode(const GP &stream, const bool do_rename=false) const; /** Encodes the directory into the specified stream, explicitely as bundled or indirect. */ void encode(const GP &stream, const bool bundled, const bool do_rename) const; /** Tests if directory defines an {\em indirect} document. */ inline bool is_indirect(void) const; /** Tests if the directory defines a {\em bundled} document. */ inline bool is_bundled(void) const; /** Translates page numbers to file records. */ GP page_to_file(int page_num) const; /** Translates file names to file records. */ GP name_to_file(const GUTF8String & name) const; /** Translates file IDs to file records. */ GP id_to_file(const GUTF8String &id) const; /** Translates file shortcuts to file records. */ GP title_to_file(const GUTF8String &title, GPosition spos) const; GP title_to_file(const GUTF8String &title) const; /** Access file record by position. */ GP pos_to_file(int fileno, int *ppageno=0) const; /** Returns position of the file in the directory. */ int get_file_pos(const File * f) const; /** Returns position of the given page in the directory. */ int get_page_pos(int page_num) const; /** Check for duplicate names, and resolve them. */ GPList resolve_duplicates(const bool save_as_bundled); /** Returns a copy of the list of file records. */ GPList get_files_list(void) const; /** Returns the number of file records. */ int get_files_num(void) const; /** Returns the number of file records representing pages. */ int get_pages_num(void) const; /** Returns back pointer to the file with #SHARED_ANNO# flag. Note that there may be only one file with shared annotations in any multipage DjVu document. */ GP get_shared_anno_file(void) const; /** Changes the title of the file with ID #id#. */ void set_file_title(const GUTF8String &id, const GUTF8String &title); /** Changes the name of the file with ID #id#. */ void set_file_name(const GUTF8String &id, const GUTF8String &name); /** Inserts the specified file record at the specified position. Specifying #pos# equal to #-1# means to append. The actual position inserted is returned. */ int insert_file(const GP & file, int pos=-1); /** Removes a file record with ID #id#. */ void delete_file(const GUTF8String &id); private: GCriticalSection class_lock; GPList files_list; GPArray page2file; GPMap name2file; GPMap id2file; private: //dummy stuff static void decode(ByteStream *); static void encode(ByteStream *); }; class DJVUAPI DjVmDir::File : public GPEnabled { public: // Out of the record: INCLUDE below must be zero and PAGE must be one. // This is to avoid problems with the File constructor, which now takes // 'int file_type' as the last argument instead of 'bool is_page' /** File type. Possible file types are: \begin{description} \item[PAGE] This is a top level page file. It may include other #INCLUDE#d files, which may in turn be shared between different pages. \item[INCLUDE] This file is included into some other file inside this document. \item[THUMBNAILS] This file contains thumbnails for the document pages. \item[SHARED_ANNO] This file contains annotations shared by all the pages. It's supposed to be included into every page for the annotations to take effect. There may be only one file with shared annotations in a document. \end{description} */ enum FILE_TYPE { INCLUDE=0, PAGE=1, THUMBNAILS=2, SHARED_ANNO=3 }; protected: /** Default constructor. */ File(void); public: static GP create(void) { return new File(); } static GP create(const GUTF8String &load_name, const GUTF8String &save_name, const GUTF8String &title, const FILE_TYPE file_type); /** Check for filenames that are not valid for the native encoding, and change them. */ const GUTF8String &check_save_name(const bool as_bundled); /** File name. The optional file name must be unique and is the name that will be used when the document is saved to an indirect file. If not assigned, the value of #id# will be used for this purpose. By keeping the name in {\em bundled} document we guarantee, that it can be expanded later into {\em indirect} document and files will still have the same names, if the name is legal on a given filesystem. */ const GUTF8String &get_save_name(void) const; /** File identifier. The encoder assigns a unique identifier to each file in a multipage document. This is the name used when loading files. Indirection chunks in other files (#"INCL"# chunks) may refer to another file using its identifier. */ const GUTF8String &get_load_name(void) const; void set_load_name(const GUTF8String &id); /** File title. The file title is assigned by the user and may be used as a shortcut for viewing a particular page. Names like #"chapter1"# or #"appendix"# are appropriate. */ const GUTF8String &get_title() const; void set_title(const GUTF8String &id); /** Reports an ascii string indicating file type. */ GUTF8String get_str_type(void) const; /** Offset of the file data in a bundled DJVM file. This number is relevant in the {\em bundled} case only when everything is packed into one single file. */ int offset; /** Size of the file data in a bundled DJVM file. This number is relevant in the {\em bundled} case only when everything is packed into one single file. */ int size; /** Have we checked the saved file name, to see if it is valid on the local disk? */ bool valid_name; /** Tests if this file represents a page of the document. */ bool is_page(void) const { return (flags & TYPE_MASK)==PAGE; } /** Returns #TRUE# if this file is included into some other files of this document. */ bool is_include(void) const { return (flags & TYPE_MASK)==INCLUDE; } /** Returns #TRUE# if this file contains thumbnails for the document pages. */ bool is_thumbnails(void) const { return (flags & TYPE_MASK)==THUMBNAILS; } /** Returns the page number of this file. This function returns #-1# if this file does not represent a page of the document. */ bool is_shared_anno(void) const { return (flags & TYPE_MASK)==SHARED_ANNO; } int get_page_num(void) const { return page_num; } protected: GUTF8String name; GUTF8String oldname; GUTF8String id; GUTF8String title; void set_save_name(const GUTF8String &name); private: friend class DjVmDir; enum FLAGS_0 { IS_PAGE_0=1, HAS_NAME_0=2, HAS_TITLE_0=4 }; enum FLAGS_1 { HAS_NAME=0x80, HAS_TITLE=0x40, TYPE_MASK=0x3f }; unsigned char flags; int page_num; }; inline const GUTF8String & DjVmDir::File::get_load_name(void) const { return id; } inline const GUTF8String & DjVmDir::File::get_title() const { return *(title.length()?&title:&id); } inline void DjVmDir::File::set_title(const GUTF8String &xtitle) { title=xtitle; } /** @name Format of the DIRM chunk. {\bf Variants} --- There are two versions of the #"DIRM"# chunk format. The version number is identified by the seven low bits of the first byte of the chunk. Version {\bf 0} is obsolete and should never be used. This section describes version {\bf 1}. There are two major multipage DjVu formats supported: {\em bundled} and {\em indirect}. The #"DIRM"# chunk indicates which format is used in the most significant bit of the first byte of the chunk. The document is bundled when this bit is set. Otherwise the document is indirect. {\bf Unencoded data} --- The #"DIRM"# chunk is composed some unencoded data followed by \Ref{bzz} encoded data. The unencoded data starts with the version byte and a 16 bit integer representing the number of component files. All integers are encoded with the most significant byte first. \begin{verbatim} BYTE: Flags/Version: 0x0000011 INT16: Number of component files. \end{verbatim} When the document is a bundled document (i.e. the flag #bundled# is set), this header is followed by the offsets of each of the component files within the #"FORM:DJVM"#. These offsets allow for random component file access. \begin{verbatim} INT32: Offset of first component file. INT32: Offset of second component file. ... INT32: Offset of last component file. \end{verbatim} {\bf BZZ encoded data} --- The rest of the chunk is entirely compressed with the BZZ general purpose compressor. We describe now the data fed into (or retrieved from) the BZZ codec (cf. \Ref{BSByteStream}.) First come the sizes and the flags associated with each component file. \begin{verbatim} INT24: Size of the first component file. INT24: Size of the second component file. ... INT24: Size of the last component file. BYTE: Flag byte for the first component file. BYTE: Flag byte for the second component file. ... BYTE: Flag byte for the last component file. \end{verbatim} The flag bytes have the following format: \begin{verbatim} 0b000000 for a file included by other files. 0b000001 for a file representing a page. 0b000010 for a file containing thumbnails. \end{verbatim} Flag #hasname# is set when the name of the file is different from the file ID. Flag #hastitle# is set when the title of the file is different from the file ID. These flags are used to avoid encoding the same string three times. Then come a sequence of zero terminated strings. There are one to three such strings per component file. The first string contains the ID of the component file. The second string contains the name of the component file. It is only present when the flag #hasname# is set. The third one contains the title of the component file. It is only present when the flag #hastitle# is set. The \Ref{bzz} encoding system makes sure that all these strings will be encoded efficiently despite their possible redundancies. \begin{verbatim} ZSTR: ID of the first component file. ZSTR: Name of the first component file (only if #hasname# is set.) ZSTR: Title of the first component file (only if #hastitle# is set.) ... ZSTR: ID of the last component file. ZSTR: Name of the last component file (only if #hasname# is set.) ZSTR: Title of the last component file (only if #hastitle# is set.) \end{verbatim} @memo Description of the format of the DIRM chunk. */ //@} // -------------- IMPLEMENTATION inline bool DjVmDir::is_bundled(void) const { return ! is_indirect(); } inline bool DjVmDir::is_indirect(void) const { GCriticalSectionLock lock((GCriticalSection *) &class_lock); return ( files_list.size() && files_list[files_list] != 0 && files_list[files_list]->offset==0 ); } inline GP DjVmDir::title_to_file(const GUTF8String &title) const { GPosition pos; return title_to_file(title, pos); } // ----- THE END #ifdef HAVE_NAMESPACES } # ifndef NOT_USING_DJVU_NAMESPACE using namespace DJVU; # endif #endif #endif