Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegraphics@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 518 insertions, 0 deletions

diff --git a/kviewshell/plugins/djvu/libdjvu/DjVuPort.h b/kviewshell/plugins/djvu/libdjvu/DjVuPort.h
new file mode 100644
index 00000000..99c165fb
--- /dev/null
+++ b/kviewshell/plugins/djvu/libdjvu/DjVuPort.h
@@ -0,0 +1,518 @@
+//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, Version 2. 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
+//C- distributed by Lizardtech Software.  On July 19th 2002, Lizardtech 
+//C- Software authorized us to replace the original DjVu(r) Reference 
+//C- Library notice by the following text (see doc/lizard2002.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, Version 2. 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- +------------------------------------------------------------------
+// 
+// $Id: DjVuPort.h,v 1.8 2003/11/07 22:08:21 leonb Exp $
+// $Name: release_3_5_15 $
+
+#ifndef _DJVUPORT_H
+#define _DJVUPORT_H
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+#if NEED_GNUG_PRAGMAS
+# pragma interface
+#endif
+
+
+#include "GThreads.h"
+#include "GURL.h"
+
+#ifdef HAVE_NAMESPACES
+namespace DJVU {
+# ifdef NOT_DEFINED // Just to fool emacs c++ mode
+}
+#endif
+#endif
+
+class DataPool;
+
+/** @name DjVuPort.h
+    Files #"DjVuPort.h"# and #"DjVuPort.cpp"# implement a communication
+    mechanism between different parties involved in decoding DjVu files.
+    It should be pretty clear that the creator of \Ref{DjVuDocument} and
+    \Ref{DjVuFile} would like to receive some information about the progress
+    of decoding, errors occurred, etc. It may also want to provide source data
+    for decoders (like it's done in the plugin where the real data is downloaded
+    from the net and is fed into DjVu decoders).
+
+    Normally this functionality is implemented by means of callbacks which are
+    run when a given condition comes true. Unfortunately it's not quite easy
+    to implement this strategy in our case. The reason is that there may be
+    more than one "client" working with the same document, and the document
+    should send the information to each of the clients. This could be done by
+    means of callback {\em lists}, of course, but we want to achieve more
+    bulletproof results: we want to be sure that the client that we're about
+    to contact is still alive, and is not being destroyed by another thread.
+    Besides, we are going to call these "callbacks" from many places, from
+    many different classes.  Maintaining multi-thread safe callback lists is
+    very difficult.
+
+    Finally, we want to provide some default implementation of these
+    "callbacks" in the library, which should attempt to process the requests
+    themselves if they can, and contact the client only if they're unable to
+    do it (like in the case of \Ref{DjVuPort::request_data}() with local URL
+    where \Ref{DjVuDocument} can get the data from the hard drive itself not
+    disturbing the document's creator.
+
+    Two classes implement a general communication mechanism: \Ref{DjVuPort} and
+    \Ref{DjVuPortcaster}. Any sender and recipient of requests should be a
+    subclass of \Ref{DjVuPort}.  \Ref{DjVuPortcaster} maintains a map of
+    routes between \Ref{DjVuPort}s, which should be configured by somebody
+    else. Whenever a port wants to send a request, it calls the corresponding
+    function of \Ref{DjVuPortcaster}, and the portcaster relays the request to
+    all the destinations that it sees in the internal map.
+
+    The \Ref{DjVuPortcaster} is responsible for keeping the map up to date by
+    getting rid of destinations that have been destroyed.  Map updates are
+    performed from a single place and are serialized by a global monitor.
+    
+    @memo DjVu decoder communication mechanism.
+    @author Andrei Erofeev <eaf@geocities.com>\\
+            L\'eon Bottou <leonb@research.att.com>
+    @version #$Id: DjVuPort.h,v 1.8 2003/11/07 22:08:21 leonb Exp $# */
+//@{
+
+class DjVuPort;
+class DjVuPortcaster;
+class DjVuFile;
+
+/** Base class for notification targets.
+    #DjVuPort# provides base functionality for classes willing to take part in
+    sending and receiving messages generated during decoding process.  You
+    need to derive your class from #DjVuPort# if you want it to be able to
+    send or receive requests. In addition, for receiving requests you should
+    override one or more virtual function.
+
+    {\bf Important remark} --- All ports should be allocated on the heap using
+    #operator new# and immediately secured using a \Ref{GP} smart pointer.
+    Ports which are not secured by a smart-pointer are not considered
+    ``alive'' and never receive notifications! */
+
+class DjVuPort : public GPEnabled
+{
+public:
+   DjVuPort();
+   virtual ~DjVuPort();
+   static void *operator new (size_t sz);
+   static void operator delete(void *addr);
+
+      /**  Use this function to get a copy of the global \Ref{DjVuPortcaster}. */
+   static DjVuPortcaster *get_portcaster(void);
+
+      /** Copy constructor. When #DjVuPort#s are copied, the portcaster
+          copies all incoming and outgoing routes of the original. */
+   DjVuPort(const DjVuPort & port);
+
+      /** Copy operator. Similarly to the copy constructor, the portcaster
+          copies all incoming and outgoing coming routes of the original. */
+   DjVuPort & operator=(const DjVuPort & port);
+
+      /** Should return 1 if the called class inherits class #class_name#.
+	  When a destination receives a request, it can retrieve the pointer
+	  to the source #DjVuPort#. This virtual function should be able
+	  to help to identify the source of the request. For example,
+	  \Ref{DjVuFile} is also derived from #DjVuPort#. In order for
+	  the receiver to recognize the sender, the \Ref{DjVuFile} should
+	  override this function to return #TRUE# when the #class_name#
+	  is either #DjVuPort# or #DjVuFile# */
+   virtual bool		inherits(const GUTF8String &class_name) const;
+
+      /** @name Notifications. 
+          These virtual functions may be overridden by the subclasses
+          of #DjVuPort#.  They are called by the \Ref{DjVuPortcaster}
+          when the port is alive and when there is a route between the 
+          source of the notification and this port. */
+      //@{
+
+      /** This request is issued to request translation of the ID, used
+	  in an DjVu INCL chunk to a URL, which may be used to request
+	  data associated with included file. \Ref{DjVuDocument} usually
+	  intercepts all such requests, and the user doesn't have to
+	  worry about the translation */
+   virtual GURL		id_to_url(const DjVuPort * source, const GUTF8String &id);
+
+      /** This request is used to get a file corresponding to the
+	  given ID. \Ref{DjVuDocument} is supposed to intercept it
+	  and either create a new instance of \Ref{DjVuFile} or reuse
+	  an existing one from the cache. */
+   virtual GP<DjVuFile>	id_to_file(const DjVuPort * source, const GUTF8String &id);
+
+      /** This request is issued when decoder needs additional data
+	  for decoding.  Both \Ref{DjVuFile} and \Ref{DjVuDocument} are
+	  initialized with a URL, not the document data.  As soon as
+	  they need the data, they call this function, whose responsibility
+	  is to locate the source of the data basing on the #URL# passed
+	  and return it back in the form of the \Ref{DataPool}. If this
+	  particular receiver is unable to fullfil the request, it should
+	  return #0#. */
+   virtual GP<DataPool>	request_data(const DjVuPort * source, const GURL & url);
+
+      /** This notification is sent when an error occurs and the error message
+	  should be shown to the user.  The receiver should return #0# if it is 
+          unable to process the request. Otherwise the receiver should return 1. */
+   virtual bool		notify_error(const DjVuPort * source, const GUTF8String &msg);
+
+      /** This notification is sent to update the decoding status.  The
+          receiver should return #0# if it is unable to process the
+          request. Otherwise the receiver should return 1. */
+   virtual bool		notify_status(const DjVuPort * source, const GUTF8String &msg);
+
+      /** This notification is sent by \Ref{DjVuImage} when it should be
+	  redrawn. It may be used to implement progressive redisplay.
+
+	  @param source The sender of the request */
+   virtual void		notify_redisplay(const class DjVuImage * source);
+
+      /** This notification is sent by \ref{DjVuImage} when its geometry
+	  has been changed as a result of decoding. It may be used to
+	  implement progressive redisplay. */
+   virtual void		notify_relayout(const class DjVuImage * source);
+
+      /** This notification is sent when a new chunk has been decoded. */
+   virtual void		notify_chunk_done(const DjVuPort * source, const GUTF8String &name);
+
+      /** This notification is sent after the \Ref{DjVuFile} flags have
+	  been changed. This happens, for example, when:
+	  \begin{itemize}
+	    \item Decoding succeeded, failed or just stopped
+	    \item All data has been received
+	    \item All included files have been created
+	  \end{itemize}
+	  
+	  @param source \Ref{DjVuFile}, which flags have been changed
+	  @param set_mask bits, which have been set
+	  @param clr_mask bits, which have been cleared */
+   virtual void		notify_file_flags_changed(const class DjVuFile * source,
+						  long set_mask, long clr_mask);
+
+      /** This notification is sent after the \Ref{DjVuDocument} flags have
+	  been changed. This happens, for example, after it receives enough
+	  data and can determine its structure (#BUNDLED#, #OLD_INDEXED#, etc.).
+
+	  @param source \Ref{DjVuDocument}, which flags have been changed
+	  @param set_mask bits, which have been set
+	  @param clr_mask bits, which have been cleared */
+   virtual void		notify_doc_flags_changed(const class DjVuDocument * source,
+						 long set_mask, long clr_mask);
+   
+      /** This notification is sent from time to time while decoding is in
+	  progress. The purpose is obvious: to provide a way to know how much
+	  is done and how long the decoding will continue.  Argument #done# is
+	  a number from 0 to 1 reflecting the progress. */
+   virtual void		notify_decode_progress(const DjVuPort * source, float done);
+
+      /** This is the standard types for defining what to do in case of errors.
+          This is only used by some of the subclasses, but it needs to be 
+          defined here to guarantee all subclasses use the same enum types.
+          In general, many errors are non recoverable.  Using a setting
+          other than ABORT may just result in even more errors. */
+   enum ErrorRecoveryAction {ABORT=0,SKIP_PAGES=1,SKIP_CHUNKS=2,KEEP_ALL=3 }; 
+      //@}
+public:
+   class DjVuPortCorpse;
+private:
+   static GCriticalSection	* corpse_lock;
+   static DjVuPortCorpse	* corpse_head, * corpse_tail;
+   static int			corpse_num;
+};
+
+/** Simple port.  
+    An instance of #DjVuSimplePort# is automatically created when you create a
+    \Ref{DjVuFile} or a \Ref{DjVuDocument} without specifying a port.  This
+    simple port can retrieve data for local urls (i.e. urls referring to local
+    files) and display error messages on #stderr#.  All other notifications
+    are ignored. */
+
+class DjVuSimplePort : public DjVuPort
+{
+public:
+      /// Returns 1 if #class_name# is #"DjVuPort"# or #"DjVuSimplePort"#.
+   virtual bool		inherits(const GUTF8String &class_name) const;
+
+      /** If #url# is local, it created a \Ref{DataPool}, connects it to the
+	  file with the given name and returns.  Otherwise returns #0#. */
+   virtual GP<DataPool>	request_data(const DjVuPort * source, const GURL & url);
+
+      /// Displays error on #stderr#. Always returns 1.
+   virtual bool		notify_error(const DjVuPort * source, const GUTF8String &msg);
+   
+      /// Displays status on #stderr#. Always returns 1.
+   virtual bool		notify_status(const DjVuPort * source, const GUTF8String &msg);
+};
+
+
+/** Memory based port.
+    This \Ref{DjVuPort} maintains a map associating pseudo urls with data
+    segments.  It processes the #request_data# notifications according to this
+    map.  After initializing the port, you should add as many pairs #<url,
+    pool># as needed need and add a route from a \Ref{DjVuDocument} or
+    \Ref{DjVuFile} to this port. */
+
+class DjVuMemoryPort : public DjVuPort
+{
+public:
+      /// Returns 1 if #class_name# is #"DjVuPort"# or #"DjVuMemoryPort"#
+   virtual bool		inherits(const GUTF8String &class_name) const;
+
+      /** If #url# is one of those, that have been added before by means
+	  of \Ref{add_data}() function, it will return the associated
+	  \Ref{DataPool}. #ZERO# otherwize. */
+   virtual GP<DataPool>	request_data(const DjVuPort * source, const GURL & url);
+
+      /** Adds #<url, pool># pair to the internal map. From now on, if
+	  somebody asks for data corresponding to the #url#, it will
+	  be returning the #pool# */
+   void		add_data(const GURL & url, const GP<DataPool> & pool);
+private:
+   GCriticalSection	lock;
+   GPMap<GURL, DataPool>map;
+};
+
+
+
+/** Maintains associations between ports.
+    It monitors the status of all ports (have they been destructed yet?),
+    accepts requests and notifications from them and forwards them to
+    destinations according to internally maintained map of routes.
+
+    The caller can modify the route map any way he likes (see
+    \Ref{add_route}(), \Ref{del_route}(), \Ref{copy_routes}(),
+    etc. functions). Any port can be either a sender of a message, an
+    intermediary receiver or a final destination.  
+
+    When a request is sent, the #DjVuPortcaster# computes the list of
+    destinations by consulting with the route map.  Notifications are only
+    sent to ``alive'' ports.  A port is alive if it is referenced by a valid
+    \Ref{GP} smartpointer.  As a consequence, a port usually becomes alive
+    after running the constructor (since the returned pointer is then assigned
+    to a smartpointer) and is no longer alive when the port is destroyed
+    (because it would not be destroyed if a smartpointer was referencing it).
+
+    Destination ports are sorted according to their distance from the source.
+    For example, if port {\bf A} is connected to ports {\bf B} and {\bf C}
+    directly, and port {\bf B} is connected to {\bf D}, then {\bf B} and {\bf
+    C} are assumed to be one hop away from {\bf A}, while {\bf D} is two hops
+    away from {\bf A}.
+
+    In some cases the requests and notifications are sent to every possible
+    destination, and the order is not significant (like it is for
+    \Ref{notify_file_flags_changed}() request). Others should be sent to the closest
+    destinations first, and only then to the farthest, in case if they have
+    not been processed by the closest. The examples are \Ref{request_data}(),
+    \Ref{notify_error}() and \Ref{notify_status}().
+
+    The user is not expected to create the #DjVuPortcaster# itself. He should
+    use \Ref{get_portcaster}() global function instead.  */
+class DjVuPortcaster
+{
+public:
+      /**  Use this function to get a copy of the global \Ref{DjVuPortcaster}. */
+   static DjVuPortcaster *get_portcaster(void)
+    { return DjVuPort::get_portcaster(); } ;
+
+      /** The default constructor. */
+   DjVuPortcaster(void);
+
+   virtual ~DjVuPortcaster(void);
+
+      /** Removes the specified port from all routes. It will no longer
+	  be able to receive or generate messages and will be considered
+    {\bf "dead"} by \Ref{is_port_alive}() function. */
+   void		del_port(const DjVuPort * port);
+   
+      /** Adds route from #src# to #dst#. Whenever a request is
+	  sent or received by #src#, it will be forwarded to #dst# as well.
+	  @param src The source
+	  @param dst The destination */
+   void		add_route(const DjVuPort *src, DjVuPort *dst);
+
+      /** The opposite of \Ref{add_route}(). Removes the association
+	  between #src# and #dst# */
+   void		del_route(const DjVuPort *src, DjVuPort *dst);
+
+      /** Copies all incoming and outgoing routes from #src# to
+	  #dst#. This function should be called when a \Ref{DjVuPort} is
+	  copied, if you want to preserve the connectivity. */
+   void		copy_routes(DjVuPort *dst, const DjVuPort *src);
+
+      /** Returns a smart pointer to the port if #port# is a valid pointer
+          to an existing #DjVuPort#.  Returns a null pointer otherwise. */
+   GP<DjVuPort> is_port_alive(DjVuPort *port);
+
+      /** Assigns one more {\em alias} for the specified \Ref{DjVuPort}.
+	  {\em Aliases} are names, which can be used later to retrieve this
+	  \Ref{DjVuPort}, if it still exists. Any \Ref{DjVuPort} may have
+	  more than one {\em alias}. But every {\em alias} must correspond
+	  to only one \Ref{DjVuPort}. Thus, if the specified alias is
+	  already associated with another port, this association will be
+	  removed. */
+   void		add_alias(const DjVuPort * port, const GUTF8String &alias);
+
+      /** Removes all the aliases */
+   static void		clear_all_aliases(void);
+
+      /** Removes all aliases associated with the given \Ref{DjVuPort}. */
+   void		clear_aliases(const DjVuPort * port);
+
+      /** Returns \Ref{DjVuPort} associated with the given #alias#. If nothing
+	  is known about name #alias#, or the port associated with it has
+	  already been destroyed #ZERO# pointer will be returned. */
+   GP<DjVuPort>	alias_to_port(const GUTF8String &name);
+
+      /** Returns a list of \Ref{DjVuPort}s with aliases starting with
+	  #prefix#. If no \Ref{DjVuPort}s have been found, empty
+	  list is returned. */
+   GPList<DjVuPort>	prefix_to_ports(const GUTF8String &prefix);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest until one of them returns non-empty \Ref{GURL}. */
+   virtual GURL		id_to_url(const DjVuPort * source, const GUTF8String &id);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest until one of them returns non-zero pointer to
+	  \Ref{DjVuFile}. */
+   virtual GP<DjVuFile>	id_to_file(const DjVuPort * source, const GUTF8String &id);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest until one of them returns non-zero \Ref{DataPool}. */
+   virtual GP<DataPool>	request_data(const DjVuPort * source, const GURL & url);
+
+      /** Computes destination list for #source# and calls the corresponding.
+	  function in each of the ports from the destination starting from
+	  the closest until one of them returns 1. */
+   virtual bool		notify_error(const DjVuPort * source, const GUTF8String &msg);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest until one of them returns 1. */
+   virtual bool		notify_status(const DjVuPort * source, const GUTF8String &msg);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest. */
+   virtual void		notify_redisplay(const class DjVuImage * source);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest. */
+   virtual void		notify_relayout(const class DjVuImage * source);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest. */
+   virtual void		notify_chunk_done(const DjVuPort * source, const GUTF8String &name);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest. */
+   virtual void		notify_file_flags_changed(const class DjVuFile * source,
+						  long set_mask, long clr_mask);
+
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest. */
+   virtual void		notify_doc_flags_changed(const class DjVuDocument * source,
+						 long set_mask, long clr_mask);
+   
+      /** Computes destination list for #source# and calls the corresponding
+	  function in each of the ports from the destination list starting from
+	  the closest. */
+   virtual void		notify_decode_progress(const DjVuPort * source, float done);
+
+private:
+      // We use these 'void *' to minimize template instantiations.
+   friend class DjVuPort;
+   GCriticalSection		map_lock;
+   GMap<const void *, void *>	route_map;	// GMap<DjVuPort *, GList<DjVuPort *> *>
+   GMap<const void *, void *>	cont_map;	// GMap<DjVuPort *, DjVuPort *>
+   GMap<GUTF8String, const void *>	a2p_map;	// GMap<GUTF8String, DjVuPort *>
+   void add_to_closure(GMap<const void*, void*> & set,
+                       const DjVuPort *dst, int distance);
+   void compute_closure(const DjVuPort *src, GPList<DjVuPort> &list,
+                        bool sorted=false);
+};
+
+
+inline bool
+DjVuPort::inherits(const GUTF8String &class_name) const
+{
+   return (class_name == "DjVuPort");
+}
+
+inline bool
+DjVuSimplePort::inherits(const GUTF8String &class_name) const
+{
+   return
+      (class_name == "DjVuSimplePort") || DjVuPort::inherits(class_name);
+}
+
+inline bool
+DjVuMemoryPort::inherits(const GUTF8String &class_name) const
+{
+   return
+      (class_name == "DjVuMemoryPort") || DjVuPort::inherits(class_name);
+}
+
+//@}
+
+
+#ifdef HAVE_NAMESPACES
+}
+# ifndef NOT_USING_DJVU_NAMESPACE
+using namespace DJVU;
+# endif
+#endif
+#endif