source: trunk/libdjvu/DjVuFile.h @ 206

Last change on this file since 206 was 206, checked in by Eugene Romanenko, 14 years ago

DJVU plugin: djvulibre updated to version 3.5.19

File size: 32.6 KB
Line 
1//C-  -*- C++ -*-
2//C- -------------------------------------------------------------------
3//C- DjVuLibre-3.5
4//C- Copyright (c) 2002  Leon Bottou and Yann Le Cun.
5//C- Copyright (c) 2001  AT&T
6//C-
7//C- This software is subject to, and may be distributed under, the
8//C- GNU General Public License, either Version 2 of the license,
9//C- or (at your option) any later version. The license should have
10//C- accompanied the software or you may obtain a copy of the license
11//C- from the Free Software Foundation at http://www.fsf.org .
12//C-
13//C- This program is distributed in the hope that it will be useful,
14//C- but WITHOUT ANY WARRANTY; without even the implied warranty of
15//C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16//C- GNU General Public License for more details.
17//C-
18//C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from
19//C- Lizardtech Software.  Lizardtech Software has authorized us to
20//C- replace the original DjVu(r) Reference Library notice by the following
21//C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):
22//C-
23//C-  ------------------------------------------------------------------
24//C- | DjVu (r) Reference Library (v. 3.5)
25//C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.
26//C- | The DjVu Reference Library is protected by U.S. Pat. No.
27//C- | 6,058,214 and patents pending.
28//C- |
29//C- | This software is subject to, and may be distributed under, the
30//C- | GNU General Public License, either Version 2 of the license,
31//C- | or (at your option) any later version. The license should have
32//C- | accompanied the software or you may obtain a copy of the license
33//C- | from the Free Software Foundation at http://www.fsf.org .
34//C- |
35//C- | The computer code originally released by LizardTech under this
36//C- | license and unmodified by other parties is deemed "the LIZARDTECH
37//C- | ORIGINAL CODE."  Subject to any third party intellectual property
38//C- | claims, LizardTech grants recipient a worldwide, royalty-free,
39//C- | non-exclusive license to make, use, sell, or otherwise dispose of
40//C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the
41//C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU
42//C- | General Public License.   This grant only confers the right to
43//C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to
44//C- | the extent such infringement is reasonably necessary to enable
45//C- | recipient to make, have made, practice, sell, or otherwise dispose
46//C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to
47//C- | any greater extent that may be necessary to utilize further
48//C- | modifications or combinations.
49//C- |
50//C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY
51//C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
52//C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF
53//C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
54//C- +------------------------------------------------------------------
55//
56// $Id: DjVuFile.h,v 1.11 2007/03/25 20:48:30 leonb Exp $
57// $Name: release_3_5_19 $
58
59#ifndef _DJVUFILE_H
60#define _DJVUFILE_H
61#ifdef HAVE_CONFIG_H
62#include "config.h"
63#endif
64#if NEED_GNUG_PRAGMAS
65# pragma interface
66#endif
67
68
69#include "DjVuInfo.h"
70#include "DjVuPalette.h"
71#include "DjVuPort.h"
72
73#ifdef HAVE_NAMESPACES
74namespace DJVU {
75# ifdef NOT_DEFINED // Just to fool emacs c++ mode
76}
77#endif
78#endif
79
80class DjVuTXT;
81class ByteStream;
82class DataPool;
83class JB2Image;
84class JB2Dict;
85class IW44Image;
86class IFFByteStream;
87class GPixmap;
88class DjVuNavDir;
89
90
91/** @name DjVuFile.h
92    Files #"DjVuFile.h"# and #"DjVuFile.cpp"# contain implementation of the
93    \Ref{DjVuFile} class, which takes the leading role in decoding of
94    \Ref{DjVuImage}s.
95
96    In the previous releases of the library the work of decoding has been
97    entirely done in \Ref{DjVuImage}. Now, due to the introduction of multipage
98    documents, the decoding procedure became significantly more complex and
99    has been moved out from \Ref{DjVuImage} into \Ref{DjVuFile}.
100
101    There is not much point though in creating just \Ref{DjVuFile} alone.
102    The maximum power of the decoder is achieved when you create the
103    \Ref{DjVuDocument} and work with {\bf it} when decoding the image.
104
105    @memo Classes representing DjVu files.
106    @author Andrei Erofeev <eaf@geocities.com>
107    @version #$Id: DjVuFile.h,v 1.11 2007/03/25 20:48:30 leonb Exp $#
108*/
109
110//@{
111
112/** #DjVuFile# plays the central role in decoding \Ref{DjVuImage}s.
113    First of all, it represents a DjVu file whether it's part of a
114    multipage all-in-one-file DjVu document, or part of a multipage
115    DjVu document where every page is in a separate file, or the whole
116    single page document. #DjVuFile# can read its contents from a file
117    and store it back when necessary.
118
119    Second, #DjVuFile# does the greatest part of decoding work. In the
120    past this was the responsibility of \Ref{DjVuImage}. Now, with the
121    introduction of the multipage DjVu formats, the decoding routines
122    have been extracted from the \Ref{DjVuImage} and put into this separate
123    class #DjVuFile#.
124
125    As \Ref{DjVuImage} before, #DjVuFile# now contains public class
126    variables corresponding to every component, that can ever be decoded
127    from a DjVu file (such as #INFO# chunk, #BG44# chunk, #SJBZ# chunk, etc.).
128
129    As before, the decoding is initiated by a single function
130    (\Ref{start_decode}() in this case, and \Ref{DjVuImage::decode}() before).
131    The difference is that #DjVuFile# now handles threads creation itself.
132    When you call the \Ref{start_decode}() function, it creates the decoding
133    thread, which starts decoding, and which can create additional threads:
134    one per each file included into this one.
135
136    {\bf Inclusion} is also a new feature specifically designed for a
137    multipage document. Indeed, inside a given document there can be a lot
138    of things shared between its pages. Examples can be the document
139    annotation (\Ref{DjVuAnno}) and other things like shared shapes and
140    dictionary (to be implemented). To avoid putting these chunks into
141    every page, we have invented new chunk called #INCL# which purpose is
142    to make the decoder open the specified file and decode it.
143   
144    {\bf Source of data.} The #DjVuFile# can be initialized in two ways:
145    \begin{itemize}
146       \item With #URL# and \Ref{DjVuPort}. In this case #DjVuFile# will
147             request its data thru the communication mechanism provided by
148             \Ref{DjVuPort} in the constructor. If this file references
149             (includes) any other file, data for them will also be requested
150             in the same way.
151       \item With \Ref{ByteStream}. In this case the #DjVuFile# will read
152             its data directly from the passed stream. This constructor
153             has been added to simplify creation of #DjVuFile#s, which do
154             no include anything else. In this case the \Ref{ByteStream}
155             is enough for the #DjVuFile# to initialize.
156    \end{itemize}
157             
158    {\bf Progress information.} #DjVuFile# does not do decoding silently.
159    Instead, it sends a whole set of notifications through the mechanism
160    provided by \Ref{DjVuPort} and \Ref{DjVuPortcaster}. It tells the user
161    of the class about the progress of the decoding, about possible errors,
162    chunk being decoded, etc. The data is requested using this mechanism too.
163
164    {\bf Creating.} Depending on where you have data of the DjVu file, the
165    #DjVuFile# can be initialized in two ways:
166    \begin{itemize}
167       \item By providing #URL# and pointer to \Ref{DjVuPort}. In this case
168             #DjVuFile# will request data using communication mechanism
169             provided by \Ref{DjVuPort}. This is useful when the data is on
170             the web or when this file includes other files.
171       \item By providing a \Ref{ByteStream} with the data for the file. Use
172             it only when the file doesn't include other files.
173    \end{itemize}
174    There is also a bunch of functions provided for composing
175    the desired \Ref{DjVuDocument} and modifying #DjVuFile# structure. The
176    examples are \Ref{delete_chunks}(), \Ref{insert_chunk}(),
177    \Ref{include_file}() and \Ref{unlink_file}().
178
179    {\bf Caching.} In the case of plugin it's important to do the caching
180    of decoded images or files. #DjVuFile# appears to be the best candidate
181    for caching, and that's why it supports this procedure. Whenever a
182    #DjVuFile# is successfully decoded, it's added to the cache by
183    \Ref{DjVuDocument}. Next time somebody needs it, it will be extracted
184    from the cache directly by \Ref{DjVuDocument} and won't be decoded again.
185
186    {\bf URLs.} Historically the biggest strain is put on making the decoder
187    available for Netscape and IE plugins where the original files reside
188    somewhere in the net. That is why #DjVuFile# uses {\bf URLs} to
189    identify itself and other files. If you're working with files on the
190    hard disk, you have to use the local URLs instead of file names.
191    A good way to do two way conversion is the \Ref{GOS} class. Sometimes it
192    happens that a given file does not reside anywhere but the memory. No
193    problem in this case either. There is a special port \Ref{DjVuMemoryPort},
194    which can associate any URL with the corresponding data in the memory.
195    All you need to do is to invent your own URL prefix for this case.
196    "#memory:#" will do. The usage of absolute URLs has many advantages among
197    which is the capability to cache files with their URL being the cache key.
198
199    Please note, that the #DjVuFile# class has been designed to work closely
200    with \Ref{DjVuDocument}. So please review the documentation on this class
201    too. */
202
203class DjVuFile : public DjVuPort
204{
205public:
206   enum { DECODING=1, DECODE_OK=2, DECODE_FAILED=4, DECODE_STOPPED=8,
207          DATA_PRESENT=16, ALL_DATA_PRESENT=32, INCL_FILES_CREATED=64,
208          MODIFIED=128, DONT_START_DECODE=256, STOPPED=512,
209          BLOCKED_STOPPED=1024, CAN_COMPRESS=2048, NEEDS_COMPRESSION=4096 };
210   enum { STARTED=1, FINISHED=2 };
211
212      /** @name Decoded file contents */
213      //@{
214      /// Pointer to the DjVu file information component.
215   GP<DjVuInfo>         info;
216      /// Pointer to the background component of DjVu image (IW44 encoded).
217   GP<IW44Image>        bg44;
218      /// Pointer to the background component of DjVu image (Raw).
219   GP<GPixmap>          bgpm;
220      /// Pointer to the mask of foreground component of DjVu image (JB2 encoded).
221   GP<JB2Image>         fgjb;
222      /// Pointer to the optional shape dictionary for the mask (JB2 encoded).
223   GP<JB2Dict>          fgjd;
224      /// Pointer to a colors layer for the foreground component of DjVu image.
225   GP<GPixmap>          fgpm;
226      /// Pointer to a colors vector for the foreground component of DjVu image.
227   GP<DjVuPalette>      fgbc;
228      /// Pointer to collected annotation chunks.
229   GP<ByteStream>       anno;
230      /// Pointer to collected hiddentext chunks.
231   GP<ByteStream>       text;
232      /// Pointer to meta data chunks.
233   GP<ByteStream>       meta;
234      /// Pointer to the *old* navigation directory contained in this file
235   GP<DjVuNavDir>       dir;
236      /// Description of the file formed during decoding
237   GUTF8String          description;
238      /// MIME type string describing the DjVu data.
239   GUTF8String          mimetype;
240      /// Size of the file.
241   int                  file_size;
242      //@}
243
244protected:
245      /** Default constructor.  Must follow with an init() */
246   DjVuFile(void);
247public:
248   virtual ~DjVuFile(void);
249
250      /** Initializes a #DjVuFile# object. This is a simplified initializer,
251          which is not supposed to be used for decoding or creating
252          #DjVuFile#s, which include other files.
253
254          If the file is stored on the hard drive, you may also use the
255          other constructor and pass it the file's URL and #ZERO# #port#.
256          The #DjVuFile# will read the data itself.
257
258          If you want to receive error messages and notifications, you
259          may connect the #DjVuFile# to your own \Ref{DjVuPort} after
260          it has been constructed.
261
262          @param str The stream containing data for the file. */
263   void init(const GP<ByteStream> & str);
264
265      /** Creator, does the init(ByteStream &str) */
266   static GP<DjVuFile> create( const GP<ByteStream> & str,
267     const ErrorRecoveryAction recover_action=ABORT,
268     const bool verbose_eof=true);
269   
270      /** Initializes a #DjVuFile# object. As you can notice, the data is not
271          directly passed to this function. The #DjVuFile# will ask for it
272          through the \Ref{DjVuPort} mechanism before the constructor
273          finishes. If the data is stored locally on the hard disk then the
274          pointer to \Ref{DjVuPort} may be set to #ZERO#, which will make
275          #DjVuFile# read all data from the hard disk and report all errors
276          to #stderr#.
277
278          {\bf Note}. If the file includes (by means of #INCL# chunks) other
279          files then you should be ready to
280          \begin{enumerate}
281             \item Reply to requests \Ref{DjVuPort::id_to_url}() issued to
282                   translate IDs (used in #INCL# chunks) to absolute URLs.
283                   Usually, when the file is created by \Ref{DjVuDocument}
284                   this job is done by it. If you construct such a file
285                   manually, be prepared to do the ID to URL translation
286             \item Provide data for all included files.
287          \end{enumerate}
288
289          @param url The URL assigned to this file. It will be used when
290                 the #DjVuFile# asks for data.
291          @param port All communication between #DjVuFile#s and \Ref{DjVuDocument}s
292                 is done through the \Ref{DjVuPort} mechanism. If the {\em url}
293                 is not local or the data does not reside on the hard disk,
294                 the {\em port} parameter must not be #ZERO#. If the {\em port}
295                 is #ZERO# then #DjVuFile# will create an internal instance
296                 of \Ref{DjVuSimplePort} for accessing local files and
297                 reporting errors. It can later be disabled by means
298                 of \Ref{disable_standard_port}() function. */
299   void init(const GURL & url, GP<DjVuPort> port=0);
300
301      /** Creator, does the init(const GURL &url, GP<DjVuPort> port=0) */
302   static GP<DjVuFile> create(
303     const GURL & url, GP<DjVuPort> port=0,
304     const ErrorRecoveryAction recover_action=ABORT,
305     const bool verbose_eof=true);
306
307      /** Disables the built-in port for accessing local files, which may
308          have been created in the case when the #port# argument to
309          the \Ref{DjVuFile::DjVuFile}() constructor is #ZERO# */
310   void         disable_standard_port(void);
311
312      /** Looks for #decoded# navigation directory (\Ref{DjVuNavDir}) in this
313          or included files. Returns #ZERO# if nothing could be found.
314
315          {\bf Note.} This function does {\bf not} attempt to decode #NDIR#
316          chunks. It is looking for predecoded components. #NDIR# can be
317          decoded either during regular decoding (initiated by
318          \Ref{start_decode}() function) or by \Ref{decode_ndir}() function,
319          which processes this and included files recursively in search
320          of #NDIR# chunks and decodes them. */
321   GP<DjVuNavDir>       find_ndir(void);
322
323      /** @name #DjVuFile# flags query functions */
324      //@{
325      /** Returns the #DjVuFile# flags. The value returned is the
326          result of ORing one or more of the following constants:
327          \begin{itemize}
328             \item #DECODING# The decoding is in progress
329             \item #DECODE_OK# The decoding has finished successfully
330             \item #DECODE_FAILED# The decoding has failed
331             \item #DECODE_STOPPED# The decoding has been stopped by
332                   \Ref{stop_decode}() function
333             \item #DATA_PRESENT# All data for this file has been received.
334                   It's especially important in the case of Netscape or IE
335                   plugins when the data is being received while the
336                   decoding is done.
337             \item #ALL_DATA_PRESENT# Not only data for this file, but also
338                   for all included file has been received.
339             \item #INCL_FILES_CREATED# All #INCL# and #INCF# chunks have been
340                   processed and the corresponding #DjVuFile#s created. This
341                   is important to know to be sure that the list returned by
342                   \Ref{get_included_files}() is OK.
343          \end{itemize} */
344   long         get_flags(void) const;
345      /// Returns #TRUE# if the file is being decoded.
346   bool         is_decoding(void) const;
347      /// Returns #TRUE# if decoding of the file has finished successfully.
348   bool         is_decode_ok(void) const;
349      /// Returns #TRUE# if decoding of the file has failed.
350   bool         is_decode_failed(void) const;
351      /** Returns #TRUE# if decoding of the file has been stopped by
352          \Ref{stop_decode}() function. */
353   bool         is_decode_stopped(void) const;
354      /// Returns #TRUE# if this file has received all data.
355   bool         is_data_present(void) const;
356      /** Returns #TRUE# if this file {\bf and} all included files have
357          received all data. */
358   bool         is_all_data_present(void) const;
359      /** Returns #TRUE# if all included files have been created. Only when
360          this function returns 1, the \Ref{get_included_files}() returns
361          the correct information. */
362   bool         are_incl_files_created(void) const;
363   bool         is_modified(void) const;
364   bool         needs_compression(void) const;
365   bool         can_compress(void) const;
366   void         set_modified(bool m);
367   void         set_needs_compression(bool m);
368   void         set_can_compress(bool m);
369      //@}
370
371      /// Returns the URL assigned to this file
372   GURL         get_url(void) const;
373
374      /** @name Decode control routines */
375      //@{
376      /** Starts decode. If threads are enabled, the decoding will be
377          done in another thread. Be sure to use \Ref{wait_for_finish}()
378          or listen for notifications sent through the \Ref{DjVuPortcaster}
379          to remain in sync. */
380   void         start_decode(void);
381      /** Start the decode iff not already decoded.  If sync is true, wait
382          wait for decode to complete.  Returns true of start_decode is called.
383          */
384   bool   resume_decode(const bool sync=false);
385      /** Stops decode. If #sync# is 1 then the function will not return
386          until the decoding thread actually dies. Otherwise it will
387          just signal the thread to stop and will return immediately.
388          Decoding of all included files will be stopped too. */
389   void         stop_decode(bool sync);
390      /** Recursively stops all data-related operations.
391
392          Depending on the value of #only_blocked# flag this works as follows:
393          \begin{itemize}
394             \item If #only_blocked# is #TRUE#, the function will make sure,
395                   that any further access to the file's data will result
396                   in a #STOP# exception if the desired data is not available
397                   (and the thread would normally block).
398             \item If #only_blocked# is #FALSE#, then {\bf any} further
399                   access to the file's data will result in immediate
400                   #STOP# exception.
401          \end{itemize}
402
403          The action of this function is recursive, meaning that any #DjVuFile#
404          included into this one will also be stopped.
405
406          Use this function when you don't need the #DjVuFile# anymore. The
407          results cannot be undone, and the whole idea is to make all threads
408          working with this file exit with the #STOP# exception. */
409   void         stop(bool only_blocked);
410      /** Wait for the decoding to finish. This will wait for the
411          termination of included files too. */
412   void         wait_for_finish(void);
413      /** Looks for #NDIR# chunk (navigation directory), and decodes its
414          contents. If the #NDIR# chunk has not been found in {\em this} file,
415          but this file includes others, the procedure will continue
416          recursively. This function is useful to obtain the document
417          navigation directory before any page has been decoded. After it
418          returns the directory can be obtained by calling \Ref{find_ndir}()
419          function.
420
421          {\bf Warning.} Contrary to \Ref{start_decode}(), this function
422          does not return before it completely decodes the directory.
423          Make sure, that this file and all included files have enough data. */
424   GP<DjVuNavDir>       decode_ndir(void);
425      /// Clears all decoded components.
426   void         reset(void);
427      /** Processes #INCL# chunks and creates included files.
428          Normally you won't need to call this function because included
429          files are created automatically when the file is being decoded.
430          But if due to some reason you'd like to obtain the list of included
431          files without decoding this file, this is an ideal function to call.
432
433          {\bf Warning.} This function does not return before it reads the
434          whole file, which may block your application under some circumstances
435          if not all data is available. */
436   void         process_incl_chunks(void);
437      //@}
438   
439      // Function needed by the cache
440   unsigned int get_memory_usage(void) const;
441
442      /** Returns the list of included DjVuFiles.
443         
444          {\bf Warning.} Included files are normally created during decoding.
445          Before that they do not exist.   If you call this function at
446          that time and set #only_created# to #FALSE# then it will have to
447          read all the data from this file in order to find #INCL# chunks,
448          which may block your application, if not all data is available.
449
450          @param only_created If #TRUE#, the file will not try to process
451                 #INCL# chunks and load referenced files. It will return
452                 just those files, which have already been created during
453                 the decoding procedure. */
454   GPList<DjVuFile>     get_included_files(bool only_created=true);
455
456      /** Includes a #DjVuFile# with the specified #id# into this one.
457          This function will also insert an #INCL# chunk at position
458          #chunk_num#. The function will request data for the included
459          file and will create it before returning. */
460   void         insert_file(const GUTF8String &id, int chunk_num=1);
461      /// Will get rid of included file with the given #id#
462   void         unlink_file(const GUTF8String &id);
463      /** Will find an #INCL# chunk containing #name# in input #data# and
464          will remove it */
465   static GP<DataPool>  unlink_file(const GP<DataPool> & data, const GUTF8String &name);
466
467      /// Returns the number of chunks in the IFF file data
468   int          get_chunks_number(void);
469      /// Returns the name of chunk number #chunk_num#
470   GUTF8String  get_chunk_name(int chunk_num);
471      /// Returns 1 if this file contains chunk with name #chunk_name#
472   bool         contains_chunk(const GUTF8String &chunk_name);
473
474      /** Processes the included files hierarchy and returns merged
475          annotations. This function may be used even when the #DjVuFile#
476          has not been decoded yet. If all data has been received for
477          this #DjVuFile# and all included #DjVuFile#s, it will will
478          gather annotations from them and will return the result.
479          If no annotations have been found, #ZERO# will be returned.
480          If either this #DjVuFile# or any of the included files do not
481          have all the data, the function will use the results of
482          decoding, which may have been started with the \Ref{start_decode}()
483          function. Otherwise #ZERO# will be returned as well.
484
485          If #max_level_ptr# pointer is not zero, the function will use
486          it to store the maximum level number from which annotations
487          have been obtained. #ZERO# level corresponds to the top-level
488          page file.
489
490          {\bf Summary:} This function will return complete annotations only
491          when the \Ref{is_all_data_present}() returns #TRUE#. */
492   GP<ByteStream>       get_merged_anno(int * max_level_ptr=0);
493
494      /** Returns the annotation chunks (#"ANTa"# and #"ANTz"#).  This
495          function may be used even when the #DjVuFile# has not been decoded
496          yet. If all data has been received for this #DjVuFile#, it will
497          gather hidden text and return the result.  If no hidden text has
498          been found, #ZERO# will be returned.
499
500          {\bf Summary:} This function will return complete annotations
501          only when the \Ref{is_all_data_present}() returns #TRUE#. */
502   GP<ByteStream>       get_anno(void);
503
504      /** Returns the text chunks (#"TXTa"# and #"TXTz"#).  This function may
505          be used even when the #DjVuFile# has not been decoded yet. If all
506          data has been received for this #DjVuFile#, it will gather hidden
507          text and return the result.  If no hidden text has been found,
508          #ZERO# will be returned.
509
510          {\bf Summary:} This function will return complete hidden text layers
511          only when the \Ref{is_all_data_present}() returns #TRUE#. */
512   GP<ByteStream>       get_text(void);
513
514      /** Returns the meta chunks (#"METa"# and #"METz"#).  This function may
515          be used even when the #DjVuFile# has not been decoded yet. If all
516          data has been received for this #DjVuFile#, it will gather metadata
517          and return the result.  If no hidden text has been found, #ZERO#
518          will be returned.
519
520          {\bf Summary:} This function will return complete meta data only
521          when the \Ref{is_all_data_present}() returns #TRUE#. */
522   GP<ByteStream>       get_meta(void);
523
524      /** Goes down the hierarchy of #DjVuFile#s and merges their annotations.
525          (shouldn't this one be private?).
526          @param max_level_ptr If this pointer is not ZERO, the function
527                 will use it to store the maximum level at which annotations
528                 were found. Top-level page files have ZERO #level#.
529          @param ignore_list The function will not process included #DjVuFile#s
530                 with URLs matching those mentioned in this #ignore_list#. */
531   GP<ByteStream>       get_merged_anno(const GList<GURL> & ignore_list,
532                                        int * max_level_ptr);
533
534      /** Clears this file of all annotations. */
535   void remove_anno(void);
536
537      /** Clears the hidden text. */
538   void remove_text(void);
539
540      /// Clears the meta data.
541   void remove_meta(void);
542
543      /** Returns #TRUE# if the file contains annotation chunks.
544          Known annotation chunks at the time of writing this help are:
545          {\bf ANTa}, {\bf ANTz}, {\bf FORM:ANNO}. */
546   bool         contains_anno(void);
547
548      /** Returns #TRUE# if the file contains hiddentext chunks.
549          Known hiddentext chunks at the time of writing this help are:
550          {\bf TXTa}, and {\bf TXTz}. */
551   bool         contains_text(void);
552
553      /** Returns #TRUE# if the file contains metadata chunks.
554          Known metadata chunks at the time of writing this help are:
555          {\bf METa}, and {\bf METz}. */
556   bool         contains_meta(void);
557
558     /** Changes the value of the hiddentext. */
559   void change_info(GP<DjVuInfo> info, const bool do_reset=false);
560   
561     /** Changes the value of the hiddentext. */
562   void change_text(GP<DjVuTXT> txt, const bool do_reset=false);
563   
564     /** Changes the value of the metadata. */
565   void change_meta(const GUTF8String &meta, const bool do_reset=false);
566   
567      /** @name Encoding routines */
568      //@{
569      /** The main function that encodes data back into binary stream.
570          The data returned will reflect possible changes made into the
571          chunk structure, annotation chunks and navigation directory
572          chunk #NDIR#.
573
574          {\bf Note:} The file stream will not have the magic
575          #0x41,0x54,0x26,0x54#
576          at the beginning.
577         
578          @param included_too Process included files too. */
579   GP<ByteStream>       get_djvu_bytestream(const bool included_too, const bool no_ndir=true);
580
581      /** Same as \Ref{get_djvu_bytestream}(), returning a DataPool.
582          @param included_too Process included files too. */
583   GP<DataPool>         get_djvu_data(const bool included_too, const bool no_ndir=true );
584      //@}
585
586      // Internal. Used by DjVuDocument
587   GP<DataPool>         get_init_data_pool(void) const { return data_pool; };
588
589      // Internal. Used by DjVuDocument. May block for data.
590   void                 move(const GURL & dir_url);
591
592      /** Internal. Used by DjVuDocument. The #name# should {\bf not}
593          be encoded with \Ref{GOS::encode_reserved}(). */
594   void                 set_name(const GUTF8String &name);
595
596      // Internal. Used by DjVuDocument
597   GSafeFlags &         get_safe_flags(void);
598
599      // Internal. Used by DjVuImage
600   void                 merge_anno(ByteStream &out);
601
602      // Internal. Used by DjVuImage
603   void                 get_text(ByteStream &out);
604
605      // Internal. Used by DjVuImage
606   void                 get_meta(ByteStream &out);
607
608      // Internal. Used by DjVuDocEditor
609   void                 rebuild_data_pool(void);
610
611      // Functions inherited from DjVuPort
612   virtual bool         inherits(const GUTF8String &class_name) const;
613   virtual void         notify_chunk_done(const DjVuPort * source, const GUTF8String &name);
614   virtual void         notify_file_flags_changed(const DjVuFile * source,
615                                                  long set_mask, long clr_mask);
616   virtual void         set_recover_errors(const ErrorRecoveryAction=ABORT);
617   virtual void         set_verbose_eof(const bool verbose_eof=true);
618   virtual void         report_error(const GException &ex,const bool=true);
619   static void set_decode_codec(GP<GPixmap> (*codec)(ByteStream &bs));
620
621protected:
622   GURL                 url;
623   GP<DataPool>         data_pool;
624
625   GPList<DjVuFile>     inc_files_list;
626   GCriticalSection     inc_files_lock;
627   GCriticalSection     anno_lock;
628   GCriticalSection     text_lock;
629   GCriticalSection     meta_lock;
630   ErrorRecoveryAction  recover_errors;
631   bool                 verbose_eof;
632   int                  chunks_number;
633private:
634   bool                 initialized;
635   GSafeFlags           flags;
636
637   GThread              * decode_thread;
638   GP<DataPool>         decode_data_pool;
639   GP<DjVuFile>         decode_life_saver;
640
641   GP<DjVuPort>         simple_port;
642
643   GMonitor             chunk_mon, finish_mon;
644
645      // Functions called when the decoding thread starts
646   static void  static_decode_func(void *);
647   void decode_func(void);
648   void decode(const GP<ByteStream> &str);
649   GUTF8String decode_chunk(const GUTF8String &chkid,
650     const GP<ByteStream> &str, bool djvi, bool djvu, bool iw44);
651   int          get_dpi(int w, int h);
652
653      // Functions dealing with the shape directory (fgjd)
654   static GP<JB2Dict> static_get_fgjd(void *);
655   GP<JB2Dict> get_fgjd(int block=0);
656
657      // Functions used to wait for smth
658   void         wait_for_chunk(void);
659   bool         wait_for_finish(bool self);
660
661      // INCL chunk processor
662   GP<DjVuFile> process_incl_chunk(ByteStream & str, int file_num=-1);
663
664      // Trigger: called when DataPool has all data
665   static void  static_trigger_cb(void *);
666   void         trigger_cb(void);
667   
668      // Progress callback: called from time to time
669   static void  progress_cb(int pos, void *);
670   static void  get_merged_anno(const GP<DjVuFile> & file,
671     const GP<ByteStream> &str_out, const GList<GURL> & ignore_list,
672     int level, int & max_level, GMap<GURL, void *> & map);
673   static void  get_anno(const GP<DjVuFile> & file,
674     const GP<ByteStream> &str_out);
675   static void  get_text(const GP<DjVuFile> & file,
676     const GP<ByteStream> &str_out);
677   static void  get_meta(const GP<DjVuFile> & file,
678     const GP<ByteStream> &str_out);
679
680   void          check() const;
681   GP<DjVuNavDir>find_ndir(GMap<GURL, void *> & map);
682   GP<DjVuNavDir>decode_ndir(GMap<GURL, void *> & map);
683   void         add_djvu_data(IFFByteStream & str,
684                              GMap<GURL, void *> & map,
685                              const bool included_too, const bool no_ndir=true);
686   void         move(GMap<GURL, void *> & map, const GURL & dir_url);
687private: // dummy stuff
688   static void decode(ByteStream *);
689   static GUTF8String decode_chunk(const GUTF8String &, ByteStream *,bool,bool,bool);
690   static void  get_merged_anno(const GP<DjVuFile> &,ByteStream *,
691     const GList<GURL> &, int, int &, GMap<GURL, void *> &);
692   static void  get_text(const GP<DjVuFile> &,ByteStream *);
693   static void  get_meta(const GP<DjVuFile> &,ByteStream *);
694
695};
696
697inline long
698DjVuFile::get_flags(void) const
699{
700   return flags;
701}
702
703inline GSafeFlags &
704DjVuFile::get_safe_flags(void)
705{
706   return flags;
707}
708
709inline bool
710DjVuFile::is_decoding(void) const
711{
712   return (flags & DECODING)!=0;
713}
714
715inline bool
716DjVuFile::is_decode_ok(void) const
717{
718   return (flags & DECODE_OK)!=0;
719}
720
721inline bool
722DjVuFile::is_decode_failed(void) const
723{
724   return (flags & DECODE_FAILED)!=0;
725}
726
727inline bool
728DjVuFile::is_decode_stopped(void) const
729{
730   return (flags & DECODE_STOPPED)!=0;
731}
732
733inline bool
734DjVuFile::is_data_present(void) const
735{
736   return (flags & DATA_PRESENT)!=0;
737}
738
739inline bool
740DjVuFile::is_all_data_present(void) const
741{
742   return (flags & ALL_DATA_PRESENT)!=0;
743}
744
745inline bool
746DjVuFile::are_incl_files_created(void) const
747{
748   return (flags & INCL_FILES_CREATED)!=0;
749}
750
751inline bool
752DjVuFile::is_modified(void) const
753{
754   return (flags & MODIFIED)!=0;
755}
756
757inline void
758DjVuFile::set_modified(bool m)
759{
760  flags=m ? (flags | MODIFIED) : (flags & ~MODIFIED);
761}
762
763inline bool
764DjVuFile::needs_compression(void) const
765{
766   return (flags & NEEDS_COMPRESSION)!=0;
767}
768
769inline void
770DjVuFile::set_needs_compression(bool m)
771{
772   if (m) flags=flags | NEEDS_COMPRESSION;
773   else flags=flags & ~NEEDS_COMPRESSION;
774}
775
776inline bool
777DjVuFile::can_compress(void) const
778{
779   return (flags & CAN_COMPRESS)!=0;
780}
781
782inline void
783DjVuFile::set_can_compress(bool m)
784{
785   if (m)
786     flags=flags | CAN_COMPRESS;
787   else
788     flags=flags & ~CAN_COMPRESS;
789}
790
791inline void
792DjVuFile::disable_standard_port(void)
793{
794   simple_port=0;
795}
796
797inline bool
798DjVuFile::inherits(const GUTF8String &class_name) const
799{
800   return
801      (GUTF8String("DjVuFile") == class_name) ||
802      DjVuPort::inherits(class_name);
803//      !strcmp("DjVuFile", class_name) ||
804//      DjVuPort::inherits(class_name);
805}
806
807inline void
808DjVuFile::wait_for_finish(void)
809{
810   while(wait_for_finish(1))
811     EMPTY_LOOP;
812}
813
814inline GURL
815DjVuFile::get_url(void) const
816{
817   return url;
818}
819
820inline void
821DjVuFile::set_verbose_eof
822(const bool verbose)
823{
824  verbose_eof=verbose;
825}
826
827inline void
828DjVuFile::set_recover_errors
829(const ErrorRecoveryAction action)
830{
831  recover_errors=action;
832}
833
834//@}
835
836
837#ifdef HAVE_NAMESPACES
838}
839# ifndef NOT_USING_DJVU_NAMESPACE
840using namespace DJVU;
841# endif
842#endif
843#endif
Note: See TracBrowser for help on using the repository browser.