}
A:link, A:visited {
+ font-weight: normal;
text-decoration: none;
- font-weight: bold;
}
A:link:hover, A:visited:hover, A:active {
text-decoration: underline;
- font-weight: bold;
}
SUB, SUP {
<body>
<div class='body'>
<!--
- "$Id: api-ppd.header 7278 2008-01-31 01:23:09Z mike $"
+ "$Id: api-ppd.header 7616 2008-05-28 00:34:13Z mike $"
PPD API header for the Common UNIX Printing System (CUPS).
<th>See Also</th>
<td>Programming: <a href='api-overview.html' target='_top'>Introduction to CUPS Programming</a><br>
Programming: <a href='api-cups.html' target='_top'>CUPS API</a><br>
- Reference: <a href='spec-ppd.html' target='_top'>CUPS PPD Specification</a></td>
+ Specifications: <a href='spec-ppd.html' target='_top'>CUPS PPD Extensions</a></td>
</tr>
</tbody>
</table></div>
</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
<li><a href="#cupsMarkOptions" title="Mark command-line options in a PPD file.">cupsMarkOptions</a></li>
+<li><a href="#cupsResolveConflicts" title="Resolve conflicts in a marked PPD.">cupsResolveConflicts</a></li>
<li><a href="#ppdClose" title="Free all memory used by the PPD file.">ppdClose</a></li>
<li><a href="#ppdCollect" title="Collect all marked options that reside in the specified
section.">ppdCollect</a></li>
<li><a href="#ppdFindOption" title="Return a pointer to the specified option.">ppdFindOption</a></li>
<li><a href="#ppdFirstCustomParam" title="Return the first parameter for a custom option.">ppdFirstCustomParam</a></li>
<li><a href="#ppdFirstOption" title="Return the first option in the PPD file.">ppdFirstOption</a></li>
+<li><a href="#ppdInstallableConflict" title="Test whether an option choice conflicts with
+an installable option.">ppdInstallableConflict</a></li>
<li><a href="#ppdIsMarked" title="Check to see if an option is marked.">ppdIsMarked</a></li>
<li><a href="#ppdLastError" title="Return the status from the last ppdOpen*().">ppdLastError</a></li>
<li><a href="#ppdLocalize" title="Localize the PPD file to the current locale.">ppdLocalize</a></li>
+<li><a href="#ppdLocalizeAttr" title="Localize an attribute.">ppdLocalizeAttr</a></li>
<li><a href="#ppdLocalizeIPPReason" title="Get the localized version of a cupsIPPReason
attribute.">ppdLocalizeIPPReason</a></li>
<li><a href="#ppdLocalizeMarkerName" title="Get the localized version of a marker-names
attribute value.">ppdLocalizeMarkerName</a></li>
<li><a href="#ppdMarkDefaults" title="Mark all default options in the PPD file.">ppdMarkDefaults</a></li>
-<li><a href="#ppdMarkOption" title="Mark an option in a PPD file.">ppdMarkOption</a></li>
+<li><a href="#ppdMarkOption" title="Mark an option in a PPD file and return the number of
+conflicts.">ppdMarkOption</a></li>
<li><a href="#ppdNextCustomParam" title="Return the next parameter for a custom option.">ppdNextCustomParam</a></li>
<li><a href="#ppdNextOption" title="Return the next option in the PPD file.">ppdNextOption</a></li>
<li><a href="#ppdOpen" title="Read a PPD file into memory.">ppdOpen</a></li>
<li><a href="#ppdOpenFile" title="Read a PPD file into memory.">ppdOpenFile</a></li>
<li><a href="#ppdPageLength" title="Get the page length for the given size.">ppdPageLength</a></li>
<li><a href="#ppdPageSize" title="Get the page size record for the given size.">ppdPageSize</a></li>
+<li><a href="#ppdPageSizeLimits" title="Return the custom page size limits.">ppdPageSizeLimits</a></li>
<li><a href="#ppdPageWidth" title="Get the page width for the given size.">ppdPageWidth</a></li>
<li><a href="#ppdSetConformance" title="Set the conformance level for PPD files.">ppdSetConformance</a></li>
</ul>
<li><a href="#ppd_cplimit_t" title="Custom Parameter Limit ">ppd_cplimit_t</a></li>
<li><a href="#ppd_cptype_t" title="Custom Parameter Type ">ppd_cptype_t</a></li>
<li><a href="#ppd_cpvalue_t" title="Custom Parameter Value ">ppd_cpvalue_t</a></li>
+ <li><a href="#ppd_cs_t" title="Colorspaces">ppd_cs_t</a></li>
<li><a href="#ppd_emul_t" title="Emulators">ppd_emul_t</a></li>
<li><a href="#ppd_file_t" title="PPD File">ppd_file_t</a></li>
<li><a href="#ppd_group_t" title="Groups">ppd_group_t</a></li>
<li><a href="#ppd_profile_t" title="sRGB Color Profiles">ppd_profile_t</a></li>
<li><a href="#ppd_section_t" title="Order dependency sections">ppd_section_t</a></li>
<li><a href="#ppd_size_t" title="Page Sizes">ppd_size_t</a></li>
+ <li><a href="#ppd_status_t" title="Types and structures...">ppd_status_t</a></li>
<li><a href="#ppd_ui_t" title="UI Types">ppd_ui_t</a></li>
</ul></li>
<li><a href="#STRUCTURES">Structures</a><ul class="code">
</ul></li>
</ul>
<!--
- "$Id: api-ppd.shtml 7278 2008-01-31 01:23:09Z mike $"
+ "$Id: api-ppd.shtml 7616 2008-05-28 00:34:13Z mike $"
PPD API introduction for the Common UNIX Printing System (CUPS).
- Copyright 2007 by Apple Inc.
+ Copyright 2007-2008 by Apple Inc.
Copyright 1997-2006 by Easy Software Products, all rights reserved.
These coded instructions, statements, and computer programs are the
<p>The CUPS PPD API provides read-only access the data in PostScript Printer
Description ("PPD") files which are used for all printers with a driver. With
-it you can display printer options to users, mark option choices and check for
-conflicting choices, and output marked choices in PostScript output. The
-<a href="#ppd_file_t"><code>ppd_file_t</code></a> structure contains all of
-the information in a PPD file.</p>
+it you can obtain the data necessary to display printer options to users, mark
+option choices and check for conflicting choices, and output marked choices in
+PostScript output. The <a href="#ppd_file_t"><code>ppd_file_t</code></a>
+structure contains all of the information in a PPD file.</p>
+
+<blockquote><b>Note:</b>
+
+<p>The CUPS PPD API uses the terms "option" and "choice" instead of the Adobe
+terms "MainKeyword" and "OptionKeyword" to refer to specific printer options and
+features. CUPS also treats option ("MainKeyword") and choice ("OptionKeyword")
+values as case-insensitive strings, so option "InputSlot" and choice "Upper"
+are equivalent to "inputslot" and "upper", respectively.</p>
+</blockquote>
<h3><a name="LOADING">Loading a PPD File</a></h3>
<a href="#ppdClose">ppdClose</a>(ppd);
</pre>
+<p>Once closed, pointers to the <a href="#ppd_file_t"><code>ppd_file_t</code></a>
+structure and any data in it will no longer be valid.</p>
+
<h3><a name="OPTIONS_AND_GROUPS">Options and Groups</a></h3>
<p>PPD files support multiple options, which are stored in arrays of
have sub-groups, however CUPS currently ignores sub-groups because of past
abuses of this functionality.</p>
-<p>Options are selected by marking them using one of three functions. The
+<p>Option choices are selected by marking them using one of three functions. The
first is <a href="#ppdMarkDefaults"><code>ppdMarkDefaults</code></a> which
selects all of the default options in the PPD file:</p>
<p>The second is <a href="#ppdMarkOption"><code>ppdMarkOption</code></a>
which selects a single option choice in the PPD file. For example, the following
-code selects the manual feed media source:</p>
+code selects the upper paper tray:</p>
<pre class="example">
#include <cups/ppd.h>
<a href="#ppd_file_t">ppd_file_t</a> *ppd;
-<a href="#ppdMarkOption">ppdMarkOption</a>(ppd, "InputSlot", "ManualFeed");
+<a href="#ppdMarkOption">ppdMarkOption</a>(ppd, "InputSlot", "Upper");
</pre>
<p>The last function is
<a href="#ppdMarkDefaults">ppdMarkDefaults</a>(ppd);
<a href="#cupsMarkOptions">cupsMarkOptions</a>(ppd, num_options, options);
+cupsFreeOptions(num_options, options);
</pre>
<h3><a name="CONSTRAINTS">Constraints</a></h3>
<a href="#ppd_const_t"><code>ppd_const_t</code></a> structures which specify
the options and choices that conflict with each other. The
<a href="#ppdConflicts"><code>ppdConflicts</code></a> function tells you
-how many of the selected options are incompatible.</p>
+how many of the selected options are incompatible. Since constraints are
+normally specified in pairs, the returned value is typically an even number.</p>
<h3><a name="PAGE_SIZES">Page Sizes</a></h3>
<a href="#ppd_size_t">ppd_size_t</a> *size = <a href="#ppdPageSize">ppdPageSize</a>(ppd, "Custom.12.7x34.5cm");
</pre>
+<p>If the PPD does not support variable page sizes, the
+<a href="#ppdPageSize"><code>ppdPageSize</code></a> function will return
+<code>NULL</code>.</p>
+
<h3><a name="ATTRIBUTES">Attributes</a></h3>
<p>Every PPD file is composed of one or more attributes. Most of these
attributes are used to define groups, options, choices, and page sizes,
-however several informations attributes are available which you may need
-to access in your program or filter. Attributes normally look like one of
-the following examples in a PPD file:</p>
+however several informational attributes may be present which you can access
+in your program or filter. Attributes normally look like one of the following
+examples in a PPD file:</p>
<pre class="example">
*name: "value"
<dd class="description">Options</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 if conflicting</p>
+<p class="description">1 if conflicts exist, 0 otherwise</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function maps the IPP "finishings", "media", "mirror",
"multiple-document-handling", "output-bin", "printer-resolution", and
"sides" attributes to their corresponding PPD options and choices.</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsResolveConflicts">cupsResolveConflicts</a></h3>
+<p class="description">Resolve conflicts in a marked PPD.</p>
+<p class="code">
+int cupsResolveConflicts (<br>
+ <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br>
+ const char *option,<br>
+ const char *choice,<br>
+ int *num_options,<br>
+ cups_option_t **options<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>ppd</dt>
+<dd class="description">PPD file</dd>
+<dt>option</dt>
+<dd class="description">Newly selected option or <code>NULL</code> for none</dd>
+<dt>choice</dt>
+<dd class="description">Newly selected choice or <code>NULL</code> for none</dd>
+<dt>num_options</dt>
+<dd class="description">Number of additional selected options</dd>
+<dt>options</dt>
+<dd class="description">Additional selected options</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 on success, 0 on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function attempts to resolve any conflicts in a marked PPD, returning
+a list of option changes that are required to resolve them. On input,
+"num_options" and "options" contain any pending option changes that have
+not yet been marked, while "option" and "choice" contain the most recent
+selection which may or may not be in "num_options" or "options".<br>
+<br>
+On successful return, "num_options" and "options" are updated to contain
+"option" and "choice" along with any changes required to resolve conflicts
+specified in the PPD file and 1 is returned.<br>
+<br>
+If option conflicts cannot be resolved, "num_options" and "options" are not
+changed and 0 is returned.<br>
+<br>
+When resolving conflicts, <code>cupsResolveConflicts</code> does not consider
+changes to the current page size (<code>media</code>, <code>PageSize</code>, and
+<code>PageRegion</code>) or to the most recent option specified in "option".
+Thus, if the only way to resolve a conflict is to change the page size
+or the option the user most recently changed, <code>cupsResolveConflicts</code>
+will return 0 to indicate it was unable to resolve the conflicts.<br>
+<br>
+The <code>cupsResolveConflicts</code> function uses one of two sources of option
+constraint information. The preferred constraint information is defined by
+<code>cupsUIConstraints</code> and <code>cupsUIResolver</code> attributes - in this
+case, the PPD file provides constraint resolution actions.<br>
+<br>
+The backup constraint information is defined by the
+<code>UIConstraints</code> and <code>NonUIConstraints</code> attributes. These
+constraints are resolved algorithmically by first selecting the default
+choice for the conflicting option, then iterating over all possible choices
+until a non-conflicting option choice is found.
+
+</p>
<h3 class="function"><a name="ppdClose">ppdClose</a></h3>
<p class="description">Free all memory used by the PPD file.</p>
<p class="code">
<p class="description">Returns the text assocated with a status.</p>
<p class="code">
const char *ppdErrorString (<br>
- ppd_status_t status<br>
+ <a href="#ppd_status_t">ppd_status_t</a> status<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<h4 class="discussion">Discussion</h4>
<p class="discussion">Options are returned from all groups in ascending alphanumeric order.
+</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="ppdInstallableConflict">ppdInstallableConflict</a></h3>
+<p class="description">Test whether an option choice conflicts with
+an installable option.</p>
+<p class="code">
+int ppdInstallableConflict (<br>
+ <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br>
+ const char *option,<br>
+ const char *choice<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>ppd</dt>
+<dd class="description">PPD file</dd>
+<dt>option</dt>
+<dd class="description">Option</dd>
+<dt>choice</dt>
+<dd class="description">Choice</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 if conflicting, 0 if not conflicting</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function tests whether a particular option choice is available based
+on constraints against options in the "InstallableOptions" group.
+
</p>
<h3 class="function"><a name="ppdIsMarked">ppdIsMarked</a></h3>
<p class="description">Check to see if an option is marked.</p>
<h3 class="function"><span class="info"> CUPS 1.1.19 </span><a name="ppdLastError">ppdLastError</a></h3>
<p class="description">Return the status from the last ppdOpen*().</p>
<p class="code">
-ppd_status_t ppdLastError (<br>
+<a href="#ppd_status_t">ppd_status_t</a> ppdLastError (<br>
int *line<br>
);</p>
<h4 class="parameters">Parameters</h4>
localized string uses the UTF-8 character encoding.
</p>
+<h3 class="function"><a name="ppdLocalizeAttr">ppdLocalizeAttr</a></h3>
+<p class="description">Localize an attribute.</p>
+<p class="code">
+<a href="#ppd_attr_t">ppd_attr_t</a> *ppdLocalizeAttr (<br>
+ <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br>
+ const char *keyword,<br>
+ const char *spec<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>ppd</dt>
+<dd class="description">PPD file</dd>
+<dt>keyword</dt>
+<dd class="description">Main keyword</dd>
+<dt>spec</dt>
+<dd class="description">Option keyword or <code>NULL</code> for none</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Localized attribute or <code>NULL</code> if none exists</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function uses the current locale to find the localized attribute for
+the given main and option keywords. If no localized version of the
+attribute exists for the current locale, the unlocalized version is returned.</p>
<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="ppdLocalizeIPPReason">ppdLocalizeIPPReason</a></h3>
<p class="description">Get the localized version of a cupsIPPReason
attribute.</p>
<dd class="description">PPD file record</dd>
</dl>
<h3 class="function"><a name="ppdMarkOption">ppdMarkOption</a></h3>
-<p class="description">Mark an option in a PPD file.</p>
+<p class="description">Mark an option in a PPD file and return the number of
+conflicts.</p>
<p class="code">
int ppdMarkOption (<br>
<a href="#ppd_file_t">ppd_file_t</a> *ppd,<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Size record for page or NULL</p>
+<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="ppdPageSizeLimits">ppdPageSizeLimits</a></h3>
+<p class="description">Return the custom page size limits.</p>
+<p class="code">
+int ppdPageSizeLimits (<br>
+ <a href="#ppd_file_t">ppd_file_t</a> *ppd,<br>
+ <a href="#ppd_size_t">ppd_size_t</a> *minimum,<br>
+ <a href="#ppd_size_t">ppd_size_t</a> *maximum<br>
+);</p>
+<h4 class="parameters">Parameters</h4>
+<dl>
+<dt>ppd</dt>
+<dd class="description">PPD file record</dd>
+<dt>minimum</dt>
+<dd class="description">Minimum custom size</dd>
+<dt>maximum</dt>
+<dd class="description">Maximum custom size</dd>
+</dl>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">1 if custom sizes are supported, 0 otherwise</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function returns the minimum and maximum custom page sizes and printable
+areas based on the currently-marked (selected) options.<br>
+<br>
+If the specified PPD file does not support custom page sizes, both
+"minimum" and "maximum" are filled with zeroes.
+
+</p>
<h3 class="function"><a name="ppdPageWidth">ppdPageWidth</a></h3>
<p class="description">Get the page width for the given size.</p>
<p class="code">
<p class="code">
typedef union <a href="#ppd_cpvalue_u">ppd_cpvalue_u</a> ppd_cpvalue_t;
</p>
+<h3 class="typedef"><a name="ppd_cs_t">ppd_cs_t</a></h3>
+<p class="description">Colorspaces</p>
+<p class="code">
+typedef enum <a href="#ppd_cs_e">ppd_cs_e</a> ppd_cs_t;
+</p>
<h3 class="typedef"><a name="ppd_emul_t">ppd_emul_t</a></h3>
<p class="description">Emulators</p>
<p class="code">
<p class="code">
typedef struct <a href="#ppd_size_s">ppd_size_s</a> ppd_size_t;
</p>
+<h3 class="typedef"><a name="ppd_status_t">ppd_status_t</a></h3>
+<p class="description">Types and structures...</p>
+<p class="code">
+typedef enum <a href="#ppd_status_e">ppd_status_e</a> ppd_status_t;
+</p>
<h3 class="typedef"><a name="ppd_ui_t">ppd_ui_t</a></h3>
<p class="description">UI Types</p>
<p class="code">
<p class="code">struct ppd_file_s {<br>
int accurate_screens;<br>
int color_device;<br>
- ppd_cs_t colorspace;<br>
+ <a href="#ppd_cs_t">ppd_cs_t</a> colorspace;<br>
<a href="#ppd_const_t">ppd_const_t</a> *consts;<br>
int contone_only;<br>
float custom_margins[4];<br>
<dd class="description">Number of pre-loaded fonts</dd>
<dt>num_groups </dt>
<dd class="description">Number of UI groups</dd>
-<dt>num_profiles </dt>
-<dd class="description">Number of sRGB color profiles</dd>
+<dt>num_profiles <span class="info"> DEPRECATED </span></dt>
+<dd class="description">Number of sRGB color profiles </dd>
<dt>num_sizes </dt>
<dd class="description">Number of page sizes</dd>
<dt>patches </dt>
<dd class="description">PCFileName string </dd>
<dt>product </dt>
<dd class="description">Product name (from PS RIP/interpreter)</dd>
-<dt>profiles </dt>
-<dd class="description">sRGB color profiles</dd>
+<dt>profiles <span class="info"> DEPRECATED </span></dt>
+<dd class="description">sRGB color profiles </dd>
<dt>protocols <span class="info"> CUPS 1.1.19 </span></dt>
<dd class="description">Protocols (BCP, TBCP) string </dd>
<dt>shortnickname </dt>
projects / thirdparty / cups.git / blobdiff