+++ /dev/null
-<HTML>
-<HEAD>
- <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2003, All Rights Reserved">
- <META NAME="DOCNUMBER" CONTENT="CUPS-SPM-1.2.0">
- <META NAME="Author" CONTENT="Easy Software Products">
- <TITLE>CUPS Software Programmers Manual</TITLE>
-</HEAD>
-<BODY>
-
-<H1 ALIGN="RIGHT">Preface</H1>
-
-<P>This software programmers manual provides software
-programming information for the Common UNIX Printing System
-("CUPS") Version 1.2.0.
-
-<EMBED SRC="system-overview.shtml">
-
-<!-- NEED 2in -->
-<H2>Document Overview</H2>
-
-<P>This software programmers manual is organized into the following sections:
-
-<UL>
- <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A>
- <LI><A HREF="#CUPS_API">2 - The CUPS API</A>
- <LI><A HREF="#WRITING_FILTERS">3 - Writing Filters</A>
- <LI><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A>
- <LI><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A>
- <LI><A HREF="#LICENSE">A - Software License Agreement</A>
- <LI><A HREF="#CONSTANTS">B - Constants</A>
- <LI><A HREF="#STRUCTURES">C - Structures</A>
- <LI><A HREF="#FUNCTIONS">D - Functions</A>
-</UL>
-
-<H2>Notation Conventions</H2>
-
-<P>Various font and syntax conventions are used in this guide. Examples and
-their meanings and uses are explained below:
-
-<CENTER><TABLE WIDTH="80%">
-<TR>
- <TH>Example</TH>
- <TD> </TD>
- <TH>Description</TH>
-</TR>
-<TR><TD> </TD></TR>
-<TR VALIGN="TOP">
- <TD><CODE>lpstat</CODE><BR>
- <CODE>lpstat(1)</CODE></TD>
-
- <TD> </TD>
-
- <TD>The names of commands; the first mention of a command or
- function in a chapter is followed by a manual page section
- number.</TD>
-</TR>
-<TR><TD> </TD></TR>
-<TR VALIGN="TOP">
- <TD><VAR>/var</VAR><BR>
- <VAR>/usr/share/cups/data/testprint.ps</VAR></TD>
-
- <TD> </TD>
-
- <TD>File and directory names.</TD>
-</TR>
-<TR><TD> </TD></TR>
-<TR VALIGN="TOP">
- <TD NOWRAP><TT>Request ID is Printer-123</TT></TD>
-
- <TD> </TD>
-
- <TD>Screen output.</TD>
-</TR>
-<TR><TD> </TD></TR>
-<TR VALIGN="TOP">
- <TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD>
-
- <TD> </TD>
-
- <TD>Literal user input; special keys like <KBD>ENTER</KBD> are
- in ALL CAPS.</TD>
-</TR>
-<TR><TD> </TD></TR>
-<TR VALIGN="TOP">
- <TD>12.3</TD>
-
- <TD> </TD>
-
- <TD>Numbers in the text are written using the period (.) to indicate
- the decimal point.</TD>
-</TR>
-</TABLE></CENTER>
-
-<!-- NEED 3in -->
-<H2>Abbreviations</H2>
-
-The following abbreviations are used throughout this manual:
-
-<UL>
-<DL>
-
- <DT>kb
- <DD>Kilobytes, or 1024 bytes<BR>
-
- <DT>Mb
- <DD>Megabytes, or 1048576 bytes<BR>
-
- <DT>Gb
- <DD>Gigabytes, or 1073741824 bytes<BR>
-
-</DL>
-</UL>
-
-<H2>Other References</H2>
-
-<UL>
-<DL>
-
- <DT>CUPS Software Administrators Manual
-
- <DD>An administration guide for the CUPS software.<BR>
-
- <DT>CUPS Software Users Manual
-
- <DD>An end-user guide for using the CUPS software.<BR>
-
-</DL>
-</UL>
-
-
-<EMBED SRC="printing-overview.shtml">
-
-
-<H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1>
-
-<P>This chapter describes the CUPS Application Programmers Interface ("API").
-
-<H2>The CUPS API Library</H2>
-
-<P>The CUPS library provides a whole collection of interfaces needed to
-support the internal needs of the CUPS software as well as the needs of
-applications, filters, printer drivers, and backends.
-
-<P>Unlike the rest of CUPS, the CUPS API library is provided under the
-GNU Library General Public License. This means that you can use the
-CUPS API library in both proprietary and open-source programs.
-
-<P>Programs that use the CUPS API library typically will include the
-<CODE><cups/cups.h></CODE> header file:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-jobid = cupsPrintFile("myprinter", "filename.ps", "title",
- num_options, options);
-</PRE></UL>
-
-<P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS API
-library:
-
-<UL><PRE>
-<B>cc -o program program.c -lcups ENTER</B>
-</PRE></UL>
-
-<P>Additional options and libraries may be required depending on the
-operating system and the location of the CUPS API library.
-
-<H3>Detecting the CUPS API Library in GNU Autoconf</H3>
-
-<P>GNU autoconf is a popular configuration tool used by many programs.
-Add the following lines to your <VAR>configure.in</VAR> file to check
-for the CUPS API library in your configuration script:
-
-<UL><PRE>
-AC_CHECK_LIB(socket,socket,
-if test "$uname" != "IRIX"; then
- LIBS="-lsocket $LIBS"
-else
- echo "Not using -lsocket since you are running IRIX."
-fi)
-AC_CHECK_LIB(nsl,gethostbyaddr,
-if test "$uname" != "IRIX"; then
- LIBS="-lnsl $LIBS"
-else
- echo "Not using -lnsl since you are running IRIX."
-fi)
-
-AC_CHECK_LIB(cups,httpConnect)
-</PRE></UL>
-
-<H2>Printing Services</H2>
-
-<P>The CUPS API library provides some basic printing services for applications
-that need to print files.
-
-<H3>Include Files</H3>
-
-<P>The include file used by all of these functions is
-<CODE><cups/cups.h></CODE>:
-
-<UL><PRE>
-#include <cups/cups.h>
-</PRE></UL>
-
-<H3>Printing a File</H3>
-
-<P>The CUPS API provides two functions for printing files. The first is
-<CODE>cupsPrintFile</CODE> which prints a single named file:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int jobid;
-
-...
-
-jobid = cupsPrintFile("<I>name</I>", "<I>filename</I>", "<I>title</I>", 0, NULL);
-</PRE></UL>
-
-<P>The <CODE>name</CODE> string is the name of the printer or class to
-print to. The <CODE>filename</CODE> string is the name of the file to
-print. The <CODE>title</CODE> string is the name of the print job, e.g.
-"Acme Word Document".
-
-<P>The return value is a unique ID number for the print job or 0 if there
-was an error.
-
-<H3>Printing Multiple Files</H3>
-
-<P>The second printing function is <CODE>cupsPrintFiles</CODE>:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int jobid;
-int num_files;
-const char *files[100];
-...
-
-jobid = cupsPrintFiles("name", <I>num_files</I>, <I>files</I>, "title", 0, NULL);
-</PRE></UL>
-
-<P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE>
-you pass a file count (<CODE>num_files</CODE>) and filename pointer array
-(<CODE>files</CODE>) for each file that you want to print.
-
-<P>As with <CODE>cupsPrintFile()</CODE> the return value is a unique ID for
-the print job.
-
-<H3>Cancelling Jobs</H3>
-
-<P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int jobid;
-int status;
-...
-
-status = cupsCancelJob("<I>name</I>", <I>jobid</I>);
-</PRE></UL>
-
-<P>The <CODE>name</CODE> string specifies the destination and is used
-to determine the server to send the request to. The <CODE>jobid</CODE>
-value is the integer returned from a previous <CODE>cupsPrintFile()</CODE>
-or <CODE>cupsPrintFiles()</CODE> call.
-
-<P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
-successfully cancelled and <CODE>0</CODE> if there was an error.
-
-<H3>Getting the Available Printers and Classes</H3>
-
-<P>The <CODE>cupsGetDests()</CODE> function can be used to get a list
-of the available printers, classes, and instances that a user has defined:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int num_dests;
-cups_dest_t *dests;
-
-...
-
-num_dests = cupsGetDests(&dests);
-</PRE></UL>
-
-<P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure which
-defines the printer or class name, the instance name (if any), if it is the
-default destination, and the default options the user has defined for the
-destination:
-
-<UL><PRE>
-typedef struct /**** Destination ****/
-{
- char *name, /* Printer or class name */
- *instance; /* Local instance name or NULL */
- int is_default; /* Is this printer the default? */
- int num_options; /* Number of options */
- cups_option_t *options; /* Options */
-} cups_dest_t;
-</PRE></UL>
-
-<P>The destinations are sorted by name and instance for your convenience.
-Once you have the list of available destinations, you can lookup a specific
-destination using the <CODE>cupsGetDest()</CODE> function:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int num_dests;
-cups_dest_t *dests;
-cups_dest_t *mydest;
-
-...
-
-mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests);
-</PRE></UL>
-
-<P>The <CODE>name</CODE> string is the printer or class name. You can pass
-a value of <CODE>NULL</CODE> to get the default destination.
-
-<P>The <CODE>instance</CODE> string is the user-defined instance name. Pass
-<CODE>NULL</CODE> to select the default instance, e.g. "name" instead of
-"name/instance".
-
-<H3>Printing with Options</H3>
-
-<P>All of the previous printing examples have passed <CODE>0</CODE> and
-<CODE>NULL</CODE> for the last two arguments to the <CODE>cupsPrintFile()</CODE>
-and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments are the
-number of options and a pointer to the option array:
-
-<UL><PRE>
-int cupsPrintFile(const char *name, const char *filename, const char *title,
- int num_options, cups_option_t *options);
-int cupsPrintFiles(const char *name, int num_files, const char **files,
- const char *title, int num_options,
- cups_option_t *options);
-</PRE></UL>
-
-<P>The <CODE>cups_option_t</CODE> structure holds each option and its value.
-These are converted as needed and passed to the CUPS server when printing a
-file.
-
-<P>The simplest way of handling options is to use the <CODE>num_options</CODE>
-and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE>
-structure described earlier:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int jobid;
-int num_dests;
-cups_dest_t *dests;
-cups_dest_t *mydest;
-
-...
-
-mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests);
-
-jobid = cupsPrintFile(mydest->name, "filename", "title",
- mydest->num_options, mydest->options);
-</PRE></UL>
-
-<P>This effectively uses the options a user has previous selected without a
-lot of code.
-
-<H3>Setting Printer Options</H3>
-
-<P>Options can also be set by your program using the <CODE>cupsAddOption()</CODE>
-function:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int num_options;
-cups_option_t *options;
-
-...
-
-num_options = 0;
-options = NULL;
-
-...
-
-num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
-num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
-num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
-num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
-</PRE></UL>
-
-<P>The <CODE>name</CODE> string is the name of the option, and the
-<CODE>value</CODE> string is the value for that option.
-
-<P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of
-options. Since adding two options with the same name overwrites the
-first value with the second, do not assume that calling
-<CODE>cupsAddOptions()</CODE> 20 times will result in 20 options.
-
-<P>Call <CODE>cupsFreeOptions</CODE> once you are done using the options:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int num_options;
-cups_option_t *options;
-
-...
-
-cupsFreeOptions(num_options, options);
-</PRE></UL>
-
-<H3>Getting Errors</H3>
-
-<P>If any of the CUPS API printing functions returns an error, the reason for
-that error can be found by calling <CODE>cupsLastError()</CODE> and
-<CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE> returns the
-last IPP error code that was encountered. <CODE>cupsErrorString()</CODE>
-converts the error code to a localized message string suitable for
-presentation to the user:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-int jobid;
-
-...
-
-if (jobid == 0)
- puts(cupsErrorString(cupsLastError()));
-</PRE></UL>
-
-<H3>Passwords and Authentication</H3>
-
-<P>CUPS supports authentication of any request, including
-submission of print jobs. The default mechanism for getting the
-username and password is to use the login user and a password
-from the console.
-
-<P>To support other types of applications, in particular
-Graphical User Interfaces ("GUIs"), the CUPS API provides
-functions to set the default username and to register a callback
-function that returns a password string.
-
-<P>The <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>
-function is used to set a password callback in your program. Only one
-function can be used at any time.
-
-<P>The <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A> function sets
-the current username for authentication. This function can be called by
-your password callback function to change the current username as needed.
-
-<P>The following example shows a simple password callback that gets a
-username and password from the user:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-const char *
-my_password_cb(const char *prompt)
-{
- char user[65];
-
-
- puts(prompt);
-
- /* Get a username from the user */
- printf("Username: ");
- if (fgets(user, sizeof(user), stdin) == NULL)
- return (NULL);
-
- /* Strip the newline from the string and set the user */
- user[strlen(user) - 1] = '\0';
-
- cupsSetUser(user);
-
- /* Use getpass() to ask for the password... */
- return (getpass("Password: "));
-}
-
-...
-
-cupsSetPasswordCB(my_password_cb);
-</PRE></UL>
-
-<P>Similarly, a GUI interface could display the prompt string in a
-window with input fields for the username and password. The username
-should probably default to the value of
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> to make things easier
-on the user.
-
-<H2>PPD Services</H2>
-
-<P>CUPS includes functions to access and manipulate PostScript Printer
-Description ("PPD") files that are used with the printer drivers in CUPS.
-
-<P>Each PPD file enumerates the available features provided by a
-printer, including conflict information for specific options (e.g.
-can't duplex output on envelopes.)
-
-<H3>Include Files</H3>
-
-<P>Include the <CODE><cups/ppd.h></CODE> header file to use the PPD
-functions:
-
-<UL><PRE>
-#include <cups/ppd.h>
-</PRE></UL>
-
-<P>This header file is also included by the
-<CODE><cups/cups.h></CODE> header file.
-
-<H3>Getting a PPD File for a Printer</H3>
-
-<P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the
-named printer or class:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-const char *filename;
-
-filename = cupsGetPPD("<I>name</I>");
-</PRE></UL>
-
-<P>The <CODE>name</CODE> string is the name of the printer or class, including
-the remote server name as appropriate (e.g. "printer@server".)
-
-<P>The return value is a pointer to a filename in static storage; this value
-is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If the printer
-or class does not exist, a <CODE>NULL</CODE> pointer will be returned.
-
-<H3>Loading a PPD File</H3>
-
-<P>The <CODE>ppdOpenFile()</CODE> function "opens" a PPD file and loads it
-into memory:
-
-<UL><PRE>
-#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-ppd = ppdOpenFile("<I>filename</I>");
-</PRE></UL>
-
-<P>The <CODE>filename</CODE> string is the name of the file to load, such as
-the value returned by the <CODE>cupsGetPPD()</CODE> function.
-
-<P>The return value is a pointer to a structure describing the contents of the
-PPD file or NULL if the PPD file could not be read.
-
-<H3>Freeing PPD File Information</H3>
-
-<P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE> function
-to free all memory that has been used:
-
-<UL><PRE>
-#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-...
-
-ppdClose(ppd);
-</PRE></UL>
-
-<H3>The PPD File Structure</H3>
-
-<P>Each PPD file contains a number of capability attributes, printer options,
-and conflict definitions. The page size options also include the physical
-margins for the printer and the minimum and maximum sizes for the printer.
-All of this information is stored in the <CODE>ppd_file_t</CODE> structure.
-
-<H4>Capabilities</H4>
-
-<P>Each PPD file contains a number of informational attributes that
-describe the capabilities of the printer. These are provided in the
-<CODE>ppd_file_t</CODE> structure in the following members:
-
-<CENTER><TABLE WIDTH="80%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD><CODE>accurate_screens</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>1 = supports accurate screens</TD>
-</TR>
-<TR>
- <TD><CODE>color_device</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>1 = color device</TD>
-</TR>
-<TR>
- <TD><CODE>colorspace</CODE></TD>
- <TD><CODE>ppd_cs_t</CODE></TD>
- <TD>Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY,
- PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N</TD>
-</TR>
-<TR>
- <TD><CODE>contone_only</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>1 = printer is continuous tone only</TD>
-</TR>
-<TR>
- <TD><CODE>num_emulations<BR>
- emulations</CODE></TD>
- <TD><CODE>int<BR>
- ppd_emul_t *</CODE></TD>
- <TD>Emulations supported by the printer</TD>
-</TR>
-<TR>
- <TD><CODE>flip_duplex</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>1 = need to flip odd pages when duplexing</TD>
-</TR>
-<TR>
- <TD><CODE>num_fonts<BR>
- fonts</CODE></TD>
- <TD><CODE>int<BR>
- char **</CODE></TD>
- <TD>The fonts available on the printer.</TD>
-</TR>
-<TR>
- <TD><CODE>jcl_begin<BR>
- jcl_ps<BR>
- jcl_end</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>Job Control Language commands for PostScript output</TD>
-</TR>
-<TR>
- <TD><CODE>landscape</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>Landscape orientation, -90 or 90 degrees</TD>
-</TR>
-<TR>
- <TD><CODE>lang_encoding</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The character used for the option strings</TD>
-</TR>
-<TR>
- <TD><CODE>lang_version</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The language used for the options strings (English, French, etc.)</TD>
-</TR>
-<TR>
- <TD><CODE>language_level</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>PostScript language level, 1 to 3</TD>
-</TR>
-<TR>
- <TD><CODE>manual_copies</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>1 = Copies are done manually</TD>
-</TR>
-<TR>
- <TD><CODE>model_number</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>Driver-specific model number.</TD>
-</TR>
-<TR>
- <TD><CODE>patches</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>Patch commands to send to the printer</TD>
-</TR>
-<TR>
- <TD><CODE>manufacturer</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The Manufacturer attribute from the PPD file, if any</TD>
-</TR>
-<TR>
- <TD><CODE>modelname</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The ModelName attribute from the PPD file</TD>
-</TR>
-<TR>
- <TD><CODE>nickname</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The NickName attribute from the PPD file, if any</TD>
-</TR>
-<TR>
- <TD><CODE>product</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The Product attribute from the PPD file, if any</TD>
-</TR>
-<TR>
- <TD><CODE>shortnickname</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The ShortNickName attribute from the PPD file, if any</TD>
-</TR>
-<TR>
- <TD><CODE>throughput</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>Number of pages per minute</TD>
-</TR>
-<TR>
- <TD><CODE>ttrasterizer</CODE></TD>
- <TD><CODE>char *</CODE></TD>
- <TD>The TruType font rasterizer (Type42)</TD>
-</TR>
-<TR>
- <TD><CODE>variable_sizes</CODE></TD>
- <TD><CODE>int</CODE></TD>
- <TD>1 = supports variable sizes</TD>
-</TR>
-</TABLE></CENTER>
-
-<H4>Options and Groups</H4>
-
-<P>PPD files support multiple options, which are stored in
-<CODE>ppd_option_t</CODE> and <CODE>ppd_choice_t</CODE> structures by
-the PPD functions.
-
-<P>Each option in turn is associated with a group
-stored in the <CODE>ppd_group_t</CODE> structure. Groups can be
-specified in the PPD file; if an option is not associated with a group
-then it is put in a "General" or "Extra" group depending on the option.
-
-<P>Groups can also have sub-groups; CUPS currently limits the depth of
-sub-groups to 1 level to reduce programming complexity.
-
-<H4>Conflicts</H4>
-
-<P>PPD files support specification of conflict conditions between
-different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE>
-structures which specify the options that conflict with each other.
-
-<H4>Page Sizes</H4>
-
-<P>PPD files specify all of the available pages sizes and the physical
-margins associated with them. These sizes are stored in
-<CODE>ppd_size_t</CODE> structures and are available in the
-<CODE>num_sizes</CODE> and <CODE>sizes</CODE> members of the
-<CODE>ppd_file_t</CODE> structure. You can lookup a particular page size
-with the <CODE>ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and
-<CODE>ppdPageSize()</CODE> functions:
-
-<UL><PRE>
-#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-ppd_size_t *size;
-float width;
-float length;
-
-...
-
-size = ppdPageSize(ppd, "<I>size</I>");
-width = ppdPageWidth(ppd, "<I>size</I>");
-length = ppdPageLength(ppd, "<I>size</I>");
-</PRE></UL>
-
-<P>The <CODE>size</CODE> string is the named page size option. The
-width and length are in points; there are 72 points per inch. The
-<CODE>ppd_size_t</CODE> structure contains the width, length, and
-margin information:
-
-<UL><PRE>
-typedef struct /**** Page Sizes ****/
-{
- int marked; /* Page size selected? */
- char name[41]; /* Media size option */
- float width, /* Width of media in points */
- length, /* Length of media in points */
- left, /* Left printable margin in points */
- bottom, /* Bottom printable margin in points */
- right, /* Right printable margin in points */
- top; /* Top printable margin in points */
-} ppd_size_t;
-</PRE></UL>
-
-<H4>Custom Page Sizes</H4>
-
-<P>Besides the standard page sizes listed in a PPD file, some printers
-support variable or custom page sizes. If <CODE>variables_sizes</CODE>
-is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and
-<CODE>custom_margins</CODE> members of the <CODE>ppd_file_t</CODE>
-structure define the limits of the variable sizes.
-
-<P>To get the resulting media size, use a page size string of
-<CODE>Custom.<I>width</I>x<I>length</I></CODE>, where <CODE>width</CODE>
-and <CODE>length</CODE> are integer values in points:
-
-<UL><PRE>
-Custom.612x792 [8.5 inches wide, 11 inches long]
-Custom.1224x792 [17 inches wide, 11 inches long]
-</PRE></UL>
-
-<H3>Marking Options</H3>
-
-<P>Before marking any user-defined options, call the <CODE>ppdMarkDefaults()</CODE>
-function to mark the default options from the PPD file:
-
-<UL><PRE>
-#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-
-...
-
-ppdMarkDefaults(ppd);
-</PRE></UL>
-
-<P>Then call the <CODE>ppdMarkOption()</CODE> function to mark individual
-options:
-
-<UL><PRE>
-#include <cups/ppd.h>
-
-...
-
-ppd_file_t *ppd;
-int conflicts;
-
-...
-
-conflicts = ppdMarkOption(ppd, "<I>name</I>", "<I>value</I>");
-</PRE></UL>
-
-<P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a
-particular option and choice, respectively. The return value is 0
-if there are not conflicts created by the selection.
-
-<P>CUPS also provides a convenience function for marking all options
-in the <CODE>cups_option_t</CODE> structure:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-ppd_file_t *ppd;
-int num_options;
-cups_option_t *options;
-int conflicts;
-
-...
-
-conflicts = cupsMarkOptions(ppd, num_options, options);
-</PRE></UL>
-
-<P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the
-IPP job template attributes to PPD options. The return value is the number
-of conflicts present.
-
-<H3>Checking for Conflicts</H3>
-
-<P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE>
-functions return the number of conflicts with the currently marked options.
-
-<P>Call the <CODE>ppdConflicts()</CODE> function to get the number of
-conflicts after you have marked all of the options:
-
-<UL><PRE>
-#include <cups/cups.h>
-
-...
-
-ppd_file_t *ppd;
-int conflicts;
-
-...
-
-conflicts = ppdConflicts(ppd);
-</PRE></UL>
-
-<P>The return value is the number of conflicting options, or 0 if there
-are no conflicts.
-
-
-<H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
-
-<P>This chapter describes how to write a file filter for CUPS.
-
-<H2>Overview</H2>
-
-<P>File filters are programs that convert from one or more MIME types to
-another type. Filters use a common command-line and environment interface
-that allows them to be joined as needed to print files to any type of
-printer.
-
-<H3>Security Considerations</H3>
-
-<P>Filters are normally run as a non-priviledged user, so the major
-security consideration is resource utilization - filters should not
-depend on unlimited amounts of memory and disk space.
-
-<H3>Users and Groups</H3>
-
-<P>The default CUPS configuration runs filters as user "lp" and group "other".
-
-<H3>Temporary Files</H3>
-
-<P>Temporary files should be created in the directory specified by the
-"TMPDIR" environment variable. The
-<A HREF="#cupsTempFile"><CODE>cupsTempFile()</CODE></A> function can be
-used to safely choose temporary files in this directory.
-
-<H3>Sending Messages to the User</H3>
-
-<P>The CUPS scheduler collects messages sent to the standard error file
-by the filter. These messages are relayed to the user based upon the
-scheduler <CODE>LogLevel</CODE> directive.
-
-<P>The type of message is determined by an initial prefix sent on each
-line:
-
-<UL>
-
- <LI><CODE>DEBUG:</CODE> - a debug message
-
- <LI><CODE>INFO:</CODE> - an informational message
-
- <LI><CODE>WARNING:</CODE> - a warning message
-
- <LI><CODE>ERROR:</CODE> - an error message
-
- <LI><CODE>PAGE:</CODE> - a page accounting message
-
-</UL>
-
-<P>If the line of text does not begin with any of the above prefixes, it
-is treated as a debug message. Text following the prefix is copied to the
-<CODE>printer-state-message</CODE> attribute for the printer, and also
-added to the <VAR>error_log</VAR> unless it is an informational or page
-accounting message.
-
-<H3>Page Accounting</H3>
-
-<P>Page accounting messages are used to inform the server when one or more
-pages are printed. Each line has the form:
-
-<UL><PRE>
-PAGE: page-number copy-count
-</PRE></UL>
-
-<P>The <I>page-number</I> field is the current page number, starting at 1.
-The <I>copy-count</I> field specifies the number of copies of that page
-that was produced.
-
-<P>Page account messages are added to the <VAR>page_log</VAR> file and
-cause the <CODE>job-sheets-completed</CODE> attribute to be updated for
-the job.
-
-<H3>Command-Line Arguments</H3>
-
-<P>Every filter accepts exactly 6 or 7 command-line arguments:
-
-<UL><PRE>
-printer job user title copies options [filename]
-</PRE>
-
- <LI><CODE>printer</CODE> - The name of the printer queue (normally
- this is the name of the program being run)
-
- <LI><CODE>job</CODE> - The numeric job ID for the job being
- printed
-
- <LI><CODE>user</CODE> - The string from the
- <CODE>originating-user-name</CODE> attribute
-
- <LI><CODE>title</CODE> - The string from the
- <CODE>job-name</CODE> attribute
-
- <LI><CODE>copies</CODE> - The numeric value from the
- <CODE>number-copies</CODE> attribute
-
- <LI><CODE>options</CODE> - String representations of the
- job template attributes, separated by spaces. Boolean attributes
- are provided as "name" for true values and "noname" for false
- values. All other attributes are provided as "name=value" for
- single-valued attributes and "name=value1,value2,...,valueN" for
- set attributes
-
- <LI><CODE>filename</CODE> - The request file
-
-</UL>
-
-<P>The <I>filename</I> argument is only provided to the first filter in the
-chain; all filters <B>must</B> be prepared to read the print file from
-the standard input if the <I>filename</I> argument is omitted.
-
-<H3>Copy Generation</H3>
-
-<P>The <I>copies</I> argument specifies the number of copies to produce
-of the input file. In general, you should only generate copies if the
-<I>filename</I> argument is supplied. The only exception to this are
-filters that produce device-independent PostScript output (without any
-printer commands from the printer's PPD file), since the PostScript
-filter <CODE>pstops</CODE> is responsible for copy generation.
-
-<H3>Environment Variables</H3>
-
-<P>Every filter receives a fixed set of environment variables that can
-be used by the filter:
-
-<UL>
-
- <LI><CODE>CHARSET</CODE> - The character set used by the client for
- this print file
-
- <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as
- "application/postscript"
-
- <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files
-
- <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration
- files
-
- <LI><CODE>DEVICE_URI</CODE> - The output device URI
-
- <LI><CODE>LANG</CODE> - The language used by the client for
- this print file
-
- <LI><CODE>PATH</CODE> - The execution path exported to the filter
-
- <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file
-
- <LI><CODE>PRINTER</CODE> - The name of the printer queue
-
- <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter
- should use
-
- <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically
- "CUPS/1.1"
-
- <LI><CODE>TZ</CODE> - The local timezone
-
- <LI><CODE>USER</CODE> - The name of the current user
-
-</UL>
-
-<H2>Dissecting the HP-GL/2 Filter</H2>
-
-<P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a
-complex program that converts HP-GL/2 files into device-independent PostScript
-output. Since it produces device-independent PostScript output, it does not
-need to handle copy generation or writing printer options from the printer's
-PPD file.
-
-<H3>Initializing the Filter</H3>
-
-<P>The first task of any filter is to ensure that the correct number of
-command-line arguments are present:
-
-<UL><PRE>
-if (argc < 6 || argc > 7)
-{
- fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr);
- return (1);
-}
-</PRE></UL>
-
-<P>After this you open the print file or read from the standard input
-as needed:
-
-<UL><PRE>
-FILE *fp;
-
-/*
- * If we have 7 arguments, print the file named on the command-line.
- * Otherwise, send stdin instead...
- */
-
-if (argc == 6)
- fp = stdin;
-else
-{
- /*
- * Try to open the print file...
- */
-
- if ((fp = fopen(argv[6], "rb")) == NULL)
- {
- perror("ERROR: unable to open print file - ");
- return (1);
- }
-}
-</PRE></UL>
-
-<P>Once the print file has been opened, options can be processed using
-the <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A> and
-<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A> functions:
-
-<UL><PRE>
-int num_options;
-cups_option_t *options;
-const char *val;
-
-/*
- * Process command-line options and write the prolog...
- */
-
-options = NULL;
-num_options = cupsParseOptions(argv[5], 0, &options);
-
-if ((val = cupsGetOption("blackplot", num_options, options)) != NULL)
- shading = 0;
-
-if ((val = cupsGetOption("fitplot", num_options, options)) != NULL)
- FitPlot = 1;
-
-if ((val = cupsGetOption("penwidth", num_options, options)) != NULL)
- PenWidth = (float)atoi(val) * 0.001f;
-</PRE></UL>
-
-<P>After the options have been processed, the filter writes PostScript code
-to the standard output based on the print file, closes the print file (as
-needed), and returns 0 to the scheduler.
-
-<H2>PostScript Output</H2>
-
-<P>Filters that produce PostScript output must generate output conforming
-to the Adobe Document Structuring Conventions, 3.0. In general this means
-the beginning of each file must begin with:
-
-<UL><PRE>
-%!PS-Adobe-3.0
-%%BoundingBox: left bottom right top
-%%Pages: (atend)
-%%EndComments
-</PRE></UL>
-
-<P>The <I>left</I>, <I>bottom</I>, <I>right</I>, and <I>top</I> values
-are integers in points from the lower-lefthand corner of the page.
-
-<P>Pages must be surrounded by:
-
-<UL><PRE>
-%%Page: number number
-gsave
-...
-grestore
-showpage
-</PRE></UL>
-
-<P>And the end of each file must contain:
-
-<UL><PRE>
-%%Trailer
-%%Pages: number-pages
-%%EOF
-</PRE></UL>
-
-<P>These comments allow the PostScript filter to correctly perform page
-accounting, copy generation, N-up printing, and so forth.
-
-<H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A></H1>
-
-<P>This chapter discusses how to write a printer driver, which is a
-special filter program that converts CUPS raster data into the
-appropriate commands and data required for a printer.
-
-<H2>Overview</H2>
-
-<P>Raster printers utilitize PPD files that specify one or more
-device-specific filters that handle converting print files for the
-printer. The simplest raster printer drivers provide a single filter
-that converts CUPS raster data to the printer's native format.
-
-<H3>CUPS Raster Data</H3>
-
-<P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists of
-a stream of raster page descriptions produced by one of the RIP filters,
-such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.
-
-<P>Each page of data begins with a page dictionary structure called
-<A HREF="#cups_raster_header_t"><CODE>cups_raster_header_t</CODE></A>. This
-structure contains the colorspace, bits per color, media size, media type,
-hardware resolution, and so forth.
-
-<P>After the page dictionary comes the page data which is a full-resolution,
-uncompressed bitmap representing the page in the printer's output colorspace.
-
-<H3>Page Accounting</H3>
-
-<P>Printer drivers must handle all page accounting. This means they must
-send "PAGE:" messages to the standard error file for each page (and in many
-cases, copy) sent to the printer.
-
-<H3>Color Management</H3>
-
-<P>Printer drivers can implement their color management via the
-<CODE>cupsColorProfile</CODE> attributes in the PPD file or internally
-in the driver from a device-independent colorspace. In general, color
-management performed by the RIP filters is more efficient than that
-performed inside printer drivers.
-
-<P>For example, the <CODE>pstoraster</CODE> filter often only has to
-perform a color conversion once each time the color is used for
-multiple output pixels, while the raster filter must convert every
-pixel on the page.
-
-<H3>Device and Bitmap Variables</H3>
-
-<P>Besides the standard PostScript page device dictionary variables defined
-in the Adobe PostScript Level 3 reference manual, the CUPS filters support
-additional variables that are passed in the page device dictionary header for
-the page and in some cases control the type of raster data that is generated:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Variable</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>cupsWidth</TD>
- <TD>read-only integer</TD>
- <TD>Width of bitmap in pixels</TD>
-</TR>
-<TR>
- <TD>cupsHeight</TD>
- <TD>read-only integer </TD>
- <TD>Height of bitmap in pixels</TD>
-</TR>
-<TR>
- <TD>cupsMediaType</TD>
- <TD>read-write integer</TD>
- <TD>Device-specific media type code</TD>
-</TR>
-<TR>
- <TD>cupsBitsPerColor</TD>
- <TD>read-write integer</TD>
- <TD>Number of bits per color; 1, 2, 4, and 8 are currently
- supported</TD>
-</TR>
-<TR>
- <TD>cupsBitsPerPixel</TD>
- <TD>read-only integer </TD>
- <TD>Number of bits per pixel; 1 to 32</TD>
-</TR>
-<TR>
- <TD>cupsBytesPerLine</TD>
- <TD>read-only integer</TD>
- <TD>Number of bytes per line of raster graphics</TD>
-</TR>
-<TR>
- <TD>cupsColorOrder</TD>
- <TD>read-write enum</TD>
- <TD>The order of color values in the bitmap:
- <UL>
- <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK CMYK CMYK
- <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK
- <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ...
- </UL>
- </TD>
-</TR>
-<TR>
- <TD>cupsColorSpace</TD>
- <TD>read-write enum</TD>
- <TD>The colorspace of the bitmap:
- <UL>
- <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)
- <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue
- <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha
- <LI><CODE>CUPS_CSPACE_K</CODE> - Black
- <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow
- <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan
- <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black
- <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black
- <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow
- <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
- light cyan, light magenta
- <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta,
- metallic cyan, black
- <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta,
- metallic cyan, metallic grey (silver)
- <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)
- <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)
- <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)
- </UL>
- </TD>
-</TR>
-<TR>
- <TD>cupsCompression</TD>
- <TD>read-write integer</TD>
- <TD>Device-specific compression type code</TD>
-</TR>
-<TR>
- <TD>cupsRowCount</TD>
- <TD>read-write integer</TD>
- <TD>Device-specific row count value</TD>
-</TR>
-<TR>
- <TD>cupsRowFeed</TD>
- <TD>read-write integer</TD>
- <TD>Device-specific row feed value</TD>
-</TR>
-<TR>
- <TD>cupsRowStep</TD>
- <TD>read-write integer</TD>
- <TD>Device-specific row step value</TD>
-</TR>
-</TABLE></CENTER>
-
-<P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit per
-color are transmitted to the raster driver in KCMY colorspace; the driver
-is responsible for producing the correct separation of normal and light
-cyan and magenta inks.
-
-<H2>Dissecting the HP-PCL Driver</H2>
-
-<P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>) converts
-bitmap data from the raster filters into HP-PCL commands for most
-PCL-compatible printers. The actual format of the raster data is controlled
-by the PPD file being used - <VAR>deskjet.ppd</VAR> or <VAR>laserjet.ppd</VAR>.
-
-<H3>PPD Files</H3>
-
-<P>PPD files play an important part of all raster printer drivers. Options
-defined in the PPD file contain PostScript commands that control the raster
-data that is sent to the printer driver.
-
-<P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>,
-<CODE>InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>,
-and <CODE>Resolution</CODE> options. Each option is shown using the
-standard PPD format:
-
-<UL><PRE>
-*OpenUI *PageSize/Media Size: PickOne
-*OrderDependency: 10 AnySetup *PageSize
-*DefaultPageSize: Letter
-*PageSize Letter/US Letter: "<<
-/PageSize [612 792]
-/ImagingBBox null
->> setpagedevice"
-*End
-*PageSize Legal/US Legal: "<<
-/PageSize [612 1008]
-/ImagingBBox null
->> setpagedevice"
-*End
-*PageSize A4/A4: "<<
-/PageSize [595 842]
-/ImagingBBox null
->> setpagedevice"
-*End
-*CloseUI: *PageSize
-</PRE></UL>
-
-<P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first
-name is the option with an asterisk (*) in front of it. The first name is
-usually followed by a slash (/) and a human-readable version of the
-option name.
-
-<P>Every option <B>must</B> have a default value, specified using the
-<CODE>Default<I>Option</I></CODE> keyword.
-
-<P>Each option begins with the option name followed by the computer and
-human-readable values. The PostScript commands follow these inside double
-quotes. PostScript commands can be provided on a single line:
-
-<UL><PRE>
-*PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice"
-</PRE></UL>
-
-<P>or broken down on separate lines using the <CODE>End</CODE> keyword to
-terminate them:
-
-<UL><PRE>
-*PageSize A4/A4: "<<
-/PageSize [595 842]
-/ImagingBBox null
->> setpagedevice"
-*End
-</PRE></UL>
-
-<P>The choice of the two formats is usually esthetic. However, each line in
-a PPD file must not exceed 255 characters, so if your PostScript commands are
-long you may need to break them up on separate lines.
-
-<H3>Reading Raster Data</H3>
-
-<P>As with any filter, your printer driver should handle raster data from
-a filename specified on the command-line or from the standard input. The
-<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function opens
-a raster stream for printing:
-
-<UL><PRE>
-int fd; /* File descriptor */
-cups_raster_t *ras; /* Raster stream for printing */
-
-
-/*
- * Check for valid arguments...
- */
-
-if (argc < 6 || argc > 7)
-{
- /*
- * We don't have the correct number of arguments; write an error message
- * and return.
- */
-
- fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr);
- return (1);
-}
-
-/*
- * Open the page stream...
- */
-
-if (argc == 7)
-{
- if ((fd = open(argv[6], O_RDONLY)) == -1)
- {
- perror("ERROR: Unable to open raster file - ");
- sleep(1);
- return (1);
- }
-}
-else
- fd = 0;
-
-ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
-</PRE></UL>
-
-<P>Once you have opened the raster stream you just need to read each
-page and print it:
-
-<UL><PRE>
-cups_raster_header_t header;
-int y;
-unsigned char data[8192];
-
-while (cupsRasterReadHeader(ras, &header))
-{
- ... initialize the printer ...
- for (y = header.cupsHeight; y > 0; y ++)
- {
- cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
- ... send raster line to printer ...
- }
-}
-</PRE></UL>
-
-<P>After you have processed all pages, close the raster stream and
-return:
-
-<UL><PRE>
-cupsRasterClose(ras);
-
-return (0);
-</PRE></UL>
-
-<H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
-
-<P>This chapter describes how to write a backend for CUPS. Backends
-communicate directly with printers and allow printer drivers and
-filters to send data using any type of connection transparently.
-
-<H2>Overview</H2>
-
-<P>Backends are special filters that communicate with printers directly.
-They are treated slightly differently than filters, however, and have some
-unique requirements.
-
-<H3>Security Considerations</H3>
-
-<P>Backends are run as the root user, so special care must be taken to
-avoid potential security violations. In particular, remember that a backend
-will be able to manipulate disk files, devices, and other resources that
-potentially could damage a system or printer.
-
-<H3>Command-Line Arguments</H3>
-
-<P>Besides the standard filter arguments, backends are also run with no
-arguments to get a list of available devices. This discovery process is
-described later in this chapter.
-
-<H3>Copy Generation</H3>
-
-<P>Like filters, backends should send multiple copies of the print file only
-if a filename is supplied on the command-line. Otherwise the backend should
-assume that the upstream filter has already added the necessary commands or
-data to produce the multiple copies.
-
-<H3>Page Accounting</H3>
-
-<P>Backend filters generally do not do page accounting, however they should
-at a minimum produce a single page message for each copy that is produced
-when a filename is present on the command-line. This is because the user
-selected "raw" printing and no other accounting information is possible.
-
-<H3>Exclusive Access</H3>
-
-<P>Backends that talk to local character or block devices should open the
-device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate with other
-printers defined for the same device.
-
-<H3>Retries</H3>
-
-<P>All backends <B>must</B> retry connections to the device. This
-includes backends that talk to local character or block devices, as the
-user may define more than one printer queue pointing at the same
-physical device.
-
-<P>To prevent excess CPU utilitization, the backend should go to sleep
-for an amount of time between retries; the CUPS-supplied backends retry
-once every 30 seconds.
-
-<H2>Dissecting the Serial Port Backend</H2>
-
-<P>The serial port backend provides support for serial printers. Since
-it does everything a good backend needs to do, it provides an excellent
-example of what to do.
-
-<H3>Supporting Device Discovery</H3>
-
-<P>As previously noted, backends are special filter programs that talk
-to printer devices. Another task a backend must perform is to list the
-available devices it supports. The backend lists the available devices
-when no additioanl arguments are supplied on the command-line (i.e.
-just the command name...)
-
-<P>The serial backend lists devices by looking at serial port files in the
-<VAR>/dev</VAR> directory, by consulting a hardware inventory (IRIX), and
-in some cases by trying to open the ports to see if they actually exist.
-
-<P>Once it finds a serial port it writes a single line for each port to
-the standard error file. Each line looks like this:
-
-<UL><PRE>
-serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
-</PRE></UL>
-
-<P>The first word "serial" is the <I>device class</I>; this identifies the
-class of device which can be used to categorize it in user interfaces. CUPS
-currently recognizes the following classes:
-
-<UL>
-
- <LI>"file" - a disk file.
-
- <LI>"direct" - a parallel or fixed-rate serial data port,
- currently used for Centronics, IEEE-1284, and USB printer
- ports.
-
- <LI>"serial" - a variable-rate serial port.
-
- <LI>"network" - a network connection, typically via AppSocket,
- HTTP, IPP, LPD, or SMB/CIFS protocols.
-
-</UL>
-
-<P>After the device class is the <I>device URI</I>, in this case
-"serial:/dev/ttyS0?baud=115200". This is the URI that should be used by
-the user to select this port. For serial ports, the "baud=115200"
-specifies the maximum baud rate supported by the port - the actual
-value will vary based on the speed the user selects for the printer.
-
-<P>The last two strings are the model and description for the port. The
-"Unknown" string means that the printer model is unknown - some devices
-are able to provide a make and model such as "HP DeskJet" that allows
-users and software to choose an appropriate printer driver more easily.
-Both the model and description must be enclosed inside double quotes.
-
-<H3>Opening the Serial Port</H3>
-
-<P>As noted previously, all backends should open device files in exclusive
-mode, and retry as needed until the port is available. The serial port does
-this using a <CODE>do-while</CODE> loop:
-
-<UL><PRE>
-do
-{
- if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
- {
- if (errno == EBUSY)
- {
- fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr);
- sleep(30);
- }
- else
- {
- perror("ERROR: Unable to open serial port device file");
- return (1);
- }
- }
-}
-while (fd < 0);
-</PRE></UL>
-
-<P>If the port is busy or in use by another process, the backend will
-go to sleep for 30 seconds and try again. If another error is detected
-a message is sent to the user and the backend aborts the print job
-until the problem can be corrected.
-
-<H3>Writing Data to the Port</H3>
-
-<P>Network and character devices pose an interesting problem when writing
-data to the port - they may not be able to write all of the bytes in your
-buffer before returning. To work around this problem you must loop until
-all bytes have been written:
-
-<UL><PRE>
-while (nbytes > 0)
-{
- if ((wbytes = write(fd, bufptr, nbytes)) < 0)
- if (errno == ENOTTY)
- wbytes = write(fd, bufptr, nbytes);
-
- if (wbytes < 0)
- {
- perror("ERROR: Unable to send print file to printer");
- break;
- }
-
- nbytes -= wbytes;
- bufptr += wbytes;
-}
-</PRE></UL>
-
-<P>The check for the <CODE>ENOTTY</CODE> error is needed on some platforms
-to clear an error from a previous <CODE>ioctl()</CODE> call.
-
-<H3>Finishing Up</H3>
-
-<P>Once you have sent the print file, return 0 if the file printed
-successfully or 1 if it did not. This will allow the scheduler to stop
-the print job if there is a device error, preserving the print job for
-later printing once the problem has been corrected.
-
-<H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
-
-<EMBED SRC="../LICENSE.html">
-
-
-<H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1>
-
-<P>This appendix lists all of the constants that are defined by the CUPS
-API.
-
-<H2>CUPS Constants</H2>
-
-<H3>Version Number</H3>
-
-<P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number
-representing the API version number. The current version number is
-1.0100 which represents CUPS version 1.1.0.
-
-<H3>Printer Capabilities</H3>
-
-<P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for
-printers and classes:
-
-<UL>
-
- <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.
-
- <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.
-
- <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.
-
- <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.
-
- <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.
-
- <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.
-
- <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.
-
- <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple
- copies on its own.
-
- <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.
-
- <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.
-
- <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.
-
- <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.
-
- <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.
-
- <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up
- to 9x14 inches.
-
- <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media
- from 9x14 to 18x24 inches.
-
- <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media
- larger than 18x24 inches.
-
- <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on
- variable or custom media sizes.
-
- <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.
-
- <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability
- and option bits.
-
-</UL>
-
-<H3>Encodings</H3>
-
-<P>CUPS defines the following character set encoding constants:
-
-<UL>
-
- <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.
-
- <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.
-
- <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.
-
- <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.
-
- <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.
-
- <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.
-
- <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.
-
- <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.
-
- <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.
-
- <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.
-
- <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.
-
- <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.
-
- <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.
-
- <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.
-
- <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.
-
- <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.
-
- <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.
-
- <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.
-
- <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.
-
- <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.
-
- <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.
-
- <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.
-
- <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.
-
- <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.
-
- <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.
-
- <LI><CODE>CUPS_KOI8_R</CODE> - Russian code page koi8-r.
-
- <LI><CODE>CUPS_KOI8_U</CODE> - Ukrainian code page koi8-r.
-
-</UL>
-
-<H2>HTTP Constants</H2>
-
-<H3>Limits</H3>
-
-<P>The following constants define the limits for strings:
-
-<UL>
-
- <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.
-
- <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.
-
- <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.
-
- <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.
-
-</UL>
-
-<H3>Status Codes</H3>
-
-<P>The following status codes can be returned by <CODE>httpUpdate()</CODE>:
-
-<UL>
-
- <LI><CODE>HTTP_ERROR</CODE> - A network error occurred
-
- <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy
-
- <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was successful
-
- <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful
-
- <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful
-
- <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't authoritative
-
- <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command
-
- <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated
-
- <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was recieved/sent
-
- <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request
-
- <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently
-
- <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily
-
- <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...
-
- <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified
-
- <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI
-
- <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request
-
- <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host
-
- <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required
-
- <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI
-
- <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found
-
- <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed
-
- <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable
-
- <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is Required
-
- <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out
-
- <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting
-
- <LI><CODE>HTTP_GONE</CODE> - Server has gone away
-
- <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is required
-
- <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed
-
- <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large
-
- <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long
-
- <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type is unsupported
-
- <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error
-
- <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented
-
- <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway
-
- <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable
-
- <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out
-
- <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported
-
-</UL>
-
-<H3>Fields</H3>
-
-<P>The following fields are indices for each of the standard HTTP fields in
-HTTP 1/1:
-
-<UL>
-
- <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language
-
- <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges
-
- <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization
-
- <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection
-
- <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding
-
- <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language
-
- <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length
-
- <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location
-
- <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5
-
- <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range
-
- <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type
-
- <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version
-
- <LI><CODE>HTTP_FIELD_DATE</CODE> - Date
-
- <LI><CODE>HTTP_FIELD_HOST</CODE> - Host
-
- <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since
-
- <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since
-
- <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive
-
- <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified
-
- <LI><CODE>HTTP_FIELD_LINK</CODE> - Link
-
- <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location
-
- <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range
-
- <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer
-
- <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After
-
- <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding
-
- <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade
-
- <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent
-
- <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate
-
-
-</UL>
-
-<H2>IPP Constants</H2>
-
-<H3>Limits</H3>
-
-<P>The following constants define array limits for IPP data:
-
-<UL>
-
- <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name
-
- <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values
- that can be read in a request.
-
-</UL>
-
-<H3>Tags</H3>
-
-<UL>
-
- <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
- used to separate groups of attributes
-
- <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation
-
- <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job
-
- <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end
-
- <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer
-
- <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type unsupported_group
-
- <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type unsupported_value
-
- <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default
-
- <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown
-
- <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue
-
- <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type notsettable
-
- <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr
-
- <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue
-
- <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer
-
- <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean
-
- <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum
-
- <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string
-
- <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date
-
- <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution
-
- <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range
-
- <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection
-
- <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang
-
- <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang
-
- <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text
-
- <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name
-
- <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword
-
- <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri
-
- <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme
-
- <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset
-
- <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language
-
- <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype
-
-</UL>
-
-<H3>Resolution Units</H3>
-
-<P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE> constants
-specify dots per inch and dots per centimeter, respectively.
-
-<H3>Finishings</H3>
-
-<P>The finishing values specify special finishing operations to be
-performed on the job.
-
-<UL>
-
- <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing
-
- <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job
-
- <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job
-
- <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job
-
- <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job
-
-</UL>
-
-<H3>Orientations</H3>
-
-<P>The orientation values specify the orientation of the job.
-
-<UL>
-
- <LI><CODE>IPP_PORTRAIT</CODE> - No rotation
-
- <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise
-
- <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise
-
- <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees
-
-</UL>
-
-<H3>Qualities</H3>
-
-<P>The quality values specify the desired quality of the print.
-<UL>
-
- <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality
-
- <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality
-
- <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality
-
-</UL>
-
-<H3>Job States</H3>
-
-<P>The job state values are used to represent the current job state.
-
-<UL>
-
- <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending
-
- <LI><CODE>IPP_JOB_HELD</CODE> - Job is held
-
- <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing
-
- <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped
-
- <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled
-
- <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted
-
- <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed
-
-</UL>
-
-<H3>Printer States</H3>
-
-<P>The printer state values are used to represent the current printer
-state.
-
-<UL>
-
- <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle
-
- <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing
-
- <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped
-
-</UL>
-
-<H3>Operations</H3>
-
-<P>The operation values represent the available IPP operations.
-
-<UL>
-
- <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file
-
- <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI
-
- <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes
-
- <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job
-
- <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job
-
- <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job
-
- <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job
-
- <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes
-
- <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs
-
- <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes
-
- <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job
-
- <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job
-
- <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job
-
- <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer
-
- <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer
-
- <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue
-
- <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes
-
- <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes
-
- <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer supported values
-
- <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination
-
- <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers
-
- <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer
-
- <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer
-
- <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes
-
- <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class
-
- <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class
-
- <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class
-
- <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class
-
- <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination
-
- <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices
-
- <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs
-
- <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination
-
-</UL>
-
-<H3>Status Codes</H3>
-
-<P>Status codes are returned by all IPP requests.
-
-<UL>
-
- <LI><CODE>IPP_OK</CODE> - Request completed with no errors
-
- <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute
- values were substituted
-
- <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes
- conflicted
-
- <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad
-
- <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource
-
- <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for
- the resource
-
- <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access
- the resource
-
- <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be
- completed
-
- <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred
-
- <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found
-
- <LI><CODE>IPP_GONE</CODE> - The resource has gone away
-
- <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large
-
- <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value
- that was unknown to the server
-
- <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not
- supported by the server
-
- <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing
-
- <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported
-
- <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported
-
- <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict
-
- <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified
- compression is not supported
-
- <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data
- contained an error
-
- <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data
- contained an error in it
-
- <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document
- could not be accessed
-
- <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an
- internal error
-
- <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation
- is not supported
-
- <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service
- is unavailable
-
- <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request
- version is not supported
-
- <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered
- an error
-
- <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred
-
- <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting
- jobs
-
- <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy
-
- <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been
- cancelled
-
- <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server
- does not support multiple jobs
-
-</UL>
-
-<H2>PPD Constants</H2>
-
-<H3>PPD Format Version</H3>
-
-<P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number
-representing the newest format version that is supported by CUPS, currently
-4.3.
-
-<H3>PPD User-Interface Types</H3>
-
-<P>Each printer option has a type associated with it:
-
-<UL>
-
- <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or off
-
- <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value
- to use.
-
- <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more
- option values.
-
-</UL>
-
-<H3>PPD Sections</H3>
-
-<P>Some options must be output before others, or in different sections of
-the output document. The <CODE>ppd_section_t</CODE> enumeration defines
-which section the option must be output in:
-
-<UL>
-
- <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of
- the document, page, or prolog sections of the document
-
- <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in
- the DocumentSetup section of the document
-
- <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before
- the document
-
- <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the
- job control section of the document
-
- <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the
- PageSetup section of the document
-
- <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the
- Prolog section of the document
-
-</UL>
-
-<H3>PPD Colorspaces</H3>
-
-<P>Each printer has a default colorspace:
-
-<UL>
-
- <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default
-
- <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default
-
- <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default
-
- <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default
-
- <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default
-
- <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace
- by default
-
-</UL>
-
-<H2>Raster Constants</H2>
-
-<H3>Raster Sync Words</H3>
-
-<P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE>
-constants define the standard sync words at the beginning of each CUPS
-raster file.
-
-<H3>Raster Stream Modes</H3>
-
-<P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE>
-constants are used with the
-<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function to
-specify a stream for reading or writing.
-
-<H3>Raster Boolean Constants</H3>
-
-<P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants
-represent boolean values in the page header.
-
-<H3>Raster Jog Values</H3>
-
-<P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the
-Jog page device dictionary variable:
-
-<UL>
-
- <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging
-
- <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file
-
- <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job
-
- <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs
-
-</UL>
-
-<H3>Raster Orientation Values</H3>
-
-<P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the
-Orientation page device dictionary variable:
-
-<UL>
-
- <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation
-
- <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation
-
- <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation
-
- <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation
-
-</UL>
-
-<H3>Raster CutMedia Values</H3>
-
-<P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the
-CutMedia page device dictionary variable:
-
-<UL>
-
- <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging
-
- <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file
-
- <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job
-
- <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs
-
- <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page
-
-</UL>
-
-<H3>Raster AdvanceMedia Values</H3>
-
-<P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the
-AdvanceMedia page device dictionary variable:
-
-<UL>
-
- <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging
-
- <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file
-
- <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job
-
- <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs
-
- <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page
-
-</UL>
-
-<H3>Raster LeadingEdge Values</H3>
-
-<P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the
-LeadingEdge page device dictionary variable:
-
-<UL>
-
- <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading
- edge
-
- <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading
- edge
-
- <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the
- leading edge
-
- <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading
- edge
-
-</UL>
-
-<H3>Raster Color Order Values</H3>
-
-<P>The <CODE>cups_order_t</CODE> enumeration defines the possible color
-value orderings:
-
-<UL>
-
- <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK CMYK CMYK
-
- <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK
-
- <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ...
-
-</UL>
-
-<H3>Raster Colorspace Values</H3>
-
-<P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible colorspaces:
-
-<UL>
-
- <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)
-
- <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue
-
- <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha
-
- <LI><CODE>CUPS_CSPACE_K</CODE> - Black
-
- <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow
-
- <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan
-
- <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black
-
- <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black
-
- <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow
-
- <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
- light cyan, light magenta
-
- <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta,
- metallic cyan, black
-
- <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta,
- metallic cyan, metallic grey (silver)
-
- <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)
-
- <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)
-
- <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)
-
-</UL>
-
-<H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1>
-
-<P>This appendix describes all of the structures that are
-defined by the CUPS API.
-
-<H2>CUPS Structures</H2>
-
-<H3><A NAME="cups_dest_t">CUPS Destinations</A></H3>
-
-<P>The CUPS destination structure (<CODE>cups_dest_t</CODE>)
-contains information on a specific destination or instance:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>char *</TD>
- <TD>The name of the printer or class.</TD>
-</TR>
-<TR>
- <TD>instance</TD>
- <TD>char *</TD>
- <TD>The instance of the printer or class; NULL for the primary
- instance.</TD>
-</TR>
-<TR>
- <TD>is_default</TD>
- <TD>int</TD>
- <TD>1 if the destination is set as the default, 0 otherwise.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>int</TD>
- <TD>The number of options associated with this destination.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD><A HREF="#cups_option_t">cups_option_t *</A></TD>
- <TD>The options associated with this destination.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3><A NAME="cups_job_t">CUPS Jobs</A></H3>
-
-<P>The CUPS job structure (<CODE>cups_job_t</CODE>) contains
-information on a specific job:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>id</TD>
- <TD>int</TD>
- <TD>The job ID for this job.</TD>
-</TR>
-<TR>
- <TD>dest</TD>
- <TD>char *</TD>
- <TD>The destination for this job (printer or class name).</TD>
-</TR>
-<TR>
- <TD>title</TD>
- <TD>char *</TD>
- <TD>The job-name for this job (title).</TD>
-</TR>
-<TR>
- <TD>user</TD>
- <TD>char *</TD>
- <TD>The job-originating-user-name for this job (username).</TD>
-</TR>
-<TR>
- <TD>format</TD>
- <TD>char *</TD>
- <TD>The document-format for this job (MIME type string).</TD>
-</TR>
-<TR>
- <TD>state</TD>
- <TD>ipp_jstate</TD>
- <TD>The current state of the job.</TD>
-</TR>
-<TR>
- <TD>size</TD>
- <TD>int</TD>
- <TD>The size of this job in kilobytes.</TD>
-</TR>
-<TR>
- <TD>priority</TD>
- <TD>int</TD>
- <TD>The priority of this job from 1 to 100 (50 is normal).</TD>
-</TR>
-<TR>
- <TD>completed_time</TD>
- <TD>time_t</TD>
- <TD>The time the job was completed, or 0 if not yet completed.</TD>
-</TR>
-<TR>
- <TD>creation_time</TD>
- <TD>time_t</TD>
- <TD>The time the job was queued.</TD>
-</TR>
-<TR>
- <TD>processing_time</TD>
- <TD>time_t</TD>
- <TD>The time the job started printing.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3><A NAME="cups_lang_t">CUPS Messages</A></H3>
-
-<P>The CUPS messages structure (<CODE>cups_lang_t</CODE>)
-contains the character set, locale name, and messages array:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>next</TD>
- <TD>cups_lang_t *</TD>
- <TD>Pointer to the next messages structure in memory.</TD>
-</TR>
-<TR>
- <TD>used</TD>
- <TD>int</TD>
- <TD>The number of active users of this messages structure.</TD>
-</TR>
-<TR>
- <TD>encoding</TD>
- <TD>cups_encoding_t</TD>
- <TD>The character encoding of the message strings.</TD>
-</TR>
-<TR>
- <TD>language</TD>
- <TD>char [16]</TD>
- <TD>The language/locale name.</TD>
-</TR>
-<TR>
- <TD>messages</TD>
- <TD>char *[]</TD>
- <TD>The array of message strings.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3><A NAME="cups_option_t">CUPS Options</A></H3>
-
-<P>The CUPS option structure (<CODE>cups_option_t</CODE>)
-contains the option name and string value:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>char *</TD>
- <TD>The name of the option.</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>char *</TD>
- <TD>The string value of the option.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H2>Networking Structures</H2>
-
-<H3><A NAME="http_t">HTTP State</A></H3>
-
-<P>The HTTP state structure (<CODE>http_t</CODE>) contains the
-current state of a HTTP request or response:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>fd</TD>
- <TD>int</TD>
- <TD>The socket for the HTTP connection.</TD>
-</TR>
-<TR>
- <TD>blocking</TD>
- <TD>int</TD>
- <TD>1 if the HTTP functions should block, 0 if not.</TD>
-</TR>
-<TR>
- <TD>error</TD>
- <TD>int</TD>
- <TD>The last OS error that occurred on the socket.</TD>
-</TR>
-<TR>
- <TD>activity</TD>
- <TD>time_t</TD>
- <TD>The last time the HTTP connection was used.</TD>
-</TR>
-<TR>
- <TD>state</TD>
- <TD>http_state_t</TD>
- <TD>The current HTTP request/response state.</TD>
-</TR>
-<TR>
- <TD>status</TD>
- <TD>int</TD>
- <TD>The last HTTP status seen.</TD>
-</TR>
-<TR>
- <TD>version</TD>
- <TD>http_version_t</TD>
- <TD>The HTTP protocol version in use.</TD>
-</TR>
-<TR>
- <TD>keep_alive</TD>
- <TD>http_keep_alive_t</TD>
- <TD>Whether or not to use Keep-Alive</TD>
-</TR>
-<TR>
- <TD>hostaddr</TD>
- <TD>struct sockaddr_in</TD>
- <TD>The IPv4 address of the HTTP server.</TD>
-</TR>
-<TR>
- <TD>hostname</TD>
- <TD>char []</TD>
- <TD>The hostname of the HTTP server.</TD>
-</TR>
-<TR>
- <TD>fields</TD>
- <TD>char [][]</TD>
- <TD>The string values of all HTTP request/response
- fields.</TD>
-</TR>
-<TR>
- <TD>data</TD>
- <TD>char *</TD>
- <TD>Current byte in data buffer.</TD>
-</TR>
-<TR>
- <TD>data_encoding</TD>
- <TD>http_encoding_t</TD>
- <TD>The transfer encoding for the request/response.</TD>
-</TR>
-<TR>
- <TD>data_remaining</TD>
- <TD>int</TD>
- <TD>The number of bytes remaining in the current request,
- response, or chunk.</TD>
-</TR>
-<TR>
- <TD>used</TD>
- <TD>int</TD>
- <TD>The number of bytes that are used in the buffer.</TD>
-</TR>
-<TR>
- <TD>buffer</TD>
- <TD>char []</TD>
- <TD>The read/write buffer.</TD>
-</TR>
-<TR>
- <TD>auth_type</TD>
- <TD>int</TD>
- <TD>The type of authentication in use.</TD>
-</TR>
-<TR>
- <TD>md5_state</TD>
- <TD>md5_state_t</TD>
- <TD>The current MD5 digest state.</TD>
-</TR>
-<TR>
- <TD>nonce</TD>
- <TD>char []</TD>
- <TD>The nonce value for Digest authentication.</TD>
-</TR>
-<TR>
- <TD>nonce_count</TD>
- <TD>int</TD>
- <TD>The nonce count value.</TD>
-</TR>
-<TR>
- <TD>tls</TD>
- <TD>void *</TD>
- <TD>A pointer to private encryption data.</TD>
-</TR>
-<TR>
- <TD>encryption</TD>
- <TD>http_encryption_t</TD>
- <TD>The current encryption mode.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3><A NAME="ipp_t">IPP State</A></H3>
-
-<P>The IPP state structure (<CODE>ipp_t</CODE>) contains the
-current state of a IPP request or response:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD></TD>
- <TD></TD>
- <TD></TD>
-</TR>
-</TABLE></CENTER>
-
-<H2>Raster Structures</H2>
-
-<H3><A NAME="cups_raster_header_t">Raster Page Header</A></H3>
-
-<P>The raster page header (<CODE>cups_raster_header_t</CODE>)
-consists of the PostScript page device dictionary for the page:
-
-<CENTER><TABLE WIDTH="90%" BORDER="1">
-<TR>
- <TH>Member</TH>
- <TH>Type</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>MediaClass</TD>
- <TD>char[64]</TD>
- <TD>The media class name</TD>
-</TR>
-<TR>
- <TD>MediaColor</TD>
- <TD>char[64]</TD>
- <TD>The media color name</TD>
-</TR>
-<TR>
- <TD>MediaType</TD>
- <TD>char[64]</TD>
- <TD>The media type name</TD>
-</TR>
-<TR>
- <TD>OutputType</TD>
- <TD>char[64]</TD>
- <TD>The output type name</TD>
-</TR>
-<TR>
- <TD>AdvanceDistance</TD>
- <TD>unsigned</TD>
- <TD>The distance to advance the media in points</TD>
-</TR>
-<TR>
- <TD>AdvanceMedia</TD>
- <TD>cups_adv_t</TD>
- <TD>When to advance the media</TD>
-</TR>
-<TR>
- <TD>Collate</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to produce collated copies</TD>
-</TR>
-<TR>
- <TD>CutMedia</TD>
- <TD>cups_cut_t</TD>
- <TD>When to cut the media</TD>
-</TR>
-<TR>
- <TD>Duplex</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to print on both sides of the paper</TD>
-</TR>
-<TR>
- <TD>HWResolution</TD>
- <TD>unsigned[2]</TD>
- <TD>The resolution of the page image in pixels per inch; the
- HWResolution[0] represents the horizontal resolution and
- HWResolution[1] represents the vertical resolution</TD>
-</TR>
-<TR>
- <TD>ImagingBoundingBox</TD>
- <TD>unsigned[4]</TD>
- <TD>The bounding box for the page in points; the elements
- represent the left, bottom, right, and top coordinates of the
- imaged area (if 0 then the whole page is imaged)</TD>
-</TR>
-<TR>
- <TD>InsertSheet</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to insert a sheet before this page</TD>
-</TR>
-<TR>
- <TD>Jog</TD>
- <TD>cups_jog_t</TD>
- <TD>When to jog copies of the page</TD>
-</TR>
-<TR>
- <TD>LeadingEdge</TD>
- <TD>cups_edge_t</TD>
- <TD>The leading edge of the page</TD>
-</TR>
-<TR>
- <TD>Margins</TD>
- <TD>unsigned[2]</TD>
- <TD>The lower-lefthand margin of the page in points</TD>
-</TR>
-<TR>
- <TD>ManualFeed</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to manually feed the page</TD>
-</TR>
-<TR>
- <TD>MediaPosition</TD>
- <TD>unsigned</TD>
- <TD>The input slot number to use</TD>
-</TR>
-<TR>
- <TD>MediaWeight</TD>
- <TD>unsigned</TD>
- <TD>The weight of the output media in grams/m<SUP>2</SUP></TD>
-</TR>
-<TR>
- <TD>MirrorPrint</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to mirror the print</TD>
-</TR>
-<TR>
- <TD>NegativePrint</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to invert the print</TD>
-</TR>
-<TR>
- <TD>NumCopies</TD>
- <TD>unsigned</TD>
- <TD>The number of copies to produce</TD>
-</TR>
-<TR>
- <TD>Orientation</TD>
- <TD>cups_orient_t</TD>
- <TD>The orientation of the page image</TD>
-</TR>
-<TR>
- <TD>OutputFaceUp</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to output the page face up</TD>
-</TR>
-<TR>
- <TD>PageSize</TD>
- <TD>unsigned[2]</TD>
- <TD>The width and height of the page in points</TD>
-</TR>
-<TR>
- <TD>Separations</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to output separations</TD>
-</TR>
-<TR>
- <TD>TraySwitch</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to automatically switch trays for the requested
- media size/type</TD>
-</TR>
-<TR>
- <TD>Tumble</TD>
- <TD>cups_bool_t</TD>
- <TD>Whether or not to rotate the back side of the page</TD>
-</TR>
-<TR>
- <TD>cupsWidth</TD>
- <TD>unsigned</TD>
- <TD>The width of the page image in pixels</TD>
-</TR>
-<TR>
- <TD>cupsHeight</TD>
- <TD>unsigned</TD>
- <TD>The height of the page image in pixels</TD>
-</TR>
-<TR>
- <TD>cupsMediaType</TD>
- <TD>unsigned</TD>
- <TD>The device-specific media type code</TD>
-</TR>
-<TR>
- <TD>cupsBitsPerColor</TD>
- <TD>unsigned</TD>
- <TD>The number of bits per color</TD>
-</TR>
-<TR>
- <TD>cupsBitsPerPixel</TD>
- <TD>unsigned</TD>
- <TD>The number of bits per pixel</TD>
-</TR>
-<TR>
- <TD>cupsBytesPerLine</TD>
- <TD>unsigned</TD>
- <TD>The number of bytes per line of image data</TD>
-</TR>
-<TR>
- <TD>cupsColorOrder</TD>
- <TD>cups_order_t</TD>
- <TD>The order of color values</TD>
-</TR>
-<TR>
- <TD>cupsColorSpace</TD>
- <TD>cups_cspace_t</TD>
- <TD>The type of color values</TD>
-</TR>
-<TR>
- <TD>cupsCompression</TD>
- <TD>unsigned</TD>
- <TD>The device-specific compression code</TD>
-</TR>
-<TR>
- <TD>cupsRowCount</TD>
- <TD>unsigned</TD>
- <TD>The device-specific row count</TD>
-</TR>
-<TR>
- <TD>cupsRowFeed</TD>
- <TD>unsigned</TD>
- <TD>The device-specific row feed</TD>
-</TR>
-<TR>
- <TD>cupsRowStep</TD>
- <TD>unsigned</TD>
- <TD>The device-specific row step</TD>
-</TR>
-</TABLE></CENTER>
-
-<H1 ALIGN="RIGHT"><A NAME="FUNCTIONS">D - Functions</A></H1>
-
-<P>This appendix provides a reference for all of the CUPS API functions.
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsAddDest">cupsAddDest()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsAddDest(const char *name,
- const char *instance,
- int num_dests,
- cups_dest_t **dests);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the destination.</TD>
-</TR>
-<TR>
- <TD>instance</TD>
- <TD>The instance of the destination, or NULL for the primary instance.</TD>
-</TR>
-<TR>
- <TD>num_dests</TD>
- <TD>The number of destinations in the array.</TD>
-</TR>
-<TR>
- <TD>dest</TD>
- <TD>A pointer to the destination array pointer.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The new number of destinations in the array.
-
-<H3>Description</H3>
-
-<P><CODE>cupsAddDest()</CODE> adds the named destination to the destination
-array if it does not already exist.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_dests;
-<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
-
-
-num_dests = cupsAddDests("foo", "bar", num_dests, &dests);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>,
-<A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
-<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsAddOption">cupsAddOption()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsAddOption(const char *name,
- const char *value,
- int num_options,
- cups_option_t **options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the option.</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>The value of the option.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>Number of options currently in the array.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>Pointer to the options array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The new number of options.
-
-<H3>Description</H3>
-
-<P><CODE>cupsAddOption()</CODE> adds an option to the specified array.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups.h>
-
-...
-
-/* Declare the options array */
-int num_options;
-<A HREF="#cups_option_t">cups_option_t</A> *options;
-
-/* Initialize the options array */
-num_options = 0;
-options = (cups_option_t *)0;
-
-/* Add options using cupsAddOption() */
-num_options = cupsAddOption("media", "letter", num_options, &options);
-num_options = cupsAddOption("resolution", "300dpi", num_options, &options);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
-<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
-<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
-<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsCancelJob(const char *dest,
- int job);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>dest</TD>
- <TD>Printer or class name</TD>
-</TR>
-<TR>
- <TD>job</TD>
- <TD>Job ID</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>1 on success, 0 on failure. On failure the error can be found by calling
-<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
-
-<H3>Description</H3>
-
-<P><CODE>cupsCancelJob()</CODE> cancels the specifies job.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups.h>
-
-cupsCancelJob("LaserJet", 1);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
-<A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>,
-<A HREF="#cupsPrintFiles"><CODE>cupsPrintFiles()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_t *
-cupsDoFileRequest(http_t *http,
- ipp_t *request,
- const char *resource,
- const char *filename);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>HTTP connection to server.</TD>
-</TR>
-<TR>
- <TD>request</TD>
- <TD>IPP request data.</TD>
-</TR>
-<TR>
- <TD>resource</TD>
- <TD>HTTP resource name for POST.</TD>
-</TR>
-<TR>
- <TD>filename</TD>
- <TD>File to send with POST request (<CODE>NULL</CODE> pointer if none.)</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
-the error can be found by calling
-<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
-
-<H3>Description</H3>
-
-<P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and provides the
-IPP request and optionally the contents of a file to the IPP server. It also
-handles resubmitting the request and performing password authentication as
-needed.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups.h>
-
-<A HREF="#http_t">http_t</A> *http;
-<A HREF="#cups_lang_t">cups_lang_t</A> *language;
-<A HREF="#ipp_t">ipp_t</A> *request;
-ipp_t *response;
-
-...
-
-/* Get the default language */
-language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
-
-/* Create a new IPP request */
-request = <A HREF="#ippNew">ippNew()</A>;
-
-request->request.op.operation_id = IPP_PRINT_FILE;
-request->request.op.request_id = 1;
-
-/* Add required attributes */
-<A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
- "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
- "attributes-natural-language", NULL,
- language != NULL ? language->language : "C");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
- NULL, "ipp://hostname/resource");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
- NULL, <A HREF="#cupsUser">cupsUser()</A>);
-
-/* Do the request... */
-response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
-<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_t *
-cupsDoRequest(http_t *http,
- ipp_t *request,
- const char *resource);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>HTTP connection to server.</TD>
-</TR>
-<TR>
- <TD>request</TD>
- <TD>IPP request data.</TD>
-</TR>
-<TR>
- <TD>resource</TD>
- <TD>HTTP resource name for POST.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
-the error can be found by calling
-<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
-
-<H3>Description</H3>
-
-<P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides
-the IPP request to the IPP server. It also handles resubmitting the
-request and performing password authentication as needed.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups.h>
-
-<A HREF="#http_t">http_t</A> *http;
-<A HREF="#cups_lang_t">cups_lang_t</A> *language;
-<A HREF="#ipp_t">ipp_t</A> *request;
-ipp_t *response;
-
-...
-
-/* Get the default language */
-language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
-
-/* Create a new IPP request */
-request = <A HREF="#ippNew">ippNew()</A>;
-
-request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
-request->request.op.request_id = 1;
-
-/* Add required attributes */
-<A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
- "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
- "attributes-natural-language", NULL,
- language != NULL ? language->language : "C");
-
-ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
- NULL, "ipp://hostname/resource");
-
-/* Do the request... */
-response = cupsDoRequest(http, request, "/resource");
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
-<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsEncodeOptions">cupsEncodeOptions()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsEncodeOptions(ipp_t *ipp,
- int num_options,
- cups_option_t *options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>The number of options.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>The options.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsEncodeOptions()</CODE> encodes all of the options
-in the specified array as IPP attributes and adds them to the
-IPP request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-<A HREF="#ipp_t">ipp_t</A> *ipp;
-int num_options;
-<A HREF="#cups_option_t">cups_option_t</A> *options;
-
-
-cupsEncodeOptions(ipp, num_options, options);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
-<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>,
-<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsEncryption">cupsEncryption()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-http_encryption_t
-cupsEncryption(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>The current encryption setting.
-
-<H3>Description</H3>
-
-<P><CODE>cupsEncryption()</CODE> returns the current encryption setting
-for IPP requests such as printing.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-printf("The current encryption setting is %d.\n", cupsEncryption());
-
-http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
-<A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>,
-<A HREF="#ippPort"><CODE>ippPort()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsFreeDests">cupsFreeDests()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsFreeDests(int num_dests,
- cups_dest_t *dests);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>num_dests</TD>
- <TD>The number of destinations in the array.</TD>
-</TR>
-<TR>
- <TD>dests</TD>
- <TD>The destination array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsFreeDests()</CODE> frees a destination array that was
-created using <CODE>cupsGetDests()</CODE>.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_dests;
-<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
- printf("The default destination is %s\n", dest->name);
-else
- puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
-<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsFreeJobs">cupsFreeJobs()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsFreeJobs(int num_jobs,
- cups_job_t *jobs);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>num_jobs</TD>
- <TD>The number of jobs.</TD>
-</TR>
-<TR>
- <TD>jobs</TD>
- <TD>The job array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsFreeJobs()</CODE> frees an array of print jobs created by
-the <CODE>cupsGetJobs()</CODE> function.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int i;
-int num_jobs;
-<A HREF="#cups_job_t">cups_job_t</A> *jobs;
-
-
-num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
-
-printf("%d active job(s):\n", num_jobs);
-for (i = 0; i < num_jobs; i ++)
- printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
- jobs[i].user, jobs[i].title,
- jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
-
-cupsFreeJobs(num_jobs, jobs);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>,
-<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsFreeOptions(int num_options,
- cups_option_t *options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>Number of options in array.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>Pointer to options array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the
-option array specified.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_options;
-<A HREF="#cups_option_t">cups_option_t</A> *options;
-
-...
-
-cupsFreeOptions(num_options, options);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
-<A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
-<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
-<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
-<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsGetClasses(char ***classes);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>classes</TD>
- <TD>Pointer to character pointer array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of printer classes available.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetClasses()</CODE> gets a list of the available printer classes.
-The returned array should be freed using the <CODE>free()</CODE> when it is
-no longer needed.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int i;
-int num_classes;
-char **classes;
-
-...
-
-num_classes = cupsGetClasses(&classes);
-
-...
-
-if (num_classes > 0)
-{
- for (i = 0; i < num_classes; i ++)
- free(classes[i]);
-
- free(classes);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetDefault"><CODE>cupsGetDefault()</CODE></A>,
-<A HREF="#cupsGetPrinters"><CODE>cupsGetPrinters()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-cupsGetDefault(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>A pointer to the default destination.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetDefault()</CODE> gets the default destination printer or class.
-The default destination is stored in a static string and will be overwritten
-(usually with the same value) after each call.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-printf("The default destination is %s\n", cupsGetDefault());
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A>,
-<A HREF="#cupsGetPrinters"><CODE>cupsGetPrinters()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetDest">cupsGetDest()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-cups_dest_t *
-cupsGetDest(const char *name,
- const char *instance,
- int num_dests,
- cups_dest_t *dests);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the destination, or NULL for the default destination.</TD>
-</TR>
-<TR>
- <TD>instance</TD>
- <TD>The instance of the destination, or NULL for the primary instance.</TD>
-</TR>
-<TR>
- <TD>num_dests</TD>
- <TD>The number of destinations.</TD>
-</TR>
-<TR>
- <TD>dests</TD>
- <TD>The destination array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the specified destination, or NULL if none exists.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetDest()</CODE> finds the specified destination in the array
-of destinations created by the <CODE>cupsGetDests()</CODE> function.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_dests;
-<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
- printf("The default destination is %s\n", dest->name);
-else
- puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>,
-<A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetDests">cupsGetDests()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsGetDests(cups_dest_t **dests);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>dests</TD>
- <TD>A pointer to a destination array pointer.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of available destinations.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetDests()</CODE> creates an array of available
-destinations that the user can print to. The array should be
-freed using the <CODE>cupsFreeDests()</CODE> function.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_dests;
-<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
-cups_dest_t *dest;
-
-num_dests = cupsGetDests(&dests);
-dest = cupsGetDest(NULL, NULL, num_dests, dests);
-
-if (dest)
- printf("The default destination is %s\n", dest->name);
-else
- puts("No default destination.");
-
-cupsFreeDests(num_dests, dests);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>,
-<A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
-<A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetJobs">cupsGetJobs()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsGetJobs(cups_job_t **jobs,
- const char *dest,
- int myjobs,
- int completed);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>jobs</TD>
- <TD>A pointer to the job array pointer.</TD>
-</TR>
-<TR>
- <TD>dest</TD>
- <TD>The destination name, or NULL if jobs for all destinations are requested.</TD>
-</TR>
-<TR>
- <TD>myjobs</TD>
- <TD>1 if only those jobs submitted by the current
- <CODE>cupsUser()</CODE> should be returned, 0 for jobs
- submitted by all users.</TD>
-</TR>
-<TR>
- <TD>completed</TD>
- <TD>1 if only completed jobs should be returned, 0 if only
- pending/processing jobs should be returned.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of jobs.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetJobs()</CODE> creates an array of print jobs based on the
-arguments supplied in the function call. The returned array should be freed
-using the <CODE>cupsFreeJobs()</CODE> function.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int i;
-int num_jobs;
-<A HREF="#cups_job_t">cups_job_t</A> *jobs;
-
-
-num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
-
-printf("%d active job(s):\n", num_jobs);
-for (i = 0; i < num_jobs; i ++)
- printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
- jobs[i].user, jobs[i].title,
- jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
-
-cupsFreeJobs(num_jobs, jobs);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsFreeJobs"><CODE>cupsFreeJobs()</CODE></A>,
-<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetOption">cupsGetOption()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-cupsGetOption(const char *name,
- int num_options,
- cups_option_t *options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the option.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>The number of options in the array.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>The options array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the option values or <CODE>NULL</CODE> if the option is
-not defined.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetOption()</CODE> returns the first occurrence of the
-named option. If the option is not included in the options array then a
-<CODE>NULL</CODE> pointer is returned.
-
-<PRE>
-#include <cups/cups.h>
-
-int num_options;
-cups_option_t *options;
-const char *media;
-
-...
-
-media = cupsGetOption("media", num_options, options);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
-<A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
-<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
-<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
-<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-cupsGetPassword(const char *prompt);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>prompt</TD>
- <TD>The prompt to display to the user.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the password that was entered or <CODE>NULL</CODE> if no
-password was entered.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks the user
-for a password. The password text is not echoed to the user.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-char *password;
-
-...
-
-password = cupsGetPassword("Please enter a password:");
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
-<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
-<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
-<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-cupsGetPPD(const char *printer);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>printer</TD>
- <TD>The name of the printer.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE>
-if the printer cannot be located or does not have a PPD file.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named printer.
-The printer name can be of the form "printer" or "printer@hostname".
-
-<P>You should remove (unlink) the PPD file after you are done using it. The
-filename is stored in a static buffer and will be overwritten with each call
-to <CODE>cupsGetPPD()</CODE>.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-char *ppd;
-
-...
-
-ppd = cupsGetPPD("printer@hostname");
-
-...
-
-unlink(ppd);
-</PRE>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsGetPrinters(char ***printers);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>printers</TD>
- <TD>Pointer to character pointer array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of printer printers available.
-
-<H3>Description</H3>
-
-<P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers.
-The returned array should be freed using the <CODE>free()</CODE> when it is
-no longer needed.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int i;
-int num_printers;
-char **printers;
-
-...
-
-num_printers = cupsGetPrinters(&printers);
-
-...
-
-if (num_printers > 0)
-{
- for (i = 0; i < num_printers; i ++)
- free(printers[i]);
-
- free(printers);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A>
-<A HREF="#cupsGetDefault"><CODE>cupsGetDefault()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-cupsLangDefault(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>A pointer to the default language structure.
-
-<H3>Description</H3>
-
-<P><CODE>cupsLangDefault()</CODE> returns a language structure for the default
-language. The default language is defined by the <CODE>LANG</CODE> environment
-variable. If the specified language cannot be located then the POSIX (English)
-locale is used.
-
-<P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with the
-language structure when you are done.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/language.h>
-
-<A HREF="#cups_lang_t">cups_lang_t</A> *language;
-...
-
-language = cupsLangDefault();
-
-...
-
-cupsLangFree(language);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
-<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
-<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
-<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
-<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-cupsLangEncoding(cups_lang_t *language);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>language</TD>
- <TD>The language structure.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the encoding string.
-
-<H3>Description</H3>
-
-<P><CODE>cupsLangEncoding()</CODE> returns the language encoding used for the
-specified language, e.g. "iso-8859-1", "utf-8", etc.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/language.h>
-
-<A HREF="#cups_lang_t">cups_lang_t</A> *language;
-char *encoding;
-...
-
-language = cupsLangDefault();
-encoding = cupsLangEncoding(language);
-...
-
-cupsLangFree(language);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
-<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
-<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
-<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
-<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsLangFlush(void);
-</PRE>
-
-<H3>Description</H3>
-
-<P><CODE>cupsLangFlush()</CODE> frees all language structures that have been
-allocated.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/language.h>
-
-...
-
-cupsLangFlush();
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
-<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
-<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
-<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
-<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsLangFree">cupsLangFree()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsLangFree(cups_lang_t *language);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>language</TD>
- <TD>The language structure to free.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsLangFree()</CODE> frees the specified language structure.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/language.h>
-
-<A HREF="#cups_lang_t">cups_lang_t</A> *language;
-...
-
-cupsLangFree(language);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
-<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
-<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
-<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
-<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsLangGet">cupsLangGet()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-cups_lang_t *
-cupsLangGet(const char *name);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the locale.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a language structure.
-
-<H3>Description</H3>
-
-<P><CODE>cupsLangGet()</CODE> returns a language structure for the specified
-locale. If the locale is not defined then the POSIX (English) locale is
-substituted.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/language.h>
-
-<A HREF="#cups_lang_t">cups_lang_t</A> *language;
-
-...
-
-language = cupsLangGet("fr");
-
-...
-
-cupsLangFree(language);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
-<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
-<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
-<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
-<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsLangString">cupsLangString()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-cupsLangString(cups_lang_t *language,
- int message);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>language</TD>
- <TD>The language to query.</TD>
-</TR>
-<TR>
- <TD>message</TD>
- <TD>The message number.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the message string or <CODE>NULL</CODE> if the message is
-not defined.
-
-<H3>Description</H3>
-
-<P><CODE>cupsLangString()</CODE> returns a pointer to the specified message
-string in the specified language.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/language.h>
-
-<A HREF="#cups_lang_t">cups_lang_t</A> *language;
-char *s;
-...
-
-language = cupsLangGet("fr");
-
-s = cupsLangString(language, CUPS_MSG_YES);
-
-...
-
-cupsLangFree(language);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
-<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
-<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
-<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
-<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsLastError">cupsLastError()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_status_t
-cupsLastError(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>An enumeration containing the last IPP error.
-
-<H3>Description</H3>
-
-<P><CODE>cupsLastError()</CODE> returns the last IPP error that occurred.
-If no error occurred then it will return <CODE>IPP_OK</CODE> or
-<CODE>IPP_OK_CONFLICT</CODE>.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-ipp_status_t status;
-
-...
-
-status = cupsLastError();
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
-<A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsMarkOptions(ppd_file_t *ppd,
- int num_options,
- cups_option_t *options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file to mark.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>The number of options in the options array.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>A pointer to the options array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of conflicts found.
-
-<H3>Description</H3>
-
-<P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also
-handles mapping of IPP option names and values to PPD option names.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_options;
-<A HREF="#cups_option_t">cups_option_t</A> *options;
-<A HREF="#ppd_file_t">ppd_file_t</A> *ppd;
-
-...
-
-cupsMarkOptions(ppd, num_options, options);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
-<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
-<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
-<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsParseOptions(const char *arg,
- int num_options,
- cups_option_t **options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>arg</TD>
- <TD>The string containing one or more options.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>The number of options in the options array.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>A pointer to the options array pointer.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The new number of options in the array.
-
-<H3>Description</H3>
-
-<P><CODE>cupsParseOptions()</CODE> parses the specifies string for one
-or more options of the form "name=value", "name", or "noname". It can
-be called multiple times to combine the options from several strings.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_options;
-<A HREF="#cups_options_t">cups_option_t</A> *options;
-
-...
-
-num_options = 0;
-options = (cups_option_t *)0;
-num_options = cupsParseOptions(argv[5], num_options, &options);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
-<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
-<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
-<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsPrintFile(const char *printer,
- const char *filename,
- const char *title,
- int num_options,
- cups_option_t *options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>printer</TD>
- <TD>The printer or class to print to.</TD>
-</TR>
-<TR>
- <TD>filename</TD>
- <TD>The file to print.</TD>
-</TR>
-<TR>
- <TD>title</TD>
- <TD>The job title.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>The number of options in the options array.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>A pointer to the options array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The new job ID number or 0 on error.
-
-<H3>Description</H3>
-
-<P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or
-class for printing. If the job cannot be printed the error code can be
-found by calling <CODE>cupsLastError()</CODE>.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_options;
-<A HREF="#cups_option_t">cups_option_t</A> *options;
-int jobid;
-
-...
-
-jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
- num_options, options);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
-<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
-<A HREF="#cupsPrintFiles"><CODE>cupsPrintFiles()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsPrintFiles(const char *printer,
- int num_files,
- const char **files,
- const char *title,
- int num_options,
- cups_option_t *options);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>printer</TD>
- <TD>The printer or class to print to.</TD>
-</TR>
-<TR>
- <TD>num_files</TD>
- <TD>The number of files to print.</TD>
-</TR>
-<TR>
- <TD>files</TD>
- <TD>The files to print.</TD>
-</TR>
-<TR>
- <TD>title</TD>
- <TD>The job title.</TD>
-</TR>
-<TR>
- <TD>num_options</TD>
- <TD>The number of options in the options array.</TD>
-</TR>
-<TR>
- <TD>options</TD>
- <TD>A pointer to the options array.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The new job ID number or 0 on error.
-
-<H3>Description</H3>
-
-<P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified
-printer or class for printing. If the job cannot be printed the error
-code can be found by calling <CODE>cupsLastError()</CODE>.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_files;
-const char *files[100];
-int num_options;
-<A HREF="#cups_option_t">cups_option_t</A> *options;
-int jobid;
-
-...
-
-jobid = cupsPrintFiles("printer@hostname", num_files, files,
- "Job Title", num_options, options);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
-<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
-<A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsRasterClose(cups_raster_t *ras);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ras</TD>
- <TD>The raster stream to close.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/raster.h>
-
-<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
-
-...
-
-cupsRasterClose(ras);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
-<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
-<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
-<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
-<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-cups_raster_t *
-cupsRasterOpen(int fd,
- cups_mode_t mode);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>fd</TD>
- <TD>The file descriptor to use.</TD>
-</TR>
-<TR>
- <TD>mode</TD>
- <TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or
- <CODE>CUPS_RASTER_WRITE</CODE>.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an error.
-
-<H3>Description</H3>
-
-<P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or writing.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/raster.h>
-
-<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
-
-...
-
-ras = cupsRasterOpen(0, CUPS_RASTER_READ);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
-<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
-<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
-<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
-<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-unsigned
-cupsRasterReadHeader(cups_raster_t *ras,
- cups_page_header_t *header);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ras</TD>
- <TD>The raster stream to read from.</TD>
-</TR>
-<TR>
- <TD>header</TD>
- <TD>A pointer to a page header structure to read into.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>1 on success, 0 on EOF or error.
-
-<H3>Description</H3>
-
-<P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the specified
-raster stream.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/raster.h>
-
-int line;
-<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
-<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
-unsigned char pixels[8192];
-...
-
-while (cupsRasterReadHeader(ras, &header))
-{
- ...
-
- for (line = 0; line < header.cupsHeight; line ++)
- {
- cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
-
- ...
- }
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
-<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
-<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
-<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
-<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-unsigned
-cupsRasterReadPixels(cups_raster_t *ras,
- unsigned char *pixels,
- unsigned length);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ras</TD>
- <TD>The raster stream to read from.</TD>
-</TR>
-<TR>
- <TD>pixels</TD>
- <TD>The pointer to a pixel buffer.</TD>
-</TR>
-<TR>
- <TD>length</TD>
- <TD>The number of bytes of pixel data to read.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of bytes read or 0 on EOF or error.
-
-<H3>Description</H3>
-
-<P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the specified
-raster stream.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/raster.h>
-
-int line;
-<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
-<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
-unsigned char pixels[8192];
-...
-
-while (cupsRasterReadHeader(ras, &header))
-{
- ...
-
- for (line = 0; line < header.cupsHeight; line ++)
- {
- cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
-
- ...
- }
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
-<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
-<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
-<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
-<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-unsigned
-cupsRasterWriteHeader(cups_raster_t *ras,
- cups_page_header_t *header);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ras</TD>
- <TD>The raster stream to write to.</TD>
-</TR>
-<TR>
- <TD>header</TD>
- <TD>A pointer to the page header to write.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>1 on success, 0 on error.
-
-<H3>Description</H3>
-
-<P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header to
-a raster stream.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/raster.h>
-
-int line;
-<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
-<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
-unsigned char pixels[8192];
-...
-
-cupsRasterWriteHeader(ras, &header);
-
-for (line = 0; line < header.cupsHeight; line ++)
-{
- ...
-
- cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
-<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
-<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
-<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
-<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-unsigned
-cupsRasterWritePixels(cups_raster_t *ras,
- unsigned char *pixels,
- unsigned length);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ras</TD>
- <TD>The raster stream to write to.</TD>
-</TR>
-<TR>
- <TD>pixels</TD>
- <TD>The pixel data to write.</TD>
-</TR>
-<TR>
- <TD>length</TD>
- <TD>The number of bytes to write.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of bytes written.
-
-<H3>Description</H3>
-
-<P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data to a
-raster stream.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/raster.h>
-
-int line;
-<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
-<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
-unsigned char pixels[8192];
-...
-
-cupsRasterWriteHeader(ras, &header);
-
-for (line = 0; line < header.cupsHeight; line ++)
-{
- ...
-
- cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
-<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
-<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
-<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
-<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsServer">cupsServer()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-cupsServer(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>A pointer to the default server name.
-
-<H3>Description</H3>
-
-<P><CODE>cupsServer()</CODE> returns a pointer to the default server name.
-The server name is stored in a static location and will be overwritten with
-every call to <CODE>cupsServer()</CODE>.
-
-<P>The default server is determined from the following locations:
-
-<OL>
-
- <LI>The <CODE>CUPS_SERVER</CODE> environment variable,
-
- <LI>The <CODE>ServerName</CODE> directive in the
- <VAR>client.conf</VAR> file,
-
- <LI>The default host, "localhost".
-
-</OL>
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-const char *server;
-
-server = cupsServer();
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>,
-<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
-<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
-<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsSetDests">cupsSetDests()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsSetDests(int num_dests,
- cups_dest_t *dests);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>num_dests</TD>
- <TD>Number of destinations.</TD>
-</TR>
-<TR>
- <TD>dests</TD>
- <TD>Array of destinations.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsSetDests()</CODE> saves the destination array to
-disk. If the current UID is 0, the destinations are saved in the
-<VAR>/etc/cups/lpoptions</VAR> file, otherwise they are saved
-in the <VAR>~/.lpoptions</VAR> file. This function is typically used
-to save the default options and instances that are set by the user.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int num_dests;
-<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
-
-...
-
-cupsSetDests(num_dests, dests);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsSetEncryption">cupsSetEncryption()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsSetEncryption(http_encryption_t encryption);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>encryption</TD>
- <TD>The type of encryption to use.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsSetEncryption()</CODE> sets the default type of encryption to
-use when connecting with the print server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-cupsSetEncryption(HTTP_ENCRYPT_REQUIRED);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsEncryption"><CODE>cupsEncryption()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsSetPasswordCB(const char *(*cb)(const char *prompt));
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>cb</TD>
- <TD>The password callback function.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use when
-asking the user for a password. The callback function must accept a single
-character string pointer (the prompt string) and return <CODE>NULL</CODE>
-if the user did not enter a password string or a pointer to the password
-string otherwise.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-const char *
-my_password_cb(const char *prompt)
-{
- return (getpass(prompt));
-}
-
-...
-
-char *password;
-
-...
-
-cupsSetPasswordCB(my_password_cb);
-password = cupsGetPassword("Please enter a password:");
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
-<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
-<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsSetServer">cupsSetServer()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsSetServer(const char *server);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>server</TD>
- <TD>The default server to use.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsSetServer()</CODE> sets the default server to use for
-the CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>,
-the default server is used.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-cupsSetServer("foo.bar.com");
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
-<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
-<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsSetUser">cupsSetUser()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-cupsSetUser(const char *user);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>user</TD>
- <TD>The user name string to use.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P><CODE>cupsSetUser()</CODE> sets the default user name for authentication.
-If the <CODE>user</CODE> argument is <CODE>NULL</CODE> then the current
-login user is used.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-...
-
-cupsSetUser("root");
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
-<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
-<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
-<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsTempFd">cupsTempFd()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-cupsTempFd(char *filename,
- int length);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>filename</TD>
- <TD>The character string to hold the temporary filename.</TD>
-</TR>
-<TR>
- <TD>length</TD>
- <TD>The size of the filename string in bytes.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A file descriptor open for reading and writing.
-
-<H3>Description</H3>
-
-<P><CODE>cupsTempFd()</CODE> create a temporary filename in the
-<VAR>/var/tmp</VAR> directory or the directory specified by the
-<CODE>TMPDIR</CODE> environment variable.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-int fd;
-char filename[256];
-
-fd = cupsTempFd(filename, sizeof(filename));
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsTempFile"><CODE>cupsTempFile()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsTempFile">cupsTempFile()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-cupsTempFile(char *filename,
- int length);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>filename</TD>
- <TD>The character string to hold the temporary filename.</TD>
-</TR>
-<TR>
- <TD>length</TD>
- <TD>The size of the filename string in bytes.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to <CODE>filename</CODE>.
-
-<H3>Description</H3>
-
-<P><CODE>cupsTempFile()</CODE> creates a temporary filename in the
-<VAR>/var/tmp</VAR> directory or the directory specified by the
-<CODE>TMPDIR</CODE> environment variable.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-char filename[256];
-
-cupsTempFile(filename, sizeof(filename));
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsTempFd"><CODE>cupsTempFd()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="cupsUser">cupsUser()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-cupsUser(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>A pointer to the current username or <CODE>NULL</CODE> if the user ID is
-undefined.
-
-<H3>Description</H3>
-
-<P><CODE>cupsUser()</CODE> returns the name associated with the current
-user ID as reported by the <CODE>getuid()</CODE> system call.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/cups.h>
-
-const char *user;
-
-user = cupsUser();
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>,
-<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpBlocking">httpBlocking()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-httpBlocking(http_t *http,
- int blocking)
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>blocking</TD>
- <TD>0 if the connection should be non-blocking, 1 if it should
- be blocking</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for the
-HTTP connection. By default HTTP connections will block (stop) the client
-program until data is available or can be sent to the server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-http = httpConnect("server", port);
-httpBlocking(http, 0);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpCheck"><CODE>httpCheck()</CODE></A>,
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpCheck">httpCheck()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpCheck(http_t *http);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 if there is no data pending, 1 otherwise.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpCheck()</CODE> function checks to see if there is any data
-pending on an HTTP connection.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-if (httpCheck(http))
-{
- ... do something ...
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpBlocking"><CODE>httpBlocking()</CODE></A>,
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
-<A HREF="#httpRead"><CODE>httpRead()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpClearFields">httpClearFields()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-httpClearFields(http_t *http)
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>httpClearFields()</CODE> function clears all HTTP request fields
-for the HTTP connection.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpClearFields(http);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpClose">httpClose()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-httpClose(http_t *http);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>httpClose()</CODE> function closes an active HTTP connection.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpClose(http);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpConnect">httpConnect()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-http_t *
-httpConnect(const char *hostname,
- int port);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>hostname</TD>
- <TD>The name or IP address of the server to connect to</TD>
-</TR>
-<TR>
- <TD>port</TD>
- <TD>The port number to use</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a HTTP connection structure or NULL if the connection could
-not be made.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to the
-specified server and port.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-http = httpConnect(cupsServer(), ippPort());
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpClose"><CODE>httpClose()</CODE></A>,
-<A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>,
-<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
-<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
-<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
-<A HREF="#httpRead"><CODE>httpRead()</CODE></A>,
-<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpConnectEncrypt">httpConnectEncrypt()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-http_t *
-httpConnectEncrypt(const char *hostname,
- int port,
- http_encryption_t encryption);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>hostname</TD>
- <TD>The name or IP address of the server to connect to</TD>
-</TR>
-<TR>
- <TD>port</TD>
- <TD>The port number to use</TD>
-</TR>
-<TR>
- <TD>encryption</TD>
- <TD>The level of encryption to use</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a HTTP connection structure or NULL if the connection could
-not be made.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpConnectEncrypt()</CODE> function opens a HTTP
-connection to the specified server, port, and encryption.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpClose"><CODE>httpClose()</CODE></A>,
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
-<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
-<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
-<A HREF="#httpRead"><CODE>httpRead()</CODE></A>,
-<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpDecode64">httpDecode64()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-httpDecode64(char *out,
- const char *in);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>out</TD>
- <TD>The output string</TD>
-</TR>
-<TR>
- <TD>in</TD>
- <TD>The input string</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the decoded string.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded string
-to the original string.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-char encoded_string[255];
-char original_string[255];
-
-httpDecode64(original_string, encoded_string);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpEncode64"><CODE>httpEncode64()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpDelete">httpDelete()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpDelete(http_t *http,
- const char *uri);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to delete</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to
-the server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpDelete(http, "/some/uri");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpEncode64">httpEncode64()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-httpEncode64(char *out,
- const char *in);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>out</TD>
- <TD>The output string</TD>
-</TR>
-<TR>
- <TD>in</TD>
- <TD>The input string</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the encoded string.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded string
-to the original string.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-char encoded_string[255];
-char original_string[255];
-
-httpEncode64(encoded_string, original_string);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpDecode64"><CODE>httpDecode64()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpEncryption">httpEncryption()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpEncryption(http_t *http,
- http_encryption_t encryption);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection.</TD>
-</TR>
-<TR>
- <TD>encryption</TD>
- <TD>The desired level of encryption.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, -1 on error.
-
-<H3>Description</H3>
-
-<P><CODE>httpEncryption()</CODE> sets the encryption level for the HTTP
-connection.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-...
-
-httpEncryption(http, HTTP_ENCRYPT_REQUIRED);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpError">httpError()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpError(http_t *http);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The last error that occurred or 0 if no error has occurred.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpError()</CODE> function returns the last error that occurred
-on the HTTP connection.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-if (httpError(http))
-{
- ... show an error message ...
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpFlush">httpFlush()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-httpFlush(http_t *http);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>httpFlush()</CODE> function flushes any remaining data left from
-a GET or POST operation.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpFlush(http);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGet">httpGet()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpGet(http_t *http,
- const char *uri);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to get</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the
-server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-httpGet(http, "/some/uri");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGets">httpGets()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-httpGets(char *line,
- int length,
- http_t *http)
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>line</TD>
- <TD>The string to fill with a line from the HTTP connection</TD>
-</TR>
-<TR>
- <TD>length</TD>
- <TD>The maximum length of the string</TD>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the string or NULL if no line could be retrieved.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpGets()</CODE> function is used to read a request line from
-the HTTP connection. It is not normally used by a client program.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-char line[1024];
-
-if (httpGets(line, sizeof(line), http))
-{
- ... process the line ...
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGetDateString">httpGetDateString()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-httpGetDateString(time_t time)
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>time</TD>
- <TD>The UNIX date/time value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a static string containing the HTTP date/time string for
-the specified UNIX time value.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpGetDateString()</CODE> function generates a date/time string
-suitable for HTTP requests from a UNIX time value.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-puts(httpGetDateString(time(NULL)));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpGetDateTime"><CODE>httpGetDateTime()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-time_t
-httpGetDateTime(const char *date)
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>date</TD>
- <TD>The HTTP date/time string</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A UNIX time value.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP
-date/time string to a UNIX time value.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpGetDateString"><CODE>httpGetDateString()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGetField">httpGetField()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-httpGetField(http_t *http,
- http_field_t field);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>field</TD>
- <TD>The HTTP field</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the field value string.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpGetField()</CODE> function returns the current value for
-the specified HTTP field.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
-puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpGetSubField"><CODE>httpGetSubField()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGetHostByName">httpGetHostByName()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-struct hostent *
-httpGetHostByName(const char *name);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>Name or IP address to lookup.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>NULL if the host could not be found or a pointer to a host entry
-containing one or more addresses.
-
-<H3>Description</H3>
-
-<P><CODE>httpGetHostByName()</CODE> is a portable wrapper around the
-<CODE>gethostbyname()</CODE> function which handles both hostnames
-and IP addresses.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-struct hostent *hostaddr;
-
-hostaddr = httpGetHostByName("foo.bar.com");
-</PRE>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGetLength">httpGetLength()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpGetLength(http_t *http);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The content length of the response or MAX_INT if chunking is used.
-
-<H3>Description</H3>
-
-<P><CODE>httpGetLength()</CODE> returns the content length of a response.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-...
-
-printf("The length of the response is %d bytes.\n", httpGetLength(http));
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
-<A HREF="#httpPost"><CODE>httpPost()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpGetSubField">httpGetSubField()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-httpGetSubField(http_t *http,
- http_field_t field,
- const char *name,
- char *value);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection.</TD>
-</TR>
-<TR>
- <TD>field</TD>
- <TD>The HTTP field.</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the subfield.</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>The string to hold the subfield value.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the subfield value string or NULL if it does not exist.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpGetSubField()</CODE> function returns a subfield value
-from the specified HTTP field. The destination string buffer must be at
-least <CODE>HTTP_MAX_VALUE</CODE> bytes in length.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-char value[HTTP_MAX_VALUE];
-
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-
-puts(httpGetSubField(http, HTTP_FIELD_CONTENT_TYPE, "charset", value));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpHead">httpHead()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpHead(http_t *http,
- const char *uri);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to head</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the
-server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpHead(http, "/some/uri");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpInitialize">httpInitialize()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void httpInitialize(void);
-</PRE>
-
-<H3>Description</H3>
-
-<P>The <CODE>httpInitialize()</CODE> function initializes the networking
-code as needed by the underlying platform. It is called automatically by
-the <CODE>httpConnect()</CODE> function.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-httpInitialize();
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpMD5">httpMD5()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-httpMD5(const char *username,
- const char *realm,
- const char *passwd,
- char md5[33]);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>username</TD>
- <TD>The authenticating user name.</TD>
-</TR>
-<TR>
- <TD>realm</TD>
- <TD>The authenticating realm name.</TD>
-</TR>
-<TR>
- <TD>passwd</TD>
- <TD>The authenticating password.</TD>
-</TR>
-<TR>
- <TD>md5</TD>
- <TD>The MD5 sum string.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the MD5 sum string.
-
-<H3>Description</H3>
-
-<P><CODE>httpMD5()</CODE> computes the MD5 hash of the username,
-realm, and password as required by the HTTP Digest specification.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-char md5[33];
-
-...
-
-httpMD5("user", "realm", "password", md5);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#httpMD5Final"><CODE>httpMD5Final()</CODE></A>,
-<A HREF="#httpMD5String"><CODE>httpMD5String()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpMD5Final">httpMD5Final()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-httpMD5Final(const char *nonce,
- const char *method,
- const char *resource,
- char md5[33]);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>nonce</TD>
- <TD>The server nonce value.</TD>
-</TR>
-<TR>
- <TD>method</TD>
- <TD>The HTTP method (GET, POST, etc.)</TD>
-</TR>
-<TR>
- <TD>resource</TD>
- <TD>The resource path.</TD>
-</TR>
-<TR>
- <TD>md5</TD>
- <TD>The MD5 sum string.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The MD5 sum string.
-
-<H3>Description</H3>
-
-<P><CODE>httpMD5Final()</CODE> appends the nonce, method, and resource
-to the specified MD5 sum.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-char md5[33];
-
-...
-
-httpMD5Final("nonce", "GET", "/jobs", md5);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>,
-<A HREF="#httpMD5String"><CODE>httpMD5String()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpMD5String">httpMD5String()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-char *
-httpMD5String(const md5_byte_t *sum,
- char md5[33]);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>sum</TD>
- <TD>The raw MD5 sum data.</TD>
-</TR>
-<TR>
- <TD>md5</TD>
- <TD>The MD5 sum string.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The MD5 sum string.
-
-<H3>Description</H3>
-
-<P><CODE>httpMD5String()</CODE> converts the raw MD5 sum value to a string.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-md5_byte_t sum[16];
-char md5[33];
-
-...
-
-httpMD5String(sum, md5);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>,
-<A HREF="#httpMD5Final"><CODE>httpMD5Final()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpOptions">httpOptions()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpOptions(http_t *http,
- const char *uri);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to check for options</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request to the
-server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpOptions(http, "/some/uri");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpPost">httpPost()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpPost(http_t *http,
- const char *uri);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to post to</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the
-server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpPost(http, "/some/uri");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpPrintf">httpPrintf()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpPrintf(http_t *http,
- const char *format,
- ...);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>format</TD>
- <TD>A printf-style format string</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of bytes written.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpPrintf()</CODE> function sends a formatted string to the
-HTTP connection. It is normally only used by the CUPS API and scheduler.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpPrintf(http, "GET / HTTP/1.1 \r\n");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpPut">httpPut()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpPut(http_t *http,
- const char *uri);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to put</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the
-server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpDelete(http, "/some/uri");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpRead">httpRead()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpRead(http_t *http,
- char *buffer,
- int length);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>buffer</TD>
- <TD>The buffer to read into</TD>
-</TR>
-<TR>
- <TD>length</TD>
- <TD>The number of bytes to read</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of bytes read or -1 on error.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpRead()</CODE> function reads data from the HTTP connection,
-possibly the result of a GET or POST request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-char buffer[1024];
-int bytes;
-
-httpGet(http, "/");
-while (httpUpdate(http) != HTTP_CONTINUE);
-while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
-{
- buffer[bytes] = '\0';
- fputs(buffer, stdout);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpReconnect">httpReconnect()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpReconnect(http_t *http);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP server.
-This is usually done automatically if the HTTP functions detect that the
-server connection has terminated.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpReconnect(http);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpSeparate">httpSeparate()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-httpSeparate(const char *uri,
- char *method,
- char *username,
- char *host,
- int *port,
- char *resource);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to separate</TD>
-</TR>
-<TR>
- <TD>method</TD>
- <TD>The method (scheme) of the URI</TD>
-</TR>
-<TR>
- <TD>username</TD>
- <TD>The username (and password) portion of the URI, if any</TD>
-</TR>
-<TR>
- <TD>host</TD>
- <TD>The hostname portion of the URI, if any</TD>
-</TR>
-<TR>
- <TD>port</TD>
- <TD>The port number for the URI, either as specified or as
- default for the method/scheme</TD>
-</TR>
-<TR>
- <TD>resource</TD>
- <TD>The resource string, usually a filename on the server</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>httpSeparate()</CODE> function separates the specified URI into
-its component parts. The method, username, hostname, and resource strings should
-be at least <CODE>HTTP_MAX_URI</CODE> characters long to avoid potential
-buffer overflow problems.
-
-<H3>Example</H3>
-
-<PRE>
-char uri[HTTP_MAX_URI];
-char method[HTTP_MAX_URI];
-char username[HTTP_MAX_URI];
-char host[HTTP_MAX_URI];
-char resource[HTTP_MAX_URI];
-int port;
-
-...
-
-httpSeparate(uri, method, username, host, &port, resource);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpSetField">httpSetField()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-httpSetField(http_t *http,
- http_field_t field,
- const char *value);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>field</TD>
- <TD>The HTTP field</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>The string value for the field</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>httpSetField()</CODE> function sets the current value for
-the specified HTTP field.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
-httpGet(http, "/some/uri");
-while (httpUpdate(http) == HTTP_CONTINUE);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpStatus">httpStatus()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-httpStatus(http_status_t status);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>status</TD>
- <TD>The HTTP status code from the server.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The standard HTTP status text associated with the status code.
-
-<H3>Description</H3>
-
-<P><CODE>httpStatus()</CODE> returns the standard HTTP status text
-associated with the status code.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-<A HREF="#http_t">http_t</A> *http;
-
-...
-
-puts(httpStatus(http->status));
-</PRE>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpTrace">httpTrace()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpTrace(http_t *http,
- const char *uri);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>uri</TD>
- <TD>The URI to trace</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, non-zero on failure.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to the
-server.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-
-httpTrace(http, "/some/uri");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
-<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpUpdate">httpUpdate()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-http_status_t
-httpUpdate(http_t *http);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The HTTP status of the current request.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpUpdate()</CODE> function updates the current request status.
-It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE
-request to finalize the HTTP request and retrieve the request status.
-
-<P>Since proxies and the current blocking mode can cause the request to
-take longer, programs should continue calling <CODE>httpUpdate()<CODE>
-until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-http_status_t status;
-
-httpGet(http, "/some/uri");
-while ((status = httpUpdate(http)) == HTTP_CONTINUE);
-printf("Request status is %d\n", status);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpDelete"><CODE>httpDelete()</CODE></A>,
-<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
-<A HREF="#httpHead"><CODE>httpHead()</CODE></A>,
-<A HREF="#httpOptions"><CODE>httpOptions()</CODE></A>,
-<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
-<A HREF="#httpPut"><CODE>httpPut()</CODE></A>,
-<A HREF="#httpTrace"><CODE>httpTrace()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="httpWrite">httpWrite()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-httpWrite(http_t *http,
- char *buffer,
- int length);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>buffer</TD>
- <TD>The buffer to read into</TD>
-</TR>
-<TR>
- <TD>length</TD>
- <TD>The number of bytes to read</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of bytes read or -1 on error.
-
-<H3>Description</H3>
-
-<P>The <CODE>httpWrite()</CODE> function reads data from the HTTP connection,
-possibly the result of a GET or POST request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-
-http_t *http;
-FILE *fp;
-char buffer[1024];
-int bytes;
-
-httpPost(http, "/");
-
-while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
- httpWrite(http, buffer, bytes);
-
-while (httpUpdate(http) != HTTP_CONTINUE);
-
-while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
-{
- buffer[bytes] = '\0';
- fputs(buffer, stdout);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
-<A HREF="#httpRead"><CODE>httpRead()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddBoolean(ipp_t *ipp,
- ipp_tag_t group,
- const char *name,
- char value);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>The boolean value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean attribute
-value to the specified IPP request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddBooleans(ipp_t *ipp,
- ipp_tag_t group,
- const char *name,
- int num_values,
- const char *values);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>num_values</TD>
- <TD>The number of values</TD>
-</TR>
-<TR>
- <TD>values</TD>
- <TD>The boolean values</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean
-attribute values to the specified IPP request. If the
-<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
-<CODE>num_values</CODE> false values is created.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-char values[10];
-
-ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddDate">ippAddDate()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddDate(ipp_t *ipp,
- ipp_tag_t group,
- const char *name,
- ipp_uchar_t *value);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>The date value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddDate()</CODE> function adds a single date-time attribute
-value to the specified IPP request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute",
- ippTimeToDate(time(NULL));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>,
-<A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddInteger">ippAddInteger()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddInteger(ipp_t *ipp,
- ipp_tag_t group,
- ipp_tag_t tag,
- const char *name,
- int value);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>tag</TD>
- <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>The integer value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddInteger()</CODE> function adds a single integer attribute
-value to the specified IPP request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddIntegers(ipp_t *ipp,
- ipp_tag_t group,
- ipp_tag_t tag,
- const char *name,
- int num_values,
- const int *values);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>tag</TD>
- <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>num_values</TD>
- <TD>The number of values</TD>
-</TR>
-<TR>
- <TD>values</TD>
- <TD>The integer values</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer
-attribute values to the specified IPP request. If the
-<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
-<CODE>num_values</CODE> 0 values is created.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-int values[100];
-
-ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddRange">ippAddRange()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddRange(ipp_t *ipp,
- ipp_tag_t group,
- const char *name,
- int low,
- int high);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>low</TD>
- <TD>The lower value</TD>
-</TR>
-<TR>
- <TD>high</TD>
- <TD>The higher value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddRange()</CODE> function adds a single range attribute
-value to the specified IPP request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddRanges">ippAddRanges()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddRanges(ipp_t *ipp,
- ipp_tag_t group,
- const char *name,
- int num_values,
- const int *lows,
- const int *highs);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>num_values</TD>
- <TD>The number of range values</TD>
-</TR>
-<TR>
- <TD>lows</TD>
- <TD>The lower values</TD>
-</TR>
-<TR>
- <TD>highs</TD>
- <TD>The higher values</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddRanges()</CODE> function adds one or more range
-attribute values to the specified IPP request. If the
-<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
-<CODE>num_values</CODE> 0,0 ranges is created.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-int lows[2];
-int highs[2];
-
-ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddResolution">ippAddResolution()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddResolution(ipp_t *ipp,
- ipp_tag_t group,
- const char *name,
- int xres,
- int yres,
- ipp_res_t units);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>xres</TD>
- <TD>The horizontal resolution</TD>
-</TR>
-<TR>
- <TD>yres</TD>
- <TD>The vertical resolution</TD>
-</TR>
-<TR>
- <TD>units</TD>
- <TD>The resolution units</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddResolution()</CODE> function adds a single resolution attribute
-value to the specified IPP request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
- 720, 720, IPP_RES_PER_INCH);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddResolutions(ipp_t *ipp,
- ipp_tag_t group,
- const char *name,
- int num_values,
- const int *xres,
- const int *yres,
- const ipp_res_t *units);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>num_values</TD>
- <TD>The number of resolution values</TD>
-</TR>
-<TR>
- <TD>xres</TD>
- <TD>The horizontal resolutions</TD>
-</TR>
-<TR>
- <TD>yres</TD>
- <TD>The vertical resolutions</TD>
-</TR>
-<TR>
- <TD>units</TD>
- <TD>The resolution units</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddResolutions()</CODE> function adds one or more
-resolution attribute values to the specified IPP request. If the
-<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
-<CODE>num_values</CODE> 0,0 resolutions is created.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-int xres[5];
-int yres[5];
-ipp_res_t units[5];
-
-ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
- 5, xres, yres, units);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddSeparator(ipp_t *ipp);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new separator or NULL if the separator could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddSeparator()</CODE> function adds a group separator
-to the specified IPP request.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddSeparator(ipp);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddString">ippAddString()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddString(ipp_t *ipp,
- ipp_tag_t group,
- ipp_tag_t tag,
- const char *name,
- const char *charset,
- const char *value);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>tag</TD>
- <TD>The type of string value</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>charset</TD>
- <TD>The character set for the string</TD>
-</TR>
-<TR>
- <TD>value</TD>
- <TD>The string value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddString()</CODE> function adds a single string attribute
-value to the specified IPP request. For <CODE>IPP_TAG_NAMELANG</CODE> and
-<CODE>IPP_TAG_TEXTLANG</CODE> strings, the charset value is provided with
-the string to identify the string encoding used. Otherwise the charset value
-is ignored.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
- NULL, "abc123");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippAddStrings">ippAddStrings()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippAddStrings(ipp_t *ipp,
- ipp_tag_t group,
- ipp_tag_t tag,
- const char *name,
- int num_values,
- const char *charset,
- const char **values);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request</TD>
-</TR>
-<TR>
- <TD>group</TD>
- <TD>The IPP group</TD>
-</TR>
-<TR>
- <TD>tag</TD>
- <TD>The type of string value</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of attribute</TD>
-</TR>
-<TR>
- <TD>num_values</TD>
- <TD>The number of strings</TD>
-</TR>
-<TR>
- <TD>charset</TD>
- <TD>The character set for the strings</TD>
-</TR>
-<TR>
- <TD>values</TD>
- <TD>The string values</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the new attribute or NULL if the attribute could not be
-created.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippAddStrings()</CODE> function adds one or more string
-attribute values to the specified IPP request. For
-<CODE>IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE>
-strings, the charset value is provided with the strings to identify the
-string encoding used. Otherwise the charset value is ignored. If the
-<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
-<CODE>num_values</CODE> NULL strings is created.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-char *values[2] = { "one", "two" };
-
-ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
- 2, NULL, values);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
-<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
-<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
-<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
-<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
-<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
-<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
-<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
-<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
-<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
-<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippDateToTime">ippDateToTime()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-time_t
-ippDateToTime(const ipp_uchar_t date[11]);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>date</TD>
- <TD>The IPP date-time value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A UNIX time value.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time value
-to a UNIX time value.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_uchar_t date[11];
-
-printf("UNIX time is %d\n", ippDateToTime(date));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippDelete">ippDelete()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-ippDelete(ipp_t *ipp);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request or response</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>ippDelete()</CODE> function deletes all memory used by an IPP
-request or response.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ippDelete(ipp);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippErrorString">ippErrorString()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-const char *
-ippErrorString(ipp_status_t error);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>error</TD>
- <TD>IPP error code.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The standard text representation of the IPP error code.
-
-<H3>Description</H3>
-
-<P><CODE>ippErrorString()</CODE> returns the standard text representation
-of the IPP error code.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-puts(ippErrorString(IPP_OK));
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippFindAttribute(ipp_t *ipp,
- const char *name,
- ipp_tag_t tag);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request or response</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the attribute</TD>
-</TR>
-<TR>
- <TD>tag</TD>
- <TD>The required value tag for the attribute or
- <CODE>IPP_TAG_ZERO</CODE> for any type of value.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the first occurrence of the requested attribute, or
-<CODE>NULL</CODE> if it was not found.
-
-<H3>Description</H3>
-
-<P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the named
-attribute. The <CODE>tag</CODE> parameter restricts the search to a specific
-value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.
-
-<P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
-match the name/text values with or without the language code.
-
-<H3>Example</H3>
-
-<PRE>
-<A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr;
-
-attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-while (attr != NULL)
-{
- puts(attr->values[0].string.text);
-
- attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>,
-<A HREF="#cupsDoRequest"><CODE>cupsDoRequest()</CODE></A>,
-<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
-<A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE></A>,
-<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippFindNextAttribute">ippFindNextAttribute()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_attribute_t *
-ippFindNextAttribute(ipp_t *ipp,
- const char *name,
- ipp_tag_t tag);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request or response</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the attribute</TD>
-</TR>
-<TR>
- <TD>tag</TD>
- <TD>The required value tag for the attribute or
- <CODE>IPP_TAG_ZERO</CODE> for any type of value.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the next occurrence of the requested attribute, or
-<CODE>NULL</CODE> if it was not found.
-
-<H3>Description</H3>
-
-<P><CODE>ippFindNextAttribute()</CODE> finds the next occurrence of the named
-attribute. The <CODE>tag</CODE> parameter restricts the search to a specific
-value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.
-
-<P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
-match the name/text values with or without the language code.
-
-<H3>Example</H3>
-
-<PRE>
-<A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr;
-
-attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-while (attr != NULL)
-{
- puts(attr->values[0].string.text);
-
- attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>,
-<A HREF="#cupsDoRequest"><CODE>cupsDoRequest()</CODE></A>,
-<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
-<A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE></A>,
-<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippLength">ippLength()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ippLength(ipp_t *ipp);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request or response</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The total encoded length of the IPP request or response in bytes.
-
-<H3>Description</H3>
-
-<P><CODE>ippLength()</CODE> returns the length of the IPP request or
-response in bytes.
-
-<H3>Example</H3>
-
-<PRE>
-printf("The length of the response is %d bytes.\n", ippLength(response));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
-<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippNew">ippNew()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_t *
-ippNew(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>A pointer to a new IPP request or response.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippNew()</CODE> function creates a new IPP request or response.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_t *ipp;
-
-ipp = ippNew();
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippPort">ippPort()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ippPort(void);
-</PRE>
-
-<H3>Returns</H3>
-
-<P>The default TCP/IP port number for IPP requests.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippPort()</CODE> function returns the default IPP port number
-for requests.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-
-http = httpConnect(cupsServer(), ippPort());
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
-<A HREF="#ippSetPort"><CODE>ippSetPort()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippRead">ippRead()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_state_t
-ippRead(http_t *http,
- ipp_t *ipp);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request or response</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The current read state.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippRead()</CODE> function reads IPP attributes from the specified
-HTTP connection. Programs should continue calling <CODE>ippRead()</CODE> until
-<CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-ipp_t *ipp;
-ipp_state_t status;
-
-ipp = ippNew();
-
-while ((status = ippRead(http, ipp)) != IPP_ERROR)
- if (status == IPP_DATA)
- break;
-
-if (status == IPP_DATA)
-{
- ... read additional non-IPP data using httpRead() ...
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippWrite"><CODE>ippWrite()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippSetPort">ippSetPort()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-ippSetPort(int port);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>port</TD>
- <TD>The port number to use</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>ippSetPort()</CODE> function sets the default IPP port number
-for requests.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-#include <cups/ipp.h>
-
-...
-
-ippSetPort(8631);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippPort"><CODE>ippPort()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_uchar_t *
-ippTimeToDate(time_t time);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>time</TD>
- <TD>The UNIX time value</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A static pointer to an IPP date-time value.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an IPP
-date-time value.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ipp.h>
-
-ipp_uchar_t *date;
-
-date = ippTimeToDate(time(NULL));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippDateToTime"><CODE>ippDateToTime()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ippWrite">ippWrite()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ipp_state_t
-ippWrite(http_t *http,
- ipp_t *ipp);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>http</TD>
- <TD>The HTTP connection</TD>
-</TR>
-<TR>
- <TD>ipp</TD>
- <TD>The IPP request or response</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The current write state.
-
-<H3>Description</H3>
-
-<P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the specified
-HTTP connection. Programs should continue calling <CODE>ippWrite()</CODE> until
-<CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/http.h>
-#include <cups/ipp.h>
-
-http_t *http;
-ipp_t *ipp;
-ipp_state_t status;
-
-ipp = ippNew();
-... add attributes ...
-
-while ((status = ippWrite(http, ipp)) != IPP_ERROR)
- if (status == IPP_DATA)
- break;
-
-if (status == IPP_DATA)
-{
- ... read additional non-IPP data using httpWrite() ...
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ippRead"><CODE>ippRead()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdClose">ppdClose()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-ppdClose(ppd_file_t *ppd);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdClose()</CODE> function frees all memory associated with the
-PPD file.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdClose(ppd);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
-<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
-<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdCollect">ppdCollect()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ppdCollect(ppd_file_t *ppd,
- ppd_section_t section,
- ppd_choice_t ***choices);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file.</TD>
-</TR>
-<TR>
- <TD>section</TD>
- <TD>The document section to collect.</TD>
-</TR>
-<TR>
- <TD>choices</TD>
- <TD>The array of option choices that are marked.</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of options collected.
-
-<H3>Description</H3>
-
-<P><CODE>ppdCollect()</CODE> collects all of the marked options in the
-specified section, sorts them by their order dependency values, and
-returns an array that can be used to emit option commands in the proper
-order. It is normally used by the <CODE>ppdEmit*()</CODE> functions.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-<A HREF="#ppd_file_t">ppd_file_t</A> *ppd;
-int num_choices;
-<A HREF="#ppd_choice_t">ppd_choice_t</A> **choices;
-
-...
-
-num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &choices);
-</PRE>
-
-<H3>See Also</H3>
-
-<P>
-<A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>,
-<A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A>,
-<A HREF="#ppdEmitJCL"><CODE>ppdEmitJCL()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdConflicts">ppdConflicts()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ppdConflicts(ppd_file_t *ppd);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of option conflicts in the file.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdConflicts()</CODE> function returns the number of conflicts
-with the currently selected options.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("%d conflicts\n", ppdConflicts(ppd));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
-<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
-<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
-<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdEmit">ppdEmit()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ppdEmit(ppd_file_t *ppd,
- FILE *file,
- ppd_section_t section);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>file</TD>
- <TD>The file to write to</TD>
-</TR>
-<TR>
- <TD>section</TD>
- <TD>The option section to write</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, -1 on error.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdEmit()</CODE> function sends printer-specific option
-commands to the specified file.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ppdEmitFd(ppd_file_t *ppd,
- int fd,
- ppd_section_t section);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>fd</TD>
- <TD>The file descriptor to write to</TD>
-</TR>
-<TR>
- <TD>section</TD>
- <TD>The option section to write</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>0 on success, -1 on error.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option
-commands to the specified file descriptor.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ppd_choice_t *
-ppdFindChoice(ppd_option_t *option,
- const char *choice);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>option</TD>
- <TD>A pointer to the option</TD>
-</TR>
-<TR>
- <TD>choice</TD>
- <TD>The name of the choice</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the choice data or NULL if the choice does not exist.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the choice
-data for the specified option.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_option_t *option;
-ppd_choice_t *choice;
-
-option = ppdFindOption(ppd, "PageSize");
-choice = ppdFindChoice(option, "Letter");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>,
-<A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ppd_choice_t *
-ppdFindMarkedChoice(ppd_file_t *ppd,
- const char *keyword);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>keyword</TD>
- <TD>The name of the option</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the choice data or NULL if the choice does not exist or
-is not marked.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to
-the marked choice data for the specified option.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_choice_t *choice;
-
-choice = ppdFindMarkedChoice(ppd, "PageSize");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
-<A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdFindOption">ppdFindOption()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ppd_option_t *
-ppdFindOption(ppd_file_t *ppd,
- const char *keyword);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>keyword</TD>
- <TD>The name of the option</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the option data or NULL if the option does not exist.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the option
-data for the specified option.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_option_t *option;
-
-option = ppdFindOption(ppd, "PageSize");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
-<A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ppdIsMarked(ppd_file_t *ppd,
- const char *keyword,
- const char *choice);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>keyword</TD>
- <TD>The name of the option</TD>
-</TR>
-<TR>
- <TD>choice</TD>
- <TD>The name of the option choice</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>1 if the choice is marked, 0 otherwise.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the
-specified option choice is marked.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Letter size %s selected.\n",
- ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
-<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
-<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
-<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
-<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-void
-ppdMarkDefaults(ppd_file_t *ppd);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default
-choices in the PPD file.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdMarkDefaults(ppd);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
-<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
-<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
-<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
-<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-int
-ppdMarkOption(ppd_file_t *ppd,
- const char *keyword,
- const char *choice);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>keyword</TD>
- <TD>The name of the option</TD>
-</TR>
-<TR>
- <TD>choice</TD>
- <TD>The name of the choice</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The number of conflicts in the PPD file.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdMarkOption()</CODE> function marks the specified option
-choice.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppdMarkOption(ppd, "PageSize", "Letter");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
-<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
-<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
-<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
-<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdOpen">ppdOpen()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ppd_file_t *
-ppdOpen(FILE *file);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>file</TD>
- <TD>The file to read from</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a PPD file structure or NULL if the PPD file could not be
-read.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the specified
-file into memory.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-FILE *file;
-
-file = fopen("filename.ppd", "rb");
-ppd = ppdOpen(file);
-fclose(file);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
-<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
-<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ppd_file_t *
-ppdOpenFd(int fd);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>fd</TD>
- <TD>The file descriptor to read from</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a PPD file structure or NULL if the PPD file could not be
-read.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the specified
-file descriptor into memory.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-int fd;
-
-fd = open("filename.ppd", O_RDONLY);
-ppd = ppdOpenFd(fd);
-close(fd);
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
-<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
-<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ppd_file_t *
-ppdOpenFile(const char *filename);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>filename</TD>
- <TD>The name of the file to read from</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to a PPD file structure or NULL if the PPD file could not be
-read.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the named
-file into memory.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-ppd = ppdOpenFile("filename.ppd");
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
-<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
-<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdPageLength">ppdPageLength()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-float
-ppdPageLength(ppd_file_t *ppd,
- const char *name);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the page size</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The length of the specified page size in points or 0 if the page size
-does not exist.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdPageLength()</CODE> function returns the page length of the
-specified page size.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
-<A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>,
-<A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdPageSize">ppdPageSize()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-ppd_size_t *
-ppdPageSize(ppd_file_t *ppd,
- const char *name);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the page size</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>A pointer to the page size record of the specified page size in
-points or NULL if the page size does not exist.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdPageSize()</CODE> function returns the page size record for the
-specified page size.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-ppd_size_t *size;
-
-size = ppdPageSize(ppd, "Letter");
-if (size != NULL)
-{
- printf(" Width = %.0f\n", size->width);
- printf("Length = %.0f\n", size->length);
- printf(" Left = %.0f\n", size->left);
- printf(" Right = %.0f\n", size->right);
- printf("Bottom = %.0f\n", size->bottom);
- printf(" Top = %.0f\n", size->top);
-}
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
-<A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
-
-
-<!-- NEW PAGE --><H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2>
-
-<H3>Usage</H3>
-
-<PRE>
-float
-ppdPageWidth(ppd_file_t *ppd,
- const char *name);
-</PRE>
-
-<H3>Arguments</H3>
-
-<CENTER><TABLE WIDTH="80%" BORDER>
-<TR>
- <TH>Argument</TH>
- <TH>Description</TH>
-</TR>
-<TR>
- <TD>ppd</TD>
- <TD>The PPD file</TD>
-</TR>
-<TR>
- <TD>name</TD>
- <TD>The name of the page size</TD>
-</TR>
-</TABLE></CENTER>
-
-<H3>Returns</H3>
-
-<P>The width of the specified page size in points or 0 if the page size
-does not exist.
-
-<H3>Description</H3>
-
-<P>The <CODE>ppdPageWidth()</CODE> function returns the page width of the
-specified page size.
-
-<H3>Example</H3>
-
-<PRE>
-#include <cups/ppd.h>
-
-ppd_file_t *ppd;
-
-printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));
-</PRE>
-
-<H3>See Also</H3>
-
-<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
-<A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>
-
-
-</BODY>
-</HTML>
projects / thirdparty / cups.git / blobdiff