cups/api-ppd.shtml

   1 <!--
   2   PPD API introduction for CUPS.
   3
   4   Copyright © 2007-2012 by Apple Inc.
   5   Copyright © 1997-2006 by Easy Software Products, all rights reserved.
   6
   7   Licensed under Apache License v2.0.  See the file "LICENSE" for more
   8   information.
   9 -->
  10
  11 <h2 class='title'><a name='OVERVIEW'>Overview</a></h2>
  12
  13 <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>
  14
  15 <p>The CUPS PPD API provides read-only access the data in PostScript Printer
  16 Description ("PPD") files which are used for all printers with a driver. With
  17 it you can obtain the data necessary to display printer options to users, mark
  18 option choices and check for conflicting choices, and output marked choices in
  19 PostScript output. The <a href="#ppd_file_t"><code>ppd_file_t</code></a>
  20 structure contains all of the information in a PPD file.</p>
  21
  22 <blockquote><b>Note:</b>
  23
  24 <p>The CUPS PPD API uses the terms "option" and "choice" instead of the Adobe
  25 terms "MainKeyword" and "OptionKeyword" to refer to specific printer options and
  26 features. CUPS also treats option ("MainKeyword") and choice ("OptionKeyword")
  27 values as case-insensitive strings, so option "InputSlot" and choice "Upper"
  28 are equivalent to "inputslot" and "upper", respectively.</p>
  29 </blockquote>
  30
  31 <h3><a name="LOADING">Loading a PPD File</a></h3>
  32
  33 <p>The <a href="#ppdOpenFile"><code>ppdOpenFile</code></a> function "opens" a
  34 PPD file and loads it into memory. For example, the following code opens the
  35 current printer's PPD file in a CUPS filter:</p>
  36
  37 <pre class="example">
  38 #include &lt;cups/ppd.h&gt;
  39
  40 <a href="#ppd_file_t">ppd_file_t</a> *ppd = <a href="#ppdOpenFile">ppdOpenFile</a>(getenv("PPD"));
  41 </pre>
  42
  43 <p>The return value is a pointer to a new
  44 <a href="#ppd_file_t"><code>ppd_file_t</code></a> structure or <code>NULL</code>
  45 if the PPD file does not exist or cannot be loaded. The
  46 <a href="#ppdClose"><code>ppdClose</code></a> function frees the memory used
  47 by the structure:</p>
  48
  49 <pre class="example">
  50 #include &lt;cups/ppd.h&gt;
  51
  52 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
  53
  54 <a href="#ppdClose">ppdClose</a>(ppd);
  55 </pre>
  56
  57 <p>Once closed, pointers to the <a href="#ppd_file_t"><code>ppd_file_t</code></a>
  58 structure and any data in it will no longer be valid.</p>
  59
  60 <h3><a name="OPTIONS_AND_GROUPS">Options and Groups</a></h3>
  61
  62 <p>PPD files support multiple options, which are stored in arrays of
  63 <a href="#ppd_option_t"><code>ppd_option_t</code></a> and
  64 <a href="#ppd_choice_t"><code>ppd_choice_t</code></a> structures.</p>
  65
  66 <p>Each option in turn is associated with a group stored in a
  67 <a href="#ppd_group_t"><code>ppd_group_t</code></a> structure. Groups can be
  68 specified in the PPD file; if an option is not associated with a group
  69 then it is put in an automatically-generated "General" group. Groups can also
  70 have sub-groups, however CUPS currently ignores sub-groups because of past
  71 abuses of this functionality.</p>
  72
  73 <p>Option choices are selected by marking them using one of three functions. The
  74 first is <a href="#ppdMarkDefaults"><code>ppdMarkDefaults</code></a> which
  75 selects all of the default options in the PPD file:</p>
  76
  77 <pre class="example">
  78 #include &lt;cups/ppd.h&gt;
  79
  80 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
  81
  82 <a href="#ppdMarkDefaults">ppdMarkDefaults</a>(ppd);
  83 </pre>
  84
  85 <p>The second is <a href="#ppdMarkOption"><code>ppdMarkOption</code></a>
  86 which selects a single option choice in the PPD file. For example, the following
  87 code selects the upper paper tray:</p>
  88
  89 <pre class="example">
  90 #include &lt;cups/ppd.h&gt;
  91
  92 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
  93
  94 <a href="#ppdMarkOption">ppdMarkOption</a>(ppd, "InputSlot", "Upper");
  95 </pre>
  96
  97 <p>The last function is
  98 <a href="#cupsMarkOptions"><code>cupsMarkOptions</code></a> which selects
  99 multiple option choices in the PPD file from an array of CUPS options, mapping
 100 IPP attributes like "media" and "sides" to their corresponding PPD options. You
 101 typically use this function in a print filter with
 102 <code>cupsParseOptions</code> and
 103 <a href="#ppdMarkDefaults"><code>ppdMarkDefaults</code></a> to select all of
 104 the option choices needed for the job, for example:</p>
 105
 106 <pre class="example">
 107 #include &lt;cups/ppd.h&gt;
 108
 109 <a href="#ppd_file_t">ppd_file_t</a> *ppd = <a href="#ppdOpenFile">ppdOpenFile</a>(getenv("PPD"));
 110 cups_option_t *options = NULL;
 111 int num_options = cupsParseOptions(argv[5], 0, &amp;options);
 112
 113 <a href="#ppdMarkDefaults">ppdMarkDefaults</a>(ppd);
 114 <a href="#cupsMarkOptions">cupsMarkOptions</a>(ppd, num_options, options);
 115 cupsFreeOptions(num_options, options);
 116 </pre>
 117
 118 <h3><a name="CONSTRAINTS">Constraints</a></h3>
 119
 120 <p>PPD files support specification of conflict conditions, called
 121 constraints, between different options. Constraints are stored in an array of
 122 <a href="#ppd_const_t"><code>ppd_const_t</code></a> structures which specify
 123 the options and choices that conflict with each other. The
 124 <a href="#ppdConflicts"><code>ppdConflicts</code></a> function tells you
 125 how many of the selected options are incompatible. Since constraints are
 126 normally specified in pairs, the returned value is typically an even number.</p>
 127
 128 <h3><a name="PAGE_SIZES">Page Sizes</a></h3>
 129
 130 <p>Page sizes are special options which have physical dimensions and margins
 131 associated with them. The size information is stored in
 132 <a href="#ppd_size_t"><code>ppd_size_t</code></a> structures and is available
 133 by looking up the named size with the
 134 <a href="#ppdPageSize"><code>ppdPageSize</code></a> function. The page size and
 135 margins are returned in units called points; there are 72 points per inch. If
 136 you pass <code>NULL</code> for the size, the currently selected size is
 137 returned:</p>
 138
 139 <pre class="example">
 140 #include &lt;cups/ppd.h&gt;
 141
 142 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
 143 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, NULL);
 144 </pre>
 145
 146 <p>Besides the standard page sizes listed in a PPD file, some printers
 147 support variable or custom page sizes. Custom page sizes are supported if the
 148 <code>variables_sizes</code> member of the
 149 <a href="#ppd_file_t"><code>ppd_file_t</code></a> structure is non-zero.
 150 The <code>custom_min</code>, <code>custom_max</code>, and
 151 <code>custom_margins</code> members of the
 152 <a href="#ppd_file_t"><code>ppd_file_t</code></a> structure define the limits
 153 of the printable area. To get the resulting media size, use a page size string
 154 of the form "Custom.<I>width</I>x<I>length</I>", where "width" and "length" are
 155 in points. Custom page size names can also be specified in inches
 156 ("Custom.<i>width</i>x<i>height</i>in"), centimeters
 157 ("Custom.<i>width</i>x<i>height</i>cm"), or millimeters
 158 ("Custom.<i>width</i>x<i>height</i>mm"):</p>
 159
 160 <pre class="example">
 161 #include &lt;cups/ppd.h&gt;
 162
 163 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
 164
 165 /* Get an 576x720 point custom page size */
 166 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.576x720");
 167
 168 /* Get an 8x10 inch custom page size */
 169 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.8x10in");
 170
 171 /* Get a 100x200 millimeter custom page size */
 172 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.100x200mm");
 173
 174 /* Get a 12.7x34.5 centimeter custom page size */
 175 <a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.12.7x34.5cm");
 176 </pre>
 177
 178 <p>If the PPD does not support variable page sizes, the
 179 <a href="#ppdPageSize"><code>ppdPageSize</code></a> function will return
 180 <code>NULL</code>.</p>
 181
 182 <h3><a name="ATTRIBUTES">Attributes</a></h3>
 183
 184 <p>Every PPD file is composed of one or more attributes. Most of these
 185 attributes are used to define groups, options, choices, and page sizes,
 186 however several informational attributes may be present which you can access
 187 in your program or filter. Attributes normally look like one of the following
 188 examples in a PPD file:</p>
 189
 190 <pre class="example">
 191 *name: "value"
 192 *name spec: "value"
 193 *name spec/text: "value"
 194 </pre>
 195
 196 <p>The <a href="#ppdFindAttr"><code>ppdFindAttr</code></a> and
 197 <a href="#ppdFindNextAttr"><code>ppdFindNextAttr</code></a> functions find the
 198 first and next instances, respectively, of the named attribute with the given
 199 "spec" string and return a <a href="#ppd_attr_t"><code>ppd_attr_t</code></a>
 200 structure. If you provide a NULL specifier string, all attributes with the
 201 given name will be returned. For example, the following code lists all of the
 202 <code>Product</code> attributes in a PPD file:</p>
 203
 204 <pre class="example">
 205 #include &lt;cups/ppd.h&gt;
 206
 207 <a href="#ppd_file_t">ppd_file_t</a> *ppd;
 208 <a href="#ppd_attr_t">ppd_attr_t</a> *attr;
 209
 210 for (attr = <a href="#ppdFindAttr">ppdFindAttr</a>(ppd, "Product", NULL);
 211      attr != NULL;
 212      attr = <a href="#ppdFindNextAttr">ppdFindNextAttr</a>(ppd, "Product", NULL))
 213   puts(attr->value);
 214 </pre>