2 PPD API introduction for CUPS.
4 Copyright 2007-2012 by Apple Inc.
5 Copyright 1997-2006 by Easy Software Products, all rights reserved.
7 These coded instructions, statements, and computer programs are the
8 property of Apple Inc. and are protected by Federal copyright
9 law. Distribution and use rights are outlined in the file "LICENSE.txt"
10 which should have been included with this file. If this file is
11 file is missing or damaged, see the license at "http://www.cups.org/".
14 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
16 <blockquote>The PPD API is deprecated starting in CUPS 1.6/macOS 10.8. Please use the new Job Ticket APIs in the <a href="api-cups.html">CUPS API</a> documentation. These functions will be removed in a future release of CUPS.</blockquote>
18 <p>The CUPS PPD API provides read-only access the data in PostScript Printer
19 Description ("PPD") files which are used for all printers with a driver. With
20 it you can obtain the data necessary to display printer options to users, mark
21 option choices and check for conflicting choices, and output marked choices in
22 PostScript output. The <a href="#ppd_file_t"><code>ppd_file_t</code></a>
23 structure contains all of the information in a PPD file.</p>
25 <blockquote><b>Note:</b>
27 <p>The CUPS PPD API uses the terms "option" and "choice" instead of the Adobe
28 terms "MainKeyword" and "OptionKeyword" to refer to specific printer options and
29 features. CUPS also treats option ("MainKeyword") and choice ("OptionKeyword")
30 values as case-insensitive strings, so option "InputSlot" and choice "Upper"
31 are equivalent to "inputslot" and "upper", respectively.</p>
34 <h3><a name="LOADING">Loading a PPD File</a></h3>
36 <p>The <a href="#ppdOpenFile"><code>ppdOpenFile</code></a> function "opens" a
37 PPD file and loads it into memory. For example, the following code opens the
38 current printer's PPD file in a CUPS filter:</p>
41 #include <cups/ppd.h>
43 <a href="#ppd_file_t">ppd_file_t</a> *ppd = <a href="#ppdOpenFile">ppdOpenFile</a>(getenv("PPD"));
46 <p>The return value is a pointer to a new
47 <a href="#ppd_file_t"><code>ppd_file_t</code></a> structure or <code>NULL</code>
48 if the PPD file does not exist or cannot be loaded. The
49 <a href="#ppdClose"><code>ppdClose</code></a> function frees the memory used
53 #include <cups/ppd.h>
55 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
57 <a href="#ppdClose">ppdClose</a>(ppd);
60 <p>Once closed, pointers to the <a href="#ppd_file_t"><code>ppd_file_t</code></a>
61 structure and any data in it will no longer be valid.</p>
63 <h3><a name="OPTIONS_AND_GROUPS">Options and Groups</a></h3>
65 <p>PPD files support multiple options, which are stored in arrays of
66 <a href="#ppd_option_t"><code>ppd_option_t</code></a> and
67 <a href="#ppd_choice_t"><code>ppd_choice_t</code></a> structures.</p>
69 <p>Each option in turn is associated with a group stored in a
70 <a href="#ppd_group_t"><code>ppd_group_t</code></a> structure. Groups can be
71 specified in the PPD file; if an option is not associated with a group
72 then it is put in an automatically-generated "General" group. Groups can also
73 have sub-groups, however CUPS currently ignores sub-groups because of past
74 abuses of this functionality.</p>
76 <p>Option choices are selected by marking them using one of three functions. The
77 first is <a href="#ppdMarkDefaults"><code>ppdMarkDefaults</code></a> which
78 selects all of the default options in the PPD file:</p>
81 #include <cups/ppd.h>
83 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
85 <a href="#ppdMarkDefaults">ppdMarkDefaults</a>(ppd);
88 <p>The second is <a href="#ppdMarkOption"><code>ppdMarkOption</code></a>
89 which selects a single option choice in the PPD file. For example, the following
90 code selects the upper paper tray:</p>
93 #include <cups/ppd.h>
95 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
97 <a href="#ppdMarkOption">ppdMarkOption</a>(ppd, "InputSlot", "Upper");
100 <p>The last function is
101 <a href="#cupsMarkOptions"><code>cupsMarkOptions</code></a> which selects
102 multiple option choices in the PPD file from an array of CUPS options, mapping
103 IPP attributes like "media" and "sides" to their corresponding PPD options. You
104 typically use this function in a print filter with
105 <code>cupsParseOptions</code> and
106 <a href="#ppdMarkDefaults"><code>ppdMarkDefaults</code></a> to select all of
107 the option choices needed for the job, for example:</p>
109 <pre class="example">
110 #include <cups/ppd.h>
112 <a href="#ppd_file_t">ppd_file_t</a> *ppd = <a href="#ppdOpenFile">ppdOpenFile</a>(getenv("PPD"));
113 cups_option_t *options = NULL;
114 int num_options = cupsParseOptions(argv[5], 0, &options);
116 <a href="#ppdMarkDefaults">ppdMarkDefaults</a>(ppd);
117 <a href="#cupsMarkOptions">cupsMarkOptions</a>(ppd, num_options, options);
118 cupsFreeOptions(num_options, options);
121 <h3><a name="CONSTRAINTS">Constraints</a></h3>
123 <p>PPD files support specification of conflict conditions, called
124 constraints, between different options. Constraints are stored in an array of
125 <a href="#ppd_const_t"><code>ppd_const_t</code></a> structures which specify
126 the options and choices that conflict with each other. The
127 <a href="#ppdConflicts"><code>ppdConflicts</code></a> function tells you
128 how many of the selected options are incompatible. Since constraints are
129 normally specified in pairs, the returned value is typically an even number.</p>
131 <h3><a name="PAGE_SIZES">Page Sizes</a></h3>
133 <p>Page sizes are special options which have physical dimensions and margins
134 associated with them. The size information is stored in
135 <a href="#ppd_size_t"><code>ppd_size_t</code></a> structures and is available
136 by looking up the named size with the
137 <a href="#ppdPageSize"><code>ppdPageSize</code></a> function. The page size and
138 margins are returned in units called points; there are 72 points per inch. If
139 you pass <code>NULL</code> for the size, the currently selected size is
142 <pre class="example">
143 #include <cups/ppd.h>
145 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
146 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, NULL);
149 <p>Besides the standard page sizes listed in a PPD file, some printers
150 support variable or custom page sizes. Custom page sizes are supported if the
151 <code>variables_sizes</code> member of the
152 <a href="#ppd_file_t"><code>ppd_file_t</code></a> structure is non-zero.
153 The <code>custom_min</code>, <code>custom_max</code>, and
154 <code>custom_margins</code> members of the
155 <a href="#ppd_file_t"><code>ppd_file_t</code></a> structure define the limits
156 of the printable area. To get the resulting media size, use a page size string
157 of the form "Custom.<I>width</I>x<I>length</I>", where "width" and "length" are
158 in points. Custom page size names can also be specified in inches
159 ("Custom.<i>width</i>x<i>height</i>in"), centimeters
160 ("Custom.<i>width</i>x<i>height</i>cm"), or millimeters
161 ("Custom.<i>width</i>x<i>height</i>mm"):</p>
163 <pre class="example">
164 #include <cups/ppd.h>
166 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
168 /* Get an 576x720 point custom page size */
169 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.576x720");
171 /* Get an 8x10 inch custom page size */
172 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.8x10in");
174 /* Get a 100x200 millimeter custom page size */
175 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.100x200mm");
177 /* Get a 12.7x34.5 centimeter custom page size */
178 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.12.7x34.5cm");
181 <p>If the PPD does not support variable page sizes, the
182 <a href="#ppdPageSize"><code>ppdPageSize</code></a> function will return
183 <code>NULL</code>.</p>
185 <h3><a name="ATTRIBUTES">Attributes</a></h3>
187 <p>Every PPD file is composed of one or more attributes. Most of these
188 attributes are used to define groups, options, choices, and page sizes,
189 however several informational attributes may be present which you can access
190 in your program or filter. Attributes normally look like one of the following
191 examples in a PPD file:</p>
193 <pre class="example">
196 *name spec/text: "value"
199 <p>The <a href="#ppdFindAttr"><code>ppdFindAttr</code></a> and
200 <a href="#ppdFindNextAttr"><code>ppdFindNextAttr</code></a> functions find the
201 first and next instances, respectively, of the named attribute with the given
202 "spec" string and return a <a href="#ppd_attr_t"><code>ppd_attr_t</code></a>
203 structure. If you provide a NULL specifier string, all attributes with the
204 given name will be returned. For example, the following code lists all of the
205 <code>Product</code> attributes in a PPD file:</p>
207 <pre class="example">
208 #include <cups/ppd.h>
210 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
211 <a href="#ppd_attr_t">ppd_attr_t</a> *attr;
213 for (attr = <a href="#ppdFindAttr">ppdFindAttr</a>(ppd, "Product", NULL);
215 attr = <a href="#ppdFindNextAttr">ppdFindNextAttr</a>(ppd, "Product", NULL))