//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 <eaf@geocities.com>
*/
//@{
#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<DjVmDir> create(void) {return new DjVmDir; } ;
/** Decodes the directory from the specified stream. */
void decode(const GP<ByteStream> &stream);
/** Encodes the directory into the specified stream. */
void encode(const GP<ByteStream> &stream, const bool do_rename=false) const;
/** Encodes the directory into the specified stream,
explicitely as bundled or indirect. */
void encode(const GP<ByteStream> &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<File> page_to_file(int page_num) const;
/** Translates file names to file records. */
GP<File> name_to_file(const GUTF8String & name) const;
/** Translates file IDs to file records. */
GP<File> id_to_file(const GUTF8String &id) const;
/** Translates file shortcuts to file records. */
GP<File> title_to_file(const GUTF8String &title) const;
/** Access file record by position. */
GP<File> 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<File> resolve_duplicates(const bool save_as_bundled);
/** Returns a copy of the list of file records. */
GPList<File> 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<File> 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> & file, int pos=-1);
/** Removes a file record with ID #id#. */
void delete_file(const GUTF8String &id);
private:
GCriticalSection class_lock;
GPList<File> files_list;
GPArray<File> page2file;
GPMap<GUTF8String, File> name2file;
GPMap<GUTF8String, File> id2file;
GPMap<GUTF8String, File> title2file;
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<File> create(void) { return new File(); }
static GP<File> 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: 0x<bundled>0000011
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}
0b<hasname><hastitle>000000 for a file included by other files.
0b<hasname><hastitle>000001 for a file representing a page.
0b<hasname><hastitle>000010 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 );
}
// ----- THE END
#ifdef HAVE_NAMESPACES
}
# ifndef NOT_USING_DJVU_NAMESPACE
using namespace DJVU;
# endif
#endif
#endif