1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2/* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6/* Interface to the Service for gwetting the Global PrintSettings object
7   or a unique PrintSettings object
8*/
9
10#include "nsISupports.idl"
11
12interface nsIPrintSettings;
13interface nsIWebBrowserPrint;
14
15%{ C++
16namespace mozilla {
17namespace embedding {
18  class PrintData;
19}
20}
21%}
22
23/**
24 * Native types
25 */
26[ref] native PrintDataRef(const mozilla::embedding::PrintData);
27[ptr] native PrintDataPtr(mozilla::embedding::PrintData);
28
29[scriptable, uuid(841387C8-72E6-484b-9296-BF6EEA80D58A)]
30interface nsIPrintSettingsService : nsISupports
31{
32  /**
33   * Returns the default print settings as used for printing.
34   */
35  [noscript] readonly attribute nsIPrintSettings defaultPrintSettingsForPrinting;
36
37  /**
38   * Returns a new, unique PrintSettings object each time.
39   *
40   * Initializes the newPrintSettings from the unprefixed printer
41   * (Note: this may not happen if there is an OS specific implementation.)
42   *
43   * XXX This should really be a function called `createPrintSettings()`.
44   */
45  readonly attribute nsIPrintSettings newPrintSettings;
46
47  /**
48   * The name of the last printer used. Note that this may not be set, or may
49   * no longer be a valid printer. The caller is responsible for checking and
50   * falling back to some other printer (such as the system default printer).
51   *
52   * XXX: make it [infallible] when AString supports that (bug 1491187).
53   */
54  readonly attribute AString lastUsedPrinterName;
55
56  /**
57   * Initializes certain settings from the native printer into the PrintSettings
58   * if aPrinterName is null then it uses the default printer name if it can
59   * These settings include, but are not limited to:
60   *   Page Orientation
61   *   Page Size
62   *   Number of Copies
63   */
64  void initPrintSettingsFromPrinter(in AString aPrinterName,
65                                    in nsIPrintSettings aPrintSettings);
66
67  /**
68   * Reads PrintSettings values from Prefs,
69   * the values to be read are indicated by the "flags" arg.
70   *
71   * aPrintSettings should be initialized with the name of a printer. First
72   * it reads in the PrintSettings from the last print job. Then it uses the
73   * PrinterName in the PrinterSettings to read any settings that were saved
74   * just for that printer.
75   *
76   * aPS - PrintSettings to have its settings read
77   * aUsePrinterNamePrefix - indicates whether to use the printer name as a prefix
78   * aFlags - indicates which prefs to read, see nsIPrintSettings.idl for the
79   *          const values.
80   *
81   * Items not read:
82   *   startPageRange, endPageRange, scaling, printRange, title
83   *   docURL, isCancelled,
84   *   printSilent, shrinkToFit, numCopies,
85   *   printerName
86   *
87   */
88  void initPrintSettingsFromPrefs(in nsIPrintSettings aPrintSettings, in boolean aUsePrinterNamePrefix, in unsigned long aFlags);
89
90  /**
91   * Writes PrintSettings values to Prefs,
92   * the values to be written are indicated by the "flags" arg.
93   *
94   * If there is no PrinterName in the PrinterSettings
95   * the values are saved as the "generic" values not associated with any printer.
96   * If a PrinterName is there, then it saves the items qualified for that Printer
97   *
98   * aPS - PrintSettings to have its settings saved
99   * aUsePrinterNamePrefix - indicates whether to use the printer name as a prefix
100   * aFlags - indicates which prefs to save, see nsIPrintSettings.idl for the const values.
101   *
102   * Items not written:
103   *   startPageRange, endPageRange, scaling, printRange, title
104   *   docURL, isCancelled,
105   *   printSilent, shrinkToFit, numCopies
106   *
107   */
108  void savePrintSettingsToPrefs(in nsIPrintSettings aPrintSettings, in boolean aUsePrinterNamePrefix, in unsigned long aFlags);
109
110  /**
111   * Given some nsIPrintSettings,
112   * populates a PrintData representing them which can be sent over IPC. Values
113   * are only ever read from aSettings and aWBP.
114   *
115   * @param aSettings
116   *        An nsIPrintSettings for a print job.
117   * @param data
118   *        Pointer to a pre-existing PrintData to populate.
119   *
120   * @return nsresult
121   */
122  [noscript]
123  void SerializeToPrintData(in nsIPrintSettings aPrintSettings,
124                            in PrintDataPtr data);
125
126  /**
127   * This function is the opposite of SerializeToPrintData, in that it takes
128   * a PrintData, and populates a pre-existing nsIPrintSettings with the data
129   * from PrintData.
130   *
131   * @param PrintData
132   *        Printing information sent through IPC.
133   * @param settings
134   *        A pre-existing nsIPrintSettings to populate with the PrintData.
135   *
136   * @return nsresult
137   */
138  [noscript]
139  void DeserializeToPrintSettings(in PrintDataRef data,
140                                  in nsIPrintSettings aPrintSettings);
141
142};
143
144%{C++
145// {841387C8-72E6-484b-9296-BF6EEA80D58A}
146#define NS_PRINTSETTINGSSERVICE_IID \
147 {0x841387c8, 0x72e6, 0x484b, { 0x92, 0x96, 0xbf, 0x6e, 0xea, 0x80, 0xd5, 0x8a}}
148%}
149