cups_printer.h

// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef PRINTING_BACKEND_CUPS_PRINTER_H_
#define PRINTING_BACKEND_CUPS_PRINTER_H_

#include <cups/cups.h>

#include <memory>
#include <string>
#include <vector>

#include "printing/backend/cups_deleters.h"
#include "printing/printing_export.h"
#include "url/gurl.h"

namespace base {
class FilePath;
}

namespace printing {

struct PrinterBasicInfo;

// Provides information regarding cups options.
class PRINTING_EXPORT CupsOptionProvider {
 public:
  virtual ~CupsOptionProvider() = default;

  // Returns the supported ipp attributes for the given |option_name|.
  // ipp_attribute_t* is owned by CupsOptionProvider.
  virtual ipp_attribute_t* GetSupportedOptionValues(
      base::StringPiece option_name) const = 0;

  // Returns supported attribute values for |option_name| where the value can be
  // convered to a string.
  virtual std::vector<base::StringPiece> GetSupportedOptionValueStrings(
      base::StringPiece option_name) const = 0;

  // Returns the default ipp attributes for the given |option_name|.
  // ipp_attribute_t* is owned by CupsOptionProvider.
  virtual ipp_attribute_t* GetDefaultOptionValue(
      base::StringPiece option_name) const = 0;

  // Returns true if the |value| is supported by option |name|.
  virtual bool CheckOptionSupported(base::StringPiece name,
                                    base::StringPiece value) const = 0;
};

// Represents a CUPS printer.
// Retrieves information from CUPS printer objects as requested.  This class
// is only valid as long as the CupsConnection which created it exists as they
// share an http connection which the CupsConnection closes on destruction.
class PRINTING_EXPORT CupsPrinter : public CupsOptionProvider {
 public:
  // Create a printer with a connection defined by |http| and |dest|.  |info|
  // can be null and will be lazily initialized when needed.
  CupsPrinter(http_t* http,
              std::unique_ptr<cups_dest_t, DestinationDeleter> dest,
              std::unique_ptr<cups_dinfo_t, DestInfoDeleter> info);

  CupsPrinter(CupsPrinter&& printer);

  ~CupsPrinter() override;

  // Returns true if this is the default printer
  bool is_default() const;

  // CupsOptionProvider
  ipp_attribute_t* GetSupportedOptionValues(
      base::StringPiece option_name) const override;
  std::vector<base::StringPiece> GetSupportedOptionValueStrings(
      base::StringPiece option_name) const override;
  ipp_attribute_t* GetDefaultOptionValue(
      base::StringPiece option_name) const override;
  bool CheckOptionSupported(base::StringPiece name,
                            base::StringPiece value) const override;

  // Returns the file name for the PPD retrieved from the print server.
  base::FilePath GetPPD() const;

  // Returns the name of the printer as configured in CUPS
  std::string GetName() const;

  std::string GetMakeAndModel() const;

  // Returns true if the printer is currently reachable and working.
  bool IsAvailable() const;

  // Populates |basic_info| with the relevant information about the printer
  bool ToPrinterInfo(PrinterBasicInfo* basic_info) const;

  // Start a print job.  Writes the id of the started job to |job_id|.  |job_id|
  // is 0 if there is an error.  Check availability before using this operation.
  // Usage on an unavailable printer is undefined.
  ipp_status_t CreateJob(int* job_id,
                         base::StringPiece job_title,
                         const std::vector<cups_option_t>& options);

  // Add a document to a print job.  |job_id| must be non-zero and refer to a
  // job started with CreateJob.  |document_name| will be displayed in print
  // status.  |last_doc| should be true if this is the last document for this
  // print job.  |options| should be IPP key value pairs for the Send-Document
  // operation.
  bool StartDocument(int job_id,
                     base::StringPiece document_name,
                     bool last_doc,
                     const std::vector<cups_option_t>& options);

  // Add data to the current document started by StartDocument.  Calling this
  // without a started document will fail.
  bool StreamData(const std::vector<char>& buffer);

  // Finish the current document.  Another document can be added or the job can
  // be closed to complete printing.
  bool FinishDocument();

  // Close the job.  If the job is not closed, the documents will not be
  // printed.  |job_id| should match the id from CreateJob.
  ipp_status_t CloseJob(int job_id);

 private:
  // Lazily initialize dest info as it can require a network call
  bool InitializeDestInfo() const;

  // http connection owned by the CupsConnection which created this object
  http_t* const cups_http_;

  // information to identify a printer
  std::unique_ptr<cups_dest_t, DestinationDeleter> destination_;

  // opaque object containing printer attributes and options
  mutable std::unique_ptr<cups_dinfo_t, DestInfoDeleter> dest_info_;

  DISALLOW_COPY_AND_ASSIGN(CupsPrinter);
};

}  // namespace printing

#endif  // PRINTING_BACKEND_CUPS_PRINTER_H_