printing/printed_document.h

   1 // Copyright 2012 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PRINTING_PRINTED_DOCUMENT_H_
   6 #define PRINTING_PRINTED_DOCUMENT_H_
   7
   8 #include <map>
   9 #include <memory>
  10 #include <string>
  11
  12 #include "base/files/file_path.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "base/synchronization/lock.h"
  15 #include "build/build_config.h"
  16 #include "printing/mojom/print.mojom.h"
  17 #include "printing/print_settings.h"
  18
  19 namespace base {
  20 class RefCountedMemory;
  21 }
  22
  23 namespace printing {
  24
  25 class MetafilePlayer;
  26 class PrintedPage;
  27 class PrintingContext;
  28
  29 // A collection of rendered pages. The settings are immutable. If the print
  30 // settings are changed, a new PrintedDocument must be created.
  31 // Warning: May be accessed from many threads at the same time. Only one thread
  32 // will have write access. Sensible functions are protected by a lock.
  33 // Warning: Once a page is loaded, it cannot be replaced. Pages may be discarded
  34 // under low memory conditions.
  35 class COMPONENT_EXPORT(PRINTING) PrintedDocument
  36     : public base::RefCountedThreadSafe<PrintedDocument> {
  37  public:
  38   // The cookie shall be unique and has a specific relationship with its
  39   // originating source and settings.
  40   PrintedDocument(std::unique_ptr<PrintSettings> settings,
  41                   const std::u16string& name,
  42                   int cookie);
  43   PrintedDocument(const PrintedDocument&) = delete;
  44   PrintedDocument& operator=(const PrintedDocument&) = delete;
  45
  46 #if BUILDFLAG(IS_WIN)
  47   // Indicates that the PDF has been generated and the document is waiting for
  48   // conversion for printing. This is needed on Windows so that the print job
  49   // is not cancelled if the web contents dies before PDF conversion finishes.
  50   // This is applicable when using the GDI print API.
  51   void SetConvertingPdf();
  52
  53   // Sets a page's data. 0-based. Note: locks for a short amount of time.
  54   void SetPage(uint32_t page_number,
  55                std::unique_ptr<MetafilePlayer> metafile,
  56                float shrink,
  57                const gfx::Size& page_size,
  58                const gfx::Rect& page_content_rect);
  59
  60   // Retrieves a page. If the page is not available right now, it
  61   // requests to have this page be rendered and returns NULL.
  62   // Note: locks for a short amount of time.
  63   scoped_refptr<PrintedPage> GetPage(uint32_t page_number);
  64
  65   // Removes reference to a particular `page` based on its page number.
  66   // Note: locks for a short amount of time.
  67   void RemovePage(const PrintedPage* page);
  68 #endif  // BUILDFLAG(IS_WIN)
  69
  70   // Sets the document data. Note: locks for a short amount of time.
  71   void SetDocument(std::unique_ptr<MetafilePlayer> metafile);
  72
  73   // Retrieves the metafile with the data to print. Lock must be held when
  74   // calling this function
  75   const MetafilePlayer* GetMetafile();
  76
  77 // Draws the page in the context.
  78 // Note: locks for a short amount of time in debug only.
  79 #if BUILDFLAG(IS_WIN)
  80   // This is applicable when using the Windows GDI print API.
  81   mojom::ResultCode RenderPrintedPage(const PrintedPage& page,
  82                                       PrintingContext* context) const;
  83
  84 #if !defined(NDEBUG)
  85   // Verifies that the page is intended to be printed for the document.
  86   // Note: locks for a short amount of time.
  87   bool IsPageInList(const PrintedPage& page) const;
  88 #endif  // !defined(NDEBUG)
  89 #endif  // BUILDFLAG(IS_WIN)
  90
  91   // Draws the document in the context.  Fails if context->NewPage() or
  92   // context->PageDone() fails.
  93   mojom::ResultCode RenderPrintedDocument(PrintingContext* context);
  94
  95   // Returns true if all the necessary pages for the settings are already
  96   // rendered.
  97   // Note: This function always locks and may parse the whole tree.
  98   bool IsComplete() const;
  99
 100   // Sets the number of pages in the document to be rendered. Can only be set
 101   // once.
 102   // Note: locks for a short amount of time.
 103   void set_page_count(uint32_t max_page);
 104
 105   // Number of pages in the document.
 106   // Note: locks for a short amount of time.
 107   uint32_t page_count() const;
 108
 109   // Returns the number of expected pages to be rendered. It is a non-linear
 110   // series if settings().ranges is not empty. It is the same value as
 111   // document_page_count() otherwise.
 112   // Note: locks for a short amount of time.
 113   uint32_t expected_page_count() const;
 114
 115   // Getters. All these items are immutable hence thread-safe.
 116   const PrintSettings& settings() const { return *immutable_.settings_; }
 117   const std::u16string& name() const { return immutable_.name_; }
 118   int cookie() const { return immutable_.cookie_; }
 119
 120   // Sets a path where to dump printing output files for debugging. If never
 121   // set, no files are generated. `debug_dump_path` must not be empty.
 122   static void SetDebugDumpPath(const base::FilePath& debug_dump_path);
 123
 124   // Returns true if SetDebugDumpPath() has been called.
 125   static bool HasDebugDumpPath();
 126
 127   // Creates debug file name from given `document_name` and `extension`.
 128   // `extension` should include the leading dot. e.g. ".pdf"
 129   // Should only be called when debug dumps are enabled.
 130   static base::FilePath CreateDebugDumpPath(
 131       const std::u16string& document_name,
 132       const base::FilePath::StringType& extension);
 133
 134   // Dump data on blocking task runner.
 135   // Should only be called when debug dumps are enabled.
 136   void DebugDumpData(const base::RefCountedMemory* data,
 137                      const base::FilePath::StringType& extension);
 138
 139  private:
 140   friend class base::RefCountedThreadSafe<PrintedDocument>;
 141
 142   ~PrintedDocument();
 143
 144   // Array of data for each print previewed page.
 145   using PrintedPages = std::map<uint32_t, scoped_refptr<PrintedPage>>;
 146
 147   // Contains all the mutable stuff. All this stuff MUST be accessed with the
 148   // lock held.
 149   struct Mutable {
 150     Mutable();
 151     ~Mutable();
 152
 153     // Number of expected pages to be rendered.
 154     // Warning: Lock must be held when accessing this member.
 155     uint32_t expected_page_count_ = 0;
 156
 157     // The total number of pages in the document.
 158     uint32_t page_count_ = 0;
 159
 160     std::unique_ptr<MetafilePlayer> metafile_;
 161
 162 #if BUILDFLAG(IS_WIN)
 163     // Contains the pages' representation. This is a collection of PrintedPage.
 164     // Warning: Lock must be held when accessing this member.
 165     // This is applicable when using the Windows GDI print API which has the
 166     // extra conversion step from PDF to EMF prior to sending to device.
 167     // The metafile_ field is not used in this scenario.
 168     PrintedPages pages_;
 169
 170     // Whether the PDF is being converted for printing.
 171     bool converting_pdf_ = false;
 172 #endif
 173   };
 174
 175   // Contains all the immutable stuff. All this stuff can be accessed without
 176   // any lock held. This is because it can't be changed after the object's
 177   // construction.
 178   struct Immutable {
 179     Immutable(std::unique_ptr<PrintSettings> settings,
 180               const std::u16string& name,
 181               int cookie);
 182     ~Immutable();
 183
 184     // Print settings used to generate this document. Immutable.
 185     std::unique_ptr<PrintSettings> settings_;
 186
 187     // Document name. Immutable.
 188     std::u16string name_;
 189
 190     // Cookie to uniquely identify this document. It is used to make sure that a
 191     // PrintedPage is correctly belonging to the PrintedDocument. Since
 192     // PrintedPage generation is completely asynchronous, it could be easy to
 193     // mess up and send the page to the wrong document. It can be viewed as a
 194     // simpler hash of PrintSettings since a new document is made each time the
 195     // print settings change.
 196     int cookie_;
 197   };
 198
 199   // All writable data member access must be guarded by this lock. Needs to be
 200   // mutable since it can be acquired from const member functions.
 201   mutable base::Lock lock_;
 202
 203   // All the mutable members.
 204   Mutable mutable_;
 205
 206   // All the immutable members.
 207   const Immutable immutable_;
 208 };
 209
 210 }  // namespace printing
 211
 212 #endif  // PRINTING_PRINTED_DOCUMENT_H_