src/chrome/browser/printing/print_job.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   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 CHROME_BROWSER_PRINTING_PRINT_JOB_H_
   6 #define CHROME_BROWSER_PRINTING_PRINT_JOB_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "base/memory/weak_ptr.h"
  11 #include "base/message_loop/message_loop.h"
  12 #include "chrome/browser/printing/print_job_worker_owner.h"
  13 #include "content/public/browser/notification_observer.h"
  14 #include "content/public/browser/notification_registrar.h"
  15
  16 class Thread;
  17
  18 namespace printing {
  19
  20 // See definition below.
  21 class JobEventDetails;
  22
  23 class PrintedDocument;
  24 class PrintedPage;
  25 class PrintedPagesSource;
  26 class PrintJobWorker;
  27 class PrinterQuery;
  28
  29 // Manages the print work for a specific document. Talks to the printer through
  30 // PrintingContext though PrintJob::Worker. Hides access to PrintingContext in a
  31 // worker thread so the caller never blocks. PrintJob will send notifications on
  32 // any state change. While printing, the PrintJobManager instance keeps a
  33 // reference to the job to be sure it is kept alive. All the code in this class
  34 // runs in the UI thread.
  35 class PrintJob : public PrintJobWorkerOwner,
  36                  public content::NotificationObserver,
  37                  public base::MessageLoop::DestructionObserver {
  38  public:
  39   // Create a empty PrintJob. When initializing with this constructor,
  40   // post-constructor initialization must be done with Initialize().
  41   PrintJob();
  42
  43   // Grabs the ownership of the PrintJobWorker from another job, which is
  44   // usually a PrinterQuery. Set the expected page count of the print job.
  45   void Initialize(PrintJobWorkerOwner* job, PrintedPagesSource* source,
  46                   int page_count);
  47
  48   // content::NotificationObserver implementation.
  49   virtual void Observe(int type,
  50                        const content::NotificationSource& source,
  51                        const content::NotificationDetails& details) OVERRIDE;
  52
  53   // PrintJobWorkerOwner implementation.
  54   virtual void GetSettingsDone(const PrintSettings& new_settings,
  55                                PrintingContext::Result result) OVERRIDE;
  56   virtual PrintJobWorker* DetachWorker(PrintJobWorkerOwner* new_owner) OVERRIDE;
  57   virtual base::MessageLoop* message_loop() OVERRIDE;
  58   virtual const PrintSettings& settings() const OVERRIDE;
  59   virtual int cookie() const OVERRIDE;
  60
  61   // DestructionObserver implementation.
  62   virtual void WillDestroyCurrentMessageLoop() OVERRIDE;
  63
  64   // Starts the actual printing. Signals the worker that it should begin to
  65   // spool as soon as data is available.
  66   void StartPrinting();
  67
  68   // Asks for the worker thread to finish its queued tasks and disconnects the
  69   // delegate object. The PrintJobManager will remove its reference. This may
  70   // have the side-effect of destroying the object if the caller doesn't have a
  71   // handle to the object. Use PrintJob::is_stopped() to check whether the
  72   // worker thread has actually stopped.
  73   void Stop();
  74
  75   // Cancels printing job and stops the worker thread. Takes effect immediately.
  76   void Cancel();
  77
  78   // Synchronously wait for the job to finish. It is mainly useful when the
  79   // process is about to be shut down and we're waiting for the spooler to eat
  80   // our data.
  81   bool FlushJob(base::TimeDelta timeout);
  82
  83   // Disconnects the PrintedPage source (PrintedPagesSource). It is done when
  84   // the source is being destroyed.
  85   void DisconnectSource();
  86
  87   // Returns true if the print job is pending, i.e. between a StartPrinting()
  88   // and the end of the spooling.
  89   bool is_job_pending() const;
  90
  91   // Returns true if the worker thread is in the process of stopping.
  92   bool is_stopping() const;
  93
  94   // Returns true if the worker thread has stopped.
  95   bool is_stopped() const;
  96
  97   // Access the current printed document. Warning: may be NULL.
  98   PrintedDocument* document() const;
  99
 100  protected:
 101   virtual ~PrintJob();
 102
 103  private:
 104   // Updates document_ to a new instance.
 105   void UpdatePrintedDocument(PrintedDocument* new_document);
 106
 107   // Processes a NOTIFY_PRINT_JOB_EVENT notification.
 108   void OnNotifyPrintJobEvent(const JobEventDetails& event_details);
 109
 110   // Releases the worker thread by calling Stop(), then broadcasts a JOB_DONE
 111   // notification.
 112   void OnDocumentDone();
 113
 114   // Terminates the worker thread in a very controlled way, to work around any
 115   // eventual deadlock.
 116   void ControlledWorkerShutdown();
 117
 118   // Called at shutdown when running a nested message loop.
 119   void Quit();
 120
 121   void HoldUntilStopIsCalled(const scoped_refptr<PrintJob>& job);
 122
 123   content::NotificationRegistrar registrar_;
 124
 125   // Main message loop reference. Used to send notifications in the right
 126   // thread.
 127   base::MessageLoop* const ui_message_loop_;
 128
 129   // Source that generates the PrintedPage's (i.e. a WebContents). It will be
 130   // set back to NULL if the source is deleted before this object.
 131   PrintedPagesSource* source_;
 132
 133   // All the UI is done in a worker thread because many Win32 print functions
 134   // are blocking and enters a message loop without your consent. There is one
 135   // worker thread per print job.
 136   scoped_ptr<PrintJobWorker> worker_;
 137
 138   // Cache of the print context settings for access in the UI thread.
 139   PrintSettings settings_;
 140
 141   // The printed document.
 142   scoped_refptr<PrintedDocument> document_;
 143
 144   // Is the worker thread printing.
 145   bool is_job_pending_;
 146
 147   // Is Canceling? If so, try to not cause recursion if on FAILED notification,
 148   // the notified calls Cancel() again.
 149   bool is_canceling_;
 150
 151   // Is the worker thread stopping.
 152   bool is_stopping_;
 153
 154   // Is the worker thread stopped.
 155   bool is_stopped_;
 156
 157   // Used at shutdown so that we can quit a nested message loop.
 158   base::WeakPtrFactory<PrintJob> quit_factory_;
 159
 160   base::WeakPtrFactory<PrintJob> weak_ptr_factory_;
 161
 162   DISALLOW_COPY_AND_ASSIGN(PrintJob);
 163 };
 164
 165 // Details for a NOTIFY_PRINT_JOB_EVENT notification. The members may be NULL.
 166 class JobEventDetails : public base::RefCountedThreadSafe<JobEventDetails> {
 167  public:
 168   // Event type.
 169   enum Type {
 170     // Print... dialog box has been closed with OK button.
 171     USER_INIT_DONE,
 172
 173     // Print... dialog box has been closed with CANCEL button.
 174     USER_INIT_CANCELED,
 175
 176     // An automated initialization has been done, e.g. Init(false, NULL).
 177     DEFAULT_INIT_DONE,
 178
 179     // A new document started printing.
 180     NEW_DOC,
 181
 182     // A new page started printing.
 183     NEW_PAGE,
 184
 185     // A page is done printing.
 186     PAGE_DONE,
 187
 188     // A document is done printing. The worker thread is still alive. Warning:
 189     // not a good moment to release the handle to PrintJob.
 190     DOC_DONE,
 191
 192     // The worker thread is finished. A good moment to release the handle to
 193     // PrintJob.
 194     JOB_DONE,
 195
 196     // All missing pages have been requested.
 197     ALL_PAGES_REQUESTED,
 198
 199     // An error occured. Printing is canceled.
 200     FAILED,
 201   };
 202
 203   JobEventDetails(Type type, PrintedDocument* document, PrintedPage* page);
 204
 205   // Getters.
 206   PrintedDocument* document() const;
 207   PrintedPage* page() const;
 208   Type type() const {
 209     return type_;
 210   }
 211
 212  private:
 213   friend class base::RefCountedThreadSafe<JobEventDetails>;
 214
 215   ~JobEventDetails();
 216
 217   scoped_refptr<PrintedDocument> document_;
 218   scoped_refptr<PrintedPage> page_;
 219   const Type type_;
 220
 221   DISALLOW_COPY_AND_ASSIGN(JobEventDetails);
 222 };
 223
 224 }  // namespace printing
 225
 226 #endif  // CHROME_BROWSER_PRINTING_PRINT_JOB_H_