/*
* "$Id: help-index.c 6649 2007-07-11 21:46:42Z mike $"
*
- * On-line help index routines for the Common UNIX Printing System (CUPS).
+ * Online help index routines for the Common UNIX Printing System (CUPS).
*
* Copyright 2007-2008 by Apple Inc.
* Copyright 1997-2007 by Easy Software Products.
/*
* "$Id: help-index.h 6649 2007-07-11 21:46:42Z mike $"
*
- * On-line help index definitions for the Common UNIX Printing System (CUPS).
+ * Online help index definitions for the Common UNIX Printing System (CUPS).
*
* Copyright 2007 by Apple Inc.
* Copyright 1997-2007 by Easy Software Products.
</pre>
<p>The hash function (type
-<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) returns a
+<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) should return a
number from 0 to (hash_size-1) that (hopefully) uniquely identifies the
element and is called whenever you look up an element in the array with
<a href='#cupsArrayFind'><code>cupsArrayFind</code></a>. The hash size is
The first function adds an element to the array, adding the new element
after any elements that have the same order, while the second inserts the
element before others with the same order. For unsorted arrays,
-<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the elemnt to
+<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the element to
the end of the array while
<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> inserts the
element at the beginning of the array. For example, the following code
<dl>
<dt><a href='#cupsArrayFind'><code>cupsArrayFind</code></a></dt>
- <dd>Returns the first matching element .</dd>
+ <dd>Returns the first matching element.</dd>
<dt><a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a></dt>
<dd>Returns the first element in the array.</dd>
<dt><a href='#cupsArrayIndex'><code>cupsArrayIndex</code></a></dt>
- <dd>Returns the Nth element in the array.</dd>
+ <dd>Returns the Nth element in the array, starting at 0.</dd>
<dt><a href='#cupsArrayLast'><code>cupsArrayLast</code></a></dt>
<dd>Returns the last element in the array.</dd>
<dt><a href='#cupsArrayNext'><code>cupsArrayNext</code></a></dt>
<tr>
<th>Headers</th>
<th>cups/backend.h<br>
- cups/sidechannel.h<br>
- cups/snmp.h</th>
+ cups/sidechannel.h</th>
</tr>
</thead>
<tbody>
<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>
Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
- Programming: <a href='api-raster.html' target='_top'>Raster API</a></td>
+ Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
+ Specifications: <a href='spec-design' target='_top'>CUPS Design Description</a></td>
</tr>
</tbody>
</table></div>
<h2 class='title'><a name="OVERVIEW">Overview</a></h2>
-<p>Filters, printer drivers, port monitors, and backends use a common interface
-for processing print jobs and communicating status information to the scheduler.
-Each filter is run with a standard set of command-line arguments:<p>
+<p>Filters (which include printer drivers and port monitors) and backends
+are used to convert job files to a printable format and send that data to the
+printer itself. All of these programs use a common interface for processing
+print jobs and communicating status information to the scheduler. Each is run
+with a standard set of command-line arguments:<p>
<dl class="code">
<dd>The options that were provided when the job was submitted</dd>
<dt>argv[6]</dt>
- <dd>The file to print (first filter only)</dd>
+ <dd>The file to print (first program only)</dd>
</dl>
<p>The scheduler runs one or more of these programs to print any given job. The
<h3><a name="ENVIRONMENT">Environment Variables</a></h3>
-<p>The following environment variables are defined by the printing system:</p>
+<p>The following environment variables are defined by the printing system
+when running print filters and backends:</p>
<dl class="code">
application/postscript).</dd>
<dt>CUPS_CACHEDIR</dt>
- <dd>The directory where cache files can be stored.</dd>
+ <dd>The directory where cache files can be stored. Cache files can be
+ used to retain information between jobs or files in a job.</dd>
<dt>CUPS_DATADIR</dt>
- <dd>The directory where data files can be found.</dd>
+ <dd>The directory where (read-only) CUPS data files can be found.</dd>
<dt>CUPS_SERVERROOT</dt>
<dd>The root directory of the server.</dd>
file for this printer.</dd>
<dt>PRINTER</dt>
- <dd>The name of the printer.</dd>
+ <dd>The queue name of the class or printer.</dd>
<dt>RIP_CACHE</dt>
<dd>The recommended amount of memory to use for Raster Image
Processors (RIPs).</dd>
+ <dt>TMPDIR</dt>
+ <dd>The directory where temporary files should be created.</dd>
+
</dl>
<h3><a name="MESSAGES">Communicating with the Scheduler</a></h3>
-<p>Filters and backends communicate wih the scheduler by writing messages
-to the standard error file. For example, the following code sets the current
-printer state message to "Printing page 5":</p>
+<p>Filters and backends communicate with the scheduler by writing messages
+to the standard error file. The scheduler reads messages from all filters in
+a job and processes the message based on its prefix. For example, the following
+code sets the current printer state message to "Printing page 5":</p>
<pre class="example">
int page = 5;
to set the <code>marker-colors</code>, <code>marker-levels</code>,
<code>marker-names</code>, <code>marker-types</code>,
<code>printer-alert</code>, and <code>printer-alert-description</code>
- printer attributes.</dd>
+ printer attributes. Standard <code>marker-types</code> values are
+ listed in <a href='#TABLE1'>Table 1</a>.</dd>
<dt>CRIT: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
<dt>ERROR: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
- message to the current error log file using the "error" log level.</dd>
+ message to the current error log file using the "error" log level.
+ Use "ERROR:" messages for non-persistent processing errors.</dd>
<dt>INFO: message</dt>
<dd>Sets the printer-state-message attribute. If the current log level
<dt>STATE: + printer-state-reason [printer-state-reason ...]</dt>
<dt>STATE: - printer-state-reason [printer-state-reason ...]</dt>
<dd>Sets, adds, or removes printer-state-reason keywords to the
- current queue. Typically this is used to indicate media, ink, and
- toner conditions on a printer.</dd>
+ current queue. Typically this is used to indicate persistent media,
+ ink, toner, and configuration conditions or errors on a printer.
+ <a href='#TABLE2'>Table 2</a> lists the standard state keywords -
+ use vendor-prefixed ("com.acme.foo") keywords for custom states.</dd>
<dt>WARNING: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
<p>Messages without one of these prefixes are treated as if they began with
the "DEBUG:" prefix string.</p>
+
+<div class='table'><table width='80%' summary='Table 1: Standard marker-types Values'>
+<caption>Table 1: <a name='TABLE1'>Standard marker-types Values</a></caption>
+<thead>
+<tr>
+ <th>marker-type</th>
+ <th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <td>developer</td>
+ <td>Developer unit</td>
+</tr>
+<tr>
+ <td>fuser</td>
+ <td>Fuser unit</td>
+</tr>
+<tr>
+ <td>fuserCleaningPad</td>
+ <td>Fuser cleaning pad</td>
+</tr>
+<tr>
+ <td>fuserOil</td>
+ <td>Fuser oil</td>
+</tr>
+<tr>
+ <td>ink</td>
+ <td>Ink supply</td>
+</tr>
+<tr>
+ <td>opc</td>
+ <td>Photo conductor</td>
+</tr>
+<tr>
+ <td>solidWax</td>
+ <td>Wax supply</td>
+</tr>
+<tr>
+ <td>staples</td>
+ <td>Staple supply</td>
+</tr>
+<tr>
+ <td>toner</td>
+ <td>Toner supply</td>
+</tr>
+<tr>
+ <td>transferUnit</td>
+ <td>Transfer unit</td>
+</tr>
+<tr>
+ <td>wasteInk</td>
+ <td>Waste ink tank</td>
+</tr>
+<tr>
+ <td>wasteToner</td>
+ <td>Waste toner tank</td>
+</tr>
+<tr>
+ <td>wasteWax</td>
+ <td>Waste wax tank</td>
+</tr>
+</tbody>
+</table></div>
+
+<br>
+
+<div class='table'><table width='80%' summary='Table 2: Standard State Keywords'>
+<caption>Table 2: <a name='TABLE2'>Standard State Keywords</a></caption>
+<thead>
+<tr>
+ <th>Keyword</th>
+ <th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <td>connecting-to-device</td>
+ <td>Connecting to printer but not printing yet</td>
+</tr>
+<tr>
+ <td>cover-open</td>
+ <td>A cover is open on the printer</td>
+</tr>
+<tr>
+ <td>input-tray-missing</td>
+ <td>An input tray is missing from the printer</td>
+</tr>
+<tr>
+ <td>marker-supply-empty</td>
+ <td>Out of ink</td>
+</tr>
+<tr>
+ <td>marker-supply-low</td>
+ <td>Low on ink</td>
+</tr>
+<tr>
+ <td>marker-waste-almost-full</td>
+ <td>Waste tank almost full</td>
+</tr>
+<tr>
+ <td>marker-waste-full</td>
+ <td>Waste tank full</td>
+</tr>
+<tr>
+ <td>media-empty</td>
+ <td>Out of media</td>
+</tr>
+<tr>
+ <td>media-jam</td>
+ <td>Media is jammed in the printer</td>
+</tr>
+<tr>
+ <td>media-low</td>
+ <td>Low on media</td>
+</tr>
+<tr>
+ <td>paused</td>
+ <td>Stop the printer</td>
+</tr>
+<tr>
+ <td>timed-out</td>
+ <td>Unable to connect to printer</td>
+</tr>
+<tr>
+ <td>toner-empty</td>
+ <td>Out of toner</td>
+</tr>
+<tr>
+ <td>toner-low</td>
+ <td>Low on toner</td>
+</tr>
+</tbody>
+</table></div>
+
<h3><a name="COMMUNICATING_BACKEND">Communicating with the Backend</a></h3>
<p>Filters can communicate with the backend via the
bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
</pre>
-The
+<p>Filters can also use <code>select()</code> or <code>poll()</code> on the
+back-channel file descriptor (3 or <code>CUPS_BC_FD</code>) to read data only
+when it is available.</p>
+
+<p>The
<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a>
function allows you to get out-of-band status information and do synchronization
with the device. For example, the following code gets the current IEEE-1284
int datalen;
<a href="#cups_sc_status_t">cups_sc_status_t</a> status;
-/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for nul-termination... */
+/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for
+ nul-termination... */
datalen = sizeof(data) - 1;
/* Get the IEEE-1284 device ID, waiting for up to 1 second */
char buffer[8192];
ssize_t bytes;
+/* Obtain data from printer/device */
+...
+
/* Use a timeout of 1.0 seconds to give filters a chance to read */
cupsBackChannelWrite(buffer, bytes, 1.0);
</pre>
<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>
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"
* 'cupsArrayAdd()' - Add an element to the array.
*
* When adding an element to a sorted array, non-unique elements are
- * appended at the end of the run. For unsorted arrays, the element
- * is inserted at the end of the array.
+ * appended at the end of the run of identical elements. For unsorted arrays,
+ * the element is appended to the end of the array.
*
* @since CUPS 1.2@
*/
/*
* 'cupsArrayClear()' - Clear the array.
*
+ * This function is equivalent to removing all elements in the array.
+ * The caller is responsible for freeing the memory used by the
+ * elements themselves.
+ *
* @since CUPS 1.2@
*/
/*
* 'cupsArrayCurrent()' - Return the current element in the array.
*
+ * The current element is undefined until you call @link cupsArrayFind@,
+ * @link cupsArrayFirst@, or @link cupsArrayIndex@, or @link cupsArrayLast@.
+ *
* @since CUPS 1.2@
*/
/*
* 'cupsArrayDelete()' - Free all memory used by the array.
*
+ * The caller is responsible for freeing the memory used by the
+ * elements themselves.
+ *
* @since CUPS 1.2@
*/
* @since CUPS 1.2@
*/
-void * /* O - First element or @code NULL@ */
+void * /* O - First element or @code NULL@ if the array is empty */
cupsArrayFirst(cups_array_t *a) /* I - Array */
{
/*
/*
* 'cupsArrayGetIndex()' - Get the index of the current element.
*
+ * The current element is undefined until you call @link cupsArrayFind@,
+ * @link cupsArrayFirst@, or @link cupsArrayIndex@, or @link cupsArrayLast@.
+ *
* @since CUPS 1.3@
*/
-int /* O - Index of the current element */
+int /* O - Index of the current element, starting at 0 */
cupsArrayGetIndex(cups_array_t *a) /* I - Array */
{
if (!a)
* @since CUPS 1.3@
*/
-int /* O - Index of the last inserted element */
+int /* O - Index of the last inserted element, starting at 0 */
cupsArrayGetInsert(cups_array_t *a) /* I - Array */
{
if (!a)
* 'cupsArrayInsert()' - Insert an element in the array.
*
* When inserting an element in a sorted array, non-unique elements are
- * inserted at the beginning of the run. For unsorted arrays, the element
- * is inserted at the beginning of the array.
+ * inserted at the beginning of the run of identical elements. For unsorted
+ * arrays, the element is inserted at the beginning of the array.
*
* @since CUPS 1.2@
*/
* @since CUPS 1.2@
*/
-void * /* O - Last element or @code NULL@ */
+void * /* O - Last element or @code NULL@ if the array is empty */
cupsArrayLast(cups_array_t *a) /* I - Array */
{
/*
/*
* 'cupsArrayNew()' - Create a new array.
*
+ * The comparison function ("f") is used to create a sorted array. The function
+ * receives pointers to two elements and the user data pointer ("d") - the user
+ * data pointer argument can safely be omitted when not required so functions
+ * like @code strcmp@ can be used for sorted string arrays.
+ *
* @since CUPS 1.2@
*/
cups_array_t * /* O - Array */
-cupsArrayNew(cups_array_func_t f, /* I - Comparison function */
- void *d) /* I - User data */
+cupsArrayNew(cups_array_func_t f, /* I - Comparison function or @code NULL@ for an unsorted array */
+ void *d) /* I - User data pointer or @code NULL@ */
{
return (cupsArrayNew2(f, d, 0, 0));
}
/*
* 'cupsArrayNew2()' - Create a new array with hash.
*
+ * The comparison function ("f") is used to create a sorted array. The function
+ * receives pointers to two elements and the user data pointer ("d") - the user
+ * data pointer argument can safely be omitted when not required so functions
+ * like @code strcmp@ can be used for sorted string arrays.
+ *
+ * The hash function ("h") is used to implement cached lookups with the
+ * specified hash size ("hsize").
+ *
* @since CUPS 1.3@
*/
cups_array_t * /* O - Array */
-cupsArrayNew2(cups_array_func_t f, /* I - Comparison function */
- void *d, /* I - User data */
- cups_ahash_func_t h, /* I - Hash function*/
- int hsize) /* I - Hash size */
+cupsArrayNew2(cups_array_func_t f, /* I - Comparison function or @code NULL@ for an unsorted array */
+ void *d, /* I - User data or @code NULL@ */
+ cups_ahash_func_t h, /* I - Hash function or @code NULL@ for unhashed lookups */
+ int hsize) /* I - Hash size (>= 0) */
{
cups_array_t *a; /* Array */
/*
* 'cupsArrayNext()' - Get the next element in the array.
*
+ * This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)".
+ *
+ * The next element is undefined until you call @link cupsArrayFind@,
+ * @link cupsArrayFirst@, or @link cupsArrayIndex@, or @link cupsArrayLast@
+ * to set the current element.
+ *
* @since CUPS 1.2@
*/
/*
* 'cupsArrayPrev()' - Get the previous element in the array.
*
+ * This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)".
+ *
+ * The previous element is undefined until you call @link cupsArrayFind@,
+ * @link cupsArrayFirst@, or @link cupsArrayIndex@, or @link cupsArrayLast@
+ * to set the current element.
+ *
* @since CUPS 1.2@
*/
/*
* 'cupsArrayRemove()' - Remove an element from the array.
*
+ * If more than one element matches "e", only the first matching element is
+ * removed.
+ *
+ * The caller is responsible for freeing the memory used by the
+ * removed element.
+ *
* @since CUPS 1.2@
*/
/*
- * 'cupsArrayRestore()' - Reset the current element to the last cupsArraySave.
+ * 'cupsArrayRestore()' - Reset the current element to the last @link cupsArraySave@.
*
* @since CUPS 1.2@
*/
/*
- * 'cupsArraySave()' - Mark the current element for a later cupsArrayRestore.
+ * 'cupsArraySave()' - Mark the current element for a later @link cupsArrayRestore@.
+ *
+ * The current element is undefined until you call @link cupsArrayFind@,
+ * @link cupsArrayFirst@, or @link cupsArrayIndex@, or @link cupsArrayLast@
+ * to set the current element.
*
* The save/restore stack is guaranteed to be at least 32 elements deep.
*
*
* Backchannel functions for the Common UNIX Printing System (CUPS).
*
- * Copyright 2007 by Apple Inc.
+ * Copyright 2007-2008 by Apple Inc.
* Copyright 1997-2007 by Easy Software Products.
*
* These coded instructions, statements, and computer programs are the
/*
* 'cupsBackChannelRead()' - Read data from the backchannel.
*
- * Reads up to "bytes" bytes from the backchannel. The "timeout"
- * parameter controls how many seconds to wait for the data - use
- * 0.0 to return immediately if there is no data, -1.0 to wait
- * for data indefinitely.
+ * Reads up to "bytes" bytes from the backchannel/backend. The "timeout"
+ * parameter controls how many seconds to wait for the data - use 0.0 to
+ * return immediately if there is no data, -1.0 to wait for data indefinitely.
*
* @since CUPS 1.2@
*/
ssize_t /* O - Bytes read or -1 on error */
-cupsBackChannelRead(char *buffer, /* I - Buffer to read */
+cupsBackChannelRead(char *buffer, /* I - Buffer to read into */
size_t bytes, /* I - Bytes to read */
- double timeout) /* I - Timeout in seconds */
+ double timeout) /* I - Timeout in seconds, typically 0.0 to poll */
{
fd_set input; /* Input set */
struct timeval tval; /* Timeout value */
/*
* 'cupsBackChannelWrite()' - Write data to the backchannel.
*
- * Writes "bytes" bytes to the backchannel. The "timeout" parameter
+ * Writes "bytes" bytes to the backchannel/filter. The "timeout" parameter
* controls how many seconds to wait for the data to be written - use
* 0.0 to return immediately if the data cannot be written, -1.0 to wait
* indefinitely.
cupsBackChannelWrite(
const char *buffer, /* I - Buffer to write */
size_t bytes, /* I - Bytes to write */
- double timeout) /* I - Timeout in seconds */
+ double timeout) /* I - Timeout in seconds, typically 1.0 */
{
fd_set output; /* Output set */
struct timeval tval; /* Timeout value */
# define CUPS_VERSION_MINOR 4
# define CUPS_VERSION_PATCH -1
+# define CUPS_BC_FD 3 /* Back-channel file descriptor for select/poll */
# define CUPS_DATE_ANY (time_t)-1
# define CUPS_EXCLUDE_NONE (const char *)0
# define CUPS_FORMAT_AUTO "application/octet-stream"
* Enumerations...
*/
-enum cups_sc_bidi_e /**** Bidirectional capabilities ****/
+enum cups_sc_bidi_e /**** Bidirectional capability values ****/
{
CUPS_SC_BIDI_NOT_SUPPORTED = 0, /* Bidirectional I/O is not supported */
CUPS_SC_BIDI_SUPPORTED = 1 /* Bidirectional I/O is supported */
enum cups_sc_state_e /**** Printer state bits ****/
{
- CUPS_SC_STATE_OFFLINE = 0, /* Device is off-line */
- CUPS_SC_STATE_ONLINE = 1, /* Device is on-line */
+ CUPS_SC_STATE_OFFLINE = 0, /* Device is offline */
+ CUPS_SC_STATE_ONLINE = 1, /* Device is online */
CUPS_SC_STATE_BUSY = 2, /* Device is busy */
CUPS_SC_STATE_ERROR = 4, /* Other error condition */
CUPS_SC_STATE_MEDIA_LOW = 16, /* Paper low condition */
<li><a href="#cupsArrayNext" title="Get the next element in the array.">cupsArrayNext</a></li>
<li><a href="#cupsArrayPrev" title="Get the previous element in the array.">cupsArrayPrev</a></li>
<li><a href="#cupsArrayRemove" title="Remove an element from the array.">cupsArrayRemove</a></li>
-<li><a href="#cupsArrayRestore" title="Reset the current element to the last cupsArraySave.">cupsArrayRestore</a></li>
-<li><a href="#cupsArraySave" title="Mark the current element for a later cupsArrayRestore.">cupsArraySave</a></li>
+<li><a href="#cupsArrayRestore" title="Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.">cupsArrayRestore</a></li>
+<li><a href="#cupsArraySave" title="Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.">cupsArraySave</a></li>
<li><a href="#cupsArrayUserData" title="Return the user data for an array.">cupsArrayUserData</a></li>
</ul>
<li><a href="#TYPES">Data Types</a><ul class="code">
</pre>
<p>The hash function (type
-<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) returns a
+<a href="#cups_ahash_func_t"><code>cups_ahash_func_t</code></a>) should return a
number from 0 to (hash_size-1) that (hopefully) uniquely identifies the
element and is called whenever you look up an element in the array with
<a href='#cupsArrayFind'><code>cupsArrayFind</code></a>. The hash size is
The first function adds an element to the array, adding the new element
after any elements that have the same order, while the second inserts the
element before others with the same order. For unsorted arrays,
-<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the elemnt to
+<a href='#cupsArrayAdd'><code>cupsArrayAdd</code></a> appends the element to
the end of the array while
<a href='#cupsArrayInsert'><code>cupsArrayInsert</code></a> inserts the
element at the beginning of the array. For example, the following code
<dl>
<dt><a href='#cupsArrayFind'><code>cupsArrayFind</code></a></dt>
- <dd>Returns the first matching element .</dd>
+ <dd>Returns the first matching element.</dd>
<dt><a href='#cupsArrayFirst'><code>cupsArrayFirst</code></a></dt>
<dd>Returns the first element in the array.</dd>
<dt><a href='#cupsArrayIndex'><code>cupsArrayIndex</code></a></dt>
- <dd>Returns the Nth element in the array.</dd>
+ <dd>Returns the Nth element in the array, starting at 0.</dd>
<dt><a href='#cupsArrayLast'><code>cupsArrayLast</code></a></dt>
<dd>Returns the last element in the array.</dd>
<dt><a href='#cupsArrayNext'><code>cupsArrayNext</code></a></dt>
<p class="description">1 on success, 0 on failure</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">When adding an element to a sorted array, non-unique elements are
-appended at the end of the run. For unsorted arrays, the element
-is inserted at the end of the array.
+appended at the end of the run of identical elements. For unsorted arrays,
+the element is appended to the end of the array.
</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayClear">cupsArrayClear</a></h3>
<dt>a</dt>
<dd class="description">Array</dd>
</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is equivalent to removing all elements in the array.
+The caller is responsible for freeing the memory used by the
+elements themselves.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayCount">cupsArrayCount</a></h3>
<p class="description">Get the number of elements in the array.</p>
<p class="code">
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Element</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayDelete">cupsArrayDelete</a></h3>
<p class="description">Free all memory used by the array.</p>
<p class="code">
<dt>a</dt>
<dd class="description">Array</dd>
</dl>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The caller is responsible for freeing the memory used by the
+elements themselves.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayDup">cupsArrayDup</a></h3>
<p class="description">Duplicate the array.</p>
<p class="code">
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">First element or <code>NULL</code></p>
+<p class="description">First element or <code>NULL</code> if the array is empty</p>
<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsArrayGetIndex">cupsArrayGetIndex</a></h3>
<p class="description">Get the index of the current element.</p>
<p class="code">
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Index of the current element</p>
+<p class="description">Index of the current element, starting at 0</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsArrayGetInsert">cupsArrayGetInsert</a></h3>
<p class="description">Get the index of the last inserted element.</p>
<p class="code">
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Index of the last inserted element</p>
+<p class="description">Index of the last inserted element, starting at 0</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayIndex">cupsArrayIndex</a></h3>
<p class="description">Get the N-th element in the array.</p>
<p class="code">
<p class="description">0 on failure, 1 on success</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">When inserting an element in a sorted array, non-unique elements are
-inserted at the beginning of the run. For unsorted arrays, the element
-is inserted at the beginning of the array.
+inserted at the beginning of the run of identical elements. For unsorted
+arrays, the element is inserted at the beginning of the array.
</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayLast">cupsArrayLast</a></h3>
<dd class="description">Array</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">Last element or <code>NULL</code></p>
+<p class="description">Last element or <code>NULL</code> if the array is empty</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayNew">cupsArrayNew</a></h3>
<p class="description">Create a new array.</p>
<p class="code">
<h4 class="parameters">Parameters</h4>
<dl>
<dt>f</dt>
-<dd class="description">Comparison function</dd>
+<dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
<dt>d</dt>
-<dd class="description">User data</dd>
+<dd class="description">User data pointer or <code>NULL</code></dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Array</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The comparison function ("f") is used to create a sorted array. The function
+receives pointers to two elements and the user data pointer ("d") - the user
+data pointer argument can safely be omitted when not required so functions
+like <code>strcmp</code> can be used for sorted string arrays.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.3 </span><a name="cupsArrayNew2">cupsArrayNew2</a></h3>
<p class="description">Create a new array with hash.</p>
<p class="code">
<h4 class="parameters">Parameters</h4>
<dl>
<dt>f</dt>
-<dd class="description">Comparison function</dd>
+<dd class="description">Comparison function or <code>NULL</code> for an unsorted array</dd>
<dt>d</dt>
-<dd class="description">User data</dd>
+<dd class="description">User data or <code>NULL</code></dd>
<dt>h</dt>
-<dd class="description">Hash function</dd>
+<dd class="description">Hash function or <code>NULL</code> for unhashed lookups</dd>
<dt>hsize</dt>
-<dd class="description">Hash size</dd>
+<dd class="description">Hash size (>= 0)</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Array</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The comparison function ("f") is used to create a sorted array. The function
+receives pointers to two elements and the user data pointer ("d") - the user
+data pointer argument can safely be omitted when not required so functions
+like <code>strcmp</code> can be used for sorted string arrays.<br>
+<br>
+The hash function ("h") is used to implement cached lookups with the
+specified hash size ("hsize").
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayNext">cupsArrayNext</a></h3>
<p class="description">Get the next element in the array.</p>
<p class="code">
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Next element or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) + 1)".<br>
+<br>
+The next element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
+to set the current element.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayPrev">cupsArrayPrev</a></h3>
<p class="description">Get the previous element in the array.</p>
<p class="code">
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Previous element or <code>NULL</code></p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is equivalent to "cupsArrayIndex(a, cupsArrayGetIndex(a) - 1)".<br>
+<br>
+The previous element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
+to set the current element.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayRemove">cupsArrayRemove</a></h3>
<p class="description">Remove an element from the array.</p>
<p class="code">
</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">If more than one element matches "e", only the first matching element is
+removed.<br>
+<br>
+The caller is responsible for freeing the memory used by the
+removed element.
+
+</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayRestore">cupsArrayRestore</a></h3>
-<p class="description">Reset the current element to the last cupsArraySave.</p>
+<p class="description">Reset the current element to the last <a href="#cupsArraySave"><code>cupsArraySave</code></a>.</p>
<p class="code">
void *cupsArrayRestore (<br>
<a href="#cups_array_t">cups_array_t</a> *a<br>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New current element</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArraySave">cupsArraySave</a></h3>
-<p class="description">Mark the current element for a later cupsArrayRestore.</p>
+<p class="description">Mark the current element for a later <a href="#cupsArrayRestore"><code>cupsArrayRestore</code></a>.</p>
<p class="code">
int cupsArraySave (<br>
<a href="#cups_array_t">cups_array_t</a> *a<br>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">The save/restore stack is guaranteed to be at least 32 elements deep.
+<p class="discussion">The current element is undefined until you call <a href="#cupsArrayFind"><code>cupsArrayFind</code></a>,
+<a href="#cupsArrayFirst"><code>cupsArrayFirst</code></a>, or <a href="#cupsArrayIndex"><code>cupsArrayIndex</code></a>, or <a href="#cupsArrayLast"><code>cupsArrayLast</code></a>
+to set the current element.<br>
+<br>
+The save/restore stack is guaranteed to be at least 32 elements deep.
</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsArrayUserData">cupsArrayUserData</a></h3>
<body>
<div class='body'>
<!--
- "$Id: api-filter.header 7285 2008-02-01 23:57:39Z mike $"
+ "$Id: api-filter.header 7615 2008-05-25 07:17:07Z mike $"
Filter and backend programming header for the Common UNIX Printing System
(CUPS).
<tr>
<th>Headers</th>
<th>cups/backend.h<br>
- cups/sidechannel.h<br>
- cups/snmp.h</th>
+ cups/sidechannel.h</th>
</tr>
</thead>
<tbody>
<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>
Programming: <a href='api-ppd.html' target='_top'>PPD API</a><br>
- Programming: <a href='api-raster.html' target='_top'>Raster API</a></td>
+ Programming: <a href='api-raster.html' target='_top'>Raster API</a><br>
+ Specifications: <a href='spec-design' target='_top'>CUPS Design Description</a></td>
</tr>
</tbody>
</table></div>
</ul></li>
<li><a href="#ENUMERATIONS">Constants</a><ul class="code">
<li><a href="#cups_backend_e" title="Backend exit codes">cups_backend_e</a></li>
- <li><a href="#cups_sc_bidi_e" title="Bidirectional capabilities">cups_sc_bidi_e</a></li>
+ <li><a href="#cups_sc_bidi_e" title="Bidirectional capability values">cups_sc_bidi_e</a></li>
<li><a href="#cups_sc_command_e" title="Request command codes">cups_sc_command_e</a></li>
<li><a href="#cups_sc_state_e" title="Printer state bits">cups_sc_state_e</a></li>
<li><a href="#cups_sc_status_e" title="Response status codes">cups_sc_status_e</a></li>
</ul></li>
</ul>
<!--
- "$Id: api-filter.shtml 7502 2008-04-28 21:30:12Z mike $"
+ "$Id: api-filter.shtml 7594 2008-05-19 23:16:03Z mike $"
Filter and backend programming introduction for the Common UNIX Printing
System (CUPS).
<h2 class='title'><a name="OVERVIEW">Overview</a></h2>
-<p>Filters, printer drivers, port monitors, and backends use a common interface
-for processing print jobs and communicating status information to the scheduler.
-Each filter is run with a standard set of command-line arguments:<p>
+<p>Filters (which include printer drivers and port monitors) and backends
+are used to convert job files to a printable format and send that data to the
+printer itself. All of these programs use a common interface for processing
+print jobs and communicating status information to the scheduler. Each is run
+with a standard set of command-line arguments:<p>
<dl class="code">
<dd>The options that were provided when the job was submitted</dd>
<dt>argv[6]</dt>
- <dd>The file to print (first filter only)</dd>
+ <dd>The file to print (first program only)</dd>
</dl>
<p>The scheduler runs one or more of these programs to print any given job. The
<h3><a name="ENVIRONMENT">Environment Variables</a></h3>
-<p>The following environment variables are defined by the printing system:</p>
+<p>The following environment variables are defined by the printing system
+when running print filters and backends:</p>
<dl class="code">
application/postscript).</dd>
<dt>CUPS_CACHEDIR</dt>
- <dd>The directory where cache files can be stored.</dd>
+ <dd>The directory where cache files can be stored. Cache files can be
+ used to retain information between jobs or files in a job.</dd>
<dt>CUPS_DATADIR</dt>
- <dd>The directory where data files can be found.</dd>
+ <dd>The directory where (read-only) CUPS data files can be found.</dd>
<dt>CUPS_SERVERROOT</dt>
<dd>The root directory of the server.</dd>
file for this printer.</dd>
<dt>PRINTER</dt>
- <dd>The name of the printer.</dd>
+ <dd>The queue name of the class or printer.</dd>
<dt>RIP_CACHE</dt>
<dd>The recommended amount of memory to use for Raster Image
Processors (RIPs).</dd>
+ <dt>TMPDIR</dt>
+ <dd>The directory where temporary files should be created.</dd>
+
</dl>
<h3><a name="MESSAGES">Communicating with the Scheduler</a></h3>
-<p>Filters and backends communicate wih the scheduler by writing messages
-to the standard error file. For example, the following code sets the current
-printer state message to "Printing page 5":</p>
+<p>Filters and backends communicate with the scheduler by writing messages
+to the standard error file. The scheduler reads messages from all filters in
+a job and processes the message based on its prefix. For example, the following
+code sets the current printer state message to "Printing page 5":</p>
<pre class="example">
int page = 5;
to set the <code>marker-colors</code>, <code>marker-levels</code>,
<code>marker-names</code>, <code>marker-types</code>,
<code>printer-alert</code>, and <code>printer-alert-description</code>
- printer attributes.</dd>
+ printer attributes. Standard <code>marker-types</code> values are
+ listed in <a href='#TABLE1'>Table 1</a>.</dd>
<dt>CRIT: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
<dt>ERROR: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
- message to the current error log file using the "error" log level.</dd>
+ message to the current error log file using the "error" log level.
+ Use "ERROR:" messages for non-persistent processing errors.</dd>
<dt>INFO: message</dt>
<dd>Sets the printer-state-message attribute. If the current log level
<dt>STATE: + printer-state-reason [printer-state-reason ...]</dt>
<dt>STATE: - printer-state-reason [printer-state-reason ...]</dt>
<dd>Sets, adds, or removes printer-state-reason keywords to the
- current queue. Typically this is used to indicate media, ink, and
- toner conditions on a printer.</dd>
+ current queue. Typically this is used to indicate persistent media,
+ ink, toner, and configuration conditions or errors on a printer.
+ <a href='#TABLE2'>Table 2</a> lists the standard state keywords -
+ use vendor-prefixed ("com.acme.foo") keywords for custom states.</dd>
<dt>WARNING: message</dt>
<dd>Sets the printer-state-message attribute and adds the specified
<p>Messages without one of these prefixes are treated as if they began with
the "DEBUG:" prefix string.</p>
+
+<div class='table'><table width='80%' summary='Table 1: Standard marker-types Values'>
+<caption>Table 1: <a name='TABLE1'>Standard marker-types Values</a></caption>
+<thead>
+<tr>
+ <th>marker-type</th>
+ <th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <td>developer</td>
+ <td>Developer unit</td>
+</tr>
+<tr>
+ <td>fuser</td>
+ <td>Fuser unit</td>
+</tr>
+<tr>
+ <td>fuserCleaningPad</td>
+ <td>Fuser cleaning pad</td>
+</tr>
+<tr>
+ <td>fuserOil</td>
+ <td>Fuser oil</td>
+</tr>
+<tr>
+ <td>ink</td>
+ <td>Ink supply</td>
+</tr>
+<tr>
+ <td>opc</td>
+ <td>Photo conductor</td>
+</tr>
+<tr>
+ <td>solidWax</td>
+ <td>Wax supply</td>
+</tr>
+<tr>
+ <td>staples</td>
+ <td>Staple supply</td>
+</tr>
+<tr>
+ <td>toner</td>
+ <td>Toner supply</td>
+</tr>
+<tr>
+ <td>transferUnit</td>
+ <td>Transfer unit</td>
+</tr>
+<tr>
+ <td>wasteInk</td>
+ <td>Waste ink tank</td>
+</tr>
+<tr>
+ <td>wasteToner</td>
+ <td>Waste toner tank</td>
+</tr>
+<tr>
+ <td>wasteWax</td>
+ <td>Waste wax tank</td>
+</tr>
+</tbody>
+</table></div>
+
+<br>
+
+<div class='table'><table width='80%' summary='Table 2: Standard State Keywords'>
+<caption>Table 2: <a name='TABLE2'>Standard State Keywords</a></caption>
+<thead>
+<tr>
+ <th>Keyword</th>
+ <th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <td>connecting-to-device</td>
+ <td>Connecting to printer but not printing yet</td>
+</tr>
+<tr>
+ <td>cover-open</td>
+ <td>A cover is open on the printer</td>
+</tr>
+<tr>
+ <td>input-tray-missing</td>
+ <td>An input tray is missing from the printer</td>
+</tr>
+<tr>
+ <td>marker-supply-empty</td>
+ <td>Out of ink</td>
+</tr>
+<tr>
+ <td>marker-supply-low</td>
+ <td>Low on ink</td>
+</tr>
+<tr>
+ <td>marker-waste-almost-full</td>
+ <td>Waste tank almost full</td>
+</tr>
+<tr>
+ <td>marker-waste-full</td>
+ <td>Waste tank full</td>
+</tr>
+<tr>
+ <td>media-empty</td>
+ <td>Out of media</td>
+</tr>
+<tr>
+ <td>media-jam</td>
+ <td>Media is jammed in the printer</td>
+</tr>
+<tr>
+ <td>media-low</td>
+ <td>Low on media</td>
+</tr>
+<tr>
+ <td>paused</td>
+ <td>Stop the printer</td>
+</tr>
+<tr>
+ <td>timed-out</td>
+ <td>Unable to connect to printer</td>
+</tr>
+<tr>
+ <td>toner-empty</td>
+ <td>Out of toner</td>
+</tr>
+<tr>
+ <td>toner-low</td>
+ <td>Low on toner</td>
+</tr>
+</tbody>
+</table></div>
+
<h3><a name="COMMUNICATING_BACKEND">Communicating with the Backend</a></h3>
<p>Filters can communicate with the backend via the
bytes = cupsBackChannelRead(buffer, sizeof(buffer), 0.0);
</pre>
-The
+<p>Filters can also use <code>select()</code> or <code>poll()</code> on the
+back-channel file descriptor (3 or <code>CUPS_BC_FD</code>) to read data only
+when it is available.</p>
+
+<p>The
<a href="#cupsSideChannelDoRequest"><code>cupsSideChannelDoRequest</code></a>
function allows you to get out-of-band status information and do synchronization
with the device. For example, the following code gets the current IEEE-1284
int datalen;
<a href="#cups_sc_status_t">cups_sc_status_t</a> status;
-/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for nul-termination... */
+/* Tell cupsSideChannelDoRequest() how big our buffer is, less 1 byte for
+ nul-termination... */
datalen = sizeof(data) - 1;
/* Get the IEEE-1284 device ID, waiting for up to 1 second */
char buffer[8192];
ssize_t bytes;
+/* Obtain data from printer/device */
+...
+
/* Use a timeout of 1.0 seconds to give filters a chance to read */
cupsBackChannelWrite(buffer, bytes, 1.0);
</pre>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>buffer</dt>
-<dd class="description">Buffer to read</dd>
+<dd class="description">Buffer to read into</dd>
<dt>bytes</dt>
<dd class="description">Bytes to read</dd>
<dt>timeout</dt>
-<dd class="description">Timeout in seconds</dd>
+<dd class="description">Timeout in seconds, typically 0.0 to poll</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Bytes read or -1 on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Reads up to "bytes" bytes from the backchannel. The "timeout"
-parameter controls how many seconds to wait for the data - use
-0.0 to return immediately if there is no data, -1.0 to wait
-for data indefinitely.
+<p class="discussion">Reads up to "bytes" bytes from the backchannel/backend. The "timeout"
+parameter controls how many seconds to wait for the data - use 0.0 to
+return immediately if there is no data, -1.0 to wait for data indefinitely.
</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsBackChannelWrite">cupsBackChannelWrite</a></h3>
<dt>bytes</dt>
<dd class="description">Bytes to write</dd>
<dt>timeout</dt>
-<dd class="description">Timeout in seconds</dd>
+<dd class="description">Timeout in seconds, typically 1.0</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Bytes written or -1 on error</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">Writes "bytes" bytes to the backchannel. The "timeout" parameter
+<p class="discussion">Writes "bytes" bytes to the backchannel/filter. The "timeout" parameter
controls how many seconds to wait for the data to be written - use
0.0 to return immediately if the data cannot be written, -1.0 to wait
indefinitely.
<dd class="description">Job failed, stop queue</dd>
</dl>
<h3 class="enumeration"><a name="cups_sc_bidi_e">cups_sc_bidi_e</a></h3>
-<p class="description">Bidirectional capabilities</p>
+<p class="description">Bidirectional capability values</p>
<h4 class="constants">Constants</h4>
<dl>
<dt>CUPS_SC_BIDI_NOT_SUPPORTED </dt>
<dt>CUPS_SC_STATE_MEDIA_LOW </dt>
<dd class="description">Paper low condition</dd>
<dt>CUPS_SC_STATE_OFFLINE </dt>
-<dd class="description">Device is off-line</dd>
+<dd class="description">Device is offline</dd>
<dt>CUPS_SC_STATE_ONLINE </dt>
-<dd class="description">Device is on-line</dd>
+<dd class="description">Device is online</dd>
</dl>
<h3 class="enumeration"><a name="cups_sc_status_e">cups_sc_status_e</a></h3>
<p class="description">Response status codes</p>
<li><a href="#http_auth_t" title="HTTP authentication types">http_auth_t</a></li>
<li><a href="#http_encoding_t" title="HTTP transfer encoding values">http_encoding_t</a></li>
<li><a href="#http_encryption_t" title="HTTP encryption values">http_encryption_t</a></li>
+ <li><a href="#http_field_t" title="HTTP field names">http_field_t</a></li>
+ <li><a href="#http_keepalive_t" title="Types and structures...">http_keepalive_t</a></li>
+ <li><a href="#http_status_t" title="HTTP status codes">http_status_t</a></li>
<li><a href="#http_t" title="HTTP connection type">http_t</a></li>
+ <li><a href="#http_uri_coding_t" title="HTTP version numbers">http_uri_coding_t</a></li>
+ <li><a href="#http_uri_status_t" title="URI en/decode flags">http_uri_status_t</a></li>
+ <li><a href="#http_version_t" title="Socket address union, which
+makes using IPv6 and other
+address types easier and
+more portable. ">http_version_t</a></li>
<li><a href="#ipp_attribute_t" title="Attribute">ipp_attribute_t</a></li>
+ <li><a href="#ipp_finish_t" title="Orientation...">ipp_finish_t</a></li>
<li><a href="#ipp_iocb_t" title="IPP IO Callback Function ">ipp_iocb_t</a></li>
+ <li><a href="#ipp_jstate_t" title="Printer States....">ipp_jstate_t</a></li>
+ <li><a href="#ipp_op_t" title="Old names for the operations">ipp_op_t</a></li>
+ <li><a href="#ipp_orient_t" title="Qualities...">ipp_orient_t</a></li>
+ <li><a href="#ipp_pstate_t" title="IPP states...">ipp_pstate_t</a></li>
+ <li><a href="#ipp_quality_t" title="Job States....">ipp_quality_t</a></li>
<li><a href="#ipp_request_t" title="Request Header">ipp_request_t</a></li>
+ <li><a href="#ipp_res_t" title="Types and structures...">ipp_res_t</a></li>
+ <li><a href="#ipp_state_t" title="IPP operations...">ipp_state_t</a></li>
<li><a href="#ipp_t" title="Attribute Value">ipp_t</a></li>
<li><a href="#ipp_uchar_t" title="IPP status codes...">ipp_uchar_t</a></li>
+ <li><a href="#ipp_tag_t" title="Format tags for attributes...">ipp_tag_t</a></li>
<li><a href="#ipp_value_t" title="New in CUPS 1.1.19">ipp_value_t</a></li>
</ul></li>
<li><a href="#STRUCTURES">Structures</a><ul class="code">
<a href="#ipp_t">ipp_t</a> *ipp,<br>
int num_options,<br>
cups_option_t *options,<br>
- ipp_tag_t group_tag<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group_tag<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsGetFd">cupsGetFd</a></h3>
<p class="description">Get a file from the server.</p>
<p class="code">
-http_status_t cupsGetFd (<br>
+<a href="#http_status_t">http_status_t</a> cupsGetFd (<br>
<a href="#http_t">http_t</a> *http,<br>
const char *resource,<br>
int fd<br>
<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsGetFile">cupsGetFile</a></h3>
<p class="description">Get a file from the server.</p>
<p class="code">
-http_status_t cupsGetFile (<br>
+<a href="#http_status_t">http_status_t</a> cupsGetFile (<br>
<a href="#http_t">http_t</a> *http,<br>
const char *resource,<br>
const char *filename<br>
<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsPutFd">cupsPutFd</a></h3>
<p class="description">Put a file on the server.</p>
<p class="code">
-http_status_t cupsPutFd (<br>
+<a href="#http_status_t">http_status_t</a> cupsPutFd (<br>
<a href="#http_t">http_t</a> *http,<br>
const char *resource,<br>
int fd<br>
<h3 class="function"><span class="info"> CUPS 1.1.20 </span><a name="cupsPutFile">cupsPutFile</a></h3>
<p class="description">Put a file on the server.</p>
<p class="code">
-http_status_t cupsPutFile (<br>
+<a href="#http_status_t">http_status_t</a> cupsPutFile (<br>
<a href="#http_t">http_t</a> *http,<br>
const char *resource,<br>
const char *filename<br>
<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsSendRequest">cupsSendRequest</a></h3>
<p class="description">Send an IPP request.</p>
<p class="code">
-http_status_t cupsSendRequest (<br>
+<a href="#http_status_t">http_status_t</a> cupsSendRequest (<br>
<a href="#http_t">http_t</a> *http,<br>
<a href="#ipp_t">ipp_t</a> *request,<br>
const char *resource,<br>
<h3 class="function"><span class="info"> CUPS 1.4 </span><a name="cupsWriteRequestData">cupsWriteRequestData</a></h3>
<p class="description">Write additional data after an IPP request.</p>
<p class="code">
-http_status_t cupsWriteRequestData (<br>
+<a href="#http_status_t">http_status_t</a> cupsWriteRequestData (<br>
<a href="#http_t">http_t</a> *http,<br>
const char *buffer,<br>
size_t length<br>
<p class="description">Assemble a uniform resource identifier from its
components.</p>
<p class="code">
-http_uri_status_t httpAssembleURI (<br>
- http_uri_coding_t encoding,<br>
+<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURI (<br>
+ <a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br>
char *uri,<br>
int urilen,<br>
const char *scheme,<br>
<p class="description">Assemble a uniform resource identifier from its
components with a formatted resource.</p>
<p class="code">
-http_uri_status_t httpAssembleURIf (<br>
- http_uri_coding_t encoding,<br>
+<a href="#http_uri_status_t">http_uri_status_t</a> httpAssembleURIf (<br>
+ <a href="#http_uri_coding_t">http_uri_coding_t</a> encoding,<br>
char *uri,<br>
int urilen,<br>
const char *scheme,<br>
<p class="code">
const char *httpGetField (<br>
<a href="#http_t">http_t</a> *http,<br>
- http_field_t field<br>
+ <a href="#http_field_t">http_field_t</a> field<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="httpGetStatus">httpGetStatus</a></h3>
<p class="description">Get the status of the last HTTP request.</p>
<p class="code">
-http_status_t httpGetStatus (<br>
+<a href="#http_status_t">http_status_t</a> httpGetStatus (<br>
<a href="#http_t">http_t</a> *http<br>
);</p>
<h4 class="parameters">Parameters</h4>
<p class="code">
char *httpGetSubField (<br>
<a href="#http_t">http_t</a> *http,<br>
- http_field_t field,<br>
+ <a href="#http_field_t">http_field_t</a> field,<br>
const char *name,<br>
char *value<br>
);</p>
<p class="code">
char *httpGetSubField2 (<br>
<a href="#http_t">http_t</a> *http,<br>
- http_field_t field,<br>
+ <a href="#http_field_t">http_field_t</a> field,<br>
const char *name,<br>
char *value,<br>
int valuelen<br>
<p class="description">Separate a Universal Resource Identifier into its
components.</p>
<p class="code">
-http_uri_status_t httpSeparateURI (<br>
- http_uri_coding_t decoding,<br>
+<a href="#http_uri_status_t">http_uri_status_t</a> httpSeparateURI (<br>
+ <a href="#http_uri_coding_t">http_uri_coding_t</a> decoding,<br>
const char *uri,<br>
char *scheme,<br>
int schemelen,<br>
<p class="code">
void httpSetExpect (<br>
<a href="#http_t">http_t</a> *http,<br>
- http_status_t expect<br>
+ <a href="#http_status_t">http_status_t</a> expect<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<p class="code">
void httpSetField (<br>
<a href="#http_t">http_t</a> *http,<br>
- http_field_t field,<br>
+ <a href="#http_field_t">http_field_t</a> field,<br>
const char *value<br>
);</p>
<h4 class="parameters">Parameters</h4>
<p class="description">Return a short string describing a HTTP status code.</p>
<p class="code">
const char *httpStatus (<br>
- http_status_t status<br>
+ <a href="#http_status_t">http_status_t</a> status<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<h3 class="function"><a name="httpUpdate">httpUpdate</a></h3>
<p class="description">Update the current HTTP state for incoming data.</p>
<p class="code">
-http_status_t httpUpdate (<br>
+<a href="#http_status_t">http_status_t</a> httpUpdate (<br>
<a href="#http_t">http_t</a> *http<br>
);</p>
<h4 class="parameters">Parameters</h4>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBoolean (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
char value<br>
);</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddBooleans (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
int num_values,<br>
const char *values<br>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollection (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
<a href="#ipp_t">ipp_t</a> *value<br>
);</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddCollections (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
int num_values,<br>
const <a href="#ipp_t">ipp_t</a> **values<br>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddDate (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
const <a href="#ipp_uchar_t">ipp_uchar_t</a> *value<br>
);</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddInteger (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
- ipp_tag_t type,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> type,<br>
const char *name,<br>
int value<br>
);</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddIntegers (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
- ipp_tag_t type,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> type,<br>
const char *name,<br>
int num_values,<br>
const int *values<br>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddOctetString (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
const void *data,<br>
int datalen<br>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRange (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
int lower,<br>
int upper<br>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddRanges (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
int num_values,<br>
const int *lower,<br>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolution (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
- ipp_res_t units,<br>
+ <a href="#ipp_res_t">ipp_res_t</a> units,<br>
int xres,<br>
int yres<br>
);</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddResolutions (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
const char *name,<br>
int num_values,<br>
- ipp_res_t units,<br>
+ <a href="#ipp_res_t">ipp_res_t</a> units,<br>
const int *xres,<br>
const int *yres<br>
);</p>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddString (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
- ipp_tag_t type,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> type,<br>
const char *name,<br>
const char *charset,<br>
const char *value<br>
<p class="code">
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippAddStrings (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
- ipp_tag_t group,<br>
- ipp_tag_t type,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group,<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> type,<br>
const char *name,<br>
int num_values,<br>
const char *charset,<br>
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindAttribute (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
const char *name,<br>
- ipp_tag_t type<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> type<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<a href="#ipp_attribute_t">ipp_attribute_t</a> *ippFindNextAttribute (<br>
<a href="#ipp_t">ipp_t</a> *ipp,<br>
const char *name,<br>
- ipp_tag_t type<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> type<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<p class="description">Allocate a new IPP request message.</p>
<p class="code">
<a href="#ipp_t">ipp_t</a> *ippNewRequest (<br>
- ipp_op_t op<br>
+ <a href="#ipp_op_t">ipp_op_t</a> op<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<p class="description">Return a name for the given operation id.</p>
<p class="code">
const char *ippOpString (<br>
- ipp_op_t op<br>
+ <a href="#ipp_op_t">ipp_op_t</a> op<br>
);</p>
<h4 class="parameters">Parameters</h4>
<dl>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="ippOpValue">ippOpValue</a></h3>
<p class="description">Return an operation id for the given name.</p>
<p class="code">
-ipp_op_t ippOpValue (<br>
+<a href="#ipp_op_t">ipp_op_t</a> ippOpValue (<br>
const char *name<br>
);</p>
<h4 class="parameters">Parameters</h4>
<h3 class="function"><a name="ippRead">ippRead</a></h3>
<p class="description">Read data for an IPP message from a HTTP connection.</p>
<p class="code">
-ipp_state_t ippRead (<br>
+<a href="#ipp_state_t">ipp_state_t</a> ippRead (<br>
<a href="#http_t">http_t</a> *http,<br>
<a href="#ipp_t">ipp_t</a> *ipp<br>
);</p>
<h3 class="function"><span class="info"> CUPS 1.1.19 </span><a name="ippReadFile">ippReadFile</a></h3>
<p class="description">Read data for an IPP message from a file.</p>
<p class="code">
-ipp_state_t ippReadFile (<br>
+<a href="#ipp_state_t">ipp_state_t</a> ippReadFile (<br>
int fd,<br>
<a href="#ipp_t">ipp_t</a> *ipp<br>
);</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="ippReadIO">ippReadIO</a></h3>
<p class="description">Read data for an IPP message.</p>
<p class="code">
-ipp_state_t ippReadIO (<br>
+<a href="#ipp_state_t">ipp_state_t</a> ippReadIO (<br>
void *src,<br>
<a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br>
int blocking,<br>
<h3 class="function"><a name="ippWrite">ippWrite</a></h3>
<p class="description">Write data for an IPP message to a HTTP connection.</p>
<p class="code">
-ipp_state_t ippWrite (<br>
+<a href="#ipp_state_t">ipp_state_t</a> ippWrite (<br>
<a href="#http_t">http_t</a> *http,<br>
<a href="#ipp_t">ipp_t</a> *ipp<br>
);</p>
<h3 class="function"><span class="info"> CUPS 1.1.19 </span><a name="ippWriteFile">ippWriteFile</a></h3>
<p class="description">Write data for an IPP message to a file.</p>
<p class="code">
-ipp_state_t ippWriteFile (<br>
+<a href="#ipp_state_t">ipp_state_t</a> ippWriteFile (<br>
int fd,<br>
<a href="#ipp_t">ipp_t</a> *ipp<br>
);</p>
<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="ippWriteIO">ippWriteIO</a></h3>
<p class="description">Write data for an IPP message.</p>
<p class="code">
-ipp_state_t ippWriteIO (<br>
+<a href="#ipp_state_t">ipp_state_t</a> ippWriteIO (<br>
void *dst,<br>
<a href="#ipp_iocb_t">ipp_iocb_t</a> cb,<br>
int blocking,<br>
<p class="code">
typedef enum <a href="#http_encryption_e">http_encryption_e</a> http_encryption_t;
</p>
+<h3 class="typedef"><a name="http_field_t">http_field_t</a></h3>
+<p class="description">HTTP field names</p>
+<p class="code">
+typedef enum <a href="#http_field_e">http_field_e</a> http_field_t;
+</p>
+<h3 class="typedef"><a name="http_keepalive_t">http_keepalive_t</a></h3>
+<p class="description">Types and structures...</p>
+<p class="code">
+typedef enum <a href="#http_keepalive_e">http_keepalive_e</a> http_keepalive_t;
+</p>
+<h3 class="typedef"><a name="http_status_t">http_status_t</a></h3>
+<p class="description">HTTP status codes</p>
+<p class="code">
+typedef enum <a href="#http_status_e">http_status_e</a> http_status_t;
+</p>
<h3 class="typedef"><a name="http_t">http_t</a></h3>
<p class="description">HTTP connection type</p>
<p class="code">
typedef struct _http_s http_t;
</p>
+<h3 class="typedef"><a name="http_uri_coding_t">http_uri_coding_t</a></h3>
+<p class="description">HTTP version numbers</p>
+<p class="code">
+typedef enum <a href="#http_uri_coding_e">http_uri_coding_e</a> http_uri_coding_t;
+</p>
+<h3 class="typedef"><a name="http_uri_status_t">http_uri_status_t</a></h3>
+<p class="description">URI en/decode flags</p>
+<p class="code">
+typedef enum <a href="#http_uri_status_e">http_uri_status_e</a> http_uri_status_t;
+</p>
+<h3 class="typedef"><span class="info"> CUPS 1.2 </span><a name="http_version_t">http_version_t</a></h3>
+<p class="description">Socket address union, which
+makes using IPv6 and other
+address types easier and
+more portable. </p>
+<p class="code">
+typedef enum <a href="#http_version_e">http_version_e</a> http_version_t;
+</p>
<h3 class="typedef"><a name="ipp_attribute_t">ipp_attribute_t</a></h3>
<p class="description">Attribute</p>
<p class="code">
typedef struct <a href="#ipp_attribute_s">ipp_attribute_s</a> ipp_attribute_t;
</p>
+<h3 class="typedef"><a name="ipp_finish_t">ipp_finish_t</a></h3>
+<p class="description">Orientation...</p>
+<p class="code">
+typedef enum <a href="#ipp_finish_e">ipp_finish_e</a> ipp_finish_t;
+</p>
<h3 class="typedef"><span class="info"> CUPS 1.2 </span><a name="ipp_iocb_t">ipp_iocb_t</a></h3>
<p class="description">IPP IO Callback Function </p>
<p class="code">
typedef ssize_t (*ipp_iocb_t)(void *, <a href="#ipp_uchar_t">ipp_uchar_t</a> *, size_t);
</p>
+<h3 class="typedef"><a name="ipp_jstate_t">ipp_jstate_t</a></h3>
+<p class="description">Printer States....</p>
+<p class="code">
+typedef enum <a href="#ipp_jstate_e">ipp_jstate_e</a> ipp_jstate_t;
+</p>
+<h3 class="typedef"><a name="ipp_op_t">ipp_op_t</a></h3>
+<p class="description">Old names for the operations</p>
+<p class="code">
+typedef enum <a href="#ipp_op_e">ipp_op_e</a> ipp_op_t;
+</p>
+<h3 class="typedef"><a name="ipp_orient_t">ipp_orient_t</a></h3>
+<p class="description">Qualities...</p>
+<p class="code">
+typedef enum <a href="#ipp_orient_e">ipp_orient_e</a> ipp_orient_t;
+</p>
+<h3 class="typedef"><a name="ipp_pstate_t">ipp_pstate_t</a></h3>
+<p class="description">IPP states...</p>
+<p class="code">
+typedef enum <a href="#ipp_pstate_e">ipp_pstate_e</a> ipp_pstate_t;
+</p>
+<h3 class="typedef"><a name="ipp_quality_t">ipp_quality_t</a></h3>
+<p class="description">Job States....</p>
+<p class="code">
+typedef enum <a href="#ipp_quality_e">ipp_quality_e</a> ipp_quality_t;
+</p>
<h3 class="typedef"><a name="ipp_request_t">ipp_request_t</a></h3>
<p class="description">Request Header</p>
<p class="code">
typedef union <a href="#ipp_request_u">ipp_request_u</a> ipp_request_t;
</p>
+<h3 class="typedef"><a name="ipp_res_t">ipp_res_t</a></h3>
+<p class="description">Types and structures...</p>
+<p class="code">
+typedef enum <a href="#ipp_res_e">ipp_res_e</a> ipp_res_t;
+</p>
+<h3 class="typedef"><a name="ipp_state_t">ipp_state_t</a></h3>
+<p class="description">IPP operations...</p>
+<p class="code">
+typedef enum <a href="#ipp_state_e">ipp_state_e</a> ipp_state_t;
+</p>
<h3 class="typedef"><a name="ipp_t">ipp_t</a></h3>
<p class="description">Attribute Value</p>
<p class="code">
<p class="code">
typedef typedef unsigned char ipp_uchar_t;
</p>
+<h3 class="typedef"><a name="ipp_tag_t">ipp_tag_t</a></h3>
+<p class="description">Format tags for attributes...</p>
+<p class="code">
+typedef enum <a href="#ipp_tag_e">ipp_tag_e</a> ipp_tag_t;
+</p>
<h3 class="typedef"><a name="ipp_value_t">ipp_value_t</a></h3>
<p class="description">New in CUPS 1.1.19</p>
<p class="code">
char *name;<br>
struct <a href="#ipp_attribute_s">ipp_attribute_s</a> *next;<br>
int num_values;<br>
- ipp_tag_t group_tag, value_tag;<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> group_tag, value_tag;<br>
<a href="#ipp_value_t">ipp_value_t</a> values[1];<br>
};</p>
<h4 class="members">Members</h4>
<p class="code">struct ipp_s {<br>
<a href="#ipp_attribute_t">ipp_attribute_t</a> *attrs;<br>
<a href="#ipp_attribute_t">ipp_attribute_t</a> *current;<br>
- ipp_tag_t curtag;<br>
+ <a href="#ipp_tag_t">ipp_tag_t</a> curtag;<br>
<a href="#ipp_attribute_t">ipp_attribute_t</a> *last;<br>
<a href="#ipp_attribute_t">ipp_attribute_t</a> *prev;<br>
<a href="#ipp_request_t">ipp_request_t</a> request;<br>
- ipp_state_t state;<br>
+ <a href="#ipp_state_t">ipp_state_t</a> state;<br>
};</p>
<h4 class="members">Members</h4>
<dl>
<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>
<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">
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"
<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>
<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>
<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>
}
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 {
<ul class="contents">
</li>
<li><a href="#OVERVIEW">Overview</a></li>
+<li><a href="#TASKS">Functions by Task</a><ul class="subcontents">
+<li><a href="#OPENCLOSE">Opening and Closing Raster Streams</a></li>
+<li><a href="#READING">Reading Raster Streams</a></li>
+<li><a href="#WRITING">Writing Raster Streams</a></li>
+</ul></li>
<li><a href="#FUNCTIONS">Functions</a><ul class="code">
<li><a href="#cupsRasterClose" title="Close a raster stream.">cupsRasterClose</a></li>
<li><a href="#cupsRasterInterpretPPD" title="Interpret PPD commands to create a page header.">cupsRasterInterpretPPD</a></li>
<li><a href="#cupsRasterOpen" title="Open a raster stream.">cupsRasterOpen</a></li>
<li><a href="#cupsRasterReadHeader" title="Read a raster page header and store it in a
-V1 page header structure.">cupsRasterReadHeader</a></li>
+version 1 page header structure.">cupsRasterReadHeader</a></li>
<li><a href="#cupsRasterReadHeader2" title="Read a raster page header and store it in a
-V2 page header structure.">cupsRasterReadHeader2</a></li>
+version 2 page header structure.">cupsRasterReadHeader2</a></li>
<li><a href="#cupsRasterReadPixels" title="Read raster pixels.">cupsRasterReadPixels</a></li>
-<li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a V1 page
+<li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a version 1 page
header structure.">cupsRasterWriteHeader</a></li>
-<li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a V2 page
-header structure.">cupsRasterWriteHeader2</a></li>
+<li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a version 2
+page header structure.">cupsRasterWriteHeader2</a></li>
<li><a href="#cupsRasterWritePixels" title="Write raster pixels.">cupsRasterWritePixels</a></li>
</ul>
<li><a href="#TYPES">Data Types</a><ul class="code">
+ <li><a href="#cups_adv_t" title="AdvanceMedia attribute values">cups_adv_t</a></li>
+ <li><a href="#cups_bool_t" title="Types...">cups_bool_t</a></li>
+ <li><a href="#cups_cspace_t" title="CutMedia attribute values">cups_cspace_t</a></li>
+ <li><a href="#cups_cut_t" title="LeadingEdge attribute values">cups_cut_t</a></li>
+ <li><a href="#cups_edge_t" title="Jog attribute values">cups_edge_t</a></li>
<li><a href="#cups_interpret_cb_t" title="cupsRasterInterpretPPD callback function">cups_interpret_cb_t</a></li>
+ <li><a href="#cups_jog_t" title="cupsRasterOpen modes">cups_jog_t</a></li>
<li><a href="#cups_mode_t" title="cupsRasterOpen modes">cups_mode_t</a></li>
+ <li><a href="#cups_order_t" title="cupsColorOrder attribute values">cups_order_t</a></li>
+ <li><a href="#cups_orient_t" title="The page header structure contains the standard PostScript page device
+dictionary, along with some CUPS-specific parameters that are provided
+by the RIPs...">cups_orient_t</a></li>
<li><a href="#cups_page_header2_t" title="Version 2 page header ">cups_page_header2_t</a></li>
- <li><a href="#cups_page_header_t" title="Version 1 page header">cups_page_header_t</a></li>
+ <li><a href="#cups_page_header_t" title="Version 1 page header ">cups_page_header_t</a></li>
<li><a href="#cups_raster_t" title="Raster stream data">cups_raster_t</a></li>
</ul></li>
<li><a href="#STRUCTURES">Structures</a><ul class="code">
<li><a href="#cups_page_header2_s" title="Version 2 page header ">cups_page_header2_s</a></li>
- <li><a href="#cups_page_header_s" title="Version 1 page header">cups_page_header_s</a></li>
+ <li><a href="#cups_page_header_s" title="Version 1 page header ">cups_page_header_s</a></li>
</ul></li>
<li><a href="#ENUMERATIONS">Constants</a><ul class="code">
<li><a href="#cups_adv_e" title="AdvanceMedia attribute values">cups_adv_e</a></li>
raster format is updated from time to time, it is important to use this API to
avoid incompatibilities with newer versions of CUPS.</p>
+<p>Two kinds of CUPS filters use the CUPS raster API - raster image processor
+(RIP) filters such as <code>pstoraster</code> and <code>cgpdftoraster</code>
+(Mac OS X) that produce CUPS raster files and printer driver filters that
+convert CUPS raster files into a format usable by the printer. Printer
+driver filters are by far the most common.</p>
+
<p>CUPS raster files (<code>application/vnd.cups-raster</code>) consists of
a stream of raster page descriptions produced by one of the RIP filters such as
<var>pstoraster</var>, <var>imagetoraster</var>, or
<p>Each page of data begins with a page dictionary structure called
<a href="#cups_page_header2_t"><code>cups_page_header2_t</code></a>. This
structure contains the colorspace, bits per color, media size, media type,
-hardware resolution, and so forth used for the page. You read the page header
-using the
+hardware resolution, and so forth used for the page.</p>
+
+<blockquote><b>Note:</b>
+
+ <p>Do not confuse the colorspace in the page header with the PPD
+ <tt>ColorModel</tt> keyword. <tt>ColorModel</tt> refers to the general type of
+ color used for a device (Gray, RGB, CMYK, DeviceN) and is often used to
+ select a particular colorspace for the page header along with the associate
+ color profile. The page header colorspace (<tt>cupsColorSpace</tt>) describes
+ both the type and organization of the color data, for example KCMY (black
+ first) instead of CMYK and RGBA (RGB + alpha) instead of RGB.</p>
+
+</blockquote>
+
+<p>You read the page header using the
<a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a>
function:</p>
if (<a href="#cupsRasterReadPixels">cupsRasterReadPixels</a>(ras, buffer, header.cupsBytesPerLine) == 0)
break;
- /* write raster data to printer */
+ /* write raster data to printer on stdout */
}
/* finish this page */
<a href="#cupsRasterClose">cupsRasterClose</a>(ras);
</pre>
+
+
+<h2 class='title'><a name="TASKS">Functions by Task</a></h2>
+
+<h3><a name="OPENCLOSE">Opening and Closing Raster Streams</a></h3>
+
+<ul class="code">
+
+ <li><a href="#cupsRasterClose" title="Close a raster stream.">cupsRasterClose</a></li>
+ <li><a href="#cupsRasterOpen" title="Open a raster stream.">cupsRasterOpen</a></li>
+
+</ul>
+
+<h3><a name="READING">Reading Raster Streams</a></h3>
+
+<ul class="code">
+
+ <li><a href="#cupsRasterReadHeader" title="Read a raster page header and store it in a version 1 page header structure.">cupsRasterReadHeader</a> <span class="info">Deprecated in CUPS 1.2/Mac OS X 10.5</span></li>
+ <li><a href="#cupsRasterReadHeader2" title="Read a raster page header and store it in a version 2 page header structure.">cupsRasterReadHeader2</a></li>
+ <li><a href="#cupsRasterReadPixels" title="Read raster pixels.">cupsRasterReadPixels</a></li>
+
+</ul>
+
+<h3><a name="WRITING">Writing Raster Streams</a></h3>
+
+<ul class="code">
+
+ <li><a href="#cupsRasterInterpretPPD" title="Interpret PPD commands to create a page header.">cupsRasterInterpretPPD</a></li>
+ <li><a href="#cupsRasterWriteHeader" title="Write a raster page header from a version 1 page header structure.">cupsRasterWriteHeader</a></li>
+ <li><a href="#cupsRasterWriteHeader2" title="Write a raster page header from a version 2 page header structure.">cupsRasterWriteHeader2</a> <span class="info">Deprecated in CUPS 1.2/Mac OS X 10.5</span></li>
+ <li><a href="#cupsRasterWritePixels" title="Write raster pixels.">cupsRasterWritePixels</a></li>
+
+</ul>
<h2 class="title"><a name="FUNCTIONS">Functions</a></h2>
<h3 class="function"><a name="cupsRasterClose">cupsRasterClose</a></h3>
<p class="description">Close a raster stream.</p>
<dt>r</dt>
<dd class="description">Stream to close</dd>
</dl>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsRasterInterpretPPD">cupsRasterInterpretPPD</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">The file descriptor associated with the raster stream must be closed
+separately as needed.</p>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRasterInterpretPPD">cupsRasterInterpretPPD</a></h3>
<p class="description">Interpret PPD commands to create a page header.</p>
<p class="code">
int cupsRasterInterpretPPD (<br>
<h4 class="parameters">Parameters</h4>
<dl>
<dt>h</dt>
-<dd class="description">Page header</dd>
+<dd class="description">Page header to create</dd>
<dt>ppd</dt>
<dd class="description">PPD file</dd>
<dt>num_options</dt>
<dt>options</dt>
<dd class="description">Options</dd>
<dt>func</dt>
-<dd class="description">Optional page header callback</dd>
+<dd class="description">Optional page header callback (<code>NULL</code> for none)</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">0 on success, -1 on failure</p>
<h4 class="discussion">Discussion</h4>
-<p class="discussion">This function does not mark the options in the PPD using the "num_options"
-and "options" arguments. Instead, mark the options with
-<code>cupsMarkOptions</code> and <code>ppdMarkOption</code> prior to calling
-<code>cupsRasterInterpretPPD</code> - this allows you to do per-page options
-without manipulating the options array.<br>
+<p class="discussion">This function is used by raster image processing (RIP) filters like
+cgpdftoraster and imagetoraster when writing CUPS raster data for a page.
+It is not used by raster printer driver filters which only read CUPS
+raster data.<br>
+<br>
+
+<code>cupsRasterInterpretPPD</code> does not mark the options in the PPD using
+the "num_options" and "options" arguments. Instead, mark the options with
+<code>cupsMarkOptions</code> and <code>ppdMarkOption</code> prior to calling it -
+this allows for per-page options without manipulating the options array.<br>
<br>
The "func" argument specifies an optional callback function that is
called prior to the computation of the final raster data. The function
can make changes to the <a href="#cups_page_header2_t"><code>cups_page_header2_t</code></a> data as needed to use a
supported raster format and then returns 0 on success and -1 if the
-requested attributes cannot be supported.
+requested attributes cannot be supported.<br>
+<br>
<code>cupsRasterInterpretPPD</code> supports a subset of the PostScript language.
Currently only the <code>[</code>, <code>]</code>, <code><<</code>, <code>>></code>, <code>{</code>,
<dt>fd</dt>
<dd class="description">File descriptor</dd>
<dt>mode</dt>
-<dd class="description">Mode</dd>
+<dd class="description">Mode - <code>CUPS_RASTER_READ</code>, <code>CUPS_RASTER_WRITE</code>, or <code>CUPS_RASTER_WRITE_COMPRESSED</code></dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New stream</p>
-<h3 class="function"><a name="cupsRasterReadHeader">cupsRasterReadHeader</a></h3>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function associates a raster stream with the given file descriptor.
+For most printer driver filters, "fd" will be 0 (stdin). For most raster
+image processor (RIP) filters that generate raster data, "fd" will be 1
+(stdout).<br>
+<br>
+When writing raster data, the <code>CUPS_RASTER_WRITE</code> or
+<code>CUPS_RASTER_WRITE_COMPRESS</code> mode can be used - compressed output
+is generally 25-50% smaller but adds a 100-300% execution time overhead.</p>
+<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsRasterReadHeader">cupsRasterReadHeader</a></h3>
<p class="description">Read a raster page header and store it in a
-V1 page header structure.</p>
+version 1 page header structure.</p>
<p class="code">
unsigned cupsRasterReadHeader (<br>
<a href="#cups_raster_t">cups_raster_t</a> *r,<br>
<dd class="description">Pointer to header data</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on fail</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsRasterReadHeader2">cupsRasterReadHeader2</a></h3>
+<p class="description">1 on success, 0 on failure/end-of-file</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is deprecated. Use <a href="#cupsRasterReadHeader2"><code>cupsRasterReadHeader2</code></a> instead.<br>
+<br>
+Version 1 page headers were used in CUPS 1.0 and 1.1 and contain a subset
+of the version 2 page header data. This function handles reading version 2
+page headers and copying only the version 1 data into the provided buffer.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRasterReadHeader2">cupsRasterReadHeader2</a></h3>
<p class="description">Read a raster page header and store it in a
-V2 page header structure.</p>
+version 2 page header structure.</p>
<p class="code">
unsigned cupsRasterReadHeader2 (<br>
<a href="#cups_raster_t">cups_raster_t</a> *r,<br>
<dd class="description">Pointer to header data</dd>
</dl>
<h4 class="returnvalue">Return Value</h4>
-<p class="description">1 on success, 0 on fail</p>
+<p class="description">1 on success, 0 on failure/end-of-file</p>
<h3 class="function"><a name="cupsRasterReadPixels">cupsRasterReadPixels</a></h3>
<p class="description">Read raster pixels.</p>
<p class="code">
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Number of bytes read</p>
-<h3 class="function"><a name="cupsRasterWriteHeader">cupsRasterWriteHeader</a></h3>
-<p class="description">Write a raster page header from a V1 page
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">For best performance, filters should read one or more whole lines.
+The "cupsBytesPerLine" value from the page header can be used to allocate
+the line buffer and as the number of bytes to read.</p>
+<h3 class="function"><span class="info"> DEPRECATED </span><a name="cupsRasterWriteHeader">cupsRasterWriteHeader</a></h3>
+<p class="description">Write a raster page header from a version 1 page
header structure.</p>
<p class="code">
unsigned cupsRasterWriteHeader (<br>
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">1 on success, 0 on failure</p>
-<h3 class="function"><span class="info"> CUPS 1.2 </span><a name="cupsRasterWriteHeader2">cupsRasterWriteHeader2</a></h3>
-<p class="description">Write a raster page header from a V2 page
-header structure.</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function is deprecated. Use <a href="#cupsRasterWriteHeader2"><code>cupsRasterWriteHeader2</code></a> instead.
+
+</p>
+<h3 class="function"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cupsRasterWriteHeader2">cupsRasterWriteHeader2</a></h3>
+<p class="description">Write a raster page header from a version 2
+page header structure.</p>
<p class="code">
unsigned cupsRasterWriteHeader2 (<br>
<a href="#cups_raster_t">cups_raster_t</a> *r,<br>
</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">The page header can be initialized using <a href="#cupsRasterInterpretPPD"><code>cupsRasterInterpretPPD</code></a>.
+
+</p>
<h3 class="function"><a name="cupsRasterWritePixels">cupsRasterWritePixels</a></h3>
<p class="description">Write raster pixels.</p>
<p class="code">
</dl>
<h4 class="returnvalue">Return Value</h4>
<p class="description">Number of bytes written</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">For best performance, filters should write one or more whole lines.
+The "cupsBytesPerLine" value from the page header can be used to allocate
+the line buffer and as the number of bytes to write.</p>
<h2 class="title"><a name="TYPES">Data Types</a></h2>
+<h3 class="typedef"><a name="cups_adv_t">cups_adv_t</a></h3>
+<p class="description">AdvanceMedia attribute values</p>
+<p class="code">
+typedef enum <a href="#cups_adv_e">cups_adv_e</a> cups_adv_t;
+</p>
+<h3 class="typedef"><a name="cups_bool_t">cups_bool_t</a></h3>
+<p class="description">Types...</p>
+<p class="code">
+typedef enum <a href="#cups_bool_e">cups_bool_e</a> cups_bool_t;
+</p>
+<h3 class="typedef"><a name="cups_cspace_t">cups_cspace_t</a></h3>
+<p class="description">CutMedia attribute values</p>
+<p class="code">
+typedef enum <a href="#cups_cspace_e">cups_cspace_e</a> cups_cspace_t;
+</p>
+<h3 class="typedef"><a name="cups_cut_t">cups_cut_t</a></h3>
+<p class="description">LeadingEdge attribute values</p>
+<p class="code">
+typedef enum <a href="#cups_cut_e">cups_cut_e</a> cups_cut_t;
+</p>
+<h3 class="typedef"><a name="cups_edge_t">cups_edge_t</a></h3>
+<p class="description">Jog attribute values</p>
+<p class="code">
+typedef enum <a href="#cups_edge_e">cups_edge_e</a> cups_edge_t;
+</p>
<h3 class="typedef"><a name="cups_interpret_cb_t">cups_interpret_cb_t</a></h3>
<p class="description">cupsRasterInterpretPPD callback function</p>
<p class="code">
typedef int (*cups_interpret_cb_t)(<a href="#cups_page_header2_t">cups_page_header2_t</a> *header, int preferred_bits);
</p>
+<h3 class="typedef"><a name="cups_jog_t">cups_jog_t</a></h3>
+<p class="description">cupsRasterOpen modes</p>
+<p class="code">
+typedef enum <a href="#cups_jog_e">cups_jog_e</a> cups_jog_t;
+</p>
<h3 class="typedef"><a name="cups_mode_t">cups_mode_t</a></h3>
<p class="description">cupsRasterOpen modes</p>
<p class="code">
typedef enum <a href="#cups_mode_e">cups_mode_e</a> cups_mode_t;
</p>
-<h3 class="typedef"><span class="info"> CUPS 1.2 </span><a name="cups_page_header2_t">cups_page_header2_t</a></h3>
+<h3 class="typedef"><a name="cups_order_t">cups_order_t</a></h3>
+<p class="description">cupsColorOrder attribute values</p>
+<p class="code">
+typedef enum <a href="#cups_order_e">cups_order_e</a> cups_order_t;
+</p>
+<h3 class="typedef"><a name="cups_orient_t">cups_orient_t</a></h3>
+<p class="description">The page header structure contains the standard PostScript page device
+dictionary, along with some CUPS-specific parameters that are provided
+by the RIPs...</p>
+<p class="code">
+typedef enum <a href="#cups_orient_e">cups_orient_e</a> cups_orient_t;
+</p>
+<h3 class="typedef"><span class="info"> CUPS 1.2/Mac OS X 10.5 </span><a name="cups_page_header2_t">cups_page_header2_t</a></h3>
<p class="description">Version 2 page header </p>
<p class="code">
typedef struct <a href="#cups_page_header2_s">cups_page_header2_s</a> cups_page_header2_t;
</p>
-<h3 class="typedef"><a name="cups_page_header_t">cups_page_header_t</a></h3>
-<p class="description">Version 1 page header</p>
+<h3 class="typedef"><span class="info"> DEPRECATED </span><a name="cups_page_header_t">cups_page_header_t</a></h3>
+<p class="description">Version 1 page header </p>
<p class="code">
typedef struct <a href="#cups_page_header_s">cups_page_header_s</a> cups_page_header_t;
</p>
typedef struct _cups_raster_s cups_raster_t;
</p>
<h2 class="title"><a name="STRUCTURES">Structures</a></h2>
-<h3 class="struct"><span class="info"> CUPS 1.2 </span><a name="cups_page_header2_s">cups_page_header2_s</a></h3>
+<h3 class="struct"><span class="info"> CUPS 1.2
/Mac OS X 10.5 </span><a name="cups_page_header2_s">cups_page_header2_s</a></h3>
<p class="description">Version 2 page header </p>
<p class="code">struct cups_page_header2_s {<br>
unsigned AdvanceDistance;<br>
- cups_adv_t AdvanceMedia;<br>
- cups_bool_t Collate;<br>
- cups_cut_t CutMedia;<br>
- cups_bool_t Duplex;<br>
+ <a href="#cups_adv_t">cups_adv_t</a> AdvanceMedia;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Collate;<br>
+ <a href="#cups_cut_t">cups_cut_t</a> CutMedia;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Duplex;<br>
unsigned HWResolution[2];<br>
unsigned ImagingBoundingBox[4];<br>
- cups_bool_t InsertSheet;<br>
- cups_jog_t Jog;<br>
- cups_edge_t LeadingEdge;<br>
- cups_bool_t ManualFeed;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> InsertSheet;<br>
+ <a href="#cups_jog_t">cups_jog_t</a> Jog;<br>
+ <a href="#cups_edge_t">cups_edge_t</a> LeadingEdge;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> ManualFeed;<br>
unsigned Margins[2];<br>
char MediaClass[64];<br>
char MediaColor[64];<br>
unsigned MediaPosition;<br>
char MediaType[64];<br>
unsigned MediaWeight;<br>
- cups_bool_t MirrorPrint;<br>
- cups_bool_t NegativePrint;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> MirrorPrint;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> NegativePrint;<br>
unsigned NumCopies;<br>
- cups_orient_t Orientation;<br>
- cups_bool_t OutputFaceUp;<br>
+ <a href="#cups_orient_t">cups_orient_t</a> Orientation;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> OutputFaceUp;<br>
char OutputType[64];<br>
unsigned PageSize[2];<br>
- cups_bool_t Separations;<br>
- cups_bool_t TraySwitch;<br>
- cups_bool_t Tumble;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Separations;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> TraySwitch;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Tumble;<br>
unsigned cupsBitsPerColor;<br>
unsigned cupsBitsPerPixel;<br>
float cupsBorderlessScalingFactor;<br>
unsigned cupsBytesPerLine;<br>
- cups_order_t cupsColorOrder;<br>
- cups_cspace_t cupsColorSpace;<br>
+ <a href="#cups_order_t">cups_order_t</a> cupsColorOrder;<br>
+ <a href="#cups_cspace_t">cups_cspace_t</a> cupsColorSpace;<br>
unsigned cupsCompression;<br>
unsigned cupsHeight;<br>
float cupsImagingBBox[4];<br>
<dt>AdvanceDistance </dt>
<dd class="description">AdvanceDistance value in points</dd>
<dt>AdvanceMedia </dt>
-<dd class="description">AdvanceMedia value (see above)</dd>
+<dd class="description">AdvanceMedia value (<a href="#cups_adv_t"><code>cups_adv_t</code></a>)</dd>
<dt>Collate </dt>
<dd class="description">Collated copies value</dd>
<dt>CutMedia </dt>
-<dd class="description">CutMedia value (see above)</dd>
+<dd class="description">CutMedia value (<a href="#cups_cut_t"><code>cups_cut_t</code></a>)</dd>
<dt>Duplex </dt>
<dd class="description">Duplexed (double-sided) value</dd>
<dt>HWResolution[2] </dt>
<dd class="description">Resolution in dots-per-inch</dd>
<dt>ImagingBoundingBox[4] </dt>
-<dd class="description">Pixel region that is painted (points)</dd>
+<dd class="description">Pixel region that is painted (points, left, bottom, right, top)</dd>
<dt>InsertSheet </dt>
<dd class="description">InsertSheet value</dd>
<dt>Jog </dt>
-<dd class="description">Jog value (see above)</dd>
+<dd class="description">Jog value (<a href="#cups_jog_t"><code>cups_jog_t</code></a>)</dd>
<dt>LeadingEdge </dt>
-<dd class="description">LeadingEdge value (see above)</dd>
+<dd class="description">LeadingEdge value (<a href="#cups_edge_t"><code>cups_edge_t</code></a>)</dd>
<dt>ManualFeed </dt>
<dd class="description">ManualFeed value</dd>
<dt>Margins[2] </dt>
<dt>NumCopies </dt>
<dd class="description">Number of copies to produce</dd>
<dt>Orientation </dt>
-<dd class="description">Orientation value (see above)</dd>
+<dd class="description">Orientation value (<a href="#cups_orient_t"><code>cups_orient_t</code></a>)</dd>
<dt>OutputFaceUp </dt>
<dd class="description">OutputFaceUp value</dd>
<dt>OutputType[64] </dt>
<dd class="description">Number of bits for each color</dd>
<dt>cupsBitsPerPixel </dt>
<dd class="description">Number of bits for each pixel</dd>
-<dt>cupsBorderlessScalingFactor <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsBorderlessScalingFactor <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Scaling that was applied to page data </dd>
<dt>cupsBytesPerLine </dt>
<dd class="description">Number of bytes per line</dd>
<dd class="description">Device compression to use</dd>
<dt>cupsHeight </dt>
<dd class="description">Height of page image in pixels</dd>
-<dt>cupsImagingBBox[4] <span class="info"> CUPS 1.2 </span></dt>
-<dd class="description">Floating point ImagingBoundingBox *
-(scaling factor not applied) </dd>
-<dt>cupsInteger[16] <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsImagingBBox[4] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
+<dd class="description">Floating point ImagingBoundingBox
+(scaling factor not applied, left,
+bottom, right, top) </dd>
+<dt>cupsInteger[16] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">User-defined integer values </dd>
-<dt>cupsMarkerType[64] <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsMarkerType[64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Ink/toner type </dd>
<dt>cupsMediaType </dt>
<dd class="description">Media type code</dd>
-<dt>cupsNumColors <span class="info"> CUPS 1.2 </span></dt>
-<dd class="description">Number of colors </dd>
-<dt>cupsPageSizeName[64] <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsNumColors <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
+<dd class="description">Number of color compoents </dd>
+<dt>cupsPageSizeName[64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">PageSize name </dd>
-<dt>cupsPageSize[2] <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsPageSize[2] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Floating point PageSize (scaling *
factor not applied) </dd>
-<dt>cupsReal[16] <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsReal[16] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">User-defined floating-point values </dd>
-<dt>cupsRenderingIntent[64] <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsRenderingIntent[64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Color rendering intent </dd>
<dt>cupsRowCount </dt>
<dd class="description">Rows per band</dd>
<dd class="description">Feed between bands</dd>
<dt>cupsRowStep </dt>
<dd class="description">Spacing between lines</dd>
-<dt>cupsString[16][64] <span class="info"> CUPS 1.2 </span></dt>
+<dt>cupsString[16][64] <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">User-defined string values </dd>
<dt>cupsWidth </dt>
<dd class="description">Width of page image in pixels</dd>
</dl>
-<h3 class="struct"><a name="cups_page_header_s">cups_page_header_s</a></h3>
-<p class="description">Version 1 page header</p>
+<h3 class="struct"><span class="info"> DEPRECATED </span><a name="cups_page_header_s">cups_page_header_s</a></h3>
+<p class="description">Version 1 page header </p>
<p class="code">struct cups_page_header_s {<br>
unsigned AdvanceDistance;<br>
- cups_adv_t AdvanceMedia;<br>
- cups_bool_t Collate;<br>
- cups_cut_t CutMedia;<br>
- cups_bool_t Duplex;<br>
+ <a href="#cups_adv_t">cups_adv_t</a> AdvanceMedia;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Collate;<br>
+ <a href="#cups_cut_t">cups_cut_t</a> CutMedia;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Duplex;<br>
unsigned HWResolution[2];<br>
unsigned ImagingBoundingBox[4];<br>
- cups_bool_t InsertSheet;<br>
- cups_jog_t Jog;<br>
- cups_edge_t LeadingEdge;<br>
- cups_bool_t ManualFeed;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> InsertSheet;<br>
+ <a href="#cups_jog_t">cups_jog_t</a> Jog;<br>
+ <a href="#cups_edge_t">cups_edge_t</a> LeadingEdge;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> ManualFeed;<br>
unsigned Margins[2];<br>
char MediaClass[64];<br>
char MediaColor[64];<br>
unsigned MediaPosition;<br>
char MediaType[64];<br>
unsigned MediaWeight;<br>
- cups_bool_t MirrorPrint;<br>
- cups_bool_t NegativePrint;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> MirrorPrint;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> NegativePrint;<br>
unsigned NumCopies;<br>
- cups_orient_t Orientation;<br>
- cups_bool_t OutputFaceUp;<br>
+ <a href="#cups_orient_t">cups_orient_t</a> Orientation;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> OutputFaceUp;<br>
char OutputType[64];<br>
unsigned PageSize[2];<br>
- cups_bool_t Separations;<br>
- cups_bool_t TraySwitch;<br>
- cups_bool_t Tumble;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Separations;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> TraySwitch;<br>
+ <a href="#cups_bool_t">cups_bool_t</a> Tumble;<br>
unsigned cupsBitsPerColor;<br>
unsigned cupsBitsPerPixel;<br>
unsigned cupsBytesPerLine;<br>
- cups_order_t cupsColorOrder;<br>
- cups_cspace_t cupsColorSpace;<br>
+ <a href="#cups_order_t">cups_order_t</a> cupsColorOrder;<br>
+ <a href="#cups_cspace_t">cups_cspace_t</a> cupsColorSpace;<br>
unsigned cupsCompression;<br>
unsigned cupsHeight;<br>
unsigned cupsMediaType;<br>
<dt>AdvanceDistance </dt>
<dd class="description">AdvanceDistance value in points</dd>
<dt>AdvanceMedia </dt>
-<dd class="description">AdvanceMedia value (see above)</dd>
+<dd class="description">AdvanceMedia value (<a href="#cups_adv_t"><code>cups_adv_t</code></a>)</dd>
<dt>Collate </dt>
<dd class="description">Collated copies value</dd>
<dt>CutMedia </dt>
-<dd class="description">CutMedia value (see above)</dd>
+<dd class="description">CutMedia value (<a href="#cups_cut_t"><code>cups_cut_t</code></a>)</dd>
<dt>Duplex </dt>
<dd class="description">Duplexed (double-sided) value</dd>
<dt>HWResolution[2] </dt>
<dd class="description">Resolution in dots-per-inch</dd>
<dt>ImagingBoundingBox[4] </dt>
-<dd class="description">Pixel region that is painted (points)</dd>
+<dd class="description">Pixel region that is painted (points, left, bottom, right, top)</dd>
<dt>InsertSheet </dt>
<dd class="description">InsertSheet value</dd>
<dt>Jog </dt>
-<dd class="description">Jog value (see above)</dd>
+<dd class="description">Jog value (<a href="#cups_jog_t"><code>cups_jog_t</code></a>)</dd>
<dt>LeadingEdge </dt>
-<dd class="description">LeadingEdge value (see above)</dd>
+<dd class="description">LeadingEdge value (<a href="#cups_edge_t"><code>cups_edge_t</code></a>)</dd>
<dt>ManualFeed </dt>
<dd class="description">ManualFeed value</dd>
<dt>Margins[2] </dt>
<dt>NumCopies </dt>
<dd class="description">Number of copies to produce</dd>
<dt>Orientation </dt>
-<dd class="description">Orientation value (see above)</dd>
+<dd class="description">Orientation value (<a href="#cups_orient_t"><code>cups_orient_t</code></a>)</dd>
<dt>OutputFaceUp </dt>
<dd class="description">OutputFaceUp value</dd>
<dt>OutputType[64] </dt>
<dd class="description">Red, green, blue</dd>
<dt>CUPS_CSPACE_RGBA </dt>
<dd class="description">Red, green, blue, alpha</dd>
-<dt>CUPS_CSPACE_RGBW <span class="info"> CUPS 1.2 </span></dt>
+<dt>CUPS_CSPACE_RGBW <span class="info"> CUPS 1.2/Mac OS X 10.5 </span></dt>
<dd class="description">Red, green, blue, white </dd>
<dt>CUPS_CSPACE_SILVER </dt>
<dd class="description">Silver foil</dd>
</HEAD>
<BODY>
-<P>CUPS has traditionally provided a dynamic web interface
-through dedicated CGI programs that are executed when users open
-special directories on the CUPS server. Each CGI performs
-administration, class, help, job, and printer functions as
-directed by the user, but the actual programs that are run and
-functions that are available are limited to those that were
-originally designed into the scheduler.</P>
+<P>CUPS provides a dynamic web interface through dedicated CGI programs that
+are executed when users open special directories on the CUPS server. Each CGI
+performs administration, class, help, job, and printer functions as directed by
+the user, but the actual programs that are run and functions that are available
+are limited to those that were originally designed into the scheduler.</P>
-<P>Support is now available for CGI programs and specific
-scripting languages, currently Java, Perl, PHP, and Python. The
-interpreters for these languages are currently configured at
-compile time. Future versions may expand the interface to allow
-for generic support of scripting languages similar to the Apache
-"AddHandler" directive, but with external programs instead of
-modules.</P>
-
-<P>Table 1 shows the MIME media types that are reserved for the
-CGI support in CUPS. The names have been chosen to mirror those
-used by Apache:</P>
+<P>CUPS also supports CGI programs and specific scripting languages (Java, Perl,
+PHP, and Python) for pages you want to provide. The interpreters for these
+languages are currently configured at compile time and are associated with
+MIME media types. <a href="#TABLE1">Table 1</a> shows the MIME media types that
+are reserved for each type of page and are the same as those used by the Apache
+web server.</P>
<DIV CLASS="table"><TABLE SUMMARY="CGI MIME Media Types">
-<CAPTION>Table 1: CGI MIME Media Types</CAPTION>
+<CAPTION><A NAME="TABLE1">Table 1</A>: CGI MIME Media Types</CAPTION>
<TR>
<TH>MIME Media Type</TH>
<TH>Description</TH>
<P>In order to enable the corresponding type, you must create a
new <VAR>/etc/cups/cgi.types</VAR> file which maps the filename
-extensions to the appropriate MIME type, for example:</P>
+extensions to the appropriate MIME types, for example:</P>
<PRE CLASS="command">
application/x-httpd-cgi cgi
application/x-httpd-python py
</PRE>
-<P>CGI scripts/programs (application/x-httpd-cgi) also must have
-execution permissions to be treated as a CGI script or
-program.</P>
+<P>CGI scripts/programs (application/x-httpd-cgi) also must have execution
+permissions to be treated as a CGI script or program.</P>
<H2><A NAME="LIMITS">Limitations</A></H2>
lpr -o prettyprint filename
</PRE>
-<H3><A NAME="WRAP">Turning Off Text Wrapping</A><H3>
+<H3><A NAME="WRAP">Turning Off Text Wrapping</A></H3>
<P>The <CODE>-o nowrap</CODE> option disables wrapping of long lines:</P>
*
* This function is deprecated. Use @link cupsRasterReadHeader2@ instead.
*
+ * Version 1 page headers were used in CUPS 1.0 and 1.1 and contain a subset
+ * of the version 2 page header data. This function handles reading version 2
+ * page headers and copying only the version 1 data into the provided buffer.
+ *
* @deprecated@
*/
-unsigned /* O - 1 on success, 0 on fail */
+unsigned /* O - 1 on success, 0 on failure/end-of-file */
cupsRasterReadHeader(
cups_raster_t *r, /* I - Raster stream */
cups_page_header_t *h) /* I - Pointer to header data */
* @since CUPS 1.2/Mac OS X 10.5@
*/
-unsigned /* O - 1 on success, 0 on fail */
+unsigned /* O - 1 on success, 0 on failure/end-of-file */
cupsRasterReadHeader2(
cups_raster_t *r, /* I - Raster stream */
cups_page_header2_t *h) /* I - Pointer to header data */
/*
* 'cupsRasterReadPixels()' - Read raster pixels.
+ *
+ * For best performance, filters should read one or more whole lines.
+ * The "cupsBytesPerLine" value from the page header can be used to allocate
+ * the line buffer and as the number of bytes to read.
*/
unsigned /* O - Number of bytes read */
/*
* 'cupsRasterWritePixels()' - Write raster pixels.
+ *
+ * For best performance, filters should write one or more whole lines.
+ * The "cupsBytesPerLine" value from the page header can be used to allocate
+ * the line buffer and as the number of bytes to write.
*/
unsigned /* O - Number of bytes written */
* The Zebra portion of the driver has been tested with the LP-2844,
* LP-2844Z, QL-320, and QL-420 label printers; it may also work with
* other models. The driver supports EPL line mode, EPL page mode,
- * ZPL, and CPCL as defined in Zebra's on-line developer documentation.
+ * ZPL, and CPCL as defined in Zebra's online developer documentation.
*/
/*
for (job = (cupsd_job_t *)cupsArrayFirst(ActiveJobs);
job;
job = (cupsd_job_t *)cupsArrayNext(ActiveJobs))
- if (job->state_value >= IPP_JOB_HELD && job->filters[0])
+ if (job->state_value >= IPP_JOB_HELD && (job->filters[0] || job->backend))
{
for (i = 0; job->filters[i]; i ++)
if (job->filters[i] == pid)
VALUE="{SECTION=help?{?QUERY}:}" AUTOSAVE="org.cups.help" RESULTS="20"></FORM></TD>
<TD><IMG SRC="/images/right.gif" WIDTH="4" HEIGHT="36" ALT=""></TD>
</TR>
+<TR><TD COLSPAN="9"> </TD></TR>
</TABLE>
-
-<H1>{title}</H1>
<DIV CLASS="sidebar"><TABLE CLASS="inset" SUMMARY="Contents">
<TR><TD>
-<H3 CLASS="title">On-Line Help Documents</H3>
+<H3 CLASS="title">Online Help Documents</H3>
<P CLASS="l0"><A HREF="/help/{QUERY??QUERY={QUERY}:}">All Documents</A></P>
<HR>
<HR NOSHADE>:}
{HELPTITLE?<FORM ACTION="/help/{?HELPFILE}" METHOD="GET"><INPUT TYPE="HIDDEN" NAME="PRINTABLE" VALUE="YES"><INPUT TYPE="SUBMIT" VALUE="View Printable Version"></FORM>:
-<P>This is the CUPS on-line help interface. Enter search words
+<P>This is the CUPS online help interface. Enter search words
above or click on any of the documentation links to display
-on-line help information.</P>
+online help information.</P>
<P>If you are new to CUPS, read the "<a
href="/help/overview.html">Overview of CUPS</a>" page. Veteran users
projects / thirdparty / cups.git / commitdiff
