source: trunk/libdjvu/DjVuFile.h @ 199

Last change on this file since 199 was 17, checked in by Eugene Romanenko, 16 years ago

update makefiles, remove absolute paths, update djvulibre to version 3.5.17

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