3 <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2003, All Rights Reserved">
4 <META NAME="DOCNUMBER" CONTENT="CUPS-SPM-1.2.0">
5 <META NAME="Author" CONTENT="Easy Software Products">
6 <TITLE>CUPS Software Programmers Manual</TITLE>
10 <H1 ALIGN="RIGHT">Preface</H1>
12 <P>This software programmers manual provides software
13 programming information for the Common UNIX Printing System
14 ("CUPS") Version 1.2.0.
16 <EMBED SRC="system-overview.shtml">
19 <H2>Document Overview</H2>
21 <P>This software programmers manual is organized into the following sections:
24 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A>
25 <LI><A HREF="#CUPS_API">2 - The CUPS API</A>
26 <LI><A HREF="#WRITING_FILTERS">3 - Writing Filters</A>
27 <LI><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A>
28 <LI><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A>
29 <LI><A HREF="#LICENSE">A - Software License Agreement</A>
30 <LI><A HREF="#CONSTANTS">B - Constants</A>
31 <LI><A HREF="#STRUCTURES">C - Structures</A>
32 <LI><A HREF="#FUNCTIONS">D - Functions</A>
35 <H2>Notation Conventions</H2>
37 <P>Various font and syntax conventions are used in this guide. Examples and
38 their meanings and uses are explained below:
40 <CENTER><TABLE WIDTH="80%">
43 <TD> </TD>
46 <TR><TD> </TD></TR>
48 <TD><CODE>lpstat</CODE><BR>
49 <CODE>lpstat(1)</CODE></TD>
51 <TD> </TD>
53 <TD>The names of commands; the first mention of a command or
54 function in a chapter is followed by a manual page section
57 <TR><TD> </TD></TR>
59 <TD><VAR>/var</VAR><BR>
60 <VAR>/usr/share/cups/data/testprint.ps</VAR></TD>
62 <TD> </TD>
64 <TD>File and directory names.</TD>
66 <TR><TD> </TD></TR>
68 <TD NOWRAP><TT>Request ID is Printer-123</TT></TD>
70 <TD> </TD>
72 <TD>Screen output.</TD>
74 <TR><TD> </TD></TR>
76 <TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD>
78 <TD> </TD>
80 <TD>Literal user input; special keys like <KBD>ENTER</KBD> are
83 <TR><TD> </TD></TR>
87 <TD> </TD>
89 <TD>Numbers in the text are written using the period (.) to indicate
90 the decimal point.</TD>
95 <H2>Abbreviations</H2>
97 The following abbreviations are used throughout this manual:
103 <DD>Kilobytes, or 1024 bytes<BR>
106 <DD>Megabytes, or 1048576 bytes<BR>
109 <DD>Gigabytes, or 1073741824 bytes<BR>
114 <H2>Other References</H2>
119 <DT>CUPS Software Administrators Manual
121 <DD>An administration guide for the CUPS software.<BR>
123 <DT>CUPS Software Users Manual
125 <DD>An end-user guide for using the CUPS software.<BR>
131 <EMBED SRC="printing-overview.shtml">
134 <H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1>
136 <P>This chapter describes the CUPS Application Programmers Interface ("API").
138 <H2>The CUPS API Library</H2>
140 <P>The CUPS library provides a whole collection of interfaces needed to
141 support the internal needs of the CUPS software as well as the needs of
142 applications, filters, printer drivers, and backends.
144 <P>Unlike the rest of CUPS, the CUPS API library is provided under the
145 GNU Library General Public License. This means that you can use the
146 CUPS API library in both proprietary and open-source programs.
148 <P>Programs that use the CUPS API library typically will include the
149 <CODE><cups/cups.h></CODE> header file:
152 #include <cups/cups.h>
156 jobid = cupsPrintFile("myprinter", "filename.ps", "title",
157 num_options, options);
160 <P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS API
164 <B>cc -o program program.c -lcups ENTER</B>
167 <P>Additional options and libraries may be required depending on the
168 operating system and the location of the CUPS API library.
170 <H3>Detecting the CUPS API Library in GNU Autoconf</H3>
172 <P>GNU autoconf is a popular configuration tool used by many programs.
173 Add the following lines to your <VAR>configure.in</VAR> file to check
174 for the CUPS API library in your configuration script:
177 AC_CHECK_LIB(socket,socket,
178 if test "$uname" != "IRIX"; then
179 LIBS="-lsocket $LIBS"
181 echo "Not using -lsocket since you are running IRIX."
183 AC_CHECK_LIB(nsl,gethostbyaddr,
184 if test "$uname" != "IRIX"; then
187 echo "Not using -lnsl since you are running IRIX."
190 AC_CHECK_LIB(cups,httpConnect)
193 <H2>Printing Services</H2>
195 <P>The CUPS API library provides some basic printing services for applications
196 that need to print files.
198 <H3>Include Files</H3>
200 <P>The include file used by all of these functions is
201 <CODE><cups/cups.h></CODE>:
204 #include <cups/cups.h>
207 <H3>Printing a File</H3>
209 <P>The CUPS API provides two functions for printing files. The first is
210 <CODE>cupsPrintFile</CODE> which prints a single named file:
213 #include <cups/cups.h>
221 jobid = cupsPrintFile("<I>name</I>", "<I>filename</I>", "<I>title</I>", 0, NULL);
224 <P>The <CODE>name</CODE> string is the name of the printer or class to
225 print to. The <CODE>filename</CODE> string is the name of the file to
226 print. The <CODE>title</CODE> string is the name of the print job, e.g.
227 "Acme Word Document".
229 <P>The return value is a unique ID number for the print job or 0 if there
232 <H3>Printing Multiple Files</H3>
234 <P>The second printing function is <CODE>cupsPrintFiles</CODE>:
237 #include <cups/cups.h>
243 const char *files[100];
246 jobid = cupsPrintFiles("name", <I>num_files</I>, <I>files</I>, "title", 0, NULL);
249 <P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE>
250 you pass a file count (<CODE>num_files</CODE>) and filename pointer array
251 (<CODE>files</CODE>) for each file that you want to print.
253 <P>As with <CODE>cupsPrintFile()</CODE> the return value is a unique ID for
256 <H3>Cancelling Jobs</H3>
258 <P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:
261 #include <cups/cups.h>
269 status = cupsCancelJob("<I>name</I>", <I>jobid</I>);
272 <P>The <CODE>name</CODE> string specifies the destination and is used
273 to determine the server to send the request to. The <CODE>jobid</CODE>
274 value is the integer returned from a previous <CODE>cupsPrintFile()</CODE>
275 or <CODE>cupsPrintFiles()</CODE> call.
277 <P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
278 successfully cancelled and <CODE>0</CODE> if there was an error.
280 <H3>Getting the Available Printers and Classes</H3>
282 <P>The <CODE>cupsGetDests()</CODE> function can be used to get a list
283 of the available printers, classes, and instances that a user has defined:
286 #include <cups/cups.h>
295 num_dests = cupsGetDests(&dests);
298 <P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure which
299 defines the printer or class name, the instance name (if any), if it is the
300 default destination, and the default options the user has defined for the
304 typedef struct /**** Destination ****/
306 char *name, /* Printer or class name */
307 *instance; /* Local instance name or NULL */
308 int is_default; /* Is this printer the default? */
309 int num_options; /* Number of options */
310 cups_option_t *options; /* Options */
314 <P>The destinations are sorted by name and instance for your convenience.
315 Once you have the list of available destinations, you can lookup a specific
316 destination using the <CODE>cupsGetDest()</CODE> function:
319 #include <cups/cups.h>
329 mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests);
332 <P>The <CODE>name</CODE> string is the printer or class name. You can pass
333 a value of <CODE>NULL</CODE> to get the default destination.
335 <P>The <CODE>instance</CODE> string is the user-defined instance name. Pass
336 <CODE>NULL</CODE> to select the default instance, e.g. "name" instead of
339 <H3>Printing with Options</H3>
341 <P>All of the previous printing examples have passed <CODE>0</CODE> and
342 <CODE>NULL</CODE> for the last two arguments to the <CODE>cupsPrintFile()</CODE>
343 and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments are the
344 number of options and a pointer to the option array:
347 int cupsPrintFile(const char *name, const char *filename, const char *title,
348 int num_options, cups_option_t *options);
349 int cupsPrintFiles(const char *name, int num_files, const char **files,
350 const char *title, int num_options,
351 cups_option_t *options);
354 <P>The <CODE>cups_option_t</CODE> structure holds each option and its value.
355 These are converted as needed and passed to the CUPS server when printing a
358 <P>The simplest way of handling options is to use the <CODE>num_options</CODE>
359 and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE>
360 structure described earlier:
363 #include <cups/cups.h>
374 mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests);
376 jobid = cupsPrintFile(mydest->name, "filename", "title",
377 mydest->num_options, mydest->options);
380 <P>This effectively uses the options a user has previous selected without a
383 <H3>Setting Printer Options</H3>
385 <P>Options can also be set by your program using the <CODE>cupsAddOption()</CODE>
389 #include <cups/cups.h>
394 cups_option_t *options;
403 num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
404 num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
405 num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
406 num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options);
409 <P>The <CODE>name</CODE> string is the name of the option, and the
410 <CODE>value</CODE> string is the value for that option.
412 <P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of
413 options. Since adding two options with the same name overwrites the
414 first value with the second, do not assume that calling
415 <CODE>cupsAddOptions()</CODE> 20 times will result in 20 options.
417 <P>Call <CODE>cupsFreeOptions</CODE> once you are done using the options:
420 #include <cups/cups.h>
425 cups_option_t *options;
429 cupsFreeOptions(num_options, options);
432 <H3>Getting Errors</H3>
434 <P>If any of the CUPS API printing functions returns an error, the reason for
435 that error can be found by calling <CODE>cupsLastError()</CODE> and
436 <CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE> returns the
437 last IPP error code that was encountered. <CODE>cupsErrorString()</CODE>
438 converts the error code to a localized message string suitable for
439 presentation to the user:
442 #include <cups/cups.h>
451 puts(cupsErrorString(cupsLastError()));
454 <H3>Passwords and Authentication</H3>
456 <P>CUPS supports authentication of any request, including
457 submission of print jobs. The default mechanism for getting the
458 username and password is to use the login user and a password
461 <P>To support other types of applications, in particular
462 Graphical User Interfaces ("GUIs"), the CUPS API provides
463 functions to set the default username and to register a callback
464 function that returns a password string.
466 <P>The <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>
467 function is used to set a password callback in your program. Only one
468 function can be used at any time.
470 <P>The <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A> function sets
471 the current username for authentication. This function can be called by
472 your password callback function to change the current username as needed.
474 <P>The following example shows a simple password callback that gets a
475 username and password from the user:
478 #include <cups/cups.h>
481 my_password_cb(const char *prompt)
488 /* Get a username from the user */
489 printf("Username: ");
490 if (fgets(user, sizeof(user), stdin) == NULL)
493 /* Strip the newline from the string and set the user */
494 user[strlen(user) - 1] = '\0';
498 /* Use getpass() to ask for the password... */
499 return (getpass("Password: "));
504 cupsSetPasswordCB(my_password_cb);
507 <P>Similarly, a GUI interface could display the prompt string in a
508 window with input fields for the username and password. The username
509 should probably default to the value of
510 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> to make things easier
513 <H2>PPD Services</H2>
515 <P>CUPS includes functions to access and manipulate PostScript Printer
516 Description ("PPD") files that are used with the printer drivers in CUPS.
518 <P>Each PPD file enumerates the available features provided by a
519 printer, including conflict information for specific options (e.g.
520 can't duplex output on envelopes.)
522 <H3>Include Files</H3>
524 <P>Include the <CODE><cups/ppd.h></CODE> header file to use the PPD
528 #include <cups/ppd.h>
531 <P>This header file is also included by the
532 <CODE><cups/cups.h></CODE> header file.
534 <H3>Getting a PPD File for a Printer</H3>
536 <P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the
537 named printer or class:
540 #include <cups/cups.h>
544 const char *filename;
546 filename = cupsGetPPD("<I>name</I>");
549 <P>The <CODE>name</CODE> string is the name of the printer or class, including
550 the remote server name as appropriate (e.g. "printer@server".)
552 <P>The return value is a pointer to a filename in static storage; this value
553 is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If the printer
554 or class does not exist, a <CODE>NULL</CODE> pointer will be returned.
556 <H3>Loading a PPD File</H3>
558 <P>The <CODE>ppdOpenFile()</CODE> function "opens" a PPD file and loads it
562 #include <cups/ppd.h>
568 ppd = ppdOpenFile("<I>filename</I>");
571 <P>The <CODE>filename</CODE> string is the name of the file to load, such as
572 the value returned by the <CODE>cupsGetPPD()</CODE> function.
574 <P>The return value is a pointer to a structure describing the contents of the
575 PPD file or NULL if the PPD file could not be read.
577 <H3>Freeing PPD File Information</H3>
579 <P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE> function
580 to free all memory that has been used:
583 #include <cups/ppd.h>
594 <H3>The PPD File Structure</H3>
596 <P>Each PPD file contains a number of capability attributes, printer options,
597 and conflict definitions. The page size options also include the physical
598 margins for the printer and the minimum and maximum sizes for the printer.
599 All of this information is stored in the <CODE>ppd_file_t</CODE> structure.
601 <H4>Capabilities</H4>
603 <P>Each PPD file contains a number of informational attributes that
604 describe the capabilities of the printer. These are provided in the
605 <CODE>ppd_file_t</CODE> structure in the following members:
607 <CENTER><TABLE WIDTH="80%" BORDER="1">
614 <TD><CODE>accurate_screens</CODE></TD>
615 <TD><CODE>int</CODE></TD>
616 <TD>1 = supports accurate screens</TD>
619 <TD><CODE>color_device</CODE></TD>
620 <TD><CODE>int</CODE></TD>
621 <TD>1 = color device</TD>
624 <TD><CODE>colorspace</CODE></TD>
625 <TD><CODE>ppd_cs_t</CODE></TD>
626 <TD>Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY,
627 PPD_CS_RGB, PPD_CS_RGBK, PPD_CS_N</TD>
630 <TD><CODE>contone_only</CODE></TD>
631 <TD><CODE>int</CODE></TD>
632 <TD>1 = printer is continuous tone only</TD>
635 <TD><CODE>num_emulations<BR>
636 emulations</CODE></TD>
638 ppd_emul_t *</CODE></TD>
639 <TD>Emulations supported by the printer</TD>
642 <TD><CODE>flip_duplex</CODE></TD>
643 <TD><CODE>int</CODE></TD>
644 <TD>1 = need to flip odd pages when duplexing</TD>
647 <TD><CODE>num_fonts<BR>
651 <TD>The fonts available on the printer.</TD>
654 <TD><CODE>jcl_begin<BR>
657 <TD><CODE>char *</CODE></TD>
658 <TD>Job Control Language commands for PostScript output</TD>
661 <TD><CODE>landscape</CODE></TD>
662 <TD><CODE>int</CODE></TD>
663 <TD>Landscape orientation, -90 or 90 degrees</TD>
666 <TD><CODE>lang_encoding</CODE></TD>
667 <TD><CODE>char *</CODE></TD>
668 <TD>The character used for the option strings</TD>
671 <TD><CODE>lang_version</CODE></TD>
672 <TD><CODE>char *</CODE></TD>
673 <TD>The language used for the options strings (English, French, etc.)</TD>
676 <TD><CODE>language_level</CODE></TD>
677 <TD><CODE>int</CODE></TD>
678 <TD>PostScript language level, 1 to 3</TD>
681 <TD><CODE>manual_copies</CODE></TD>
682 <TD><CODE>int</CODE></TD>
683 <TD>1 = Copies are done manually</TD>
686 <TD><CODE>model_number</CODE></TD>
687 <TD><CODE>int</CODE></TD>
688 <TD>Driver-specific model number.</TD>
691 <TD><CODE>patches</CODE></TD>
692 <TD><CODE>char *</CODE></TD>
693 <TD>Patch commands to send to the printer</TD>
696 <TD><CODE>manufacturer</CODE></TD>
697 <TD><CODE>char *</CODE></TD>
698 <TD>The Manufacturer attribute from the PPD file, if any</TD>
701 <TD><CODE>modelname</CODE></TD>
702 <TD><CODE>char *</CODE></TD>
703 <TD>The ModelName attribute from the PPD file</TD>
706 <TD><CODE>nickname</CODE></TD>
707 <TD><CODE>char *</CODE></TD>
708 <TD>The NickName attribute from the PPD file, if any</TD>
711 <TD><CODE>product</CODE></TD>
712 <TD><CODE>char *</CODE></TD>
713 <TD>The Product attribute from the PPD file, if any</TD>
716 <TD><CODE>shortnickname</CODE></TD>
717 <TD><CODE>char *</CODE></TD>
718 <TD>The ShortNickName attribute from the PPD file, if any</TD>
721 <TD><CODE>throughput</CODE></TD>
722 <TD><CODE>int</CODE></TD>
723 <TD>Number of pages per minute</TD>
726 <TD><CODE>ttrasterizer</CODE></TD>
727 <TD><CODE>char *</CODE></TD>
728 <TD>The TruType font rasterizer (Type42)</TD>
731 <TD><CODE>variable_sizes</CODE></TD>
732 <TD><CODE>int</CODE></TD>
733 <TD>1 = supports variable sizes</TD>
737 <H4>Options and Groups</H4>
739 <P>PPD files support multiple options, which are stored in
740 <CODE>ppd_option_t</CODE> and <CODE>ppd_choice_t</CODE> structures by
743 <P>Each option in turn is associated with a group
744 stored in the <CODE>ppd_group_t</CODE> structure. Groups can be
745 specified in the PPD file; if an option is not associated with a group
746 then it is put in a "General" or "Extra" group depending on the option.
748 <P>Groups can also have sub-groups; CUPS currently limits the depth of
749 sub-groups to 1 level to reduce programming complexity.
753 <P>PPD files support specification of conflict conditions between
754 different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE>
755 structures which specify the options that conflict with each other.
759 <P>PPD files specify all of the available pages sizes and the physical
760 margins associated with them. These sizes are stored in
761 <CODE>ppd_size_t</CODE> structures and are available in the
762 <CODE>num_sizes</CODE> and <CODE>sizes</CODE> members of the
763 <CODE>ppd_file_t</CODE> structure. You can lookup a particular page size
764 with the <CODE>ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and
765 <CODE>ppdPageSize()</CODE> functions:
768 #include <cups/ppd.h>
779 size = ppdPageSize(ppd, "<I>size</I>");
780 width = ppdPageWidth(ppd, "<I>size</I>");
781 length = ppdPageLength(ppd, "<I>size</I>");
784 <P>The <CODE>size</CODE> string is the named page size option. The
785 width and length are in points; there are 72 points per inch. The
786 <CODE>ppd_size_t</CODE> structure contains the width, length, and
790 typedef struct /**** Page Sizes ****/
792 int marked; /* Page size selected? */
793 char name[41]; /* Media size option */
794 float width, /* Width of media in points */
795 length, /* Length of media in points */
796 left, /* Left printable margin in points */
797 bottom, /* Bottom printable margin in points */
798 right, /* Right printable margin in points */
799 top; /* Top printable margin in points */
803 <H4>Custom Page Sizes</H4>
805 <P>Besides the standard page sizes listed in a PPD file, some printers
806 support variable or custom page sizes. If <CODE>variables_sizes</CODE>
807 is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and
808 <CODE>custom_margins</CODE> members of the <CODE>ppd_file_t</CODE>
809 structure define the limits of the variable sizes.
811 <P>To get the resulting media size, use a page size string of
812 <CODE>Custom.<I>width</I>x<I>length</I></CODE>, where <CODE>width</CODE>
813 and <CODE>length</CODE> are integer values in points:
816 Custom.612x792 [8.5 inches wide, 11 inches long]
817 Custom.1224x792 [17 inches wide, 11 inches long]
820 <H3>Marking Options</H3>
822 <P>Before marking any user-defined options, call the <CODE>ppdMarkDefaults()</CODE>
823 function to mark the default options from the PPD file:
826 #include <cups/ppd.h>
834 ppdMarkDefaults(ppd);
837 <P>Then call the <CODE>ppdMarkOption()</CODE> function to mark individual
841 #include <cups/ppd.h>
850 conflicts = ppdMarkOption(ppd, "<I>name</I>", "<I>value</I>");
853 <P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a
854 particular option and choice, respectively. The return value is 0
855 if there are not conflicts created by the selection.
857 <P>CUPS also provides a convenience function for marking all options
858 in the <CODE>cups_option_t</CODE> structure:
861 #include <cups/cups.h>
867 cups_option_t *options;
872 conflicts = cupsMarkOptions(ppd, num_options, options);
875 <P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the
876 IPP job template attributes to PPD options. The return value is the number
877 of conflicts present.
879 <H3>Checking for Conflicts</H3>
881 <P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE>
882 functions return the number of conflicts with the currently marked options.
884 <P>Call the <CODE>ppdConflicts()</CODE> function to get the number of
885 conflicts after you have marked all of the options:
888 #include <cups/cups.h>
897 conflicts = ppdConflicts(ppd);
900 <P>The return value is the number of conflicting options, or 0 if there
904 <H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
906 <P>This chapter describes how to write a file filter for CUPS.
910 <P>File filters are programs that convert from one or more MIME types to
911 another type. Filters use a common command-line and environment interface
912 that allows them to be joined as needed to print files to any type of
915 <H3>Security Considerations</H3>
917 <P>Filters are normally run as a non-priviledged user, so the major
918 security consideration is resource utilization - filters should not
919 depend on unlimited amounts of memory and disk space.
921 <H3>Users and Groups</H3>
923 <P>The default CUPS configuration runs filters as user "lp" and group "other".
925 <H3>Temporary Files</H3>
927 <P>Temporary files should be created in the directory specified by the
928 "TMPDIR" environment variable. The
929 <A HREF="#cupsTempFile"><CODE>cupsTempFile()</CODE></A> function can be
930 used to safely choose temporary files in this directory.
932 <H3>Sending Messages to the User</H3>
934 <P>The CUPS scheduler collects messages sent to the standard error file
935 by the filter. These messages are relayed to the user based upon the
936 scheduler <CODE>LogLevel</CODE> directive.
938 <P>The type of message is determined by an initial prefix sent on each
943 <LI><CODE>DEBUG:</CODE> - a debug message
945 <LI><CODE>INFO:</CODE> - an informational message
947 <LI><CODE>WARNING:</CODE> - a warning message
949 <LI><CODE>ERROR:</CODE> - an error message
951 <LI><CODE>PAGE:</CODE> - a page accounting message
955 <P>If the line of text does not begin with any of the above prefixes, it
956 is treated as a debug message. Text following the prefix is copied to the
957 <CODE>printer-state-message</CODE> attribute for the printer, and also
958 added to the <VAR>error_log</VAR> unless it is an informational or page
961 <H3>Page Accounting</H3>
963 <P>Page accounting messages are used to inform the server when one or more
964 pages are printed. Each line has the form:
967 PAGE: page-number copy-count
970 <P>The <I>page-number</I> field is the current page number, starting at 1.
971 The <I>copy-count</I> field specifies the number of copies of that page
974 <P>Page account messages are added to the <VAR>page_log</VAR> file and
975 cause the <CODE>job-sheets-completed</CODE> attribute to be updated for
978 <H3>Command-Line Arguments</H3>
980 <P>Every filter accepts exactly 6 or 7 command-line arguments:
983 printer job user title copies options [filename]
986 <LI><CODE>printer</CODE> - The name of the printer queue (normally
987 this is the name of the program being run)
989 <LI><CODE>job</CODE> - The numeric job ID for the job being
992 <LI><CODE>user</CODE> - The string from the
993 <CODE>originating-user-name</CODE> attribute
995 <LI><CODE>title</CODE> - The string from the
996 <CODE>job-name</CODE> attribute
998 <LI><CODE>copies</CODE> - The numeric value from the
999 <CODE>number-copies</CODE> attribute
1001 <LI><CODE>options</CODE> - String representations of the
1002 job template attributes, separated by spaces. Boolean attributes
1003 are provided as "name" for true values and "noname" for false
1004 values. All other attributes are provided as "name=value" for
1005 single-valued attributes and "name=value1,value2,...,valueN" for
1008 <LI><CODE>filename</CODE> - The request file
1012 <P>The <I>filename</I> argument is only provided to the first filter in the
1013 chain; all filters <B>must</B> be prepared to read the print file from
1014 the standard input if the <I>filename</I> argument is omitted.
1016 <H3>Copy Generation</H3>
1018 <P>The <I>copies</I> argument specifies the number of copies to produce
1019 of the input file. In general, you should only generate copies if the
1020 <I>filename</I> argument is supplied. The only exception to this are
1021 filters that produce device-independent PostScript output (without any
1022 printer commands from the printer's PPD file), since the PostScript
1023 filter <CODE>pstops</CODE> is responsible for copy generation.
1025 <H3>Environment Variables</H3>
1027 <P>Every filter receives a fixed set of environment variables that can
1028 be used by the filter:
1032 <LI><CODE>CHARSET</CODE> - The character set used by the client for
1035 <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as
1036 "application/postscript"
1038 <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files
1040 <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration
1043 <LI><CODE>DEVICE_URI</CODE> - The output device URI
1045 <LI><CODE>LANG</CODE> - The language used by the client for
1048 <LI><CODE>PATH</CODE> - The execution path exported to the filter
1050 <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file
1052 <LI><CODE>PRINTER</CODE> - The name of the printer queue
1054 <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter
1057 <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically
1060 <LI><CODE>TZ</CODE> - The local timezone
1062 <LI><CODE>USER</CODE> - The name of the current user
1066 <H2>Dissecting the HP-GL/2 Filter</H2>
1068 <P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a
1069 complex program that converts HP-GL/2 files into device-independent PostScript
1070 output. Since it produces device-independent PostScript output, it does not
1071 need to handle copy generation or writing printer options from the printer's
1074 <H3>Initializing the Filter</H3>
1076 <P>The first task of any filter is to ensure that the correct number of
1077 command-line arguments are present:
1080 if (argc < 6 || argc > 7)
1082 fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr);
1087 <P>After this you open the print file or read from the standard input
1094 * If we have 7 arguments, print the file named on the command-line.
1095 * Otherwise, send stdin instead...
1103 * Try to open the print file...
1106 if ((fp = fopen(argv[6], "rb")) == NULL)
1108 perror("ERROR: unable to open print file - ");
1114 <P>Once the print file has been opened, options can be processed using
1115 the <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A> and
1116 <A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A> functions:
1120 cups_option_t *options;
1124 * Process command-line options and write the prolog...
1128 num_options = cupsParseOptions(argv[5], 0, &options);
1130 if ((val = cupsGetOption("blackplot", num_options, options)) != NULL)
1133 if ((val = cupsGetOption("fitplot", num_options, options)) != NULL)
1136 if ((val = cupsGetOption("penwidth", num_options, options)) != NULL)
1137 PenWidth = (float)atoi(val) * 0.001f;
1140 <P>After the options have been processed, the filter writes PostScript code
1141 to the standard output based on the print file, closes the print file (as
1142 needed), and returns 0 to the scheduler.
1144 <H2>PostScript Output</H2>
1146 <P>Filters that produce PostScript output must generate output conforming
1147 to the Adobe Document Structuring Conventions, 3.0. In general this means
1148 the beginning of each file must begin with:
1152 %%BoundingBox: left bottom right top
1157 <P>The <I>left</I>, <I>bottom</I>, <I>right</I>, and <I>top</I> values
1158 are integers in points from the lower-lefthand corner of the page.
1160 <P>Pages must be surrounded by:
1163 %%Page: number number
1170 <P>And the end of each file must contain:
1174 %%Pages: number-pages
1178 <P>These comments allow the PostScript filter to correctly perform page
1179 accounting, copy generation, N-up printing, and so forth.
1181 <H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A></H1>
1183 <P>This chapter discusses how to write a printer driver, which is a
1184 special filter program that converts CUPS raster data into the
1185 appropriate commands and data required for a printer.
1189 <P>Raster printers utilitize PPD files that specify one or more
1190 device-specific filters that handle converting print files for the
1191 printer. The simplest raster printer drivers provide a single filter
1192 that converts CUPS raster data to the printer's native format.
1194 <H3>CUPS Raster Data</H3>
1196 <P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists of
1197 a stream of raster page descriptions produced by one of the RIP filters,
1198 such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.
1200 <P>Each page of data begins with a page dictionary structure called
1201 <A HREF="#cups_raster_header_t"><CODE>cups_raster_header_t</CODE></A>. This
1202 structure contains the colorspace, bits per color, media size, media type,
1203 hardware resolution, and so forth.
1205 <P>After the page dictionary comes the page data which is a full-resolution,
1206 uncompressed bitmap representing the page in the printer's output colorspace.
1208 <H3>Page Accounting</H3>
1210 <P>Printer drivers must handle all page accounting. This means they must
1211 send "PAGE:" messages to the standard error file for each page (and in many
1212 cases, copy) sent to the printer.
1214 <H3>Color Management</H3>
1216 <P>Printer drivers can implement their color management via the
1217 <CODE>cupsColorProfile</CODE> attributes in the PPD file or internally
1218 in the driver from a device-independent colorspace. In general, color
1219 management performed by the RIP filters is more efficient than that
1220 performed inside printer drivers.
1222 <P>For example, the <CODE>pstoraster</CODE> filter often only has to
1223 perform a color conversion once each time the color is used for
1224 multiple output pixels, while the raster filter must convert every
1227 <H3>Device and Bitmap Variables</H3>
1229 <P>Besides the standard PostScript page device dictionary variables defined
1230 in the Adobe PostScript Level 3 reference manual, the CUPS filters support
1231 additional variables that are passed in the page device dictionary header for
1232 the page and in some cases control the type of raster data that is generated:
1234 <CENTER><TABLE WIDTH="90%" BORDER="1">
1238 <TH>Description</TH>
1242 <TD>read-only integer</TD>
1243 <TD>Width of bitmap in pixels</TD>
1247 <TD>read-only integer </TD>
1248 <TD>Height of bitmap in pixels</TD>
1251 <TD>cupsMediaType</TD>
1252 <TD>read-write integer</TD>
1253 <TD>Device-specific media type code</TD>
1256 <TD>cupsBitsPerColor</TD>
1257 <TD>read-write integer</TD>
1258 <TD>Number of bits per color; 1, 2, 4, and 8 are currently
1262 <TD>cupsBitsPerPixel</TD>
1263 <TD>read-only integer </TD>
1264 <TD>Number of bits per pixel; 1 to 32</TD>
1267 <TD>cupsBytesPerLine</TD>
1268 <TD>read-only integer</TD>
1269 <TD>Number of bytes per line of raster graphics</TD>
1272 <TD>cupsColorOrder</TD>
1273 <TD>read-write enum</TD>
1274 <TD>The order of color values in the bitmap:
1276 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK CMYK CMYK
1277 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK
1278 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ...
1283 <TD>cupsColorSpace</TD>
1284 <TD>read-write enum</TD>
1285 <TD>The colorspace of the bitmap:
1287 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)
1288 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue
1289 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha
1290 <LI><CODE>CUPS_CSPACE_K</CODE> - Black
1291 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow
1292 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan
1293 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black
1294 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black
1295 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow
1296 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
1297 light cyan, light magenta
1298 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta,
1299 metallic cyan, black
1300 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta,
1301 metallic cyan, metallic grey (silver)
1302 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)
1303 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)
1304 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)
1309 <TD>cupsCompression</TD>
1310 <TD>read-write integer</TD>
1311 <TD>Device-specific compression type code</TD>
1314 <TD>cupsRowCount</TD>
1315 <TD>read-write integer</TD>
1316 <TD>Device-specific row count value</TD>
1319 <TD>cupsRowFeed</TD>
1320 <TD>read-write integer</TD>
1321 <TD>Device-specific row feed value</TD>
1324 <TD>cupsRowStep</TD>
1325 <TD>read-write integer</TD>
1326 <TD>Device-specific row step value</TD>
1330 <P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit per
1331 color are transmitted to the raster driver in KCMY colorspace; the driver
1332 is responsible for producing the correct separation of normal and light
1333 cyan and magenta inks.
1335 <H2>Dissecting the HP-PCL Driver</H2>
1337 <P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>) converts
1338 bitmap data from the raster filters into HP-PCL commands for most
1339 PCL-compatible printers. The actual format of the raster data is controlled
1340 by the PPD file being used - <VAR>deskjet.ppd</VAR> or <VAR>laserjet.ppd</VAR>.
1344 <P>PPD files play an important part of all raster printer drivers. Options
1345 defined in the PPD file contain PostScript commands that control the raster
1346 data that is sent to the printer driver.
1348 <P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>,
1349 <CODE>InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>,
1350 and <CODE>Resolution</CODE> options. Each option is shown using the
1351 standard PPD format:
1354 *OpenUI *PageSize/Media Size: PickOne
1355 *OrderDependency: 10 AnySetup *PageSize
1356 *DefaultPageSize: Letter
1357 *PageSize Letter/US Letter: "<<
1362 *PageSize Legal/US Legal: "<<
1363 /PageSize [612 1008]
1367 *PageSize A4/A4: "<<
1375 <P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first
1376 name is the option with an asterisk (*) in front of it. The first name is
1377 usually followed by a slash (/) and a human-readable version of the
1380 <P>Every option <B>must</B> have a default value, specified using the
1381 <CODE>Default<I>Option</I></CODE> keyword.
1383 <P>Each option begins with the option name followed by the computer and
1384 human-readable values. The PostScript commands follow these inside double
1385 quotes. PostScript commands can be provided on a single line:
1388 *PageSize A4/A4: "<</PageSize[595 842]/ImagingBBox null>> setpagedevice"
1391 <P>or broken down on separate lines using the <CODE>End</CODE> keyword to
1395 *PageSize A4/A4: "<<
1402 <P>The choice of the two formats is usually esthetic. However, each line in
1403 a PPD file must not exceed 255 characters, so if your PostScript commands are
1404 long you may need to break them up on separate lines.
1406 <H3>Reading Raster Data</H3>
1408 <P>As with any filter, your printer driver should handle raster data from
1409 a filename specified on the command-line or from the standard input. The
1410 <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function opens
1411 a raster stream for printing:
1414 int fd; /* File descriptor */
1415 cups_raster_t *ras; /* Raster stream for printing */
1419 * Check for valid arguments...
1422 if (argc < 6 || argc > 7)
1425 * We don't have the correct number of arguments; write an error message
1429 fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr);
1434 * Open the page stream...
1439 if ((fd = open(argv[6], O_RDONLY)) == -1)
1441 perror("ERROR: Unable to open raster file - ");
1449 ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
1452 <P>Once you have opened the raster stream you just need to read each
1456 cups_raster_header_t header;
1458 unsigned char data[8192];
1460 while (cupsRasterReadHeader(ras, &header))
1462 ... initialize the printer ...
1463 for (y = header.cupsHeight; y > 0; y ++)
1465 cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
1466 ... send raster line to printer ...
1471 <P>After you have processed all pages, close the raster stream and
1475 cupsRasterClose(ras);
1480 <H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
1482 <P>This chapter describes how to write a backend for CUPS. Backends
1483 communicate directly with printers and allow printer drivers and
1484 filters to send data using any type of connection transparently.
1488 <P>Backends are special filters that communicate with printers directly.
1489 They are treated slightly differently than filters, however, and have some
1490 unique requirements.
1492 <H3>Security Considerations</H3>
1494 <P>Backends are run as the root user, so special care must be taken to
1495 avoid potential security violations. In particular, remember that a backend
1496 will be able to manipulate disk files, devices, and other resources that
1497 potentially could damage a system or printer.
1499 <H3>Command-Line Arguments</H3>
1501 <P>Besides the standard filter arguments, backends are also run with no
1502 arguments to get a list of available devices. This discovery process is
1503 described later in this chapter.
1505 <H3>Copy Generation</H3>
1507 <P>Like filters, backends should send multiple copies of the print file only
1508 if a filename is supplied on the command-line. Otherwise the backend should
1509 assume that the upstream filter has already added the necessary commands or
1510 data to produce the multiple copies.
1512 <H3>Page Accounting</H3>
1514 <P>Backend filters generally do not do page accounting, however they should
1515 at a minimum produce a single page message for each copy that is produced
1516 when a filename is present on the command-line. This is because the user
1517 selected "raw" printing and no other accounting information is possible.
1519 <H3>Exclusive Access</H3>
1521 <P>Backends that talk to local character or block devices should open the
1522 device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate with other
1523 printers defined for the same device.
1527 <P>All backends <B>must</B> retry connections to the device. This
1528 includes backends that talk to local character or block devices, as the
1529 user may define more than one printer queue pointing at the same
1532 <P>To prevent excess CPU utilitization, the backend should go to sleep
1533 for an amount of time between retries; the CUPS-supplied backends retry
1534 once every 30 seconds.
1536 <H2>Dissecting the Serial Port Backend</H2>
1538 <P>The serial port backend provides support for serial printers. Since
1539 it does everything a good backend needs to do, it provides an excellent
1540 example of what to do.
1542 <H3>Supporting Device Discovery</H3>
1544 <P>As previously noted, backends are special filter programs that talk
1545 to printer devices. Another task a backend must perform is to list the
1546 available devices it supports. The backend lists the available devices
1547 when no additioanl arguments are supplied on the command-line (i.e.
1548 just the command name...)
1550 <P>The serial backend lists devices by looking at serial port files in the
1551 <VAR>/dev</VAR> directory, by consulting a hardware inventory (IRIX), and
1552 in some cases by trying to open the ports to see if they actually exist.
1554 <P>Once it finds a serial port it writes a single line for each port to
1555 the standard error file. Each line looks like this:
1558 serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
1561 <P>The first word "serial" is the <I>device class</I>; this identifies the
1562 class of device which can be used to categorize it in user interfaces. CUPS
1563 currently recognizes the following classes:
1567 <LI>"file" - a disk file.
1569 <LI>"direct" - a parallel or fixed-rate serial data port,
1570 currently used for Centronics, IEEE-1284, and USB printer
1573 <LI>"serial" - a variable-rate serial port.
1575 <LI>"network" - a network connection, typically via AppSocket,
1576 HTTP, IPP, LPD, or SMB/CIFS protocols.
1580 <P>After the device class is the <I>device URI</I>, in this case
1581 "serial:/dev/ttyS0?baud=115200". This is the URI that should be used by
1582 the user to select this port. For serial ports, the "baud=115200"
1583 specifies the maximum baud rate supported by the port - the actual
1584 value will vary based on the speed the user selects for the printer.
1586 <P>The last two strings are the model and description for the port. The
1587 "Unknown" string means that the printer model is unknown - some devices
1588 are able to provide a make and model such as "HP DeskJet" that allows
1589 users and software to choose an appropriate printer driver more easily.
1590 Both the model and description must be enclosed inside double quotes.
1592 <H3>Opening the Serial Port</H3>
1594 <P>As noted previously, all backends should open device files in exclusive
1595 mode, and retry as needed until the port is available. The serial port does
1596 this using a <CODE>do-while</CODE> loop:
1601 if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
1605 fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr);
1610 perror("ERROR: Unable to open serial port device file");
1618 <P>If the port is busy or in use by another process, the backend will
1619 go to sleep for 30 seconds and try again. If another error is detected
1620 a message is sent to the user and the backend aborts the print job
1621 until the problem can be corrected.
1623 <H3>Writing Data to the Port</H3>
1625 <P>Network and character devices pose an interesting problem when writing
1626 data to the port - they may not be able to write all of the bytes in your
1627 buffer before returning. To work around this problem you must loop until
1628 all bytes have been written:
1633 if ((wbytes = write(fd, bufptr, nbytes)) < 0)
1634 if (errno == ENOTTY)
1635 wbytes = write(fd, bufptr, nbytes);
1639 perror("ERROR: Unable to send print file to printer");
1648 <P>The check for the <CODE>ENOTTY</CODE> error is needed on some platforms
1649 to clear an error from a previous <CODE>ioctl()</CODE> call.
1651 <H3>Finishing Up</H3>
1653 <P>Once you have sent the print file, return 0 if the file printed
1654 successfully or 1 if it did not. This will allow the scheduler to stop
1655 the print job if there is a device error, preserving the print job for
1656 later printing once the problem has been corrected.
1658 <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
1660 <EMBED SRC="../LICENSE.html">
1663 <H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1>
1665 <P>This appendix lists all of the constants that are defined by the CUPS
1668 <H2>CUPS Constants</H2>
1670 <H3>Version Number</H3>
1672 <P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number
1673 representing the API version number. The current version number is
1674 1.0100 which represents CUPS version 1.1.0.
1676 <H3>Printer Capabilities</H3>
1678 <P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for
1679 printers and classes:
1683 <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.
1685 <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.
1687 <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.
1689 <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.
1691 <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.
1693 <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.
1695 <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.
1697 <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple
1700 <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.
1702 <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.
1704 <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.
1706 <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.
1708 <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.
1710 <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up
1713 <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media
1714 from 9x14 to 18x24 inches.
1716 <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media
1717 larger than 18x24 inches.
1719 <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on
1720 variable or custom media sizes.
1722 <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.
1724 <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability
1731 <P>CUPS defines the following character set encoding constants:
1735 <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.
1737 <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.
1739 <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.
1741 <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.
1743 <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.
1745 <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.
1747 <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.
1749 <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.
1751 <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.
1753 <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.
1755 <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.
1757 <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.
1759 <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.
1761 <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.
1763 <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.
1765 <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.
1767 <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.
1769 <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.
1771 <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.
1773 <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.
1775 <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.
1777 <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.
1779 <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.
1781 <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.
1783 <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.
1785 <LI><CODE>CUPS_KOI8_R</CODE> - Russian code page koi8-r.
1787 <LI><CODE>CUPS_KOI8_U</CODE> - Ukrainian code page koi8-r.
1791 <H2>HTTP Constants</H2>
1795 <P>The following constants define the limits for strings:
1799 <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.
1801 <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.
1803 <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.
1805 <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.
1809 <H3>Status Codes</H3>
1811 <P>The following status codes can be returned by <CODE>httpUpdate()</CODE>:
1815 <LI><CODE>HTTP_ERROR</CODE> - A network error occurred
1817 <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy
1819 <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was successful
1821 <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful
1823 <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful
1825 <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't authoritative
1827 <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command
1829 <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated
1831 <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was recieved/sent
1833 <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request
1835 <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently
1837 <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily
1839 <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...
1841 <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified
1843 <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI
1845 <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request
1847 <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host
1849 <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required
1851 <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI
1853 <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found
1855 <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed
1857 <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable
1859 <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is Required
1861 <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out
1863 <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting
1865 <LI><CODE>HTTP_GONE</CODE> - Server has gone away
1867 <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is required
1869 <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed
1871 <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large
1873 <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long
1875 <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type is unsupported
1877 <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error
1879 <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented
1881 <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway
1883 <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable
1885 <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out
1887 <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported
1893 <P>The following fields are indices for each of the standard HTTP fields in
1898 <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language
1900 <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges
1902 <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization
1904 <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection
1906 <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding
1908 <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language
1910 <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length
1912 <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location
1914 <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5
1916 <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range
1918 <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type
1920 <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version
1922 <LI><CODE>HTTP_FIELD_DATE</CODE> - Date
1924 <LI><CODE>HTTP_FIELD_HOST</CODE> - Host
1926 <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since
1928 <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since
1930 <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive
1932 <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified
1934 <LI><CODE>HTTP_FIELD_LINK</CODE> - Link
1936 <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location
1938 <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range
1940 <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer
1942 <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After
1944 <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding
1946 <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade
1948 <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent
1950 <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate
1955 <H2>IPP Constants</H2>
1959 <P>The following constants define array limits for IPP data:
1963 <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name
1965 <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values
1966 that can be read in a request.
1974 <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
1975 used to separate groups of attributes
1977 <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation
1979 <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job
1981 <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end
1983 <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer
1985 <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type unsupported_group
1987 <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type unsupported_value
1989 <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default
1991 <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown
1993 <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue
1995 <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type notsettable
1997 <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr
1999 <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue
2001 <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer
2003 <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean
2005 <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum
2007 <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string
2009 <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date
2011 <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution
2013 <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range
2015 <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection
2017 <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang
2019 <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang
2021 <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text
2023 <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name
2025 <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword
2027 <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri
2029 <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme
2031 <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset
2033 <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language
2035 <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype
2039 <H3>Resolution Units</H3>
2041 <P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE> constants
2042 specify dots per inch and dots per centimeter, respectively.
2046 <P>The finishing values specify special finishing operations to be
2047 performed on the job.
2051 <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing
2053 <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job
2055 <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job
2057 <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job
2059 <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job
2063 <H3>Orientations</H3>
2065 <P>The orientation values specify the orientation of the job.
2069 <LI><CODE>IPP_PORTRAIT</CODE> - No rotation
2071 <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise
2073 <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise
2075 <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees
2081 <P>The quality values specify the desired quality of the print.
2084 <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality
2086 <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality
2088 <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality
2094 <P>The job state values are used to represent the current job state.
2098 <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending
2100 <LI><CODE>IPP_JOB_HELD</CODE> - Job is held
2102 <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing
2104 <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped
2106 <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled
2108 <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted
2110 <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed
2114 <H3>Printer States</H3>
2116 <P>The printer state values are used to represent the current printer
2121 <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle
2123 <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing
2125 <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped
2131 <P>The operation values represent the available IPP operations.
2135 <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file
2137 <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI
2139 <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes
2141 <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job
2143 <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job
2145 <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job
2147 <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job
2149 <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes
2151 <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs
2153 <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes
2155 <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job
2157 <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job
2159 <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job
2161 <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer
2163 <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer
2165 <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue
2167 <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes
2169 <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes
2171 <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer supported values
2173 <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination
2175 <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers
2177 <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer
2179 <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer
2181 <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes
2183 <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class
2185 <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class
2187 <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class
2189 <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class
2191 <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination
2193 <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices
2195 <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs
2197 <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination
2201 <H3>Status Codes</H3>
2203 <P>Status codes are returned by all IPP requests.
2207 <LI><CODE>IPP_OK</CODE> - Request completed with no errors
2209 <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute
2210 values were substituted
2212 <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes
2215 <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad
2217 <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource
2219 <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for
2222 <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access
2225 <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be
2228 <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred
2230 <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found
2232 <LI><CODE>IPP_GONE</CODE> - The resource has gone away
2234 <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large
2236 <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value
2237 that was unknown to the server
2239 <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not
2240 supported by the server
2242 <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing
2244 <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported
2246 <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported
2248 <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict
2250 <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified
2251 compression is not supported
2253 <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data
2256 <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data
2257 contained an error in it
2259 <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document
2260 could not be accessed
2262 <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an
2265 <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation
2268 <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service
2271 <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request
2272 version is not supported
2274 <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered
2277 <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred
2279 <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting
2282 <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy
2284 <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been
2287 <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server
2288 does not support multiple jobs
2292 <H2>PPD Constants</H2>
2294 <H3>PPD Format Version</H3>
2296 <P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number
2297 representing the newest format version that is supported by CUPS, currently
2300 <H3>PPD User-Interface Types</H3>
2302 <P>Each printer option has a type associated with it:
2306 <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or off
2308 <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value
2311 <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more
2316 <H3>PPD Sections</H3>
2318 <P>Some options must be output before others, or in different sections of
2319 the output document. The <CODE>ppd_section_t</CODE> enumeration defines
2320 which section the option must be output in:
2324 <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of
2325 the document, page, or prolog sections of the document
2327 <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in
2328 the DocumentSetup section of the document
2330 <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before
2333 <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the
2334 job control section of the document
2336 <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the
2337 PageSetup section of the document
2339 <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the
2340 Prolog section of the document
2344 <H3>PPD Colorspaces</H3>
2346 <P>Each printer has a default colorspace:
2350 <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default
2352 <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default
2354 <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default
2356 <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default
2358 <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default
2360 <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace
2365 <H2>Raster Constants</H2>
2367 <H3>Raster Sync Words</H3>
2369 <P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE>
2370 constants define the standard sync words at the beginning of each CUPS
2373 <H3>Raster Stream Modes</H3>
2375 <P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE>
2376 constants are used with the
2377 <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function to
2378 specify a stream for reading or writing.
2380 <H3>Raster Boolean Constants</H3>
2382 <P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants
2383 represent boolean values in the page header.
2385 <H3>Raster Jog Values</H3>
2387 <P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the
2388 Jog page device dictionary variable:
2392 <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging
2394 <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file
2396 <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job
2398 <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs
2402 <H3>Raster Orientation Values</H3>
2404 <P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the
2405 Orientation page device dictionary variable:
2409 <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation
2411 <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation
2413 <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation
2415 <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation
2419 <H3>Raster CutMedia Values</H3>
2421 <P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the
2422 CutMedia page device dictionary variable:
2426 <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging
2428 <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file
2430 <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job
2432 <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs
2434 <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page
2438 <H3>Raster AdvanceMedia Values</H3>
2440 <P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the
2441 AdvanceMedia page device dictionary variable:
2445 <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging
2447 <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file
2449 <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job
2451 <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs
2453 <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page
2457 <H3>Raster LeadingEdge Values</H3>
2459 <P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the
2460 LeadingEdge page device dictionary variable:
2464 <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading
2467 <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading
2470 <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the
2473 <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading
2478 <H3>Raster Color Order Values</H3>
2480 <P>The <CODE>cups_order_t</CODE> enumeration defines the possible color
2485 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK CMYK CMYK
2487 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK
2489 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ...
2493 <H3>Raster Colorspace Values</H3>
2495 <P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible colorspaces:
2499 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)
2501 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue
2503 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha
2505 <LI><CODE>CUPS_CSPACE_K</CODE> - Black
2507 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow
2509 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan
2511 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black
2513 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black
2515 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow
2517 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
2518 light cyan, light magenta
2520 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta,
2521 metallic cyan, black
2523 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta,
2524 metallic cyan, metallic grey (silver)
2526 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)
2528 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)
2530 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)
2534 <H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1>
2536 <P>This appendix describes all of the structures that are
2537 defined by the CUPS API.
2539 <H2>CUPS Structures</H2>
2541 <H3><A NAME="cups_dest_t">CUPS Destinations</A></H3>
2543 <P>The CUPS destination structure (<CODE>cups_dest_t</CODE>)
2544 contains information on a specific destination or instance:
2546 <CENTER><TABLE WIDTH="90%" BORDER="1">
2550 <TH>Description</TH>
2555 <TD>The name of the printer or class.</TD>
2560 <TD>The instance of the printer or class; NULL for the primary
2566 <TD>1 if the destination is set as the default, 0 otherwise.</TD>
2569 <TD>num_options</TD>
2571 <TD>The number of options associated with this destination.</TD>
2575 <TD><A HREF="#cups_option_t">cups_option_t *</A></TD>
2576 <TD>The options associated with this destination.</TD>
2580 <H3><A NAME="cups_job_t">CUPS Jobs</A></H3>
2582 <P>The CUPS job structure (<CODE>cups_job_t</CODE>) contains
2583 information on a specific job:
2585 <CENTER><TABLE WIDTH="90%" BORDER="1">
2589 <TH>Description</TH>
2594 <TD>The job ID for this job.</TD>
2599 <TD>The destination for this job (printer or class name).</TD>
2604 <TD>The job-name for this job (title).</TD>
2609 <TD>The job-originating-user-name for this job (username).</TD>
2614 <TD>The document-format for this job (MIME type string).</TD>
2619 <TD>The current state of the job.</TD>
2624 <TD>The size of this job in kilobytes.</TD>
2629 <TD>The priority of this job from 1 to 100 (50 is normal).</TD>
2632 <TD>completed_time</TD>
2634 <TD>The time the job was completed, or 0 if not yet completed.</TD>
2637 <TD>creation_time</TD>
2639 <TD>The time the job was queued.</TD>
2642 <TD>processing_time</TD>
2644 <TD>The time the job started printing.</TD>
2648 <H3><A NAME="cups_lang_t">CUPS Messages</A></H3>
2650 <P>The CUPS messages structure (<CODE>cups_lang_t</CODE>)
2651 contains the character set, locale name, and messages array:
2653 <CENTER><TABLE WIDTH="90%" BORDER="1">
2657 <TH>Description</TH>
2661 <TD>cups_lang_t *</TD>
2662 <TD>Pointer to the next messages structure in memory.</TD>
2667 <TD>The number of active users of this messages structure.</TD>
2671 <TD>cups_encoding_t</TD>
2672 <TD>The character encoding of the message strings.</TD>
2677 <TD>The language/locale name.</TD>
2682 <TD>The array of message strings.</TD>
2686 <H3><A NAME="cups_option_t">CUPS Options</A></H3>
2688 <P>The CUPS option structure (<CODE>cups_option_t</CODE>)
2689 contains the option name and string value:
2691 <CENTER><TABLE WIDTH="90%" BORDER="1">
2695 <TH>Description</TH>
2700 <TD>The name of the option.</TD>
2705 <TD>The string value of the option.</TD>
2709 <H2>Networking Structures</H2>
2711 <H3><A NAME="http_t">HTTP State</A></H3>
2713 <P>The HTTP state structure (<CODE>http_t</CODE>) contains the
2714 current state of a HTTP request or response:
2716 <CENTER><TABLE WIDTH="90%" BORDER="1">
2720 <TH>Description</TH>
2725 <TD>The socket for the HTTP connection.</TD>
2730 <TD>1 if the HTTP functions should block, 0 if not.</TD>
2735 <TD>The last OS error that occurred on the socket.</TD>
2740 <TD>The last time the HTTP connection was used.</TD>
2744 <TD>http_state_t</TD>
2745 <TD>The current HTTP request/response state.</TD>
2750 <TD>The last HTTP status seen.</TD>
2754 <TD>http_version_t</TD>
2755 <TD>The HTTP protocol version in use.</TD>
2759 <TD>http_keep_alive_t</TD>
2760 <TD>Whether or not to use Keep-Alive</TD>
2764 <TD>struct sockaddr_in</TD>
2765 <TD>The IPv4 address of the HTTP server.</TD>
2770 <TD>The hostname of the HTTP server.</TD>
2775 <TD>The string values of all HTTP request/response
2781 <TD>Current byte in data buffer.</TD>
2784 <TD>data_encoding</TD>
2785 <TD>http_encoding_t</TD>
2786 <TD>The transfer encoding for the request/response.</TD>
2789 <TD>data_remaining</TD>
2791 <TD>The number of bytes remaining in the current request,
2792 response, or chunk.</TD>
2797 <TD>The number of bytes that are used in the buffer.</TD>
2802 <TD>The read/write buffer.</TD>
2807 <TD>The type of authentication in use.</TD>
2811 <TD>md5_state_t</TD>
2812 <TD>The current MD5 digest state.</TD>
2817 <TD>The nonce value for Digest authentication.</TD>
2820 <TD>nonce_count</TD>
2822 <TD>The nonce count value.</TD>
2827 <TD>A pointer to private encryption data.</TD>
2831 <TD>http_encryption_t</TD>
2832 <TD>The current encryption mode.</TD>
2836 <H3><A NAME="ipp_t">IPP State</A></H3>
2838 <P>The IPP state structure (<CODE>ipp_t</CODE>) contains the
2839 current state of a IPP request or response:
2841 <CENTER><TABLE WIDTH="90%" BORDER="1">
2845 <TH>Description</TH>
2854 <H2>Raster Structures</H2>
2856 <H3><A NAME="cups_raster_header_t">Raster Page Header</A></H3>
2858 <P>The raster page header (<CODE>cups_raster_header_t</CODE>)
2859 consists of the PostScript page device dictionary for the page:
2861 <CENTER><TABLE WIDTH="90%" BORDER="1">
2865 <TH>Description</TH>
2870 <TD>The media class name</TD>
2875 <TD>The media color name</TD>
2880 <TD>The media type name</TD>
2885 <TD>The output type name</TD>
2888 <TD>AdvanceDistance</TD>
2890 <TD>The distance to advance the media in points</TD>
2893 <TD>AdvanceMedia</TD>
2895 <TD>When to advance the media</TD>
2899 <TD>cups_bool_t</TD>
2900 <TD>Whether or not to produce collated copies</TD>
2905 <TD>When to cut the media</TD>
2909 <TD>cups_bool_t</TD>
2910 <TD>Whether or not to print on both sides of the paper</TD>
2913 <TD>HWResolution</TD>
2914 <TD>unsigned[2]</TD>
2915 <TD>The resolution of the page image in pixels per inch; the
2916 HWResolution[0] represents the horizontal resolution and
2917 HWResolution[1] represents the vertical resolution</TD>
2920 <TD>ImagingBoundingBox</TD>
2921 <TD>unsigned[4]</TD>
2922 <TD>The bounding box for the page in points; the elements
2923 represent the left, bottom, right, and top coordinates of the
2924 imaged area (if 0 then the whole page is imaged)</TD>
2927 <TD>InsertSheet</TD>
2928 <TD>cups_bool_t</TD>
2929 <TD>Whether or not to insert a sheet before this page</TD>
2934 <TD>When to jog copies of the page</TD>
2937 <TD>LeadingEdge</TD>
2938 <TD>cups_edge_t</TD>
2939 <TD>The leading edge of the page</TD>
2943 <TD>unsigned[2]</TD>
2944 <TD>The lower-lefthand margin of the page in points</TD>
2948 <TD>cups_bool_t</TD>
2949 <TD>Whether or not to manually feed the page</TD>
2952 <TD>MediaPosition</TD>
2954 <TD>The input slot number to use</TD>
2957 <TD>MediaWeight</TD>
2959 <TD>The weight of the output media in grams/m<SUP>2</SUP></TD>
2962 <TD>MirrorPrint</TD>
2963 <TD>cups_bool_t</TD>
2964 <TD>Whether or not to mirror the print</TD>
2967 <TD>NegativePrint</TD>
2968 <TD>cups_bool_t</TD>
2969 <TD>Whether or not to invert the print</TD>
2974 <TD>The number of copies to produce</TD>
2977 <TD>Orientation</TD>
2978 <TD>cups_orient_t</TD>
2979 <TD>The orientation of the page image</TD>
2982 <TD>OutputFaceUp</TD>
2983 <TD>cups_bool_t</TD>
2984 <TD>Whether or not to output the page face up</TD>
2988 <TD>unsigned[2]</TD>
2989 <TD>The width and height of the page in points</TD>
2992 <TD>Separations</TD>
2993 <TD>cups_bool_t</TD>
2994 <TD>Whether or not to output separations</TD>
2998 <TD>cups_bool_t</TD>
2999 <TD>Whether or not to automatically switch trays for the requested
3000 media size/type</TD>
3004 <TD>cups_bool_t</TD>
3005 <TD>Whether or not to rotate the back side of the page</TD>
3010 <TD>The width of the page image in pixels</TD>
3015 <TD>The height of the page image in pixels</TD>
3018 <TD>cupsMediaType</TD>
3020 <TD>The device-specific media type code</TD>
3023 <TD>cupsBitsPerColor</TD>
3025 <TD>The number of bits per color</TD>
3028 <TD>cupsBitsPerPixel</TD>
3030 <TD>The number of bits per pixel</TD>
3033 <TD>cupsBytesPerLine</TD>
3035 <TD>The number of bytes per line of image data</TD>
3038 <TD>cupsColorOrder</TD>
3039 <TD>cups_order_t</TD>
3040 <TD>The order of color values</TD>
3043 <TD>cupsColorSpace</TD>
3044 <TD>cups_cspace_t</TD>
3045 <TD>The type of color values</TD>
3048 <TD>cupsCompression</TD>
3050 <TD>The device-specific compression code</TD>
3053 <TD>cupsRowCount</TD>
3055 <TD>The device-specific row count</TD>
3058 <TD>cupsRowFeed</TD>
3060 <TD>The device-specific row feed</TD>
3063 <TD>cupsRowStep</TD>
3065 <TD>The device-specific row step</TD>
3069 <H1 ALIGN="RIGHT"><A NAME="FUNCTIONS">D - Functions</A></H1>
3071 <P>This appendix provides a reference for all of the CUPS API functions.
3074 <!-- NEW PAGE --><H2><A NAME="cupsAddDest">cupsAddDest()</A></H2>
3080 cupsAddDest(const char *name,
3081 const char *instance,
3083 cups_dest_t **dests);
3088 <CENTER><TABLE WIDTH="80%" BORDER>
3091 <TH>Description</TH>
3095 <TD>The name of the destination.</TD>
3099 <TD>The instance of the destination, or NULL for the primary instance.</TD>
3103 <TD>The number of destinations in the array.</TD>
3107 <TD>A pointer to the destination array pointer.</TD>
3113 <P>The new number of destinations in the array.
3115 <H3>Description</H3>
3117 <P><CODE>cupsAddDest()</CODE> adds the named destination to the destination
3118 array if it does not already exist.
3123 #include <cups/cups.h>
3126 <A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3129 num_dests = cupsAddDests("foo", "bar", num_dests, &dests);
3135 <A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>,
3136 <A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
3137 <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
3140 <!-- NEW PAGE --><H2><A NAME="cupsAddOption">cupsAddOption()</A></H2>
3146 cupsAddOption(const char *name,
3149 cups_option_t **options);
3154 <CENTER><TABLE WIDTH="80%" BORDER>
3157 <TH>Description</TH>
3161 <TD>The name of the option.</TD>
3165 <TD>The value of the option.</TD>
3168 <TD>num_options</TD>
3169 <TD>Number of options currently in the array.</TD>
3173 <TD>Pointer to the options array.</TD>
3179 <P>The new number of options.
3181 <H3>Description</H3>
3183 <P><CODE>cupsAddOption()</CODE> adds an option to the specified array.
3188 #include <cups.h>
3192 /* Declare the options array */
3194 <A HREF="#cups_option_t">cups_option_t</A> *options;
3196 /* Initialize the options array */
3198 options = (cups_option_t *)0;
3200 /* Add options using cupsAddOption() */
3201 num_options = cupsAddOption("media", "letter", num_options, &options);
3202 num_options = cupsAddOption("resolution", "300dpi", num_options, &options);
3207 <A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
3208 <A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
3209 <A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
3210 <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
3213 <!-- NEW PAGE --><H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2>
3219 cupsCancelJob(const char *dest,
3225 <CENTER><TABLE WIDTH="80%" BORDER>
3228 <TH>Description</TH>
3232 <TD>Printer or class name</TD>
3242 <P>1 on success, 0 on failure. On failure the error can be found by calling
3243 <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
3245 <H3>Description</H3>
3247 <P><CODE>cupsCancelJob()</CODE> cancels the specifies job.
3252 #include <cups.h>
3254 cupsCancelJob("LaserJet", 1);
3260 <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
3261 <A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>,
3262 <A HREF="#cupsPrintFiles"><CODE>cupsPrintFiles()</CODE></A>
3265 <!-- NEW PAGE --><H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2>
3271 cupsDoFileRequest(http_t *http,
3273 const char *resource,
3274 const char *filename);
3279 <CENTER><TABLE WIDTH="80%" BORDER>
3282 <TH>Description</TH>
3286 <TD>HTTP connection to server.</TD>
3290 <TD>IPP request data.</TD>
3294 <TD>HTTP resource name for POST.</TD>
3298 <TD>File to send with POST request (<CODE>NULL</CODE> pointer if none.)</TD>
3304 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
3305 the error can be found by calling
3306 <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
3308 <H3>Description</H3>
3310 <P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and provides the
3311 IPP request and optionally the contents of a file to the IPP server. It also
3312 handles resubmitting the request and performing password authentication as
3318 #include <cups.h>
3320 <A HREF="#http_t">http_t</A> *http;
3321 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
3322 <A HREF="#ipp_t">ipp_t</A> *request;
3327 /* Get the default language */
3328 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3330 /* Create a new IPP request */
3331 request = <A HREF="#ippNew">ippNew()</A>;
3333 request->request.op.operation_id = IPP_PRINT_FILE;
3334 request->request.op.request_id = 1;
3336 /* Add required attributes */
3337 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3338 "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3340 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3341 "attributes-natural-language", NULL,
3342 language != NULL ? language->language : "C");
3344 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
3345 NULL, "ipp://hostname/resource");
3347 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
3348 NULL, <A HREF="#cupsUser">cupsUser()</A>);
3350 /* Do the request... */
3351 response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
3357 <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
3358 <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
3359 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
3360 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
3361 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
3362 <A HREF="#ippNew"><CODE>ippNew()</CODE></A>
3365 <!-- NEW PAGE --><H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2>
3371 cupsDoRequest(http_t *http,
3373 const char *resource);
3378 <CENTER><TABLE WIDTH="80%" BORDER>
3381 <TH>Description</TH>
3385 <TD>HTTP connection to server.</TD>
3389 <TD>IPP request data.</TD>
3393 <TD>HTTP resource name for POST.</TD>
3399 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
3400 the error can be found by calling
3401 <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
3403 <H3>Description</H3>
3405 <P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides
3406 the IPP request to the IPP server. It also handles resubmitting the
3407 request and performing password authentication as needed.
3412 #include <cups.h>
3414 <A HREF="#http_t">http_t</A> *http;
3415 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
3416 <A HREF="#ipp_t">ipp_t</A> *request;
3421 /* Get the default language */
3422 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3424 /* Create a new IPP request */
3425 request = <A HREF="#ippNew">ippNew()</A>;
3427 request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
3428 request->request.op.request_id = 1;
3430 /* Add required attributes */
3431 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3432 "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3434 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3435 "attributes-natural-language", NULL,
3436 language != NULL ? language->language : "C");
3438 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
3439 NULL, "ipp://hostname/resource");
3441 /* Do the request... */
3442 response = cupsDoRequest(http, request, "/resource");
3448 <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
3449 <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
3450 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
3451 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
3452 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
3453 <A HREF="#ippNew"><CODE>ippNew()</CODE></A>
3456 <!-- NEW PAGE --><H2><A NAME="cupsEncodeOptions">cupsEncodeOptions()</A></H2>
3462 cupsEncodeOptions(ipp_t *ipp,
3464 cups_option_t *options);
3469 <CENTER><TABLE WIDTH="80%" BORDER>
3472 <TH>Description</TH>
3476 <TD>The IPP request.</TD>
3479 <TD>num_options</TD>
3480 <TD>The number of options.</TD>
3484 <TD>The options.</TD>
3488 <H3>Description</H3>
3490 <P><CODE>cupsEncodeOptions()</CODE> encodes all of the options
3491 in the specified array as IPP attributes and adds them to the
3497 #include <cups/cups.h>
3499 <A HREF="#ipp_t">ipp_t</A> *ipp;
3501 <A HREF="#cups_option_t">cups_option_t</A> *options;
3504 cupsEncodeOptions(ipp, num_options, options);
3510 <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
3511 <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>,
3512 <A HREF="#ippNew"><CODE>ippNew()</CODE></A>
3515 <!-- NEW PAGE --><H2><A NAME="cupsEncryption">cupsEncryption()</A></H2>
3521 cupsEncryption(void);
3526 <P>The current encryption setting.
3528 <H3>Description</H3>
3530 <P><CODE>cupsEncryption()</CODE> returns the current encryption setting
3531 for IPP requests such as printing.
3536 #include <cups/cups.h>
3538 <A HREF="#http_t">http_t</A> *http;
3540 printf("The current encryption setting is %d.\n", cupsEncryption());
3542 http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
3548 <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
3549 <A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>,
3550 <A HREF="#ippPort"><CODE>ippPort()</CODE></A>
3553 <!-- NEW PAGE --><H2><A NAME="cupsFreeDests">cupsFreeDests()</A></H2>
3559 cupsFreeDests(int num_dests,
3560 cups_dest_t *dests);
3565 <CENTER><TABLE WIDTH="80%" BORDER>
3568 <TH>Description</TH>
3572 <TD>The number of destinations in the array.</TD>
3576 <TD>The destination array.</TD>
3580 <H3>Description</H3>
3582 <P><CODE>cupsFreeDests()</CODE> frees a destination array that was
3583 created using <CODE>cupsGetDests()</CODE>.
3588 #include <cups/cups.h>
3591 <A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3594 num_dests = cupsGetDests(&dests);
3595 dest = cupsGetDest(NULL, NULL, num_dests, dests);
3598 printf("The default destination is %s\n", dest->name);
3600 puts("No default destination.");
3602 cupsFreeDests(num_dests, dests);
3608 <A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
3609 <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
3612 <!-- NEW PAGE --><H2><A NAME="cupsFreeJobs">cupsFreeJobs()</A></H2>
3618 cupsFreeJobs(int num_jobs,
3624 <CENTER><TABLE WIDTH="80%" BORDER>
3627 <TH>Description</TH>
3631 <TD>The number of jobs.</TD>
3635 <TD>The job array.</TD>
3639 <H3>Description</H3>
3641 <P><CODE>cupsFreeJobs()</CODE> frees an array of print jobs created by
3642 the <CODE>cupsGetJobs()</CODE> function.
3647 #include <cups/cups.h>
3651 <A HREF="#cups_job_t">cups_job_t</A> *jobs;
3654 num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
3656 printf("%d active job(s):\n", num_jobs);
3657 for (i = 0; i < num_jobs; i ++)
3658 printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
3659 jobs[i].user, jobs[i].title,
3660 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
3662 cupsFreeJobs(num_jobs, jobs);
3668 <A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>,
3669 <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
3672 <!-- NEW PAGE --><H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2>
3678 cupsFreeOptions(int num_options,
3679 cups_option_t *options);
3684 <CENTER><TABLE WIDTH="80%" BORDER>
3687 <TH>Description</TH>
3690 <TD>num_options</TD>
3691 <TD>Number of options in array.</TD>
3695 <TD>Pointer to options array.</TD>
3699 <H3>Description</H3>
3701 <P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the
3702 option array specified.
3707 #include <cups/cups.h>
3710 <A HREF="#cups_option_t">cups_option_t</A> *options;
3714 cupsFreeOptions(num_options, options);
3720 <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
3721 <A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
3722 <A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
3723 <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
3724 <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
3727 <!-- NEW PAGE --><H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2>
3733 cupsGetClasses(char ***classes);
3738 <CENTER><TABLE WIDTH="80%" BORDER>
3741 <TH>Description</TH>
3745 <TD>Pointer to character pointer array.</TD>
3751 <P>The number of printer classes available.
3753 <H3>Description</H3>
3755 <P><CODE>cupsGetClasses()</CODE> gets a list of the available printer classes.
3756 The returned array should be freed using the <CODE>free()</CODE> when it is
3762 #include <cups/cups.h>
3770 num_classes = cupsGetClasses(&classes);
3774 if (num_classes > 0)
3776 for (i = 0; i < num_classes; i ++)
3786 <A HREF="#cupsGetDefault"><CODE>cupsGetDefault()</CODE></A>,
3787 <A HREF="#cupsGetPrinters"><CODE>cupsGetPrinters()</CODE></A>
3790 <!-- NEW PAGE --><H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2>
3796 cupsGetDefault(void);
3801 <P>A pointer to the default destination.
3803 <H3>Description</H3>
3805 <P><CODE>cupsGetDefault()</CODE> gets the default destination printer or class.
3806 The default destination is stored in a static string and will be overwritten
3807 (usually with the same value) after each call.
3812 #include <cups/cups.h>
3814 printf("The default destination is %s\n", cupsGetDefault());
3820 <A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A>,
3821 <A HREF="#cupsGetPrinters"><CODE>cupsGetPrinters()</CODE></A>
3824 <!-- NEW PAGE --><H2><A NAME="cupsGetDest">cupsGetDest()</A></H2>
3830 cupsGetDest(const char *name,
3831 const char *instance,
3833 cups_dest_t *dests);
3838 <CENTER><TABLE WIDTH="80%" BORDER>
3841 <TH>Description</TH>
3845 <TD>The name of the destination, or NULL for the default destination.</TD>
3849 <TD>The instance of the destination, or NULL for the primary instance.</TD>
3853 <TD>The number of destinations.</TD>
3857 <TD>The destination array.</TD>
3863 <P>A pointer to the specified destination, or NULL if none exists.
3865 <H3>Description</H3>
3867 <P><CODE>cupsGetDest()</CODE> finds the specified destination in the array
3868 of destinations created by the <CODE>cupsGetDests()</CODE> function.
3873 #include <cups/cups.h>
3876 <A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3879 num_dests = cupsGetDests(&dests);
3880 dest = cupsGetDest(NULL, NULL, num_dests, dests);
3883 printf("The default destination is %s\n", dest->name);
3885 puts("No default destination.");
3887 cupsFreeDests(num_dests, dests);
3893 <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>,
3894 <A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>
3897 <!-- NEW PAGE --><H2><A NAME="cupsGetDests">cupsGetDests()</A></H2>
3903 cupsGetDests(cups_dest_t **dests);
3908 <CENTER><TABLE WIDTH="80%" BORDER>
3911 <TH>Description</TH>
3915 <TD>A pointer to a destination array pointer.</TD>
3921 <P>The number of available destinations.
3923 <H3>Description</H3>
3925 <P><CODE>cupsGetDests()</CODE> creates an array of available
3926 destinations that the user can print to. The array should be
3927 freed using the <CODE>cupsFreeDests()</CODE> function.
3932 #include <cups/cups.h>
3935 <A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3938 num_dests = cupsGetDests(&dests);
3939 dest = cupsGetDest(NULL, NULL, num_dests, dests);
3942 printf("The default destination is %s\n", dest->name);
3944 puts("No default destination.");
3946 cupsFreeDests(num_dests, dests);
3952 <A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>,
3953 <A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
3954 <A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>
3957 <!-- NEW PAGE --><H2><A NAME="cupsGetJobs">cupsGetJobs()</A></H2>
3963 cupsGetJobs(cups_job_t **jobs,
3971 <CENTER><TABLE WIDTH="80%" BORDER>
3974 <TH>Description</TH>
3978 <TD>A pointer to the job array pointer.</TD>
3982 <TD>The destination name, or NULL if jobs for all destinations are requested.</TD>
3986 <TD>1 if only those jobs submitted by the current
3987 <CODE>cupsUser()</CODE> should be returned, 0 for jobs
3988 submitted by all users.</TD>
3992 <TD>1 if only completed jobs should be returned, 0 if only
3993 pending/processing jobs should be returned.</TD>
3999 <P>The number of jobs.
4001 <H3>Description</H3>
4003 <P><CODE>cupsGetJobs()</CODE> creates an array of print jobs based on the
4004 arguments supplied in the function call. The returned array should be freed
4005 using the <CODE>cupsFreeJobs()</CODE> function.
4010 #include <cups/cups.h>
4014 <A HREF="#cups_job_t">cups_job_t</A> *jobs;
4017 num_jobs = cupsGetJobs(&jobs, NULL, 0, 0);
4019 printf("%d active job(s):\n", num_jobs);
4020 for (i = 0; i < num_jobs; i ++)
4021 printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
4022 jobs[i].user, jobs[i].title,
4023 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
4025 cupsFreeJobs(num_jobs, jobs);
4031 <A HREF="#cupsFreeJobs"><CODE>cupsFreeJobs()</CODE></A>,
4032 <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
4035 <!-- NEW PAGE --><H2><A NAME="cupsGetOption">cupsGetOption()</A></H2>
4041 cupsGetOption(const char *name,
4043 cups_option_t *options);
4048 <CENTER><TABLE WIDTH="80%" BORDER>
4051 <TH>Description</TH>
4055 <TD>The name of the option.</TD>
4058 <TD>num_options</TD>
4059 <TD>The number of options in the array.</TD>
4063 <TD>The options array.</TD>
4069 <P>A pointer to the option values or <CODE>NULL</CODE> if the option is
4072 <H3>Description</H3>
4074 <P><CODE>cupsGetOption()</CODE> returns the first occurrence of the
4075 named option. If the option is not included in the options array then a
4076 <CODE>NULL</CODE> pointer is returned.
4079 #include <cups/cups.h>
4082 cups_option_t *options;
4087 media = cupsGetOption("media", num_options, options);
4093 <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
4094 <A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
4095 <A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
4096 <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
4097 <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
4100 <!-- NEW PAGE --><H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2>
4106 cupsGetPassword(const char *prompt);
4111 <CENTER><TABLE WIDTH="80%" BORDER>
4114 <TH>Description</TH>
4118 <TD>The prompt to display to the user.</TD>
4124 <P>A pointer to the password that was entered or <CODE>NULL</CODE> if no
4125 password was entered.
4127 <H3>Description</H3>
4129 <P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks the user
4130 for a password. The password text is not echoed to the user.
4135 #include <cups/cups.h>
4141 password = cupsGetPassword("Please enter a password:");
4147 <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
4148 <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
4149 <A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
4150 <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
4151 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
4154 <!-- NEW PAGE --><H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2>
4160 cupsGetPPD(const char *printer);
4165 <CENTER><TABLE WIDTH="80%" BORDER>
4168 <TH>Description</TH>
4172 <TD>The name of the printer.</TD>
4178 <P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE>
4179 if the printer cannot be located or does not have a PPD file.
4181 <H3>Description</H3>
4183 <P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named printer.
4184 The printer name can be of the form "printer" or "printer@hostname".
4186 <P>You should remove (unlink) the PPD file after you are done using it. The
4187 filename is stored in a static buffer and will be overwritten with each call
4188 to <CODE>cupsGetPPD()</CODE>.
4193 #include <cups/cups.h>
4199 ppd = cupsGetPPD("printer@hostname");
4207 <!-- NEW PAGE --><H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2>
4213 cupsGetPrinters(char ***printers);
4218 <CENTER><TABLE WIDTH="80%" BORDER>
4221 <TH>Description</TH>
4225 <TD>Pointer to character pointer array.</TD>
4231 <P>The number of printer printers available.
4233 <H3>Description</H3>
4235 <P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers.
4236 The returned array should be freed using the <CODE>free()</CODE> when it is
4242 #include <cups/cups.h>
4250 num_printers = cupsGetPrinters(&printers);
4254 if (num_printers > 0)
4256 for (i = 0; i < num_printers; i ++)
4266 <A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A>
4267 <A HREF="#cupsGetDefault"><CODE>cupsGetDefault()</CODE></A>
4270 <!-- NEW PAGE --><H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2>
4276 cupsLangDefault(void);
4281 <P>A pointer to the default language structure.
4283 <H3>Description</H3>
4285 <P><CODE>cupsLangDefault()</CODE> returns a language structure for the default
4286 language. The default language is defined by the <CODE>LANG</CODE> environment
4287 variable. If the specified language cannot be located then the POSIX (English)
4290 <P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with the
4291 language structure when you are done.
4296 #include <cups/language.h>
4298 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
4301 language = cupsLangDefault();
4305 cupsLangFree(language);
4311 <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4312 <A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4313 <A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4314 <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4315 <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4318 <!-- NEW PAGE --><H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2>
4324 cupsLangEncoding(cups_lang_t *language);
4329 <CENTER><TABLE WIDTH="80%" BORDER>
4332 <TH>Description</TH>
4336 <TD>The language structure.</TD>
4342 <P>A pointer to the encoding string.
4344 <H3>Description</H3>
4346 <P><CODE>cupsLangEncoding()</CODE> returns the language encoding used for the
4347 specified language, e.g. "iso-8859-1", "utf-8", etc.
4352 #include <cups/language.h>
4354 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
4358 language = cupsLangDefault();
4359 encoding = cupsLangEncoding(language);
4362 cupsLangFree(language);
4368 <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4369 <A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4370 <A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4371 <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4372 <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4375 <!-- NEW PAGE --><H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2>
4381 cupsLangFlush(void);
4384 <H3>Description</H3>
4386 <P><CODE>cupsLangFlush()</CODE> frees all language structures that have been
4392 #include <cups/language.h>
4402 <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4403 <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4404 <A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4405 <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4406 <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4409 <!-- NEW PAGE --><H2><A NAME="cupsLangFree">cupsLangFree()</A></H2>
4415 cupsLangFree(cups_lang_t *language);
4420 <CENTER><TABLE WIDTH="80%" BORDER>
4423 <TH>Description</TH>
4427 <TD>The language structure to free.</TD>
4431 <H3>Description</H3>
4433 <P><CODE>cupsLangFree()</CODE> frees the specified language structure.
4438 #include <cups/language.h>
4440 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
4443 cupsLangFree(language);
4449 <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4450 <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4451 <A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4452 <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4453 <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4456 <!-- NEW PAGE --><H2><A NAME="cupsLangGet">cupsLangGet()</A></H2>
4462 cupsLangGet(const char *name);
4467 <CENTER><TABLE WIDTH="80%" BORDER>
4470 <TH>Description</TH>
4474 <TD>The name of the locale.</TD>
4480 <P>A pointer to a language structure.
4482 <H3>Description</H3>
4484 <P><CODE>cupsLangGet()</CODE> returns a language structure for the specified
4485 locale. If the locale is not defined then the POSIX (English) locale is
4491 #include <cups/language.h>
4493 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
4497 language = cupsLangGet("fr");
4501 cupsLangFree(language);
4507 <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4508 <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4509 <A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4510 <A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4511 <A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4514 <!-- NEW PAGE --><H2><A NAME="cupsLangString">cupsLangString()</A></H2>
4520 cupsLangString(cups_lang_t *language,
4526 <CENTER><TABLE WIDTH="80%" BORDER>
4529 <TH>Description</TH>
4533 <TD>The language to query.</TD>
4537 <TD>The message number.</TD>
4543 <P>A pointer to the message string or <CODE>NULL</CODE> if the message is
4546 <H3>Description</H3>
4548 <P><CODE>cupsLangString()</CODE> returns a pointer to the specified message
4549 string in the specified language.
4554 #include <cups/language.h>
4556 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
4560 language = cupsLangGet("fr");
4562 s = cupsLangString(language, CUPS_MSG_YES);
4566 cupsLangFree(language);
4572 <A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4573 <A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4574 <A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4575 <A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4576 <A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>
4579 <!-- NEW PAGE --><H2><A NAME="cupsLastError">cupsLastError()</A></H2>
4585 cupsLastError(void);
4590 <P>An enumeration containing the last IPP error.
4592 <H3>Description</H3>
4594 <P><CODE>cupsLastError()</CODE> returns the last IPP error that occurred.
4595 If no error occurred then it will return <CODE>IPP_OK</CODE> or
4596 <CODE>IPP_OK_CONFLICT</CODE>.
4601 #include <cups/cups.h>
4603 ipp_status_t status;
4607 status = cupsLastError();
4613 <A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
4614 <A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>
4617 <!-- NEW PAGE --><H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2>
4623 cupsMarkOptions(ppd_file_t *ppd,
4625 cups_option_t *options);
4630 <CENTER><TABLE WIDTH="80%" BORDER>
4633 <TH>Description</TH>
4637 <TD>The PPD file to mark.</TD>
4640 <TD>num_options</TD>
4641 <TD>The number of options in the options array.</TD>
4645 <TD>A pointer to the options array.</TD>
4651 <P>The number of conflicts found.
4653 <H3>Description</H3>
4655 <P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also
4656 handles mapping of IPP option names and values to PPD option names.
4661 #include <cups/cups.h>
4664 <A HREF="#cups_option_t">cups_option_t</A> *options;
4665 <A HREF="#ppd_file_t">ppd_file_t</A> *ppd;
4669 cupsMarkOptions(ppd, num_options, options);
4675 <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
4676 <A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
4677 <A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
4678 <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
4681 <!-- NEW PAGE --><H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2>
4687 cupsParseOptions(const char *arg,
4689 cups_option_t **options);
4694 <CENTER><TABLE WIDTH="80%" BORDER>
4697 <TH>Description</TH>
4701 <TD>The string containing one or more options.</TD>
4704 <TD>num_options</TD>
4705 <TD>The number of options in the options array.</TD>
4709 <TD>A pointer to the options array pointer.</TD>
4715 <P>The new number of options in the array.
4717 <H3>Description</H3>
4719 <P><CODE>cupsParseOptions()</CODE> parses the specifies string for one
4720 or more options of the form "name=value", "name", or "noname". It can
4721 be called multiple times to combine the options from several strings.
4726 #include <cups/cups.h>
4729 <A HREF="#cups_options_t">cups_option_t</A> *options;
4734 options = (cups_option_t *)0;
4735 num_options = cupsParseOptions(argv[5], num_options, &options);
4741 <A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
4742 <A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
4743 <A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
4744 <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>
4747 <!-- NEW PAGE --><H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2>
4753 cupsPrintFile(const char *printer,
4754 const char *filename,
4757 cups_option_t *options);
4762 <CENTER><TABLE WIDTH="80%" BORDER>
4765 <TH>Description</TH>
4769 <TD>The printer or class to print to.</TD>
4773 <TD>The file to print.</TD>
4777 <TD>The job title.</TD>
4780 <TD>num_options</TD>
4781 <TD>The number of options in the options array.</TD>
4785 <TD>A pointer to the options array.</TD>
4791 <P>The new job ID number or 0 on error.
4793 <H3>Description</H3>
4795 <P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or
4796 class for printing. If the job cannot be printed the error code can be
4797 found by calling <CODE>cupsLastError()</CODE>.
4802 #include <cups/cups.h>
4805 <A HREF="#cups_option_t">cups_option_t</A> *options;
4810 jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
4811 num_options, options);
4817 <A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
4818 <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
4819 <A HREF="#cupsPrintFiles"><CODE>cupsPrintFiles()</CODE></A>
4822 <!-- NEW PAGE --><H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2>
4828 cupsPrintFiles(const char *printer,
4833 cups_option_t *options);
4838 <CENTER><TABLE WIDTH="80%" BORDER>
4841 <TH>Description</TH>
4845 <TD>The printer or class to print to.</TD>
4849 <TD>The number of files to print.</TD>
4853 <TD>The files to print.</TD>
4857 <TD>The job title.</TD>
4860 <TD>num_options</TD>
4861 <TD>The number of options in the options array.</TD>
4865 <TD>A pointer to the options array.</TD>
4871 <P>The new job ID number or 0 on error.
4873 <H3>Description</H3>
4875 <P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified
4876 printer or class for printing. If the job cannot be printed the error
4877 code can be found by calling <CODE>cupsLastError()</CODE>.
4882 #include <cups/cups.h>
4885 const char *files[100];
4887 <A HREF="#cups_option_t">cups_option_t</A> *options;
4892 jobid = cupsPrintFiles("printer@hostname", num_files, files,
4893 "Job Title", num_options, options);
4899 <A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
4900 <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
4901 <A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>
4904 <!-- NEW PAGE --><H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2>
4910 cupsRasterClose(cups_raster_t *ras);
4915 <CENTER><TABLE WIDTH="80%" BORDER>
4918 <TH>Description</TH>
4922 <TD>The raster stream to close.</TD>
4926 <H3>Description</H3>
4928 <P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.
4933 #include <cups/raster.h>
4935 <A HREF="#cups_raster_t">cups_raster_t</A> *ras;
4939 cupsRasterClose(ras);
4945 <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
4946 <A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
4947 <A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
4948 <A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
4949 <A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
4952 <!-- NEW PAGE --><H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2>
4958 cupsRasterOpen(int fd,
4964 <CENTER><TABLE WIDTH="80%" BORDER>
4967 <TH>Description</TH>
4971 <TD>The file descriptor to use.</TD>
4975 <TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or
4976 <CODE>CUPS_RASTER_WRITE</CODE>.</TD>
4982 <P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an error.
4984 <H3>Description</H3>
4986 <P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or writing.
4991 #include <cups/raster.h>
4993 <A HREF="#cups_raster_t">cups_raster_t</A> *ras;
4997 ras = cupsRasterOpen(0, CUPS_RASTER_READ);
5003 <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5004 <A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5005 <A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5006 <A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
5007 <A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5010 <!-- NEW PAGE --><H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2>
5016 cupsRasterReadHeader(cups_raster_t *ras,
5017 cups_page_header_t *header);
5022 <CENTER><TABLE WIDTH="80%" BORDER>
5025 <TH>Description</TH>
5029 <TD>The raster stream to read from.</TD>
5033 <TD>A pointer to a page header structure to read into.</TD>
5039 <P>1 on success, 0 on EOF or error.
5041 <H3>Description</H3>
5043 <P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the specified
5049 #include <cups/raster.h>
5052 <A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5053 <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5054 unsigned char pixels[8192];
5057 while (cupsRasterReadHeader(ras, &header))
5061 for (line = 0; line < header.cupsHeight; line ++)
5063 cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
5073 <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5074 <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5075 <A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5076 <A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
5077 <A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5080 <!-- NEW PAGE --><H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2>
5086 cupsRasterReadPixels(cups_raster_t *ras,
5087 unsigned char *pixels,
5093 <CENTER><TABLE WIDTH="80%" BORDER>
5096 <TH>Description</TH>
5100 <TD>The raster stream to read from.</TD>
5104 <TD>The pointer to a pixel buffer.</TD>
5108 <TD>The number of bytes of pixel data to read.</TD>
5114 <P>The number of bytes read or 0 on EOF or error.
5116 <H3>Description</H3>
5118 <P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the specified
5124 #include <cups/raster.h>
5127 <A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5128 <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5129 unsigned char pixels[8192];
5132 while (cupsRasterReadHeader(ras, &header))
5136 for (line = 0; line < header.cupsHeight; line ++)
5138 cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
5148 <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5149 <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5150 <A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5151 <A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
5152 <A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5155 <!-- NEW PAGE --><H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2>
5161 cupsRasterWriteHeader(cups_raster_t *ras,
5162 cups_page_header_t *header);
5167 <CENTER><TABLE WIDTH="80%" BORDER>
5170 <TH>Description</TH>
5174 <TD>The raster stream to write to.</TD>
5178 <TD>A pointer to the page header to write.</TD>
5184 <P>1 on success, 0 on error.
5186 <H3>Description</H3>
5188 <P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header to
5194 #include <cups/raster.h>
5197 <A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5198 <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5199 unsigned char pixels[8192];
5202 cupsRasterWriteHeader(ras, &header);
5204 for (line = 0; line < header.cupsHeight; line ++)
5208 cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
5215 <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5216 <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5217 <A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5218 <A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5219 <A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5222 <!-- NEW PAGE --><H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2>
5228 cupsRasterWritePixels(cups_raster_t *ras,
5229 unsigned char *pixels,
5235 <CENTER><TABLE WIDTH="80%" BORDER>
5238 <TH>Description</TH>
5242 <TD>The raster stream to write to.</TD>
5246 <TD>The pixel data to write.</TD>
5250 <TD>The number of bytes to write.</TD>
5256 <P>The number of bytes written.
5258 <H3>Description</H3>
5260 <P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data to a
5266 #include <cups/raster.h>
5269 <A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5270 <A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5271 unsigned char pixels[8192];
5274 cupsRasterWriteHeader(ras, &header);
5276 for (line = 0; line < header.cupsHeight; line ++)
5280 cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
5287 <A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5288 <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5289 <A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5290 <A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5291 <A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>
5294 <!-- NEW PAGE --><H2><A NAME="cupsServer">cupsServer()</A></H2>
5305 <P>A pointer to the default server name.
5307 <H3>Description</H3>
5309 <P><CODE>cupsServer()</CODE> returns a pointer to the default server name.
5310 The server name is stored in a static location and will be overwritten with
5311 every call to <CODE>cupsServer()</CODE>.
5313 <P>The default server is determined from the following locations:
5317 <LI>The <CODE>CUPS_SERVER</CODE> environment variable,
5319 <LI>The <CODE>ServerName</CODE> directive in the
5320 <VAR>client.conf</VAR> file,
5322 <LI>The default host, "localhost".
5329 #include <cups/cups.h>
5333 server = cupsServer();
5339 <A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>,
5340 <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
5341 <A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
5342 <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
5343 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5346 <!-- NEW PAGE --><H2><A NAME="cupsSetDests">cupsSetDests()</A></H2>
5352 cupsSetDests(int num_dests,
5353 cups_dest_t *dests);
5358 <CENTER><TABLE WIDTH="80%" BORDER>
5361 <TH>Description</TH>
5365 <TD>Number of destinations.</TD>
5369 <TD>Array of destinations.</TD>
5373 <H3>Description</H3>
5375 <P><CODE>cupsSetDests()</CODE> saves the destination array to
5376 disk. If the current UID is 0, the destinations are saved in the
5377 <VAR>/etc/cups/lpoptions</VAR> file, otherwise they are saved
5378 in the <VAR>~/.lpoptions</VAR> file. This function is typically used
5379 to save the default options and instances that are set by the user.
5384 #include <cups/cups.h>
5387 <A HREF="#cups_dest_t">cups_dest_t</A> *dests;
5391 cupsSetDests(num_dests, dests);
5397 <A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
5400 <!-- NEW PAGE --><H2><A NAME="cupsSetEncryption">cupsSetEncryption()</A></H2>
5406 cupsSetEncryption(http_encryption_t encryption);
5411 <CENTER><TABLE WIDTH="80%" BORDER>
5414 <TH>Description</TH>
5418 <TD>The type of encryption to use.</TD>
5422 <H3>Description</H3>
5424 <P><CODE>cupsSetEncryption()</CODE> sets the default type of encryption to
5425 use when connecting with the print server.
5430 #include <cups/cups.h>
5432 cupsSetEncryption(HTTP_ENCRYPT_REQUIRED);
5438 <A HREF="#cupsEncryption"><CODE>cupsEncryption()</CODE></A>
5441 <!-- NEW PAGE --><H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2>
5447 cupsSetPasswordCB(const char *(*cb)(const char *prompt));
5452 <CENTER><TABLE WIDTH="80%" BORDER>
5455 <TH>Description</TH>
5459 <TD>The password callback function.</TD>
5463 <H3>Description</H3>
5465 <P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use when
5466 asking the user for a password. The callback function must accept a single
5467 character string pointer (the prompt string) and return <CODE>NULL</CODE>
5468 if the user did not enter a password string or a pointer to the password
5474 #include <cups/cups.h>
5477 my_password_cb(const char *prompt)
5479 return (getpass(prompt));
5488 cupsSetPasswordCB(my_password_cb);
5489 password = cupsGetPassword("Please enter a password:");
5495 <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
5496 <A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
5497 <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
5498 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5501 <!-- NEW PAGE --><H2><A NAME="cupsSetServer">cupsSetServer()</A></H2>
5507 cupsSetServer(const char *server);
5512 <CENTER><TABLE WIDTH="80%" BORDER>
5515 <TH>Description</TH>
5519 <TD>The default server to use.</TD>
5523 <H3>Description</H3>
5525 <P><CODE>cupsSetServer()</CODE> sets the default server to use for
5526 the CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>,
5527 the default server is used.
5532 #include <cups/cups.h>
5534 cupsSetServer("foo.bar.com");
5540 <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
5541 <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
5542 <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
5543 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5546 <!-- NEW PAGE --><H2><A NAME="cupsSetUser">cupsSetUser()</A></H2>
5552 cupsSetUser(const char *user);
5557 <CENTER><TABLE WIDTH="80%" BORDER>
5560 <TH>Description</TH>
5564 <TD>The user name string to use.</TD>
5568 <H3>Description</H3>
5570 <P><CODE>cupsSetUser()</CODE> sets the default user name for authentication.
5571 If the <CODE>user</CODE> argument is <CODE>NULL</CODE> then the current
5577 #include <cups/cups.h>
5581 cupsSetUser("root");
5587 <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
5588 <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
5589 <A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
5590 <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5593 <!-- NEW PAGE --><H2><A NAME="cupsTempFd">cupsTempFd()</A></H2>
5599 cupsTempFd(char *filename,
5605 <CENTER><TABLE WIDTH="80%" BORDER>
5608 <TH>Description</TH>
5612 <TD>The character string to hold the temporary filename.</TD>
5616 <TD>The size of the filename string in bytes.</TD>
5622 <P>A file descriptor open for reading and writing.
5624 <H3>Description</H3>
5626 <P><CODE>cupsTempFd()</CODE> create a temporary filename in the
5627 <VAR>/var/tmp</VAR> directory or the directory specified by the
5628 <CODE>TMPDIR</CODE> environment variable.
5633 #include <cups/cups.h>
5638 fd = cupsTempFd(filename, sizeof(filename));
5644 <A HREF="#cupsTempFile"><CODE>cupsTempFile()</CODE></A>
5647 <!-- NEW PAGE --><H2><A NAME="cupsTempFile">cupsTempFile()</A></H2>
5653 cupsTempFile(char *filename,
5659 <CENTER><TABLE WIDTH="80%" BORDER>
5662 <TH>Description</TH>
5666 <TD>The character string to hold the temporary filename.</TD>
5670 <TD>The size of the filename string in bytes.</TD>
5676 <P>A pointer to <CODE>filename</CODE>.
5678 <H3>Description</H3>
5680 <P><CODE>cupsTempFile()</CODE> creates a temporary filename in the
5681 <VAR>/var/tmp</VAR> directory or the directory specified by the
5682 <CODE>TMPDIR</CODE> environment variable.
5687 #include <cups/cups.h>
5691 cupsTempFile(filename, sizeof(filename));
5697 <A HREF="#cupsTempFd"><CODE>cupsTempFd()</CODE></A>
5700 <!-- NEW PAGE --><H2><A NAME="cupsUser">cupsUser()</A></H2>
5711 <P>A pointer to the current username or <CODE>NULL</CODE> if the user ID is
5714 <H3>Description</H3>
5716 <P><CODE>cupsUser()</CODE> returns the name associated with the current
5717 user ID as reported by the <CODE>getuid()</CODE> system call.
5722 #include <cups/cups.h>
5732 <A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>,
5733 <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>
5736 <!-- NEW PAGE --><H2><A NAME="httpBlocking">httpBlocking()</A></H2>
5742 httpBlocking(http_t *http,
5748 <CENTER><TABLE WIDTH="80%" BORDER>
5751 <TH>Description</TH>
5755 <TD>The HTTP connection</TD>
5759 <TD>0 if the connection should be non-blocking, 1 if it should
5764 <H3>Description</H3>
5766 <P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for the
5767 HTTP connection. By default HTTP connections will block (stop) the client
5768 program until data is available or can be sent to the server.
5773 #include <cups/http.h>
5777 http = httpConnect("server", port);
5778 httpBlocking(http, 0);
5783 <A HREF="#httpCheck"><CODE>httpCheck()</CODE></A>,
5784 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
5787 <!-- NEW PAGE --><H2><A NAME="httpCheck">httpCheck()</A></H2>
5793 httpCheck(http_t *http);
5798 <CENTER><TABLE WIDTH="80%" BORDER>
5801 <TH>Description</TH>
5805 <TD>The HTTP connection</TD>
5811 <P>0 if there is no data pending, 1 otherwise.
5813 <H3>Description</H3>
5815 <P>The <CODE>httpCheck()</CODE> function checks to see if there is any data
5816 pending on an HTTP connection.
5821 #include <cups/http.h>
5825 if (httpCheck(http))
5827 ... do something ...
5833 <A HREF="#httpBlocking"><CODE>httpBlocking()</CODE></A>,
5834 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5835 <A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
5836 <A HREF="#httpRead"><CODE>httpRead()</CODE></A>
5839 <!-- NEW PAGE --><H2><A NAME="httpClearFields">httpClearFields()</A></H2>
5845 httpClearFields(http_t *http)
5850 <CENTER><TABLE WIDTH="80%" BORDER>
5853 <TH>Description</TH>
5857 <TD>The HTTP connection</TD>
5861 <H3>Description</H3>
5863 <P>The <CODE>httpClearFields()</CODE> function clears all HTTP request fields
5864 for the HTTP connection.
5869 #include <cups/http.h>
5873 httpClearFields(http);
5878 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5879 <A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>,
5880 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
5883 <!-- NEW PAGE --><H2><A NAME="httpClose">httpClose()</A></H2>
5889 httpClose(http_t *http);
5894 <CENTER><TABLE WIDTH="80%" BORDER>
5897 <TH>Description</TH>
5901 <TD>The HTTP connection</TD>
5905 <H3>Description</H3>
5907 <P>The <CODE>httpClose()</CODE> function closes an active HTTP connection.
5912 #include <cups/http.h>
5921 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
5924 <!-- NEW PAGE --><H2><A NAME="httpConnect">httpConnect()</A></H2>
5930 httpConnect(const char *hostname,
5936 <CENTER><TABLE WIDTH="80%" BORDER>
5939 <TH>Description</TH>
5943 <TD>The name or IP address of the server to connect to</TD>
5947 <TD>The port number to use</TD>
5953 <P>A pointer to a HTTP connection structure or NULL if the connection could
5956 <H3>Description</H3>
5958 <P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to the
5959 specified server and port.
5964 #include <cups/http.h>
5966 <A HREF="#http_t">http_t</A> *http;
5968 http = httpConnect(cupsServer(), ippPort());
5973 <A HREF="#httpClose"><CODE>httpClose()</CODE></A>,
5974 <A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>,
5975 <A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
5976 <A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
5977 <A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
5978 <A HREF="#httpRead"><CODE>httpRead()</CODE></A>,
5979 <A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
5982 <!-- NEW PAGE --><H2><A NAME="httpConnectEncrypt">httpConnectEncrypt()</A></H2>
5988 httpConnectEncrypt(const char *hostname,
5990 http_encryption_t encryption);
5995 <CENTER><TABLE WIDTH="80%" BORDER>
5998 <TH>Description</TH>
6002 <TD>The name or IP address of the server to connect to</TD>
6006 <TD>The port number to use</TD>
6010 <TD>The level of encryption to use</TD>
6016 <P>A pointer to a HTTP connection structure or NULL if the connection could
6019 <H3>Description</H3>
6021 <P>The <CODE>httpConnectEncrypt()</CODE> function opens a HTTP
6022 connection to the specified server, port, and encryption.
6027 #include <cups/http.h>
6029 <A HREF="#http_t">http_t</A> *http;
6031 http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
6036 <A HREF="#httpClose"><CODE>httpClose()</CODE></A>,
6037 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6038 <A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
6039 <A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
6040 <A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
6041 <A HREF="#httpRead"><CODE>httpRead()</CODE></A>,
6042 <A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
6045 <!-- NEW PAGE --><H2><A NAME="httpDecode64">httpDecode64()</A></H2>
6051 httpDecode64(char *out,
6057 <CENTER><TABLE WIDTH="80%" BORDER>
6060 <TH>Description</TH>
6064 <TD>The output string</TD>
6068 <TD>The input string</TD>
6074 <P>A pointer to the decoded string.
6076 <H3>Description</H3>
6078 <P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded string
6079 to the original string.
6084 #include <cups/http.h>
6086 char encoded_string[255];
6087 char original_string[255];
6089 httpDecode64(original_string, encoded_string);
6094 <A HREF="#httpEncode64"><CODE>httpEncode64()</CODE></A>
6097 <!-- NEW PAGE --><H2><A NAME="httpDelete">httpDelete()</A></H2>
6103 httpDelete(http_t *http,
6109 <CENTER><TABLE WIDTH="80%" BORDER>
6112 <TH>Description</TH>
6116 <TD>The HTTP connection</TD>
6120 <TD>The URI to delete</TD>
6126 <P>0 on success, non-zero on failure.
6128 <H3>Description</H3>
6130 <P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to
6136 #include <cups/http.h>
6140 httpDelete(http, "/some/uri");
6145 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6146 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
6147 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6150 <!-- NEW PAGE --><H2><A NAME="httpEncode64">httpEncode64()</A></H2>
6156 httpEncode64(char *out,
6162 <CENTER><TABLE WIDTH="80%" BORDER>
6165 <TH>Description</TH>
6169 <TD>The output string</TD>
6173 <TD>The input string</TD>
6179 <P>A pointer to the encoded string.
6181 <H3>Description</H3>
6183 <P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded string
6184 to the original string.
6189 #include <cups/http.h>
6191 char encoded_string[255];
6192 char original_string[255];
6194 httpEncode64(encoded_string, original_string);
6199 <A HREF="#httpDecode64"><CODE>httpDecode64()</CODE></A>
6202 <!-- NEW PAGE --><H2><A NAME="httpEncryption">httpEncryption()</A></H2>
6208 httpEncryption(http_t *http,
6209 http_encryption_t encryption);
6214 <CENTER><TABLE WIDTH="80%" BORDER>
6217 <TH>Description</TH>
6221 <TD>The HTTP connection.</TD>
6225 <TD>The desired level of encryption.</TD>
6231 <P>0 on success, -1 on error.
6233 <H3>Description</H3>
6235 <P><CODE>httpEncryption()</CODE> sets the encryption level for the HTTP
6241 #include <cups/http.h>
6243 <A HREF="#http_t">http_t</A> *http;
6247 httpEncryption(http, HTTP_ENCRYPT_REQUIRED);
6253 <A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>
6256 <!-- NEW PAGE --><H2><A NAME="httpError">httpError()</A></H2>
6262 httpError(http_t *http);
6267 <CENTER><TABLE WIDTH="80%" BORDER>
6270 <TH>Description</TH>
6274 <TD>The HTTP connection</TD>
6280 <P>The last error that occurred or 0 if no error has occurred.
6282 <H3>Description</H3>
6284 <P>The <CODE>httpError()</CODE> function returns the last error that occurred
6285 on the HTTP connection.
6290 #include <cups/http.h>
6294 if (httpError(http))
6296 ... show an error message ...
6302 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
6305 <!-- NEW PAGE --><H2><A NAME="httpFlush">httpFlush()</A></H2>
6311 httpFlush(http_t *http);
6316 <CENTER><TABLE WIDTH="80%" BORDER>
6319 <TH>Description</TH>
6323 <TD>The HTTP connection</TD>
6327 <H3>Description</H3>
6329 <P>The <CODE>httpFlush()</CODE> function flushes any remaining data left from
6330 a GET or POST operation.
6335 #include <cups/http.h>
6344 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6347 <!-- NEW PAGE --><H2><A NAME="httpGet">httpGet()</A></H2>
6353 httpGet(http_t *http,
6359 <CENTER><TABLE WIDTH="80%" BORDER>
6362 <TH>Description</TH>
6366 <TD>The HTTP connection</TD>
6370 <TD>The URI to get</TD>
6376 <P>0 on success, non-zero on failure.
6378 <H3>Description</H3>
6380 <P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the
6386 #include <cups/http.h>
6388 <A HREF="#http_t">http_t</A> *http;
6390 httpGet(http, "/some/uri");
6395 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6396 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
6397 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6400 <!-- NEW PAGE --><H2><A NAME="httpGets">httpGets()</A></H2>
6406 httpGets(char *line,
6413 <CENTER><TABLE WIDTH="80%" BORDER>
6416 <TH>Description</TH>
6420 <TD>The string to fill with a line from the HTTP connection</TD>
6424 <TD>The maximum length of the string</TD>
6428 <TD>The HTTP connection</TD>
6434 <P>A pointer to the string or NULL if no line could be retrieved.
6436 <H3>Description</H3>
6438 <P>The <CODE>httpGets()</CODE> function is used to read a request line from
6439 the HTTP connection. It is not normally used by a client program.
6444 #include <cups/http.h>
6446 <A HREF="#http_t">http_t</A> *http;
6449 if (httpGets(line, sizeof(line), http))
6451 ... process the line ...
6457 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6458 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6461 <!-- NEW PAGE --><H2><A NAME="httpGetDateString">httpGetDateString()</A></H2>
6467 httpGetDateString(time_t time)
6472 <CENTER><TABLE WIDTH="80%" BORDER>
6475 <TH>Description</TH>
6479 <TD>The UNIX date/time value</TD>
6485 <P>A pointer to a static string containing the HTTP date/time string for
6486 the specified UNIX time value.
6488 <H3>Description</H3>
6490 <P>The <CODE>httpGetDateString()</CODE> function generates a date/time string
6491 suitable for HTTP requests from a UNIX time value.
6496 #include <cups/http.h>
6498 puts(httpGetDateString(time(NULL)));
6503 <A HREF="#httpGetDateTime"><CODE>httpGetDateTime()</CODE></A>
6506 <!-- NEW PAGE --><H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2>
6512 httpGetDateTime(const char *date)
6517 <CENTER><TABLE WIDTH="80%" BORDER>
6520 <TH>Description</TH>
6524 <TD>The HTTP date/time string</TD>
6530 <P>A UNIX time value.
6532 <H3>Description</H3>
6534 <P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP
6535 date/time string to a UNIX time value.
6540 #include <cups/http.h>
6542 printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
6547 <A HREF="#httpGetDateString"><CODE>httpGetDateString()</CODE></A>
6550 <!-- NEW PAGE --><H2><A NAME="httpGetField">httpGetField()</A></H2>
6556 httpGetField(http_t *http,
6557 http_field_t field);
6562 <CENTER><TABLE WIDTH="80%" BORDER>
6565 <TH>Description</TH>
6569 <TD>The HTTP connection</TD>
6573 <TD>The HTTP field</TD>
6579 <P>A pointer to the field value string.
6581 <H3>Description</H3>
6583 <P>The <CODE>httpGetField()</CODE> function returns the current value for
6584 the specified HTTP field.
6589 #include <cups/http.h>
6591 <A HREF="#http_t">http_t</A> *http;
6593 httpGet(http, "/some/uri");
6594 while (httpUpdate(http) == HTTP_CONTINUE);
6596 puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
6601 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6602 <A HREF="#httpGetSubField"><CODE>httpGetSubField()</CODE></A>,
6603 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
6606 <!-- NEW PAGE --><H2><A NAME="httpGetHostByName">httpGetHostByName()</A></H2>
6612 httpGetHostByName(const char *name);
6617 <CENTER><TABLE WIDTH="80%" BORDER>
6620 <TH>Description</TH>
6624 <TD>Name or IP address to lookup.</TD>
6630 <P>NULL if the host could not be found or a pointer to a host entry
6631 containing one or more addresses.
6633 <H3>Description</H3>
6635 <P><CODE>httpGetHostByName()</CODE> is a portable wrapper around the
6636 <CODE>gethostbyname()</CODE> function which handles both hostnames
6642 #include <cups/http.h>
6644 struct hostent *hostaddr;
6646 hostaddr = httpGetHostByName("foo.bar.com");
6650 <!-- NEW PAGE --><H2><A NAME="httpGetLength">httpGetLength()</A></H2>
6656 httpGetLength(http_t *http);
6661 <CENTER><TABLE WIDTH="80%" BORDER>
6664 <TH>Description</TH>
6668 <TD>The HTTP connection.</TD>
6674 <P>The content length of the response or MAX_INT if chunking is used.
6676 <H3>Description</H3>
6678 <P><CODE>httpGetLength()</CODE> returns the content length of a response.
6683 #include <cups/http.h>
6685 <A HREF="#http_t">http_t</A> *http;
6689 printf("The length of the response is %d bytes.\n", httpGetLength(http));
6695 <A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
6696 <A HREF="#httpPost"><CODE>httpPost()</CODE></A>
6699 <!-- NEW PAGE --><H2><A NAME="httpGetSubField">httpGetSubField()</A></H2>
6705 httpGetSubField(http_t *http,
6713 <CENTER><TABLE WIDTH="80%" BORDER>
6716 <TH>Description</TH>
6720 <TD>The HTTP connection.</TD>
6724 <TD>The HTTP field.</TD>
6728 <TD>The name of the subfield.</TD>
6732 <TD>The string to hold the subfield value.</TD>
6738 <P>A pointer to the subfield value string or NULL if it does not exist.
6740 <H3>Description</H3>
6742 <P>The <CODE>httpGetSubField()</CODE> function returns a subfield value
6743 from the specified HTTP field. The destination string buffer must be at
6744 least <CODE>HTTP_MAX_VALUE</CODE> bytes in length.
6749 #include <cups/http.h>
6751 <A HREF="#http_t">http_t</A> *http;
6752 char value[HTTP_MAX_VALUE];
6754 httpGet(http, "/some/uri");
6755 while (httpUpdate(http) == HTTP_CONTINUE);
6757 puts(httpGetSubField(http, HTTP_FIELD_CONTENT_TYPE, "charset", value));
6762 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6763 <A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>,
6764 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
6767 <!-- NEW PAGE --><H2><A NAME="httpHead">httpHead()</A></H2>
6773 httpHead(http_t *http,
6779 <CENTER><TABLE WIDTH="80%" BORDER>
6782 <TH>Description</TH>
6786 <TD>The HTTP connection</TD>
6790 <TD>The URI to head</TD>
6796 <P>0 on success, non-zero on failure.
6798 <H3>Description</H3>
6800 <P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the
6806 #include <cups/http.h>
6810 httpHead(http, "/some/uri");
6815 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6816 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
6817 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6820 <!-- NEW PAGE --><H2><A NAME="httpInitialize">httpInitialize()</A></H2>
6825 void httpInitialize(void);
6828 <H3>Description</H3>
6830 <P>The <CODE>httpInitialize()</CODE> function initializes the networking
6831 code as needed by the underlying platform. It is called automatically by
6832 the <CODE>httpConnect()</CODE> function.
6837 #include <cups/http.h>
6844 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
6847 <!-- NEW PAGE --><H2><A NAME="httpMD5">httpMD5()</A></H2>
6853 httpMD5(const char *username,
6861 <CENTER><TABLE WIDTH="80%" BORDER>
6864 <TH>Description</TH>
6868 <TD>The authenticating user name.</TD>
6872 <TD>The authenticating realm name.</TD>
6876 <TD>The authenticating password.</TD>
6880 <TD>The MD5 sum string.</TD>
6886 <P>A pointer to the MD5 sum string.
6888 <H3>Description</H3>
6890 <P><CODE>httpMD5()</CODE> computes the MD5 hash of the username,
6891 realm, and password as required by the HTTP Digest specification.
6896 #include <cups/http.h>
6902 httpMD5("user", "realm", "password", md5);
6908 <A HREF="#httpMD5Final"><CODE>httpMD5Final()</CODE></A>,
6909 <A HREF="#httpMD5String"><CODE>httpMD5String()</CODE></A>
6912 <!-- NEW PAGE --><H2><A NAME="httpMD5Final">httpMD5Final()</A></H2>
6918 httpMD5Final(const char *nonce,
6920 const char *resource,
6926 <CENTER><TABLE WIDTH="80%" BORDER>
6929 <TH>Description</TH>
6933 <TD>The server nonce value.</TD>
6937 <TD>The HTTP method (GET, POST, etc.)</TD>
6941 <TD>The resource path.</TD>
6945 <TD>The MD5 sum string.</TD>
6951 <P>The MD5 sum string.
6953 <H3>Description</H3>
6955 <P><CODE>httpMD5Final()</CODE> appends the nonce, method, and resource
6956 to the specified MD5 sum.
6961 #include <cups/http.h>
6967 httpMD5Final("nonce", "GET", "/jobs", md5);
6973 <A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>,
6974 <A HREF="#httpMD5String"><CODE>httpMD5String()</CODE></A>
6977 <!-- NEW PAGE --><H2><A NAME="httpMD5String">httpMD5String()</A></H2>
6983 httpMD5String(const md5_byte_t *sum,
6989 <CENTER><TABLE WIDTH="80%" BORDER>
6992 <TH>Description</TH>
6996 <TD>The raw MD5 sum data.</TD>
7000 <TD>The MD5 sum string.</TD>
7006 <P>The MD5 sum string.
7008 <H3>Description</H3>
7010 <P><CODE>httpMD5String()</CODE> converts the raw MD5 sum value to a string.
7015 #include <cups/http.h>
7022 httpMD5String(sum, md5);
7028 <A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>,
7029 <A HREF="#httpMD5Final"><CODE>httpMD5Final()</CODE></A>
7032 <!-- NEW PAGE --><H2><A NAME="httpOptions">httpOptions()</A></H2>
7038 httpOptions(http_t *http,
7044 <CENTER><TABLE WIDTH="80%" BORDER>
7047 <TH>Description</TH>
7051 <TD>The HTTP connection</TD>
7055 <TD>The URI to check for options</TD>
7061 <P>0 on success, non-zero on failure.
7063 <H3>Description</H3>
7065 <P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request to the
7071 #include <cups/http.h>
7075 httpOptions(http, "/some/uri");
7080 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7081 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7082 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7085 <!-- NEW PAGE --><H2><A NAME="httpPost">httpPost()</A></H2>
7091 httpPost(http_t *http,
7097 <CENTER><TABLE WIDTH="80%" BORDER>
7100 <TH>Description</TH>
7104 <TD>The HTTP connection</TD>
7108 <TD>The URI to post to</TD>
7114 <P>0 on success, non-zero on failure.
7116 <H3>Description</H3>
7118 <P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the
7124 #include <cups/http.h>
7128 httpPost(http, "/some/uri");
7133 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7134 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7135 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7138 <!-- NEW PAGE --><H2><A NAME="httpPrintf">httpPrintf()</A></H2>
7144 httpPrintf(http_t *http,
7151 <CENTER><TABLE WIDTH="80%" BORDER>
7154 <TH>Description</TH>
7158 <TD>The HTTP connection</TD>
7162 <TD>A printf-style format string</TD>
7168 <P>The number of bytes written.
7170 <H3>Description</H3>
7172 <P>The <CODE>httpPrintf()</CODE> function sends a formatted string to the
7173 HTTP connection. It is normally only used by the CUPS API and scheduler.
7178 #include <cups/http.h>
7182 httpPrintf(http, "GET / HTTP/1.1 \r\n");
7187 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
7190 <!-- NEW PAGE --><H2><A NAME="httpPut">httpPut()</A></H2>
7196 httpPut(http_t *http,
7202 <CENTER><TABLE WIDTH="80%" BORDER>
7205 <TH>Description</TH>
7209 <TD>The HTTP connection</TD>
7213 <TD>The URI to put</TD>
7219 <P>0 on success, non-zero on failure.
7221 <H3>Description</H3>
7223 <P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the
7229 #include <cups/http.h>
7233 httpDelete(http, "/some/uri");
7238 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7239 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7240 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7243 <!-- NEW PAGE --><H2><A NAME="httpRead">httpRead()</A></H2>
7249 httpRead(http_t *http,
7256 <CENTER><TABLE WIDTH="80%" BORDER>
7259 <TH>Description</TH>
7263 <TD>The HTTP connection</TD>
7267 <TD>The buffer to read into</TD>
7271 <TD>The number of bytes to read</TD>
7277 <P>The number of bytes read or -1 on error.
7279 <H3>Description</H3>
7281 <P>The <CODE>httpRead()</CODE> function reads data from the HTTP connection,
7282 possibly the result of a GET or POST request.
7287 #include <cups/http.h>
7294 while (httpUpdate(http) != HTTP_CONTINUE);
7295 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
7297 buffer[bytes] = '\0';
7298 fputs(buffer, stdout);
7304 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7305 <A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
7308 <!-- NEW PAGE --><H2><A NAME="httpReconnect">httpReconnect()</A></H2>
7314 httpReconnect(http_t *http);
7319 <CENTER><TABLE WIDTH="80%" BORDER>
7322 <TH>Description</TH>
7326 <TD>The HTTP connection</TD>
7332 <P>0 on success, non-zero on failure.
7334 <H3>Description</H3>
7336 <P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP server.
7337 This is usually done automatically if the HTTP functions detect that the
7338 server connection has terminated.
7343 #include <cups/http.h>
7347 httpReconnect(http);
7352 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
7355 <!-- NEW PAGE --><H2><A NAME="httpSeparate">httpSeparate()</A></H2>
7361 httpSeparate(const char *uri,
7371 <CENTER><TABLE WIDTH="80%" BORDER>
7374 <TH>Description</TH>
7378 <TD>The URI to separate</TD>
7382 <TD>The method (scheme) of the URI</TD>
7386 <TD>The username (and password) portion of the URI, if any</TD>
7390 <TD>The hostname portion of the URI, if any</TD>
7394 <TD>The port number for the URI, either as specified or as
7395 default for the method/scheme</TD>
7399 <TD>The resource string, usually a filename on the server</TD>
7403 <H3>Description</H3>
7405 <P>The <CODE>httpSeparate()</CODE> function separates the specified URI into
7406 its component parts. The method, username, hostname, and resource strings should
7407 be at least <CODE>HTTP_MAX_URI</CODE> characters long to avoid potential
7408 buffer overflow problems.
7413 char uri[HTTP_MAX_URI];
7414 char method[HTTP_MAX_URI];
7415 char username[HTTP_MAX_URI];
7416 char host[HTTP_MAX_URI];
7417 char resource[HTTP_MAX_URI];
7422 httpSeparate(uri, method, username, host, &port, resource);
7427 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
7430 <!-- NEW PAGE --><H2><A NAME="httpSetField">httpSetField()</A></H2>
7436 httpSetField(http_t *http,
7443 <CENTER><TABLE WIDTH="80%" BORDER>
7446 <TH>Description</TH>
7450 <TD>The HTTP connection</TD>
7454 <TD>The HTTP field</TD>
7458 <TD>The string value for the field</TD>
7462 <H3>Description</H3>
7464 <P>The <CODE>httpSetField()</CODE> function sets the current value for
7465 the specified HTTP field.
7470 #include <cups/http.h>
7474 httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
7475 httpGet(http, "/some/uri");
7476 while (httpUpdate(http) == HTTP_CONTINUE);
7481 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7482 <A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>
7485 <!-- NEW PAGE --><H2><A NAME="httpStatus">httpStatus()</A></H2>
7491 httpStatus(http_status_t status);
7496 <CENTER><TABLE WIDTH="80%" BORDER>
7499 <TH>Description</TH>
7503 <TD>The HTTP status code from the server.</TD>
7509 <P>The standard HTTP status text associated with the status code.
7511 <H3>Description</H3>
7513 <P><CODE>httpStatus()</CODE> returns the standard HTTP status text
7514 associated with the status code.
7519 #include <cups/http.h>
7521 <A HREF="#http_t">http_t</A> *http;
7525 puts(httpStatus(http->status));
7529 <!-- NEW PAGE --><H2><A NAME="httpTrace">httpTrace()</A></H2>
7535 httpTrace(http_t *http,
7541 <CENTER><TABLE WIDTH="80%" BORDER>
7544 <TH>Description</TH>
7548 <TD>The HTTP connection</TD>
7552 <TD>The URI to trace</TD>
7558 <P>0 on success, non-zero on failure.
7560 <H3>Description</H3>
7562 <P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to the
7568 #include <cups/http.h>
7572 httpTrace(http, "/some/uri");
7577 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7578 <A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7579 <A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7582 <!-- NEW PAGE --><H2><A NAME="httpUpdate">httpUpdate()</A></H2>
7588 httpUpdate(http_t *http);
7593 <CENTER><TABLE WIDTH="80%" BORDER>
7596 <TH>Description</TH>
7600 <TD>The HTTP connection</TD>
7606 <P>The HTTP status of the current request.
7608 <H3>Description</H3>
7610 <P>The <CODE>httpUpdate()</CODE> function updates the current request status.
7611 It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE
7612 request to finalize the HTTP request and retrieve the request status.
7614 <P>Since proxies and the current blocking mode can cause the request to
7615 take longer, programs should continue calling <CODE>httpUpdate()<CODE>
7616 until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>.
7621 #include <cups/http.h>
7624 http_status_t status;
7626 httpGet(http, "/some/uri");
7627 while ((status = httpUpdate(http)) == HTTP_CONTINUE);
7628 printf("Request status is %d\n", status);
7633 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7634 <A HREF="#httpDelete"><CODE>httpDelete()</CODE></A>,
7635 <A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
7636 <A HREF="#httpHead"><CODE>httpHead()</CODE></A>,
7637 <A HREF="#httpOptions"><CODE>httpOptions()</CODE></A>,
7638 <A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
7639 <A HREF="#httpPut"><CODE>httpPut()</CODE></A>,
7640 <A HREF="#httpTrace"><CODE>httpTrace()</CODE></A>
7643 <!-- NEW PAGE --><H2><A NAME="httpWrite">httpWrite()</A></H2>
7649 httpWrite(http_t *http,
7656 <CENTER><TABLE WIDTH="80%" BORDER>
7659 <TH>Description</TH>
7663 <TD>The HTTP connection</TD>
7667 <TD>The buffer to read into</TD>
7671 <TD>The number of bytes to read</TD>
7677 <P>The number of bytes read or -1 on error.
7679 <H3>Description</H3>
7681 <P>The <CODE>httpWrite()</CODE> function reads data from the HTTP connection,
7682 possibly the result of a GET or POST request.
7687 #include <cups/http.h>
7694 httpPost(http, "/");
7696 while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
7697 httpWrite(http, buffer, bytes);
7699 while (httpUpdate(http) != HTTP_CONTINUE);
7701 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
7703 buffer[bytes] = '\0';
7704 fputs(buffer, stdout);
7710 <A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7711 <A HREF="#httpRead"><CODE>httpRead()</CODE></A>
7714 <!-- NEW PAGE --><H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2>
7720 ippAddBoolean(ipp_t *ipp,
7728 <CENTER><TABLE WIDTH="80%" BORDER>
7731 <TH>Description</TH>
7735 <TD>The IPP request</TD>
7739 <TD>The IPP group</TD>
7743 <TD>The name of attribute</TD>
7747 <TD>The boolean value</TD>
7753 <P>A pointer to the new attribute or NULL if the attribute could not be
7756 <H3>Description</H3>
7758 <P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean attribute
7759 value to the specified IPP request.
7764 #include <cups/ipp.h>
7768 ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
7773 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
7774 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
7775 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
7776 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
7777 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
7778 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
7779 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
7780 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
7781 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
7782 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
7783 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
7786 <!-- NEW PAGE --><H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2>
7792 ippAddBooleans(ipp_t *ipp,
7796 const char *values);
7801 <CENTER><TABLE WIDTH="80%" BORDER>
7804 <TH>Description</TH>
7808 <TD>The IPP request</TD>
7812 <TD>The IPP group</TD>
7816 <TD>The name of attribute</TD>
7820 <TD>The number of values</TD>
7824 <TD>The boolean values</TD>
7830 <P>A pointer to the new attribute or NULL if the attribute could not be
7833 <H3>Description</H3>
7835 <P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean
7836 attribute values to the specified IPP request. If the
7837 <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
7838 <CODE>num_values</CODE> false values is created.
7843 #include <cups/ipp.h>
7848 ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
7853 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
7854 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
7855 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
7856 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
7857 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
7858 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
7859 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
7860 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
7861 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
7862 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
7863 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
7866 <!-- NEW PAGE --><H2><A NAME="ippAddDate">ippAddDate()</A></H2>
7872 ippAddDate(ipp_t *ipp,
7875 ipp_uchar_t *value);
7880 <CENTER><TABLE WIDTH="80%" BORDER>
7883 <TH>Description</TH>
7887 <TD>The IPP request</TD>
7891 <TD>The IPP group</TD>
7895 <TD>The name of attribute</TD>
7899 <TD>The date value</TD>
7905 <P>A pointer to the new attribute or NULL if the attribute could not be
7908 <H3>Description</H3>
7910 <P>The <CODE>ippAddDate()</CODE> function adds a single date-time attribute
7911 value to the specified IPP request.
7916 #include <cups/ipp.h>
7920 ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute",
7921 ippTimeToDate(time(NULL));
7926 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
7927 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
7928 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
7929 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
7930 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
7931 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
7932 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
7933 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
7934 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
7935 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
7936 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>,
7937 <A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
7940 <!-- NEW PAGE --><H2><A NAME="ippAddInteger">ippAddInteger()</A></H2>
7946 ippAddInteger(ipp_t *ipp,
7955 <CENTER><TABLE WIDTH="80%" BORDER>
7958 <TH>Description</TH>
7962 <TD>The IPP request</TD>
7966 <TD>The IPP group</TD>
7970 <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
7974 <TD>The name of attribute</TD>
7978 <TD>The integer value</TD>
7984 <P>A pointer to the new attribute or NULL if the attribute could not be
7987 <H3>Description</H3>
7989 <P>The <CODE>ippAddInteger()</CODE> function adds a single integer attribute
7990 value to the specified IPP request.
7995 #include <cups/ipp.h>
7999 ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
8004 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8005 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8006 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8007 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8008 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8009 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8010 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8011 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8012 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8013 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8014 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8017 <!-- NEW PAGE --><H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2>
8023 ippAddIntegers(ipp_t *ipp,
8033 <CENTER><TABLE WIDTH="80%" BORDER>
8036 <TH>Description</TH>
8040 <TD>The IPP request</TD>
8044 <TD>The IPP group</TD>
8048 <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
8052 <TD>The name of attribute</TD>
8056 <TD>The number of values</TD>
8060 <TD>The integer values</TD>
8066 <P>A pointer to the new attribute or NULL if the attribute could not be
8069 <H3>Description</H3>
8071 <P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer
8072 attribute values to the specified IPP request. If the
8073 <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8074 <CODE>num_values</CODE> 0 values is created.
8079 #include <cups/ipp.h>
8084 ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
8089 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8090 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8091 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8092 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8093 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8094 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8095 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8096 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8097 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8098 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8099 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8102 <!-- NEW PAGE --><H2><A NAME="ippAddRange">ippAddRange()</A></H2>
8108 ippAddRange(ipp_t *ipp,
8117 <CENTER><TABLE WIDTH="80%" BORDER>
8120 <TH>Description</TH>
8124 <TD>The IPP request</TD>
8128 <TD>The IPP group</TD>
8132 <TD>The name of attribute</TD>
8136 <TD>The lower value</TD>
8140 <TD>The higher value</TD>
8146 <P>A pointer to the new attribute or NULL if the attribute could not be
8149 <H3>Description</H3>
8151 <P>The <CODE>ippAddRange()</CODE> function adds a single range attribute
8152 value to the specified IPP request.
8157 #include <cups/ipp.h>
8161 ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
8166 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8167 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8168 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8169 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8170 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8171 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8172 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8173 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8174 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8175 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8176 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8179 <!-- NEW PAGE --><H2><A NAME="ippAddRanges">ippAddRanges()</A></H2>
8185 ippAddRanges(ipp_t *ipp,
8195 <CENTER><TABLE WIDTH="80%" BORDER>
8198 <TH>Description</TH>
8202 <TD>The IPP request</TD>
8206 <TD>The IPP group</TD>
8210 <TD>The name of attribute</TD>
8214 <TD>The number of range values</TD>
8218 <TD>The lower values</TD>
8222 <TD>The higher values</TD>
8228 <P>A pointer to the new attribute or NULL if the attribute could not be
8231 <H3>Description</H3>
8233 <P>The <CODE>ippAddRanges()</CODE> function adds one or more range
8234 attribute values to the specified IPP request. If the
8235 <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8236 <CODE>num_values</CODE> 0,0 ranges is created.
8241 #include <cups/ipp.h>
8247 ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
8252 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8253 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8254 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8255 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8256 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8257 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8258 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8259 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8260 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8261 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8262 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8265 <!-- NEW PAGE --><H2><A NAME="ippAddResolution">ippAddResolution()</A></H2>
8271 ippAddResolution(ipp_t *ipp,
8281 <CENTER><TABLE WIDTH="80%" BORDER>
8284 <TH>Description</TH>
8288 <TD>The IPP request</TD>
8292 <TD>The IPP group</TD>
8296 <TD>The name of attribute</TD>
8300 <TD>The horizontal resolution</TD>
8304 <TD>The vertical resolution</TD>
8308 <TD>The resolution units</TD>
8314 <P>A pointer to the new attribute or NULL if the attribute could not be
8317 <H3>Description</H3>
8319 <P>The <CODE>ippAddResolution()</CODE> function adds a single resolution attribute
8320 value to the specified IPP request.
8325 #include <cups/ipp.h>
8329 ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
8330 720, 720, IPP_RES_PER_INCH);
8335 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8336 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8337 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8338 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8339 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8340 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8341 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8342 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8343 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8344 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8345 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8348 <!-- NEW PAGE --><H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2>
8354 ippAddResolutions(ipp_t *ipp,
8360 const ipp_res_t *units);
8365 <CENTER><TABLE WIDTH="80%" BORDER>
8368 <TH>Description</TH>
8372 <TD>The IPP request</TD>
8376 <TD>The IPP group</TD>
8380 <TD>The name of attribute</TD>
8384 <TD>The number of resolution values</TD>
8388 <TD>The horizontal resolutions</TD>
8392 <TD>The vertical resolutions</TD>
8396 <TD>The resolution units</TD>
8402 <P>A pointer to the new attribute or NULL if the attribute could not be
8405 <H3>Description</H3>
8407 <P>The <CODE>ippAddResolutions()</CODE> function adds one or more
8408 resolution attribute values to the specified IPP request. If the
8409 <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8410 <CODE>num_values</CODE> 0,0 resolutions is created.
8415 #include <cups/ipp.h>
8422 ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
8423 5, xres, yres, units);
8428 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8429 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8430 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8431 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8432 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8433 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8434 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8435 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8436 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8437 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8438 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8441 <!-- NEW PAGE --><H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2>
8447 ippAddSeparator(ipp_t *ipp);
8452 <CENTER><TABLE WIDTH="80%" BORDER>
8455 <TH>Description</TH>
8459 <TD>The IPP request</TD>
8465 <P>A pointer to the new separator or NULL if the separator could not be
8468 <H3>Description</H3>
8470 <P>The <CODE>ippAddSeparator()</CODE> function adds a group separator
8471 to the specified IPP request.
8476 #include <cups/ipp.h>
8480 ippAddSeparator(ipp);
8485 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8486 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8487 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8488 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8489 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8490 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8491 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8492 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8493 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8494 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8495 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8498 <!-- NEW PAGE --><H2><A NAME="ippAddString">ippAddString()</A></H2>
8504 ippAddString(ipp_t *ipp,
8508 const char *charset,
8514 <CENTER><TABLE WIDTH="80%" BORDER>
8517 <TH>Description</TH>
8521 <TD>The IPP request</TD>
8525 <TD>The IPP group</TD>
8529 <TD>The type of string value</TD>
8533 <TD>The name of attribute</TD>
8537 <TD>The character set for the string</TD>
8541 <TD>The string value</TD>
8547 <P>A pointer to the new attribute or NULL if the attribute could not be
8550 <H3>Description</H3>
8552 <P>The <CODE>ippAddString()</CODE> function adds a single string attribute
8553 value to the specified IPP request. For <CODE>IPP_TAG_NAMELANG</CODE> and
8554 <CODE>IPP_TAG_TEXTLANG</CODE> strings, the charset value is provided with
8555 the string to identify the string encoding used. Otherwise the charset value
8561 #include <cups/ipp.h>
8565 ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
8571 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8572 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8573 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8574 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8575 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8576 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8577 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8578 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8579 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8580 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8581 <A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8584 <!-- NEW PAGE --><H2><A NAME="ippAddStrings">ippAddStrings()</A></H2>
8590 ippAddStrings(ipp_t *ipp,
8595 const char *charset,
8596 const char **values);
8601 <CENTER><TABLE WIDTH="80%" BORDER>
8604 <TH>Description</TH>
8608 <TD>The IPP request</TD>
8612 <TD>The IPP group</TD>
8616 <TD>The type of string value</TD>
8620 <TD>The name of attribute</TD>
8624 <TD>The number of strings</TD>
8628 <TD>The character set for the strings</TD>
8632 <TD>The string values</TD>
8638 <P>A pointer to the new attribute or NULL if the attribute could not be
8641 <H3>Description</H3>
8643 <P>The <CODE>ippAddStrings()</CODE> function adds one or more string
8644 attribute values to the specified IPP request. For
8645 <CODE>IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE>
8646 strings, the charset value is provided with the strings to identify the
8647 string encoding used. Otherwise the charset value is ignored. If the
8648 <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8649 <CODE>num_values</CODE> NULL strings is created.
8654 #include <cups/ipp.h>
8657 char *values[2] = { "one", "two" };
8659 ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
8665 <A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8666 <A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8667 <A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8668 <A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8669 <A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8670 <A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8671 <A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8672 <A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8673 <A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8674 <A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8675 <A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>
8678 <!-- NEW PAGE --><H2><A NAME="ippDateToTime">ippDateToTime()</A></H2>
8684 ippDateToTime(const ipp_uchar_t date[11]);
8689 <CENTER><TABLE WIDTH="80%" BORDER>
8692 <TH>Description</TH>
8696 <TD>The IPP date-time value</TD>
8702 <P>A UNIX time value.
8704 <H3>Description</H3>
8706 <P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time value
8707 to a UNIX time value.
8712 #include <cups/ipp.h>
8714 ipp_uchar_t date[11];
8716 printf("UNIX time is %d\n", ippDateToTime(date));
8721 <A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
8724 <!-- NEW PAGE --><H2><A NAME="ippDelete">ippDelete()</A></H2>
8730 ippDelete(ipp_t *ipp);
8735 <CENTER><TABLE WIDTH="80%" BORDER>
8738 <TH>Description</TH>
8742 <TD>The IPP request or response</TD>
8746 <H3>Description</H3>
8748 <P>The <CODE>ippDelete()</CODE> function deletes all memory used by an IPP
8749 request or response.
8754 #include <cups/ipp.h>
8763 <A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8766 <!-- NEW PAGE --><H2><A NAME="ippErrorString">ippErrorString()</A></H2>
8772 ippErrorString(ipp_status_t error);
8777 <CENTER><TABLE WIDTH="80%" BORDER>
8780 <TH>Description</TH>
8784 <TD>IPP error code.</TD>
8790 <P>The standard text representation of the IPP error code.
8792 <H3>Description</H3>
8794 <P><CODE>ippErrorString()</CODE> returns the standard text representation
8795 of the IPP error code.
8800 #include <cups/ipp.h>
8802 puts(ippErrorString(IPP_OK));
8808 <A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>
8811 <!-- NEW PAGE --><H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2>
8817 ippFindAttribute(ipp_t *ipp,
8824 <CENTER><TABLE WIDTH="80%" BORDER>
8827 <TH>Description</TH>
8831 <TD>The IPP request or response</TD>
8835 <TD>The name of the attribute</TD>
8839 <TD>The required value tag for the attribute or
8840 <CODE>IPP_TAG_ZERO</CODE> for any type of value.</TD>
8846 <P>A pointer to the first occurrence of the requested attribute, or
8847 <CODE>NULL</CODE> if it was not found.
8849 <H3>Description</H3>
8851 <P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the named
8852 attribute. The <CODE>tag</CODE> parameter restricts the search to a specific
8853 value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.
8855 <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
8856 match the name/text values with or without the language code.
8861 <A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr;
8863 attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8864 while (attr != NULL)
8866 puts(attr->values[0].string.text);
8868 attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8874 <A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>,
8875 <A HREF="#cupsDoRequest"><CODE>cupsDoRequest()</CODE></A>,
8876 <A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
8877 <A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE></A>,
8878 <A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8881 <!-- NEW PAGE --><H2><A NAME="ippFindNextAttribute">ippFindNextAttribute()</A></H2>
8887 ippFindNextAttribute(ipp_t *ipp,
8894 <CENTER><TABLE WIDTH="80%" BORDER>
8897 <TH>Description</TH>
8901 <TD>The IPP request or response</TD>
8905 <TD>The name of the attribute</TD>
8909 <TD>The required value tag for the attribute or
8910 <CODE>IPP_TAG_ZERO</CODE> for any type of value.</TD>
8916 <P>A pointer to the next occurrence of the requested attribute, or
8917 <CODE>NULL</CODE> if it was not found.
8919 <H3>Description</H3>
8921 <P><CODE>ippFindNextAttribute()</CODE> finds the next occurrence of the named
8922 attribute. The <CODE>tag</CODE> parameter restricts the search to a specific
8923 value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.
8925 <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
8926 match the name/text values with or without the language code.
8931 <A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr;
8933 attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8934 while (attr != NULL)
8936 puts(attr->values[0].string.text);
8938 attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8944 <A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>,
8945 <A HREF="#cupsDoRequest"><CODE>cupsDoRequest()</CODE></A>,
8946 <A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
8947 <A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE></A>,
8948 <A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8951 <!-- NEW PAGE --><H2><A NAME="ippLength">ippLength()</A></H2>
8957 ippLength(ipp_t *ipp);
8962 <CENTER><TABLE WIDTH="80%" BORDER>
8965 <TH>Description</TH>
8969 <TD>The IPP request or response</TD>
8975 <P>The total encoded length of the IPP request or response in bytes.
8977 <H3>Description</H3>
8979 <P><CODE>ippLength()</CODE> returns the length of the IPP request or
8985 printf("The length of the response is %d bytes.\n", ippLength(response));
8990 <A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
8991 <A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8994 <!-- NEW PAGE --><H2><A NAME="ippNew">ippNew()</A></H2>
9005 <P>A pointer to a new IPP request or response.
9007 <H3>Description</H3>
9009 <P>The <CODE>ippNew()</CODE> function creates a new IPP request or response.
9014 #include <cups/ipp.h>
9023 <A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>
9026 <!-- NEW PAGE --><H2><A NAME="ippPort">ippPort()</A></H2>
9037 <P>The default TCP/IP port number for IPP requests.
9039 <H3>Description</H3>
9041 <P>The <CODE>ippPort()</CODE> function returns the default IPP port number
9047 #include <cups/http.h>
9048 #include <cups/ipp.h>
9052 http = httpConnect(cupsServer(), ippPort());
9057 <A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
9058 <A HREF="#ippSetPort"><CODE>ippSetPort()</CODE></A>
9061 <!-- NEW PAGE --><H2><A NAME="ippRead">ippRead()</A></H2>
9067 ippRead(http_t *http,
9073 <CENTER><TABLE WIDTH="80%" BORDER>
9076 <TH>Description</TH>
9080 <TD>The HTTP connection</TD>
9084 <TD>The IPP request or response</TD>
9090 <P>The current read state.
9092 <H3>Description</H3>
9094 <P>The <CODE>ippRead()</CODE> function reads IPP attributes from the specified
9095 HTTP connection. Programs should continue calling <CODE>ippRead()</CODE> until
9096 <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
9101 #include <cups/http.h>
9102 #include <cups/ipp.h>
9110 while ((status = ippRead(http, ipp)) != IPP_ERROR)
9111 if (status == IPP_DATA)
9114 if (status == IPP_DATA)
9116 ... read additional non-IPP data using httpRead() ...
9122 <A HREF="#ippWrite"><CODE>ippWrite()</CODE></A>
9125 <!-- NEW PAGE --><H2><A NAME="ippSetPort">ippSetPort()</A></H2>
9131 ippSetPort(int port);
9136 <CENTER><TABLE WIDTH="80%" BORDER>
9139 <TH>Description</TH>
9143 <TD>The port number to use</TD>
9147 <H3>Description</H3>
9149 <P>The <CODE>ippSetPort()</CODE> function sets the default IPP port number
9155 #include <cups/http.h>
9156 #include <cups/ipp.h>
9165 <A HREF="#ippPort"><CODE>ippPort()</CODE></A>
9168 <!-- NEW PAGE --><H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2>
9174 ippTimeToDate(time_t time);
9179 <CENTER><TABLE WIDTH="80%" BORDER>
9182 <TH>Description</TH>
9186 <TD>The UNIX time value</TD>
9192 <P>A static pointer to an IPP date-time value.
9194 <H3>Description</H3>
9196 <P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an IPP
9202 #include <cups/ipp.h>
9206 date = ippTimeToDate(time(NULL));
9211 <A HREF="#ippDateToTime"><CODE>ippDateToTime()</CODE></A>
9214 <!-- NEW PAGE --><H2><A NAME="ippWrite">ippWrite()</A></H2>
9220 ippWrite(http_t *http,
9226 <CENTER><TABLE WIDTH="80%" BORDER>
9229 <TH>Description</TH>
9233 <TD>The HTTP connection</TD>
9237 <TD>The IPP request or response</TD>
9243 <P>The current write state.
9245 <H3>Description</H3>
9247 <P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the specified
9248 HTTP connection. Programs should continue calling <CODE>ippWrite()</CODE> until
9249 <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
9254 #include <cups/http.h>
9255 #include <cups/ipp.h>
9262 ... add attributes ...
9264 while ((status = ippWrite(http, ipp)) != IPP_ERROR)
9265 if (status == IPP_DATA)
9268 if (status == IPP_DATA)
9270 ... read additional non-IPP data using httpWrite() ...
9276 <A HREF="#ippRead"><CODE>ippRead()</CODE></A>
9279 <!-- NEW PAGE --><H2><A NAME="ppdClose">ppdClose()</A></H2>
9285 ppdClose(ppd_file_t *ppd);
9290 <CENTER><TABLE WIDTH="80%" BORDER>
9293 <TH>Description</TH>
9297 <TD>The PPD file</TD>
9301 <H3>Description</H3>
9303 <P>The <CODE>ppdClose()</CODE> function frees all memory associated with the
9309 #include <cups/ppd.h>
9318 <A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
9319 <A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
9320 <A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
9323 <!-- NEW PAGE --><H2><A NAME="ppdCollect">ppdCollect()</A></H2>
9329 ppdCollect(ppd_file_t *ppd,
9330 ppd_section_t section,
9331 ppd_choice_t ***choices);
9336 <CENTER><TABLE WIDTH="80%" BORDER>
9339 <TH>Description</TH>
9343 <TD>The PPD file.</TD>
9347 <TD>The document section to collect.</TD>
9351 <TD>The array of option choices that are marked.</TD>
9357 <P>The number of options collected.
9359 <H3>Description</H3>
9361 <P><CODE>ppdCollect()</CODE> collects all of the marked options in the
9362 specified section, sorts them by their order dependency values, and
9363 returns an array that can be used to emit option commands in the proper
9364 order. It is normally used by the <CODE>ppdEmit*()</CODE> functions.
9369 #include <cups/ppd.h>
9371 <A HREF="#ppd_file_t">ppd_file_t</A> *ppd;
9373 <A HREF="#ppd_choice_t">ppd_choice_t</A> **choices;
9377 num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &choices);
9383 <A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>,
9384 <A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A>,
9385 <A HREF="#ppdEmitJCL"><CODE>ppdEmitJCL()</CODE></A>
9388 <!-- NEW PAGE --><H2><A NAME="ppdConflicts">ppdConflicts()</A></H2>
9394 ppdConflicts(ppd_file_t *ppd);
9399 <CENTER><TABLE WIDTH="80%" BORDER>
9402 <TH>Description</TH>
9406 <TD>The PPD file</TD>
9412 <P>The number of option conflicts in the file.
9414 <H3>Description</H3>
9416 <P>The <CODE>ppdConflicts()</CODE> function returns the number of conflicts
9417 with the currently selected options.
9422 #include <cups/ppd.h>
9426 printf("%d conflicts\n", ppdConflicts(ppd));
9431 <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9432 <A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9433 <A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9434 <A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9437 <!-- NEW PAGE --><H2><A NAME="ppdEmit">ppdEmit()</A></H2>
9443 ppdEmit(ppd_file_t *ppd,
9445 ppd_section_t section);
9450 <CENTER><TABLE WIDTH="80%" BORDER>
9453 <TH>Description</TH>
9457 <TD>The PPD file</TD>
9461 <TD>The file to write to</TD>
9465 <TD>The option section to write</TD>
9471 <P>0 on success, -1 on error.
9473 <H3>Description</H3>
9475 <P>The <CODE>ppdEmit()</CODE> function sends printer-specific option
9476 commands to the specified file.
9481 #include <cups/ppd.h>
9485 ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
9490 <A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A>
9493 <!-- NEW PAGE --><H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2>
9499 ppdEmitFd(ppd_file_t *ppd,
9501 ppd_section_t section);
9506 <CENTER><TABLE WIDTH="80%" BORDER>
9509 <TH>Description</TH>
9513 <TD>The PPD file</TD>
9517 <TD>The file descriptor to write to</TD>
9521 <TD>The option section to write</TD>
9527 <P>0 on success, -1 on error.
9529 <H3>Description</H3>
9531 <P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option
9532 commands to the specified file descriptor.
9537 #include <cups/ppd.h>
9541 ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
9546 <A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>
9549 <!-- NEW PAGE --><H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2>
9555 ppdFindChoice(ppd_option_t *option,
9556 const char *choice);
9561 <CENTER><TABLE WIDTH="80%" BORDER>
9564 <TH>Description</TH>
9568 <TD>A pointer to the option</TD>
9572 <TD>The name of the choice</TD>
9578 <P>A pointer to the choice data or NULL if the choice does not exist.
9580 <H3>Description</H3>
9582 <P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the choice
9583 data for the specified option.
9588 #include <cups/ppd.h>
9591 ppd_option_t *option;
9592 ppd_choice_t *choice;
9594 option = ppdFindOption(ppd, "PageSize");
9595 choice = ppdFindChoice(option, "Letter");
9600 <A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>,
9601 <A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
9604 <!-- NEW PAGE --><H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2>
9610 ppdFindMarkedChoice(ppd_file_t *ppd,
9611 const char *keyword);
9616 <CENTER><TABLE WIDTH="80%" BORDER>
9619 <TH>Description</TH>
9623 <TD>The PPD file</TD>
9627 <TD>The name of the option</TD>
9633 <P>A pointer to the choice data or NULL if the choice does not exist or
9636 <H3>Description</H3>
9638 <P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to
9639 the marked choice data for the specified option.
9644 #include <cups/ppd.h>
9647 ppd_choice_t *choice;
9649 choice = ppdFindMarkedChoice(ppd, "PageSize");
9654 <A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
9655 <A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
9658 <!-- NEW PAGE --><H2><A NAME="ppdFindOption">ppdFindOption()</A></H2>
9664 ppdFindOption(ppd_file_t *ppd,
9665 const char *keyword);
9670 <CENTER><TABLE WIDTH="80%" BORDER>
9673 <TH>Description</TH>
9677 <TD>The PPD file</TD>
9681 <TD>The name of the option</TD>
9687 <P>A pointer to the option data or NULL if the option does not exist.
9689 <H3>Description</H3>
9691 <P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the option
9692 data for the specified option.
9697 #include <cups/ppd.h>
9700 ppd_option_t *option;
9702 option = ppdFindOption(ppd, "PageSize");
9707 <A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
9708 <A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>
9711 <!-- NEW PAGE --><H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2>
9717 ppdIsMarked(ppd_file_t *ppd,
9718 const char *keyword,
9719 const char *choice);
9724 <CENTER><TABLE WIDTH="80%" BORDER>
9727 <TH>Description</TH>
9731 <TD>The PPD file</TD>
9735 <TD>The name of the option</TD>
9739 <TD>The name of the option choice</TD>
9745 <P>1 if the choice is marked, 0 otherwise.
9747 <H3>Description</H3>
9749 <P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the
9750 specified option choice is marked.
9755 #include <cups/ppd.h>
9759 printf("Letter size %s selected.\n",
9760 ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
9765 <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9766 <A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
9767 <A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9768 <A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9769 <A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9772 <!-- NEW PAGE --><H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2>
9778 ppdMarkDefaults(ppd_file_t *ppd);
9783 <CENTER><TABLE WIDTH="80%" BORDER>
9786 <TH>Description</TH>
9790 <TD>The PPD file</TD>
9794 <H3>Description</H3>
9796 <P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default
9797 choices in the PPD file.
9802 #include <cups/ppd.h>
9806 ppdMarkDefaults(ppd);
9811 <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9812 <A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
9813 <A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9814 <A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9815 <A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9818 <!-- NEW PAGE --><H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2>
9824 ppdMarkOption(ppd_file_t *ppd,
9825 const char *keyword,
9826 const char *choice);
9831 <CENTER><TABLE WIDTH="80%" BORDER>
9834 <TH>Description</TH>
9838 <TD>The PPD file</TD>
9842 <TD>The name of the option</TD>
9846 <TD>The name of the choice</TD>
9852 <P>The number of conflicts in the PPD file.
9854 <H3>Description</H3>
9856 <P>The <CODE>ppdMarkOption()</CODE> function marks the specified option
9862 #include <cups/ppd.h>
9866 ppdMarkOption(ppd, "PageSize", "Letter");
9871 <A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9872 <A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
9873 <A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9874 <A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9875 <A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9878 <!-- NEW PAGE --><H2><A NAME="ppdOpen">ppdOpen()</A></H2>
9884 ppdOpen(FILE *file);
9889 <CENTER><TABLE WIDTH="80%" BORDER>
9892 <TH>Description</TH>
9896 <TD>The file to read from</TD>
9902 <P>A pointer to a PPD file structure or NULL if the PPD file could not be
9905 <H3>Description</H3>
9907 <P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the specified
9913 #include <cups/ppd.h>
9918 file = fopen("filename.ppd", "rb");
9919 ppd = ppdOpen(file);
9925 <A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
9926 <A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
9927 <A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
9930 <!-- NEW PAGE --><H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2>
9941 <CENTER><TABLE WIDTH="80%" BORDER>
9944 <TH>Description</TH>
9948 <TD>The file descriptor to read from</TD>
9954 <P>A pointer to a PPD file structure or NULL if the PPD file could not be
9957 <H3>Description</H3>
9959 <P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the specified
9960 file descriptor into memory.
9965 #include <cups/ppd.h>
9970 fd = open("filename.ppd", O_RDONLY);
9971 ppd = ppdOpenFd(fd);
9977 <A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
9978 <A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
9979 <A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
9982 <!-- NEW PAGE --><H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2>
9988 ppdOpenFile(const char *filename);
9993 <CENTER><TABLE WIDTH="80%" BORDER>
9996 <TH>Description</TH>
10000 <TD>The name of the file to read from</TD>
10006 <P>A pointer to a PPD file structure or NULL if the PPD file could not be
10009 <H3>Description</H3>
10011 <P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the named
10017 #include <cups/ppd.h>
10021 ppd = ppdOpenFile("filename.ppd");
10026 <A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
10027 <A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
10028 <A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>
10031 <!-- NEW PAGE --><H2><A NAME="ppdPageLength">ppdPageLength()</A></H2>
10037 ppdPageLength(ppd_file_t *ppd,
10043 <CENTER><TABLE WIDTH="80%" BORDER>
10046 <TH>Description</TH>
10050 <TD>The PPD file</TD>
10054 <TD>The name of the page size</TD>
10060 <P>The length of the specified page size in points or 0 if the page size
10063 <H3>Description</H3>
10065 <P>The <CODE>ppdPageLength()</CODE> function returns the page length of the
10066 specified page size.
10071 #include <cups/ppd.h>
10075 printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
10080 <A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
10081 <A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>,
10082 <A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
10085 <!-- NEW PAGE --><H2><A NAME="ppdPageSize">ppdPageSize()</A></H2>
10091 ppdPageSize(ppd_file_t *ppd,
10097 <CENTER><TABLE WIDTH="80%" BORDER>
10100 <TH>Description</TH>
10104 <TD>The PPD file</TD>
10108 <TD>The name of the page size</TD>
10114 <P>A pointer to the page size record of the specified page size in
10115 points or NULL if the page size does not exist.
10117 <H3>Description</H3>
10119 <P>The <CODE>ppdPageSize()</CODE> function returns the page size record for the
10120 specified page size.
10125 #include <cups/ppd.h>
10130 size = ppdPageSize(ppd, "Letter");
10133 printf(" Width = %.0f\n", size->width);
10134 printf("Length = %.0f\n", size->length);
10135 printf(" Left = %.0f\n", size->left);
10136 printf(" Right = %.0f\n", size->right);
10137 printf("Bottom = %.0f\n", size->bottom);
10138 printf(" Top = %.0f\n", size->top);
10144 <A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
10145 <A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
10148 <!-- NEW PAGE --><H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2>
10154 ppdPageWidth(ppd_file_t *ppd,
10160 <CENTER><TABLE WIDTH="80%" BORDER>
10163 <TH>Description</TH>
10167 <TD>The PPD file</TD>
10171 <TD>The name of the page size</TD>
10177 <P>The width of the specified page size in points or 0 if the page size
10180 <H3>Description</H3>
10182 <P>The <CODE>ppdPageWidth()</CODE> function returns the page width of the
10183 specified page size.
10188 #include <cups/ppd.h>
10192 printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));
10197 <A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
10198 <A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>