]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/spm.shtml
projects / thirdparty / cups.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Copyright update...
[thirdparty/cups.git] / doc / spm.shtml
CommitLineData
902da432 1<HTML>
2<HEAD>
efb2f309 3 <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2002, All Rights Reserved">
2ac04bfa 4 <META NAME="DOCNUMBER" CONTENT="CUPS-SPM-1.1.13">
902da432 5 <META NAME="Author" CONTENT="Easy Software Products">
7bfde0bb 6 <TITLE>CUPS Software Programmers Manual</TITLE>
902da432 7</HEAD>
8<BODY>
9
10<H1 ALIGN="RIGHT">Preface</H1>
11
646faf5a 12<P>This software programmers manual provides software
13programming information for the Common UNIX Printing System
2ac04bfa 14("CUPS") Version 1.1.13.
902da432 15
1aee2644 16<EMBED SRC="system-overview.shtml">
902da432 17
7bfde0bb 18<!-- NEED 2in -->
902da432 19<H2>Document Overview</H2>
20
7bfde0bb 21<P>This software programmers manual is organized into the following sections:
902da432 22
23<UL>
7bfde0bb 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>
902da432 33</UL>
34
7bfde0bb 35<H2>Notation Conventions</H2>
36
37<P>Various font and syntax conventions are used in this guide. Examples and
38their meanings and uses are explained below:
39
40<CENTER><TABLE WIDTH="80%">
41<TR>
42 <TH>Example</TH>
43 <TD>&nbsp;&nbsp;&nbsp;</TD>
44 <TH>Description</TH>
45</TR>
46<TR><TD>&nbsp;</TD></TR>
47<TR VALIGN="TOP">
48 <TD><CODE>lpstat</CODE><BR>
49 <CODE>lpstat(1)</CODE></TD>
50
51 <TD>&nbsp;&nbsp;&nbsp;</TD>
52
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
55 number.</TD>
56</TR>
57<TR><TD>&nbsp;</TD></TR>
58<TR VALIGN="TOP">
59 <TD><VAR>/var</VAR><BR>
60 <VAR>/usr/share/cups/data/testprint.ps</VAR></TD>
61
62 <TD>&nbsp;&nbsp;&nbsp;</TD>
63
64 <TD>File and directory names.</TD>
65</TR>
66<TR><TD>&nbsp;</TD></TR>
67<TR VALIGN="TOP">
68 <TD NOWRAP><TT>Request ID is Printer-123</TT></TD>
69
70 <TD>&nbsp;&nbsp;&nbsp;</TD>
71
72 <TD>Screen output.</TD>
73</TR>
74<TR><TD>&nbsp;</TD></TR>
75<TR VALIGN="TOP">
76 <TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD>
77
78 <TD>&nbsp;&nbsp;&nbsp;</TD>
79
80 <TD>Literal user input; special keys like <KBD>ENTER</B></KBD> are
81 in ALL CAPS.</TD>
82</TR>
83<TR><TD>&nbsp;</TD></TR>
84<TR VALIGN="TOP">
85 <TD>12.3</TD>
86
87 <TD>&nbsp;&nbsp;&nbsp;</TD>
88
89 <TD>Numbers in the text are written using the period (.) to indicate
90 the decimal point.</TD>
91</TR>
92</TABLE></CENTER>
93
94<!-- NEED 3in -->
95<H2>Abbreviations</H2>
96
97The following abbreviations are used throughout this manual:
98
99<UL>
100<DL>
101
102 <DT>kb
103 <DD>Kilobytes, or 1024 bytes<BR>&nbsp;
104
105 <DT>Mb
106 <DD>Megabytes, or 1048576 bytes<BR>&nbsp;
107
108 <DT>Gb
109 <DD>Gigabytes, or 1073741824 bytes<BR>&nbsp;
110
111</DL>
112</UL>
113
114<H2>Other References</H2>
115
116<UL>
117<DL>
118
119 <DT>CUPS Software Administrators Manual
120
121 <DD>An administration guide for the CUPS software.<BR>&nbsp;
122
123 <DT>CUPS Software Users Manual
124
125 <DD>An end-user guide for using the CUPS software.<BR>&nbsp;
126
127</DL>
128</UL>
129
130
131<EMBED SRC="printing-overview.shtml">
132
133
134<H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1>
902da432 135
136<P>This chapter describes the CUPS Application Programmers Interface ("API").
137
7bfde0bb 138<H2>The CUPS API Library</H2>
902da432 139
7bfde0bb 140<P>The CUPS library provides a whole collection of interfaces needed to
141support the internal needs of the CUPS software as well as the needs of
142applications, filters, printer drivers, and backends.
902da432 143
7bfde0bb 144<P>Unlike the rest of CUPS, the CUPS API library is provided under the
145GNU Library General Public License. This means that you can use the
146CUPS API library in both proprietary and open-source programs.
902da432 147
7bfde0bb 148<P>Programs that use the CUPS API library typically will include the
149<CODE>&lt;cups/cups.h&gt;</CODE> header file:
150
151<UL><PRE>
152#include &lt;cups/cups.h&gt;
153
154...
155
156jobid = cupsPrintFile("myprinter", "filename.ps", "title",
157 num_options, options);
158</PRE></UL>
159
160<P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS API
161library:
162
163<UL><PRE>
164<B>cc -o program program.c -lcups ENTER</B>
165</PRE></UL>
166
167<P>Additional options and libraries may be required depending on the
168operating system and the location of the CUPS API library.
169
170<H3>Detecting the CUPS API Library in GNU Autoconf</H3>
171
172<P>GNU autoconf is a popular configuration tool used by many programs.
173Add the following lines to your <VAR>configure.in</CODE> file to check
174for the CUPS API library in your configuration script:
175
176<UL><PRE>
177AC_CHECK_LIB(socket,socket,
178if test "$uname" != "IRIX"; then
179 LIBS="-lsocket $LIBS"
180else
181 echo "Not using -lsocket since you are running IRIX."
182fi)
183AC_CHECK_LIB(nsl,gethostbyaddr,
184if test "$uname" != "IRIX"; then
185 LIBS="-lnsl $LIBS"
186else
187 echo "Not using -lnsl since you are running IRIX."
188fi)
189
190AC_CHECK_LIB(cups,httpConnect)
191</PRE></UL>
192
193<H2>Printing Services</H2>
194
195<P>The CUPS API library provides some basic printing services for applications
196that need to print files.
902da432 197
198<H3>Include Files</H3>
199
7bfde0bb 200<P>The include file used by all of these functions is
201<CODE>&lt;cups/cups.h&gt;</CODE>:
202
203<UL><PRE>
204#include &lt;cups/cups.h&gt;
205</PRE></UL>
902da432 206
7bfde0bb 207<H3>Printing a File</H3>
902da432 208
7bfde0bb 209<P>The CUPS API provides two functions for printing files. The first is
210<CODE>cupsPrintFile</CODE> which prints a single named file:
211
212<UL><PRE>
213#include &lt;cups/cups.h&gt;
214
215...
216
217int jobid;
218
219...
220
221jobid = cupsPrintFile("<I>name</I>", "<I>filename</I>", "<I>title</I>", 0, NULL);
222</PRE></UL>
223
224<P>The <CODE>name</CODE> string is the name of the printer or class to
225print to. The <CODE>filename</CODE> string is the name of the file to
226print. The <CODE>title</CODE> string is the name of the print job, e.g.
227"Acme Word Document".
228
229<P>The return value is a unique ID number for the print job or 0 if there
230was an error.
231
232<H3>Printing Multiple Files</H3>
233
234<P>The second printing function is <CODE>cupsPrintFiles</CODE>:
235
236<UL><PRE>
237#include &lt;cups/cups.h&gt;
238
239...
240
241int jobid;
242int num_files;
243const char *files[100];
244...
245
246jobid = cupsPrintFiles("name", <I>num_files</I>, <I>files</I>, "title", 0, NULL);
247</PRE></UL>
248
249<P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE>,
250you pass a file count (<CODE>num_files</CODE>) and filename pointer array
251(<CODE>files</CODE>) for each file that you want to print.
252
253<P>As with <CODE>cupsPrintFile()</CODE>, the return value is a unique ID for
254the print job.
902da432 255
256<H3>Cancelling Jobs</H3>
257
7bfde0bb 258<P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:
902da432 259
7bfde0bb 260<UL><PRE>
261#include &lt;cups/cups.h&gt;
902da432 262
7bfde0bb 263...
902da432 264
7bfde0bb 265int jobid;
266int status;
267...
902da432 268
7bfde0bb 269status = cupsCancelJob("<I>name</I>", <I>jobid</I>);
270</PRE></UL>
902da432 271
7bfde0bb 272<P>The <CODE>name</CODE> string specifies the destination and is used
273to determine the server to send the request to. The <CODE>jobid</CODE>
274value is the integer returned from a previous <CODE>cupsPrintFile()</CODE>
275or <CODE>cupsPrintFiles()</CODE> call.
902da432 276
7bfde0bb 277<P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
278successfully cancelled and <CODE>0</CODE> if there was an error.
902da432 279
7bfde0bb 280<H3>Getting the Available Printers and Classes</H3>
902da432 281
7bfde0bb 282<P>The <CODE>cupsGetDests()</CODE> function can be used to get a list
283of the available printers, classes, and instances that a user has defined:
902da432 284
7bfde0bb 285<UL><PRE>
286#include &lt;cups/cups.h&gt;
902da432 287
7bfde0bb 288...
902da432 289
7bfde0bb 290int num_dests;
291cups_dest_t *dests;
902da432 292
7bfde0bb 293...
902da432 294
7bfde0bb 295num_dests = cupsGetDests(&amp;dests);
296</PRE></UL>
902da432 297
7bfde0bb 298<P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure which
299defines the printer or class name, the instance name (if any), if it is the
300default destination, and the default options the user has defined for the
301destination:
902da432 302
7bfde0bb 303<UL><PRE>
304typedef struct /**** Destination ****/
305{
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 */
311} cups_dest_t;
312</PRE></UL>
313
314<P>The destinations are sorted by name and instance for your convenience.
315Once you have the list of available destinations, you can lookup a specific
316destination using the <CODE>cupsGetDest()</CODE> function:
317
318<UL><PRE>
319#include &lt;cups/cups.h&gt;
902da432 320
7bfde0bb 321...
902da432 322
7bfde0bb 323int num_dests;
324cups_dest_t *dests;
325cups_dest_t *mydest;
902da432 326
7bfde0bb 327...
902da432 328
7bfde0bb 329mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests);
330</PRE></UL>
902da432 331
7bfde0bb 332<P>The <CODE>name</CODE> string is the printer or class name. You can pass
333a value of <CODE>NULL</CODE> to get the default destination.
902da432 334
7bfde0bb 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
337"name/instance".
902da432 338
7bfde0bb 339<H3>Printing with Options</H3>
902da432 340
7bfde0bb 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>
343and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments are the
344number of options and a pointer to the option array:
345
346<UL><PRE>
347int cupsPrintFile(const char *name, const char *filename, const char *title,
348 int num_options, cups_option_t *options);
349int cupsPrintFiles(const char *name, int num_files, const char **files,
350 const char *title, int num_options,
351 cups_option_t *options);
352</UL></PRE>
353
354<P>The <CODE>cups_option_t</CODE> structure holds each option and its value.
355These are converted as needed and passed to the CUPS server when printing a
356file.
357
358<P>The simplest way of handling options is to use the <CODE>num_options</CODE>
359and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE>
360structure described earlier:
361
362<UL><PRE>
363#include &lt;cups/cups.h&gt;
364
365...
366
367int jobid;
368int num_dests;
369cups_dest_t *dests;
370cups_dest_t *mydest;
371
372...
373
374mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests);
375
376jobid = cupsPrintFile(mydest-&gt;name, "filename", "title",
377 mydest-&gt;num_options, mydest-&gt;options);
378</PRE></UL>
379
380<P>This effectively uses the options a user has previous selected without a
381lot of code.
382
383<H3>Setting Printer Options</H3>
384
385<P>Options can also be set by your program using the <CODE>cupsAddOption()</CODE>
386function:
387
388<UL><PRE>
389#include &lt;cups/cups.h&gt;
390
391...
392
393int num_options;
394cups_option_t *options;
395
396...
397
398num_options = 0;
399options = NULL;
400
401...
402
403num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &amp;options);
404num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &amp;options);
405num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &amp;options);
406num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &amp;options);
407</PRE></UL>
408
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.
411
412<P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of
413options. Since adding two options with the same name overwrites the
414first value with the second, do not assume that calling
415<CODE>cupsAddOptions()</CODE> 20 times will result in 20 options.
416
417<P>Call <CODE>cupsFreeOptions</CODE> once you are done using the options:
418
419<UL><PRE>
420#include &lt;cups/cups.h&gt;
421
422...
902da432 423
7bfde0bb 424int num_options;
425cups_option_t *options;
426
427...
428
429cupsFreeOptions(num_options, options);
430</PRE></UL>
431
432<H3>Getting Errors</H3>
433
434<P>If any of the CUPS API printing functions returns an error, the reason for
435that error can be found by calling <CODE>cupsLastError()</CODE> and
436<CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE> returns the
437last IPP error code that was encountered. <CODE>cupsErrorString()</CODE>
438converts the error code to a localized message string suitable for
439presentation to the user:
440
441<UL><PRE>
442#include &lt;cups/cups.h&gt;
443
444...
902da432 445
7bfde0bb 446int jobid;
902da432 447
7bfde0bb 448...
902da432 449
7bfde0bb 450if (jobid == 0)
451 puts(cupsErrorString(cupsLastError()));
452</PRE></UL>
902da432 453
ebd737f3 454<H3>Passwords and Authentication</H3>
455
456<P>CUPS supports authentication of any request, including
457submission of print jobs. The default mechanism for getting the
458username and password is to use the login user and a password
459from the console.
460
461<P>To support other types of applications, in particular
462Graphical User Interfaces ("GUIs"), the CUPS API provides
463functions to set the default username and to register a callback
464function that returns a password string.
465
466<P>The <A HREF="cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>
467function is used to set a password callback in your program. Only one
468function can be used at any time.
469
470<P>The <A HREF="cupsSetUser"><CODE>cupsSetUser()</CODE></A> function sets
471the current username for authentication. This function can be called by
472your password callback function to change the current username as needed.
473
474<P>The following example shows a simple password callback that gets a
475username and password from the user:
476
477<UL><PRE>
478#include &lt;cups/cups.h&gt;
479
480const char *
481my_password_cb(const char *prompt)
482{
483 char user[65];
484
485
486 puts(prompt);
487
488 /* Get a username from the user */
489 printf("Username: ");
490 if (fgets(user, sizeof(user), stdin) == NULL)
491 return (NULL);
492
493 /* Strip the newline from the string and set the user */
494 user[strlen(user) - 1] = '\0';
495
496 cupsSetUser(user);
497
498 /* Use getpass() to ask for the password... */
499 return (getpass("Password: "));
500}
501
502...
503
504cupsSetPasswordCB(my_password_cb);
505</PRE></UL>
506
507<P>Similarly, a GUI interface could display the prompt string in a
508window with input fields for the username and password. The username
509should probably default to the value of
510<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> to make things easier
511on the user.
512
902da432 513<H2>PPD Services</H2>
514
7bfde0bb 515<P>CUPS includes functions to access and manipulate PostScript Printer
516Description ("PPD") files that are used with the printer drivers in CUPS.
517
518<P>Each PPD file enumerates the available features provided by a
519printer, including conflict information for specific options (e.g.
520can't duplex output on envelopes.)
521
902da432 522<H3>Include Files</H3>
523
7bfde0bb 524<P>Include the <CODE>&lt;cups/ppd.h&gt;</CODE> header file to use the PPD
525functions:
526
527<UL><PRE>
528#include &lt;cups/ppd.h&gt;
529</PRE></UL>
530
531<P>This header file is also included by the
532<CODE>&lt;cups/cups.h&gt;</CODE> header file.
533
534<H3>Getting a PPD File for a Printer</H3>
535
536<P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the
537named printer or class:
538
539<UL><PRE>
540#include &lt;cups/cups.h&gt;
541
542...
543
544const char *filename;
545
546filename = cupsGetPPD("<I>name</I>");
547</PRE></UL>
548
549<P>The <CODE>name</CODE> string is the name of the printer or class, including
550the remote server name as appropriate (e.g. "printer@server".)
551
552<P>The return value is a pointer to a filename in static storage; this value
553is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If the printer
554or class does not exist, a <CODE>NULL</CODE> pointer will be returned.
555
902da432 556<H3>Loading a PPD File</H3>
557
7bfde0bb 558<P>The <CODE>ppdOpenFile()</CODE> function "opens" a PPD file and loads it
559into memory:
560
561<UL><PRE>
562#include &lt;cups/ppd.h&gt;
563
564...
565
566ppd_file_t *ppd;
567
568ppd = ppdOpenFile("<I>filename</I>");
569</PRE></UL>
570
571<P>The <CODE>filename</CODE> string is the name of the file to load, such as
572the value returned by the <CODE>cupsGetPPD()</CODE> function.
573
574<P>The return value is a pointer to a structure describing the contents of the
575PPD file or NULL if the PPD file could not be read.
576
577<H3>Freeing PPD File Information</H3>
578
579<P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE> function
580to free all memory that has been used:
581
582<UL><PRE>
583#include &lt;cups/ppd.h&gt;
584
585...
586
587ppd_file_t *ppd;
588
589...
590
591ppdClose(ppd);
592</PRE></UL>
902da432 593
7bfde0bb 594<H3>The PPD File Structure</H3>
902da432 595
7bfde0bb 596<P>Each PPD file contains a number of capability attributes, printer options,
597and conflict definitions. The page size options also include the physical
598margins for the printer and the minimum and maximum sizes for the printer.
599All of this information is stored in the <CODE>ppd_file_t</CODE> structure.
600
601<H4>Capabilities</H4>
602
603<P>Each PPD file contains a number of informational attributes that
604describe the capabilities of the printer. These are provided in the
605<CODE>ppd_file_t</CODE> structure in the following members:
606
607<CENTER><TABLE WIDTH="80%" BORDER="1">
608<TR>
609 <TH>Member</TH>
610 <TH>Type</TH>
611 <TH>Description</TH>
612</TR>
613<TR>
614 <TD><CODE>accurate_screens</CODE></TD>
615 <TD><CODE>int</CODE></TD>
616 <TD>1 = supports accurate screens</TD>
617</TR>
618<TR>
619 <TD><CODE>color_device</CODE></TD>
620 <TD><CODE>int</CODE></TD>
621 <TD>1 = color device</TD>
622</TR>
623<TR>
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>
628</TR>
629<TR>
630 <TD><CODE>contone_only</CODE></TD>
631 <TD><CODE>int</CODE></TD>
632 <TD>1 = printer is continuous tone only</TD>
633</TR>
634<TR>
635 <TD><CODE>num_emulations<BR>
636 emulations</CODE></TD>
637 <TD><CODE>int<BR>
638 ppd_emul_t *</CODE></TD>
639 <TD>Emulations supported by the printer</TD>
640</TR>
641<TR>
642 <TD><CODE>flip_duplex</CODE></TD>
643 <TD><CODE>int</CODE></TD>
644 <TD>1 = need to flip odd pages when duplexing</TD>
645</TR>
646<TR>
647 <TD><CODE>num_fonts<BR>
648 fonts</CODE></TD>
649 <TD><CODE>int<BR>
650 char **</CODE></TD>
651 <TD>The fonts available on the printer.</TD>
652</TR>
653<TR>
654 <TD><CODE>jcl_begin<BR>
655 jcl_ps<BR>
656 jcl_end</CODE></TD>
657 <TD><CODE>char *</CODE></TD>
658 <TD>Job Control Language commands for PostScript output</TD>
659</TR>
660<TR>
661 <TD><CODE>landscape</CODE></TD>
662 <TD><CODE>int</CODE></TD>
663 <TD>Landscape orientation, -90 or 90 degrees</TD>
664</TR>
665<TR>
666 <TD><CODE>lang_encoding</CODE></TD>
667 <TD><CODE>char *</CODE></TD>
668 <TD>The character used for the option strings</TD>
669</TR>
670<TR>
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>
674</TR>
675<TR>
676 <TD><CODE>language_level</CODE></TD>
677 <TD><CODE>int</CODE></TD>
678 <TD>PostScript language level, 1 to 3</TD>
679</TR>
680<TR>
681 <TD><CODE>manual_copies</CODE></TD>
682 <TD><CODE>int</CODE></TD>
683 <TD>1 = Copies are done manually</TD>
684</TR>
685<TR>
686 <TD><CODE>model_number</CODE></TD>
687 <TD><CODE>int</CODE></TD>
688 <TD>Driver-specific model number.</TD>
689</TR>
690<TR>
691 <TD><CODE>patches</CODE></TD>
692 <TD><CODE>char *</CODE></TD>
693 <TD>Patch commands to send to the printer</TD>
694</TR>
695<TR>
696 <TD><CODE>manufacturer</CODE></TD>
697 <TD><CODE>char *</CODE></TD>
698 <TD>The Manufacturer attribute from the PPD file, if any</TD>
699</TR>
700<TR>
701 <TD><CODE>modelname</CODE></TD>
702 <TD><CODE>char *</CODE></TD>
703 <TD>The ModelName attribute from the PPD file</TD>
704</TR>
705<TR>
706 <TD><CODE>nickname</CODE></TD>
707 <TD><CODE>char *</CODE></TD>
708 <TD>The NickName attribute from the PPD file, if any</TD>
709</TR>
710<TR>
711 <TD><CODE>product</CODE></TD>
712 <TD><CODE>char *</CODE></TD>
713 <TD>The Product attribute from the PPD file, if any</TD>
714</TR>
715<TR>
716 <TD><CODE>shortnickname</CODE></TD>
717 <TD><CODE>char *</CODE></TD>
718 <TD>The ShortNickName attribute from the PPD file, if any</TD>
719</TR>
720<TR>
721 <TD><CODE>throughput</CODE></TD>
722 <TD><CODE>int</CODE></TD>
723 <TD>Number of pages per minute</TD>
724</TR>
725<TR>
726 <TD><CODE>ttrasterizer</CODE></TD>
727 <TD><CODE>char *</CODE></TD>
728 <TD>The TruType font rasterizer (Type42)</TD>
729</TR>
730<TR>
731 <TD><CODE>variable_sizes</CODE></TD>
732 <TD><CODE>int</CODE></TD>
733 <TD>1 = supports variable sizes</TD>
734</TR>
735</TABLE></CENTER>
736
737<H4>Options and Groups</H4>
738
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
741the PPD functions.
742
743<P>Each option in turn is associated with a group
744stored in the <CODE>ppd_group_t</CODE> structure. Groups can be
745specified in the PPD file; if an option is not associated with a group
746then it is put in a "General" or "Extra" group depending on the option.
747
748<P>Groups can also have sub-groups; CUPS currently limits the depth of
749sub-groups to 1 level to reduce programming complexity.
750
751<H4>Conflicts</H4>
752
753<P>PPD files support specification of conflict conditions between
754different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE>
755structures which specify the options that conflict with each other.
756
757<H4>Page Sizes</H4>
758
759<P>PPD files specify all of the available pages sizes and the physical
760margins 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
764with the <CODE>ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and
765<CODE>ppdPageSize()</CODE> functions:
766
767<UL><PRE>
768#include &lt;cups/ppd.h&gt;
769
770...
771
772ppd_file_t *ppd;
773ppd_size_t *size;
774float width;
775float length;
776
777...
778
779size = ppdPageSize(ppd, "<I>size</I>");
780width = ppdPageWidth(ppd, "<I>size</I>");
781length = ppdPageLength(ppd, "<I>size</I>");
782</PRE></UL>
783
784<P>The <CODE>size</CODE> string is the named page size option. The
785width and length are in points; there are 72 points per inch. The
786<CODE>ppd_size_t</CODE> structure contains the width, length, and
787margin information:
788
789<UL><PRE>
790typedef struct /**** Page Sizes ****/
791{
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 */
800} ppd_size_t;
801</PRE></UL>
802
803<H4>Custom Page Sizes</H4>
804
805<P>Besides the standard page sizes listed in a PPD file, some printers
806support variable or custom page sizes. If <CODE>variables_sizes</CODE>
807is 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>
809structure define the limits of the variable sizes.
810
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>
813and <CODE>length</CODE> are integer values in points:
814
815<UL><PRE>
816Custom.612x792 [8.5 inches wide, 11 inches long]
817Custom.1224x792 [17 inches wide, 11 inches long]
818</PRE></UL>
902da432 819
820<H3>Marking Options</H3>
821
7bfde0bb 822<P>Before marking any user-defined options, call the <CODE>ppdMarkDefaults()</CODE>
823function to mark the default options from the PPD file:
824
825<UL><PRE>
826#include &lt;cups/ppd.h&gt;
827
828...
829
830ppd_file_t *ppd;
831
832...
833
834ppdMarkDefaults(ppd);
835</PRE></UL>
836
837<P>Then call the <CODE>ppdMarkOption()</CODE> function to mark individual
838options:
839
840<UL><PRE>
841#include &lt;cups/ppd.h&gt;
842
843...
844
845ppd_file_t *ppd;
846int conflicts;
847
848...
849
850conflicts = ppdMarkOption(ppd, "<I>name</I>", "<I>value</I>");
851</PRE></UL>
852
853<P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a
854particular option and choice, respectively. The return value is 0
855if there are not conflicts created by the selection.
856
857<P>CUPS also provides a convenience function for marking all options
858in the <CODE>cups_option_t</CODE> structure:
859
860<UL><PRE>
861#include &lt;cups/cups.h&gt;
862
863...
864
865ppd_file_t *ppd;
866int num_options;
867cups_option_t *options;
868int conflicts;
869
870...
871
872conflicts = cupsMarkOptions(ppd, num_options, options);
873</PRE></UL>
874
875<P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the
876IPP job template attributes to PPD options. The return value is the number
877of conflicts present.
878
902da432 879<H3>Checking for Conflicts</H3>
880
7bfde0bb 881<P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE>
882functions return the number of conflicts with the currently marked options.
883
884<P>Call the <CODE>ppdConflicts()</CODE> function to get the number of
885conflicts after you have marked all of the options:
886
887<UL><PRE>
888#include &lt;cups/cups.h&gt;
889
890...
891
892ppd_file_t *ppd;
893int conflicts;
894
895...
896
897conflicts = ppdConflicts(ppd);
898</PRE></UL>
902da432 899
7bfde0bb 900<P>The return value is the number of conflicting options, or 0 if there
901are no conflicts.
902da432 902
7bfde0bb 903
904<H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
902da432 905
906<P>This chapter describes how to write a file filter for CUPS.
907
908<H2>Overview</H2>
909
4ce43341 910<P>File filters are programs that convert from one or more MIME types to
911another type. Filters use a common command-line and environment interface
912that allows them to be joined as needed to print files to any type of
913printer.
914
902da432 915<H3>Security Considerations</H3>
916
4ce43341 917<P>Filters are normally run as a non-priviledged user, so the major
918security consideration is resource utilization - filters should not
919depend on unlimited amounts of memory and disk space.
920
7bfde0bb 921<H3>Users and Groups</H3>
902da432 922
4ce43341 923<P>The default CUPS configuration runs filters as user "lp" and group "other".
924
902da432 925<H3>Temporary Files</H3>
926
4ce43341 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
930used to safely choose temporary files in this directory.
931
932<H3>Sending Messages to the User</H3>
933
934<P>The CUPS scheduler collects messages sent to the standard error file
935by the filter. These messages are relayed to the user based upon the
936scheduler <CODE>LogLevel</CODE> directive.
937
938<P>The type of message is determined by an initial prefix sent on each
939line:
940
941<UL>
942
943 <LI><CODE>DEBUG:</CODE> - a debug message
944
945 <LI><CODE>INFO:</CODE> - an informational message
946
947 <LI><CODE>WARNING:</CODE> - a warning message
948
949 <LI><CODE>ERROR:</CODE> - an error message
950
951 <LI><CODE>PAGE:</CODE> - a page accounting message
952
953</UL>
954
955<P>If the line of text does not begin with any of the above prefixes, it
956is 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
958added to the <VAR>error_log</VAR> unless it is an informational or page
959accounting message.
960
902da432 961<H3>Page Accounting</H3>
962
4ce43341 963<P>Page accounting messages are used to inform the server when one or more
964pages are printed. Each line has the form:
965
966<UL><PRE>
967PAGE: page-number copy-count
968</PRE></UL>
969
970<P>The <I>page-number</I> field is the current page number, starting at 1.
971The <I>copy-count</I> field specifies the number of copies of that page
972that was produced.
973
974<P>Page account messages are added to the <VAR>page_log</VAR> file and
975cause the <CODE>job-sheets-completed</CODE> attribute to be updated for
976the job.
977
978<H3>Command-Line Arguments</H3>
979
980<P>Every filter accepts exactly 6 or 7 command-line arguments:
981
982<UL><PRE>
983printer job user title copies options [filename]
984</PRE>
902da432 985
4ce43341 986 <LI><CODE>printer</CODE> - The name of the printer queue (normally
987 this is the name of the program being run)
988
989 <LI><CODE>job</CODE> - The numeric job ID for the job being
990 printed
991
992 <LI><CODE>user</CODE> - The string from the
993 <CODE>originating-user-name</CODE> attribute
994
995 <LI><CODE>title</CODE> - The string from the
996 <CODE>job-name</CODE> attribute
997
998 <LI><CODE>copies</CODE> - The numeric value from the
999 <CODE>number-copies</CODE> attribute
1000
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
1006 set attributes
1007
1008 <LI><CODE>filename</CODE> - The request file
1009
1010</UL>
1011
1012<P>The <I>filename</I> argument is only provided to the first filter in the
1013chain; all filters <B>must</B> be prepared to read the print file from
1014the standard input if the <I>filename</I> argument is omitted.
902da432 1015
1016<H3>Copy Generation</H3>
1017
4ce43341 1018<P>The <I>copies</I> argument specifies the number of copies to produce
1019of 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
1021filters that produce device-independent PostScript output (without any
1022printer commands from the printer's PPD file), since the PostScript
1023filter <CODE>pstops</CODE> is responsible for copy generation.
1024
1025<H3>Environment Variables</H3>
1026
1027<P>Every filter receives a fixed set of environment variables that can
1028be used by the filter:
1029
1030<UL>
1031
1032 <LI><CODE>CHARSET</CODE> - The character set used by the client for
1033 this print file
1034
1035 <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as
1036 "application/postscript"
1037
1038 <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files
1039
1040 <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration
1041 files
1042
1043 <LI><CODE>DEVICE_URI</CODE> - The output device URI
1044
1045 <LI><CODE>LANG</CODE> - The language used by the client for
1046 this print file
1047
1048 <LI><CODE>PATH</CODE> - The execution path exported to the filter
1049
1050 <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file
1051
1052 <LI><CODE>PRINTER</CODE> - The name of the printer queue
1053
1054 <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter
1055 should use
1056
1057 <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically
1058 "CUPS/1.1"
1059
1060 <LI><CODE>TZ</CODE> - The local timezone
902da432 1061
4ce43341 1062 <LI><CODE>USER</CODE> - The name of the current user
902da432 1063
4ce43341 1064</UL>
1065
70bb1290 1066<H2>Dissecting the HP-GL/2 Filter</H2>
4ce43341 1067
1068<P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a
1069complex program that converts HP-GL/2 files into device-independent PostScript
1070output. Since it produces device-independent PostScript output, it does not
1071need to handle copy generation or writing printer options from the printer's
1072PPD file.
1073
1074<H3>Initializing the Filter</H3>
1075
1076<P>The first task of any filter is to ensure that the correct number of
1077command-line arguments are present:
1078
1079<UL><PRE>
1080if (argc &lt; 6 || argc > 7)
1081{
1082 fputs("ERROR: hpgltops job-id user title copies options [file]\n", stderr);
1083 return (1);
1084}
1085</PRE></UL>
1086
1087<P>After this you open the print file or read from the standard input
1088as needed:
1089
1090<UL><PRE>
1091FILE *fp;
1092
1093/*
1094 * If we have 7 arguments, print the file named on the command-line.
1095 * Otherwise, send stdin instead...
1096 */
902da432 1097
4ce43341 1098if (argc == 6)
1099 fp = stdin;
1100else
1101{
1102 /*
1103 * Try to open the print file...
1104 */
1105
1106 if ((fp = fopen(argv[6], "rb")) == NULL)
1107 {
1108 perror("ERROR: unable to open print file - ");
1109 return (1);
1110 }
1111}
1112</PRE></UL>
1113
1114<P>Once the print file has been opened, options can be processed using
1115the <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A> and
1116<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A> functions:
902da432 1117
4ce43341 1118<UL><PRE>
1119int num_options;
1120cups_option_t *options;
1121const char *val;
1122
1123/*
1124 * Process command-line options and write the prolog...
1125 */
1126
1127options = NULL;
1128num_options = cupsParseOptions(argv[5], 0, &options);
1129
1130if ((val = cupsGetOption("blackplot", num_options, options)) != NULL)
1131 shading = 0;
1132
1133if ((val = cupsGetOption("fitplot", num_options, options)) != NULL)
1134 FitPlot = 1;
1135
1136if ((val = cupsGetOption("penwidth", num_options, options)) != NULL)
1137 PenWidth = (float)atoi(val) * 0.001f;
1138</PRE></UL>
1139
1140<P>After the options have been processed, the filter writes PostScript code
1141to the standard output based on the print file, closes the print file (as
1142needed), and returns 0 to the scheduler.
1143
1144<H2>PostScript Output</H2>
1145
1146<P>Filters that produce PostScript output must generate output conforming
1147to the Adobe Document Structuring Conventions, 3.0. In general this means
1148the beginning of each file must begin with:
1149
1150<UL><PRE>
1151%!PS-Adobe-3.0
1152%%BoundingBox: left bottom right top
1153%%Pages: (atend)
1154%%EndComments
1155</PRE></UL>
1156
1157<P>The <I>left</I>, <I>bottom</I>, <I>right</I>, and <I>top</I> values
1158are integers in points from the lower-lefthand corner of the page.
1159
1160<P>Pages must be surrounded by:
1161
1162<UL><PRE>
1163%%Page: number number
1164gsave
1165...
1166grestore
1167showpage
1168</PRE></UL>
1169
1170<P>And the end of each file must contain:
1171
1172<UL><PRE>
1173%%Trailer
1174%%Pages: number-pages
1175%%EOF
1176</PRE></UL>
1177
1178<P>These comments allow the PostScript filter to correctly perform page
1179accounting, copy generation, N-up printing, and so forth.
902da432 1180
20e87460 1181<H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A></H1>
902da432 1182
1183<P>This chapter discusses how to write a printer driver, which is a
1184special filter program that converts CUPS raster data into the
1185appropriate commands and data required for a printer.
1186
1187<H2>Overview</H2>
1188
4ce43341 1189<P>Raster printers utilitize PPD files that specify one or more
1190device-specific filters that handle converting print files for the
1191printer. The simplest raster printer drivers provide a single filter
1192that converts CUPS raster data to the printer's native format.
1193
1194<H3>CUPS Raster Data</H3>
1195
1196<P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists of
1197a stream of raster page descriptions produced by one of the RIP filters,
1198such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.
1199
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
1202structure contains the colorspace, bits per color, media size, media type,
1203hardware resolution, and so forth.
1204
1205<P>After the page dictionary comes the page data which is a full-resolution,
1206uncompressed bitmap representing the page in the printer's output colorspace.
1207
902da432 1208<H3>Page Accounting</H3>
1209
4ce43341 1210<P>Printer drivers must handle all page accounting. This means they must
1211send "PAGE:" messages to the standard error file for each page (and in many
1212cases, copy) sent to the printer.
1213
902da432 1214<H3>Color Management</H3>
1215
4ce43341 1216<P>Printer drivers can implement their color management via the
1217<CODE>cupsColorProfile</CODE> attributes in the PPD file or internally
1218in the driver from a device-independent colorspace. In general, color
1219management performed by the RIP filters is more efficient than that
1220performed inside printer drivers.
1221
1222<P>For example, the <CODE>pstoraster</CODE> filter often only has to
1223perform a color conversion once each time the color is used for
1224multiple output pixels, while the raster filter must convert every
1225pixel on the page.
902da432 1226
70bb1290 1227<H3>Device and Bitmap Variables</H3>
902da432 1228
70bb1290 1229<P>Besides the standard PostScript page device dictionary variables defined
1230in the Adobe PostScript Level 3 reference manual, the CUPS filters support
1231additional variables that are passed in the page device dictionary header for
1232the page and in some cases control the type of raster data that is generated:
902da432 1233
70bb1290 1234<CENTER><TABLE WIDTH="90%" BORDER="1">
1235<TR>
1236 <TH>Variable</TH>
1237 <TH>Type</TH>
1238 <TH>Description</TH>
1239</TR>
1240<TR>
1241 <TD>cupsWidth</TD>
1242 <TD>read-only integer</TD>
1243 <TD>Width of bitmap in pixels</TD>
1244</TR>
1245<TR>
1246 <TD>cupsHeight</TD>
1247 <TD>read-only integer </TD>
1248 <TD>Height of bitmap in pixels</TD>
1249</TR>
1250<TR>
1251 <TD>cupsMediaType</TD>
1252 <TD>read-write integer</TD>
1253 <TD>Device-specific media type code</TD>
1254</TR>
1255<TR>
1256 <TD>cupsBitsPerColor</TD>
1257 <TD>read-write integer</TD>
1258 <TD>Number of bits per color; 1, 2, 4, and 8 are currently
1259 supported</TD>
1260</TR>
1261<TR>
1262 <TD>cupsBitsPerPixel</TD>
1263 <TD>read-only integer </TD>
1264 <TD>Number of bits per pixel; 1 to 32</TD>
1265</TR>
1266<TR>
1267 <TD>cupsBytesPerLine</TD>
1268 <TD>read-only integer</TD>
1269 <TD>Number of bytes per line of raster graphics</TD>
1270</TR>
1271<TR>
1272 <TD>cupsColorOrder</TD>
1273 <TD>read-write enum</TD>
1274 <TD>The order of color values in the bitmap:
1275 <UL>
1276 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK
1277 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK
1278 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...
1279 </UL>
1280 </TD>
1281</TR>
1282<TR>
1283 <TD>cupsColorSpace</TD>
1284 <TD>read-write enum</TD>
1285 <TD>The colorspace of the bitmap:
1286 <UL>
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)
1305 </UL>
1306 </TD>
1307</TR>
1308<TR>
1309 <TD>cupsCompression</TD>
1310 <TD>read-write integer</TD>
1311 <TD>Device-specific compression type code</TD>
1312</TR>
1313<TR>
1314 <TD>cupsRowCount</TD>
1315 <TD>read-write integer</TD>
1316 <TD>Device-specific row count value</TD>
1317</TR>
1318<TR>
1319 <TD>cupsRowFeed</TD>
1320 <TD>read-write integer</TD>
1321 <TD>Device-specific row feed value</TD>
1322</TR>
1323<TR>
1324 <TD>cupsRowStep</TD>
1325 <TD>read-write integer</TD>
1326 <TD>Device-specific row step value</TD>
1327</TR>
1328</TABLE></CENTER>
1329
1330<P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit per
1331color are transmitted to the raster driver in KCMY colorspace; the driver
1332is responsible for producing the correct separation of normal and light
1333cyan and magenta inks.
1334
1335<H2>Dissecting the HP-PCL Driver</H2>
1336
1337<P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>) converts
1338bitmap data from the raster filters into HP-PCL commands for most
1339PCL-compatible printers. The actual format of the raster data is controlled
1340by the PPD file being used - <VAR>deskjet.ppd</VAR> or <VAR>laserjet.ppd</VAR>.
1341
1342<H3>PPD Files</H3>
1343
1344<P>PPD files play an important part of all raster printer drivers. Options
1345defined in the PPD file contain PostScript commands that control the raster
1346data that is sent to the printer driver.
1347
1348<P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>,
1349<CODE>InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>,
1350and <CODE>Resolution</CODE> options. Each option is shown using the
1351standard PPD format:
1352
1353<UL><PRE>
1354*OpenUI *PageSize/Media Size: PickOne
1355*OrderDependency: 10 AnySetup *PageSize
1356*DefaultPageSize: Letter
1357*PageSize Letter/US Letter: "&lt;&lt;
1358/PageSize [612 792]
1359/ImagingBBox null
1360>> setpagedevice"
1361*End
1362*PageSize Legal/US Legal: "&lt;&lt;
1363/PageSize [612 1008]
1364/ImagingBBox null
1365>> setpagedevice"
1366*End
1367*PageSize A4/A4: "&lt;&lt;
1368/PageSize [595 842]
1369/ImagingBBox null
1370>> setpagedevice"
1371*End
1372*CloseUI: *PageSize
1373</UL></PRE>
1374
1375<P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first
1376name is the option with an asterisk (*) in front of it. The first name is
1377usually followed by a slash (/) and a human-readable version of the
1378option name.
1379
1380<P>Every option <B>must</B> have a default value, specified using the
1381<CODE>Default<I>Option</I></CODE> keyword.
1382
1383<P>Each option begins with the option name followed by the computer and
1384human-readable values. The PostScript commands follow these inside double
1385quotes. PostScript commands can be provided on a single line:
1386
1387<UL><PRE>
1388*PageSize A4/A4: "&lt;&lt;/PageSize[595 842]/ImagingBBox null>> setpagedevice"
1389</PRE></UL>
1390
1391<P>or broken down on separate lines using the <CODE>End</CODE> keyword to
1392terminate them:
1393
1394<UL><PRE>
1395*PageSize A4/A4: "&lt;&lt;
1396/PageSize [595 842]
1397/ImagingBBox null
1398>> setpagedevice"
1399*End
1400</PRE></UL>
1401
1402<P>The choice of the two formats is usually esthetic. However, each line in
1403a PPD file must not exceed 255 characters, so if your PostScript commands are
1404long you may need to break them up on separate lines.
1405
1406<H3>Reading Raster Data</H3>
1407
1408<P>As with any filter, your printer driver should handle raster data from
1409a filename specified on the command-line or from the standard input. The
1410<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function opens
1411a raster stream for printing:
1412
1413<UL><PRE>
1414int fd; /* File descriptor */
1415cups_raster_t *ras; /* Raster stream for printing */
1416
1417
1418/*
1419 * Check for valid arguments...
1420 */
1421
1422if (argc &lt; 6 || argc > 7)
1423{
1424 /*
1425 * We don't have the correct number of arguments; write an error message
1426 * and return.
1427 */
1428
1429 fputs("ERROR: rastertopcl job-id user title copies options [file]\n", stderr);
1430 return (1);
1431}
1432
1433/*
1434 * Open the page stream...
1435 */
1436
1437if (argc == 7)
1438{
1439 if ((fd = open(argv[6], O_RDONLY)) == -1)
1440 {
1441 perror("ERROR: Unable to open raster file - ");
1442 sleep(1);
1443 return (1);
1444 }
1445}
1446else
1447 fd = 0;
1448
1449ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
1450</PRE></UL>
1451
1452<P>Once you have opened the raster stream you just need to read each
1453page and print it:
902da432 1454
70bb1290 1455<UL><PRE>
1456cups_raster_header_t header;
1457int y;
1458unsigned char data[8192];
902da432 1459
70bb1290 1460while (cupsRasterReadHeader(ras, &amp;header))
1461{
1462 ... initialize the printer ...
1463 for (y = header.cupsHeight; y > 0; y ++)
1464 {
1465 cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
1466 ... send raster line to printer ...
1467 }
1468}
1469</PRE></UL>
902da432 1470
70bb1290 1471<P>After you have processed all pages, close the raster stream and
1472return:
902da432 1473
70bb1290 1474<UL><PRE>
1475cupsRasterClose(ras);
902da432 1476
70bb1290 1477return (0);
1478</PRE></UL>
902da432 1479
20e87460 1480<H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
902da432 1481
1482<P>This chapter describes how to write a backend for CUPS. Backends
1483communicate directly with printers and allow printer drivers and
1484filters to send data using any type of connection transparently.
1485
1486<H2>Overview</H2>
1487
70bb1290 1488<P>Backends are special filters that communicate with printers directly.
1489They are treated slightly differently than filters, however, and have some
1490unique requirements.
1491
902da432 1492<H3>Security Considerations</H3>
1493
70bb1290 1494<P>Backends are run as the root user, so special care must be taken to
1495avoid potential security violations. In particular, remember that a backend
1496will be able to manipulate disk files, devices, and other resources that
1497potentially could damage a system or printer.
902da432 1498
70bb1290 1499<H3>Command-Line Arguments</H3>
1500
1501<P>Besides the standard filter arguments, backends are also run with no
1502arguments to get a list of available devices. This discovery process is
1503described later in this chapter.
1504
1505<H3>Copy Generation</H3>
1506
1507<P>Like filters, backends should send multiple copies of the print file only
1508if a filename is supplied on the command-line. Otherwise the backend should
1509assume that the upstream filter has already added the necessary commands or
1510data to produce the multiple copies.
902da432 1511
1512<H3>Page Accounting</H3>
1513
70bb1290 1514<P>Backend filters generally do not do page accounting, however they should
1515at a minimum produce a single page message for each copy that is produced
1516when a filename is present on the command-line. This is because the user
1517selected "raw" printing and no other accounting information is possible.
1518
1519<H3>Exclusive Access</H3>
1520
1521<P>Backends that talk to local character or block devices should open the
1522device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate with other
1523printers defined for the same device.
1524
902da432 1525<H3>Retries</H3>
1526
70bb1290 1527<P>All backends <B>must</B> retry connections to the device. This
1528includes backends that talk to local character or block devices, as the
1529user may define more than one printer queue pointing at the same
1530physical device.
902da432 1531
70bb1290 1532<P>To prevent excess CPU utilitization, the backend should go to sleep
1533for an amount of time between retries; the CUPS-supplied backends retry
1534once every 30 seconds.
902da432 1535
70bb1290 1536<H2>Dissecting the Serial Port Backend</H2>
1537
1538<P>The serial port backend provides support for serial printers. Since
1539it does everything a good backend needs to do, it provides an excellent
1540example of what to do.
1541
1542<H3>Supporting Device Discovery</H3>
1543
1544<P>As previously noted, backends are special filter programs that talk
1545to printer devices. Another task a backend must perform is to list the
1546available devices it supports. The backend lists the available devices
1547when no additioanl arguments are supplied on the command-line (i.e.
1548just the command name...)
1549
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
1552in some cases by trying to open the ports to see if they actually exist.
1553
1554<P>Once it finds a serial port it writes a single line for each port to
1555the standard error file. Each line looks like this:
1556
1557<UL><PRE>
1558serial serial:/dev/ttyS0?baud=115200 "Unknown" "Serial Port 1"
1559</PRE></UL>
1560
1561<P>The first word "serial" is the <I>device class</I>; this identifies the
1562class of device which can be used to categorize it in user interfaces. CUPS
1563currently recognizes the following classes:
1564
1565<UL>
1566
1567 <LI>"file" - a disk file.
1568
1569 <LI>"direct" - a parallel or fixed-rate serial data port,
1570 currently used for Centronics, IEEE-1284, and USB printer
1571 ports.
1572
1573 <LI>"serial" - a variable-rate serial port.
1574
1575 <LI>"network" - a network connection, typically via AppSocket,
1576 HTTP, IPP, LPD, or SMB/CIFS protocols.
1577
1578</UL>
1579
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
1582the user to select this port. For serial ports, the "baud=115200"
1583specifies the maximum baud rate supported by the port - the actual
1584value will vary based on the speed the user selects for the printer.
1585
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
1588are able to provide a make and model such as "HP DeskJet" that allows
1589users and software to choose an appropriate printer driver more easily.
1590Both the model and description must be enclosed inside double quotes.
1591
1592<H3>Opening the Serial Port</H3>
1593
1594<P>As noted previously, all backends should open device files in exclusive
1595mode, and retry as needed until the port is available. The serial port does
1596this using a <CODE>do-while</CODE> loop:
1597
1598<UL><PRE>
1599do
1600{
1601 if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
1602 {
1603 if (errno == EBUSY)
1604 {
1605 fputs("INFO: Serial port busy; will retry in 30 seconds...\n", stderr);
1606 sleep(30);
1607 }
1608 else
1609 {
1610 perror("ERROR: Unable to open serial port device file");
1611 return (1);
1612 }
1613 }
1614}
1615while (fd &lt; 0);
1616</PRE></UL>
1617
1618<P>If the port is busy or in use by another process, the backend will
1619go to sleep for 30 seconds and try again. If another error is detected
1620a message is sent to the user and the backend aborts the print job
1621until the problem can be corrected.
1622
1623<H3>Writing Data to the Port</H3>
1624
1625<P>Network and character devices pose an interesting problem when writing
1626data to the port - they may not be able to write all of the bytes in your
1627buffer before returning. To work around this problem you must loop until
1628all bytes have been written:
902da432 1629
70bb1290 1630<UL><PRE>
1631while (nbytes > 0)
1632{
1633 if ((wbytes = write(fd, bufptr, nbytes)) &lt; 0)
1634 if (errno == ENOTTY)
1635 wbytes = write(fd, bufptr, nbytes);
1636
1637 if (wbytes &lt; 0)
1638 {
1639 perror("ERROR: Unable to send print file to printer");
1640 break;
1641 }
902da432 1642
70bb1290 1643 nbytes -= wbytes;
1644 bufptr += wbytes;
1645}
1646</PRE></UL>
902da432 1647
70bb1290 1648<P>The check for the <CODE>ENOTTY</CODE> error is needed on some platforms
1649to clear an error from a previous <CODE>ioctl()</CODE> call.
902da432 1650
70bb1290 1651<H3>Finishing Up</H3>
902da432 1652
70bb1290 1653<P>Once you have sent the print file, return 0 if the file printed
1654successfully or 1 if it did not. This will allow the scheduler to stop
1655the print job if there is a device error, preserving the print job for
1656later printing once the problem has been corrected.
902da432 1657
7bfde0bb 1658<H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
1659
1660<EMBED SRC="../LICENSE.html">
1661
1662
1663<H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1>
902da432 1664
1665<P>This appendix lists all of the constants that are defined by the CUPS
1666API.
1667
1668<H2>CUPS Constants</H2>
1669
a0beb32e 1670<H3>Version Number</H3>
1671
1672<P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number
1673representing the API version number. The current version number is
16741.0100 which represents CUPS version 1.1.0.
1675
1676<H3>Printer Capabilities</H3>
1677
1678<P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for
1679printers and classes:
1680
1681<UL>
1682
1683 <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.
1684
1685 <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.
1686
1687 <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.
1688
1689 <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.
1690
1691 <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.
1692
1693 <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.
1694
1695 <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.
1696
1697 <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple
1698 copies on its own.
1699
1700 <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.
1701
1702 <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.
1703
1704 <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.
1705
1706 <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.
1707
1708 <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.
1709
1710 <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up
1711 to 9x14 inches.
1712
1713 <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media
1714 from 9x14 to 18x24 inches.
1715
1716 <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media
1717 larger than 18x24 inches.
1718
1719 <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on
1720 variable or custom media sizes.
1721
1722 <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.
1723
1724 <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability
1725 and option bits.
1726
1727</UL>
1728
1729<H3>Encodings</H3>
1730
1731<P>CUPS defines the following character set encoding constants:
1732
1733<UL>
1734
1735 <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.
1736
1737 <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.
1738
1739 <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.
1740
1741 <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.
1742
1743 <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.
1744
1745 <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.
1746
1747 <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.
1748
1749 <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.
1750
1751 <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.
1752
1753 <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.
1754
1755 <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.
1756
1757 <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.
1758
1759 <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.
1760
1761 <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.
1762
1763 <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.
1764
1765 <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.
1766
1767 <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.
1768
1769 <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.
1770
1771 <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.
1772
1773 <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.
1774
1775 <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.
1776
1777 <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.
1778
1779 <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.
1780
1781 <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.
1782
1783 <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.
1784
1785</UL>
1786
902da432 1787<H2>HTTP Constants</H2>
1788
a0beb32e 1789<H3>Limits</H3>
1790
1791<P>The following constants define the limits for strings:
1792
1793<UL>
1794
1795 <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.
1796
1797 <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.
1798
1799 <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.
1800
1801 <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.
1802
1803</UL>
1804
1805<H3>Status Codes</H3>
1806
1807<P>The following status codes can be returned by <CODE>httpUpdate()</CODE>:
1808
1809<UL>
1810
1811 <LI><CODE>HTTP_ERROR</CODE> - A network error occurred
1812
1813 <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy
1814
1815 <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was successful
1816
1817 <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful
1818
1819 <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful
1820
1821 <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't authoritative
1822
1823 <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command
1824
1825 <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated
1826
1827 <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was recieved/sent
1828
1829 <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request
1830
1831 <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently
1832
1833 <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily
1834
1835 <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...
1836
1837 <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified
1838
1839 <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI
1840
1841 <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request
1842
1843 <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host
1844
1845 <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required
1846
1847 <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI
1848
1849 <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found
1850
1851 <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed
1852
1853 <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable
1854
1855 <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is Required
1856
1857 <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out
1858
1859 <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting
1860
1861 <LI><CODE>HTTP_GONE</CODE> - Server has gone away
1862
1863 <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is required
1864
1865 <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed
1866
1867 <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large
1868
1869 <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long
1870
1871 <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type is unsupported
1872
1873 <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error
1874
1875 <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented
1876
1877 <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway
1878
1879 <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable
1880
1881 <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out
1882
1883 <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported
1884
1885</UL>
1886
1887<H3>Fields</H3>
1888
1889<P>The following fields are indices for each of the standard HTTP fields in
1890HTTP 1/1:
1891
1892<UL>
1893
1894 <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language
1895
1896 <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges
1897
1898 <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization
1899
1900 <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection
1901
1902 <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding
1903
1904 <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language
1905
1906 <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length
1907
1908 <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location
1909
1910 <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5
1911
1912 <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range
1913
1914 <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type
1915
1916 <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version
1917
1918 <LI><CODE>HTTP_FIELD_DATE</CODE> - Date
1919
1920 <LI><CODE>HTTP_FIELD_HOST</CODE> - Host
1921
1922 <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since
1923
1924 <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since
1925
1926 <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive
1927
1928 <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified
1929
1930 <LI><CODE>HTTP_FIELD_LINK</CODE> - Link
1931
1932 <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location
1933
1934 <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range
1935
1936 <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer
1937
1938 <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After
1939
1940 <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding
1941
1942 <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade
1943
1944 <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent
1945
1946 <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate
1947
1948
1949</UL>
1950
902da432 1951<H2>IPP Constants</H2>
1952
a0beb32e 1953<H3>Limits</H3>
1954
1955<P>The following constants define array limits for IPP data:
1956
1957<UL>
1958
1959 <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name
1960
1961 <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values
1962 that can be read in a request.
1963
1964</UL>
1965
1966<H3>Tags</H3>
1967
1968<UL>
1969
1970 <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
1971 used to separate groups of attributes
1972
1973 <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation
1974
1975 <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job
1976
1977 <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end
1978
1979 <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer
1980
1981 <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type unsupported_group
1982
1983 <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type unsupported_value
1984
1985 <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default
1986
1987 <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown
1988
1989 <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue
1990
1991 <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type notsettable
1992
1993 <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr
1994
1995 <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue
1996
1997 <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer
1998
1999 <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean
2000
2001 <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum
2002
2003 <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string
2004
2005 <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date
2006
2007 <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution
2008
2009 <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range
2010
2011 <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection
2012
2013 <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang
2014
2015 <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang
2016
2017 <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text
2018
2019 <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name
2020
2021 <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword
2022
2023 <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri
2024
2025 <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme
2026
2027 <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset
2028
2029 <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language
2030
2031 <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype
2032
2033</UL>
2034
2035<H3>Resolution Units</H3>
2036
2037<P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE> constants
2038specify dots per inch and dots per centimeter, respectively.
2039
2040<H3>Finishings</H3>
2041
2042<P>The finishing values specify special finishing operations to be
2043performed on the job.
2044
2045<UL>
2046
2047 <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing
2048
2049 <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job
2050
2051 <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job
2052
2053 <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job
2054
2055 <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job
2056
2057</UL>
2058
2059<H3>Orientations</H3>
2060
2061<P>The orientation values specify the orientation of the job.
2062
2063<UL>
2064
2065 <LI><CODE>IPP_PORTRAIT</CODE> - No rotation
2066
2067 <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise
2068
2069 <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise
2070
2071 <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees
2072
2073</UL>
2074
2075<H3>Qualities</H3>
2076
2077<P>The quality values specify the desired quality of the print.
2078<UL>
2079
2080 <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality
2081
2082 <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality
2083
2084 <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality
2085
2086</UL>
2087
2088<H3>Job States</H3>
2089
2090<P>The job state values are used to represent the current job state.
2091
2092<UL>
2093
2094 <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending
2095
2096 <LI><CODE>IPP_JOB_HELD</CODE> - Job is held
2097
2098 <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing
2099
2100 <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped
2101
2102 <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled
2103
2104 <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted
2105
2106 <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed
2107
2108</UL>
2109
2110<H3>Printer States</H3>
2111
2112<P>The printer state values are used to represent the current printer
2113state.
2114
2115<UL>
2116
2117 <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle
2118
2119 <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing
2120
2121 <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped
2122
2123</UL>
2124
2125<H3>Operations</H3>
2126
2127<P>The operation values represent the available IPP operations.
2128
2129<UL>
2130
2131 <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file
2132
2133 <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI
2134
2135 <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes
2136
2137 <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job
2138
2139 <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job
2140
2141 <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job
2142
2143 <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job
2144
2145 <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes
2146
2147 <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs
2148
2149 <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes
2150
2151 <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job
2152
2153 <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job
2154
2155 <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job
2156
2157 <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer
2158
2159 <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer
2160
2161 <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue
2162
2163 <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes
2164
2165 <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes
2166
2167 <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer supported values
2168
2169 <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination
2170
2171 <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers
2172
2173 <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer
2174
2175 <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer
2176
2177 <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes
2178
2179 <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class
2180
2181 <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class
2182
2183 <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class
2184
2185 <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class
2186
2187 <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination
2188
2189 <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices
2190
2191 <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs
2192
2193 <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination
2194
2195</UL>
2196
2197<H3>Status Codes</H3>
2198
2199<P>Status codes are returned by all IPP requests.
2200
2201<UL>
2202
2203 <LI><CODE>IPP_OK</CODE> - Request completed with no errors
2204
2205 <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute
2206 values were substituted
2207
2208 <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes
2209 conflicted
2210
2211 <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad
2212
2213 <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource
2214
2215 <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for
2216 the resource
2217
2218 <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access
2219 the resource
2220
2221 <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be
2222 completed
2223
2224 <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred
2225
2226 <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found
2227
2228 <LI><CODE>IPP_GONE</CODE> - The resource has gone away
2229
2230 <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large
2231
2232 <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value
2233 that was unknown to the server
2234
2235 <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not
2236 supported by the server
2237
2238 <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing
2239
2240 <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported
2241
2242 <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported
2243
2244 <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict
2245
2246 <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified
2247 compression is not supported
2248
2249 <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data
2250 contained an error
2251
2252 <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data
2253 contained an error in it
2254
2255 <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document
2256 could not be accessed
2257
2258 <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an
2259 internal error
2260
2261 <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation
2262 is not supported
2263
2264 <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service
2265 is unavailable
2266
2267 <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request
2268 version is not supported
2269
2270 <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered
2271 an error
2272
2273 <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred
2274
2275 <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting
2276 jobs
2277
2278 <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy
2279
2280 <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been
2281 cancelled
2282
2283 <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server
2284 does not support multiple jobs
2285
2286</UL>
902da432 2287
902da432 2288<H2>PPD Constants</H2>
2289
70bb1290 2290<H3>PPD Format Version</H3>
902da432 2291
70bb1290 2292<P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number
2293representing the newest format version that is supported by CUPS, currently
22944.3.
902da432 2295
70bb1290 2296<H3>PPD User-Interface Types</H3>
902da432 2297
70bb1290 2298<P>Each printer option has a type associated with it:
902da432 2299
70bb1290 2300<UL>
902da432 2301
70bb1290 2302 <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or off
902da432 2303
70bb1290 2304 <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value
2305 to use.
902da432 2306
70bb1290 2307 <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more
2308 option values.
902da432 2309
70bb1290 2310</UL>
902da432 2311
70bb1290 2312<H3>PPD Sections</H3>
902da432 2313
70bb1290 2314<P>Some options must be output before others, or in different sections of
2315the output document. The <CODE>ppd_section_t</CODE> enumeration defines
2316which section the option must be output in:
902da432 2317
70bb1290 2318<UL>
902da432 2319
70bb1290 2320 <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of
2321 the document, page, or prolog sections of the document
902da432 2322
70bb1290 2323 <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in
2324 the DocumentSetup section of the document
902da432 2325
70bb1290 2326 <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before
2327 the document
902da432 2328
70bb1290 2329 <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the
2330 job control section of the document
902da432 2331
70bb1290 2332 <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the
2333 PageSetup section of the document
902da432 2334
70bb1290 2335 <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the
2336 Prolog section of the document
902da432 2337
70bb1290 2338</UL>
902da432 2339
70bb1290 2340<H3>PPD Colorspaces</H3>
902da432 2341
70bb1290 2342<P>Each printer has a default colorspace:
902da432 2343
70bb1290 2344<UL>
902da432 2345
70bb1290 2346 <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default
902da432 2347
70bb1290 2348 <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default
902da432 2349
70bb1290 2350 <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default
902da432 2351
70bb1290 2352 <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default
902da432 2353
70bb1290 2354 <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default
902da432 2355
70bb1290 2356 <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace
2357 by default
902da432 2358
70bb1290 2359</UL>
902da432 2360
70bb1290 2361<H2>Raster Constants</H2>
902da432 2362
70bb1290 2363<H3>Raster Sync Words</H3>
902da432 2364
70bb1290 2365<P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE>
2366constants define the standard sync words at the beginning of each CUPS
2367raster file.
902da432 2368
70bb1290 2369<H3>Raster Stream Modes</H3>
03efb52b 2370
70bb1290 2371<P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE>
2372constants are used with the
2373<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function to
2374specify a stream for reading or writing.
03efb52b 2375
70bb1290 2376<H3>Raster Boolean Constants</H3>
03efb52b 2377
70bb1290 2378<P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants
2379represent boolean values in the page header.
902da432 2380
70bb1290 2381<H3>Raster Jog Values</H3>
902da432 2382
70bb1290 2383<P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the
2384Jog page device dictionary variable:
902da432 2385
70bb1290 2386<UL>
902da432 2387
70bb1290 2388 <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging
902da432 2389
70bb1290 2390 <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file
03efb52b 2391
70bb1290 2392 <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job
902da432 2393
70bb1290 2394 <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs
2395
2396</UL>
2397
2398<H3>Raster Orientation Values</H3>
2399
2400<P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the
2401Orientation page device dictionary variable:
2402
2403<UL>
2404
2405 <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation
2406
2407 <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation
2408
2409 <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation
2410
2411 <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation
2412
2413</UL>
2414
2415<H3>Raster CutMedia Values</H3>
2416
2417<P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the
2418CutMedia page device dictionary variable:
2419
2420<UL>
2421
2422 <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging
2423
2424 <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file
2425
2426 <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job
2427
2428 <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs
2429
2430 <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page
2431
2432</UL>
2433
2434<H3>Raster AdvanceMedia Values</H3>
2435
2436<P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the
2437AdvanceMedia page device dictionary variable:
2438
2439<UL>
2440
2441 <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging
2442
2443 <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file
2444
2445 <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job
2446
2447 <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs
2448
2449 <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page
2450
2451</UL>
2452
2453<H3>Raster LeadingEdge Values</H3>
2454
2455<P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the
2456LeadingEdge page device dictionary variable:
2457
2458<UL>
2459
2460 <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading
2461 edge
2462
2463 <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading
2464 edge
2465
2466 <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the
2467 leading edge
2468
2469 <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading
2470 edge
2471
2472</UL>
2473
2474<H3>Raster Color Order Values</H3>
2475
2476<P>The <CODE>cups_order_t</CODE> enumeration defines the possible color
2477value orderings:
2478
2479<UL>
2480
2481 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK
2482
2483 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK
2484
2485 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...
2486
2487</UL>
2488
2489<H3>Raster Colorspace Values</H3>
2490
2491<P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible colorspaces:
2492
2493<UL>
2494
2495 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)
2496
2497 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue
2498
2499 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha
2500
2501 <LI><CODE>CUPS_CSPACE_K</CODE> - Black
2502
2503 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow
2504
2505 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan
2506
2507 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black
2508
2509 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black
2510
2511 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow
2512
2513 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
2514 light cyan, light magenta
2515
2516 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta,
2517 metallic cyan, black
2518
2519 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta,
2520 metallic cyan, metallic grey (silver)
2521
2522 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)
2523
2524 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)
2525
2526 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)
2527
2528</UL>
2529
2530<H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1>
2531
2532<P>This appendix describes all of the structures that are defined by the CUPS
2533API.
2534
2535<H2>Raster Structures</H2>
2536
2537<H3>Raster Page Header</H3>
2538
2539<P>The raster page header consists of the PostScript page device dictionary
2540for the page:
2541
2542<CENTER><TABLE WIDTH="90%" BORDER="1">
2543<TR>
2544 <TH>Member</TH>
2545 <TH>Type</TH>
2546 <TH>Description</TH>
2547</TR>
2548<TR>
2549 <TD>MediaClass</TD>
2550 <TD>char[64]</TD>
2551 <TD>The media class name</TD>
2552</TR>
2553<TR>
2554 <TD>MediaColor</TD>
2555 <TD>char[64]</TD>
2556 <TD>The media color name</TD>
2557</TR>
2558<TR>
2559 <TD>MediaType</TD>
2560 <TD>char[64]</TD>
2561 <TD>The media type name</TD>
2562</TR>
2563<TR>
2564 <TD>OutputType</TD>
2565 <TD>char[64]</TD>
2566 <TD>The output type name</TD>
2567</TR>
2568<TR>
2569 <TD>AdvanceDistance</TD>
2570 <TD>unsigned</TD>
2571 <TD>The distance to advance the media in points</TD>
2572</TR>
2573<TR>
2574 <TD>AdvanceMedia</TD>
2575 <TD>cups_adv_t</TD>
2576 <TD>When to advance the media</TD>
2577</TR>
2578<TR>
2579 <TD>Collate</TD>
2580 <TD>cups_bool_t</TD>
2581 <TD>Whether or not to produce collated copies</TD>
2582</TR>
2583<TR>
2584 <TD>CutMedia</TD>
2585 <TD>cups_cut_t</TD>
2586 <TD>When to cut the media</TD>
2587</TR>
2588<TR>
2589 <TD>Duplex</TD>
2590 <TD>cups_bool_t</TD>
2591 <TD>Whether or not to print on both sides of the paper</TD>
2592</TR>
2593<TR>
2594 <TD>HWResolution</TD>
2595 <TD>unsigned[2]</TD>
2596 <TD>The resolution of the page image in pixels per inch; the
2597 HWResolution[0] represents the horizontal resolution and
2598 HWResolution[1] represents the vertical resolution</TD>
2599</TR>
2600<TR>
2601 <TD>ImagingBoundingBox</TD>
2602 <TD>unsigned[4]</TD>
2603 <TD>The bounding box for the page in points; the elements
2604 represent the left, bottom, right, and top coordinates of the
2605 imaged area (if 0 then the whole page is imaged)</TD>
2606</TR>
2607<TR>
2608 <TD>InsertSheet</TD>
2609 <TD>cups_bool_t</TD>
2610 <TD>Whether or not to insert a sheet before this page</TD>
2611</TR>
2612<TR>
2613 <TD>Jog</TD>
2614 <TD>cups_jog_t</TD>
2615 <TD>When to jog copies of the page</TD>
2616</TR>
2617<TR>
2618 <TD>LeadingEdge</TD>
2619 <TD>cups_edge_t</TD>
2620 <TD>The leading edge of the page</TD>
2621</TR>
2622<TR>
2623 <TD>Margins</TD>
2624 <TD>unsigned[2]</TD>
2625 <TD>The lower-lefthand margin of the page in points</TD>
2626</TR>
2627<TR>
2628 <TD>ManualFeed</TD>
2629 <TD>cups_bool_t</TD>
2630 <TD>Whether or not to manually feed the page</TD>
2631</TR>
2632<TR>
2633 <TD>MediaPosition</TD>
2634 <TD>unsigned</TD>
2635 <TD>The input slot number to use</TD>
2636</TR>
2637<TR>
2638 <TD>MediaWeight</TD>
2639 <TD>unsigned</TD>
2640 <TD>The weight of the output media in grams/m<SUP>2</SUP></TD>
2641</TR>
2642<TR>
2643 <TD>MirrorPrint</TD>
2644 <TD>cups_bool_t</TD>
2645 <TD>Whether or not to mirror the print</TD>
2646</TR>
2647<TR>
2648 <TD>NegativePrint</TD>
2649 <TD>cups_bool_t</TD>
2650 <TD>Whether or not to invert the print</TD>
2651</TR>
2652<TR>
2653 <TD>NumCopies</TD>
2654 <TD>unsigned</TD>
2655 <TD>The number of copies to produce</TD>
2656</TR>
2657<TR>
2658 <TD>Orientation</TD>
2659 <TD>cups_orient_t</TD>
2660 <TD>The orientation of the page image</TD>
2661</TR>
2662<TR>
2663 <TD>OutputFaceUp</TD>
2664 <TD>cups_bool_t</TD>
2665 <TD>Whether or not to output the page face up</TD>
2666</TR>
2667<TR>
2668 <TD>PageSize</TD>
2669 <TD>unsigned[2]</TD>
2670 <TD>The width and height of the page in points</TD>
2671</TR>
2672<TR>
2673 <TD>Separations</TD>
2674 <TD>cups_bool_t</TD>
2675 <TD>Whether or not to output separations</TD>
2676</TR>
2677<TR>
2678 <TD>TraySwitch</TD>
2679 <TD>cups_bool_t</TD>
2680 <TD>Whether or not to automatically switch trays for the requested
2681 media size/type</TD>
2682</TR>
2683<TR>
2684 <TD>Tumble</TD>
2685 <TD>cups_bool_t</TD>
2686 <TD>Whether or not to rotate the back side of the page</TD>
2687</TR>
2688<TR>
2689 <TD>cupsWidth</TD>
2690 <TD>unsigned</TD>
2691 <TD>The width of the page image in pixels</TD>
2692</TR>
2693<TR>
2694 <TD>cupsHeight</TD>
2695 <TD>unsigned</TD>
2696 <TD>The height of the page image in pixels</TD>
2697</TR>
2698<TR>
2699 <TD>cupsMediaType</TD>
2700 <TD>unsigned</TD>
2701 <TD>The device-specific media type code</TD>
2702</TR>
2703<TR>
2704 <TD>cupsBitsPerColor</TD>
2705 <TD>unsigned</TD>
2706 <TD>The number of bits per color</TD>
2707</TR>
2708<TR>
2709 <TD>cupsBitsPerPixel</TD>
2710 <TD>unsigned</TD>
2711 <TD>The number of bits per pixel</TD>
2712</TR>
2713<TR>
2714 <TD>cupsBytesPerLine</TD>
2715 <TD>unsigned</TD>
2716 <TD>The number of bytes per line of image data</TD>
2717</TR>
2718<TR>
2719 <TD>cupsColorOrder</TD>
2720 <TD>cups_order_t</TD>
2721 <TD>The order of color values</TD>
2722</TR>
2723<TR>
2724 <TD>cupsColorSpace</TD>
2725 <TD>cups_cspace_t</TD>
2726 <TD>The type of color values</TD>
2727</TR>
2728<TR>
2729 <TD>cupsCompression</TD>
2730 <TD>unsigned</TD>
2731 <TD>The device-specific compression code</TD>
2732</TR>
2733<TR>
2734 <TD>cupsRowCount</TD>
2735 <TD>unsigned</TD>
2736 <TD>The device-specific row count</TD>
2737</TR>
2738<TR>
2739 <TD>cupsRowFeed</TD>
2740 <TD>unsigned</TD>
2741 <TD>The device-specific row feed</TD>
2742</TR>
2743<TR>
2744 <TD>cupsRowStep</TD>
2745 <TD>unsigned</TD>
2746 <TD>The device-specific row step</TD>
2747</TR>
2748</TABLE></CENTER>
2749
2750<H1 ALIGN="RIGHT"><A HREF="FUNCTIONS">D - Functions</A></H1>
2751
2752<P>This appendix provides a reference for all of the CUPS API functions.
2753
2754<!-- NEW PAGE --><H2><A NAME="cupsAddOption">cupsAddOption()</A></H2>
2755
2756<H3>Usage</H3>
2757
2758<PRE>
2759int
2760cupsAddOption(const char *name,
2761 const char *value,
2762 int num_options,
2763 cups_option_t **options);
2764</PRE>
2765
2766<H3>Arguments</H3>
2767
2768<CENTER><TABLE WIDTH="80%" BORDER>
2769<TR>
2770 <TH>Argument</TH>
2771 <TH>Description</TH>
2772</TR>
2773<TR>
2774 <TD>name</TD>
2775 <TD>The name of the option.</TD>
2776</TR>
2777<TR>
2778 <TD>value</TD>
2779 <TD>The value of the option.</TD>
2780</TR>
2781<TR>
2782 <TD>num_options</TD>
2783 <TD>Number of options currently in the array.</TD>
2784</TR>
2785<TR>
2786 <TD>options</TD>
2787 <TD>Pointer to the options array.</TD>
2788</TR>
2789</TABLE></CENTER>
2790
2791<H3>Returns</H3>
2792
2793<P>The new number of options.
2794
2795<H3>Description</H3>
2796
2797<P><CODE>cupsAddOption()</CODE> adds an option to the specified array.
2798
2799<H3>Example</H3>
2800
2801<PRE>
2802#include &lt;cups.h&gt;
2803
2804...
2805
2806/* Declare the options array */
2807int num_options;
2808<A HREF="#cups_option_t">cups_option_t</A> *options;
2809
2810/* Initialize the options array */
2811num_options = 0;
2812options = (cups_option_t *)0;
2813
2814/* Add options using cupsAddOption() */
2815num_options = cupsAddOption("media", "letter", num_options, &amp;options);
2816num_options = cupsAddOption("resolution", "300dpi", num_options, &amp;options);
2817</PRE>
2818
2819<H3>See Also</H3>
2820
2821<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
2822<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
2823<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
2824
2825<!-- NEW PAGE --><H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2>
2826
2827<H3>Usage</H3>
2828
2829<PRE>
2830int
2831cupsCancelJob(const char *dest,
2832 int job);
2833</PRE>
2834
2835<H3>Arguments</H3>
2836
2837<CENTER><TABLE WIDTH="80%" BORDER>
2838<TR>
2839 <TH>Argument</TH>
2840 <TH>Description</TH>
2841</TR>
2842<TR>
2843 <TD>dest</TD>
2844 <TD>Printer or class name</TD>
2845</TR>
2846<TR>
2847 <TD>job</TD>
2848 <TD>Job ID</TD>
2849</TR>
2850</TABLE></CENTER>
2851
2852<H3>Returns</H3>
2853
2854<P>1 on success, 0 on failure. On failure the error can be found by calling
2855<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
2856
2857<H3>Description</H3>
2858
2859<P><CODE>cupsCancelJob()</CODE> cancels the specifies job.
2860
2861<H3>Example</H3>
2862
2863<PRE>
2864#include &lt;cups.h&gt;
2865
2866cupsCancelJob("LaserJet", 1);
2867</PRE>
2868
2869<H3>See Also</H3>
2870
2871<P>
2872<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
2873<A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>
2874
2875<!-- NEW PAGE --><H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2>
2876
2877<H3>Usage</H3>
2878
2879<PRE>
2880ipp_t *
2881cupsDoFileRequest(http_t *http,
2882 ipp_t *request,
2883 const char *resource,
2884 const char *filename);
2885</PRE>
2886
2887<H3>Arguments</H3>
2888
2889<CENTER><TABLE WIDTH="80%" BORDER>
2890<TR>
2891 <TH>Argument</TH>
902da432 2892 <TH>Description</TH>
2893</TR>
2894<TR>
03efb52b 2895 <TD>http</TD>
2896 <TD>HTTP connection to server.</TD>
2897</TR>
2898<TR>
2899 <TD>request</TD>
2900 <TD>IPP request data.</TD>
2901</TR>
2902<TR>
2903 <TD>resource</TD>
2904 <TD>HTTP resource name for POST.</TD>
2905</TR>
2906<TR>
2907 <TD>filename</TD>
2908 <TD>File to send with POST request (<CODE>NULL</CODE> pointer if none.)</TD>
902da432 2909</TR>
2910</TABLE></CENTER>
2911
2912<H3>Returns</H3>
2913
03efb52b 2914<P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
2915the error can be found by calling
2916<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
2917
902da432 2918<H3>Description</H3>
2919
03efb52b 2920<P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and provides the
2921IPP request and optionally the contents of a file to the IPP server. It also
2922handles resubmitting the request and performing password authentication as
2923needed.
2924
2925<H3>Example</H3>
2926
2927<PRE>
2928#include &lt;cups.h&gt;
2929
2930<A HREF="#http_t">http_t</A> *http;
2931<A HREF="#cups_lang_t">cups_lang_t</A> *language;
2932<A HREF="#ipp_t">ipp_t</A> *request;
2933ipp_t *response;
2934
2935...
2936
2937/* Get the default language */
2938language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
2939
2940/* Create a new IPP request */
2941request = <A HREF="#ippNew">ippNew()</A>;
2942
2943request-&gt;request.op.operation_id = IPP_PRINT_FILE;
2944request-&gt;request.op.request_id = 1;
2945
2946/* Add required attributes */
2947<A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
2948 "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
2949
2950ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
2951 "attributes-natural-language", NULL,
2952 language != NULL ? language-&gt;language : "C");
2953
2954ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
2955 NULL, "ipp://hostname/resource");
2956
2957ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
2958 NULL, <A HREF="#cupsUser">cupsUser()</A>);
2959
2960/* Do the request... */
2961response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
2962</PRE>
902da432 2963
2964<H3>See Also</H3>
2965
03efb52b 2966<P>
2967<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
2968<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
2969<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
2970<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
2971<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
2972<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
902da432 2973
03efb52b 2974<!-- NEW PAGE --><H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2>
902da432 2975
2976<H3>Usage</H3>
2977
03efb52b 2978<PRE>
2979ipp_t *
2980cupsDoRequest(http_t *http,
2981 ipp_t *request,
2982 const char *resource);
2983</PRE>
2984
902da432 2985<H3>Arguments</H3>
2986
03efb52b 2987<CENTER><TABLE WIDTH="80%" BORDER>
902da432 2988<TR>
2989 <TH>Argument</TH>
2990 <TH>Description</TH>
2991</TR>
2992<TR>
03efb52b 2993 <TD>http</TD>
2994 <TD>HTTP connection to server.</TD>
2995</TR>
2996<TR>
2997 <TD>request</TD>
2998 <TD>IPP request data.</TD>
2999</TR>
3000<TR>
3001 <TD>resource</TD>
3002 <TD>HTTP resource name for POST.</TD>
902da432 3003</TR>
3004</TABLE></CENTER>
3005
3006<H3>Returns</H3>
3007
03efb52b 3008<P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
3009the error can be found by calling
3010<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
3011
902da432 3012<H3>Description</H3>
3013
03efb52b 3014<P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides
3015the IPP request to the IPP server. It also handles resubmitting the
3016request and performing password authentication as needed.
3017
3018<H3>Example</H3>
3019
3020<PRE>
3021#include &lt;cups.h&gt;
3022
3023<A HREF="#http_t">http_t</A> *http;
3024<A HREF="#cups_lang_t">cups_lang_t</A> *language;
3025<A HREF="#ipp_t">ipp_t</A> *request;
3026ipp_t *response;
3027
3028...
3029
3030/* Get the default language */
3031language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3032
3033/* Create a new IPP request */
3034request = <A HREF="#ippNew">ippNew()</A>;
3035
3036request-&gt;request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
3037request-&gt;request.op.request_id = 1;
3038
3039/* Add required attributes */
3040<A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3041 "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3042
3043ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3044 "attributes-natural-language", NULL,
3045 language != NULL ? language-&gt;language : "C");
3046
3047ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
3048 NULL, "ipp://hostname/resource");
3049
3050/* Do the request... */
3051response = cupsDoRequest(http, request, "/resource");
3052</PRE>
902da432 3053
3054<H3>See Also</H3>
3055
03efb52b 3056<P>
3057<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
3058<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
3059<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
3060<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
3061<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
3062<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
902da432 3063
30eb152d 3064<!-- NEW PAGE --><H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2>
902da432 3065
3066<H3>Usage</H3>
3067
30eb152d 3068<PRE>
3069void
3070cupsFreeOptions(int num_options,
3071 cups_option_t *options);
3072
902da432 3073<H3>Arguments</H3>
3074
03efb52b 3075<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3076<TR>
3077 <TH>Argument</TH>
3078 <TH>Description</TH>
3079</TR>
3080<TR>
30eb152d 3081 <TD>num_options</TD>
3082 <TD>Number of options in array.</TD>
3083</TR>
3084<TR>
3085 <TD>options</TD>
3086 <TD>Pointer to options array.</TD>
902da432 3087</TR>
3088</TABLE></CENTER>
3089
902da432 3090<H3>Description</H3>
3091
30eb152d 3092<P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the
3093option array specified.
3094
03efb52b 3095<H3>Example</H3>
902da432 3096
30eb152d 3097<PRE>
3098#include &lt;cups/cups.h&gt;
3099
3100int num_options;
3101cups_option_t *options;
3102
3103...
3104
3105cupsFreeOptions(num_options, options);
3106</PRE>
3107
902da432 3108<H3>See Also</H3>
3109
30eb152d 3110<P>
3111<A HREF="#cupsAddOption">cupsAddOption()</A>,
3112<A HREF="#cupsGetOption">cupsGetOption()</A>,
3113<A HREF="#cupsMarkOptions">cupsMarkOptions()</A>,
3114<A HREF="#cupsParseOptions">cupsParseOptions()</A>
902da432 3115
30eb152d 3116<!-- NEW PAGE --><H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2>
902da432 3117
3118<H3>Usage</H3>
3119
30eb152d 3120<PRE>
3121int
3122cupsGetClasses(char ***classes);
3123</PRE>
3124
902da432 3125<H3>Arguments</H3>
3126
03efb52b 3127<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3128<TR>
3129 <TH>Argument</TH>
3130 <TH>Description</TH>
3131</TR>
3132<TR>
30eb152d 3133 <TD>classes</TD>
3134 <TD>Pointer to character pointer array.</TD>
902da432 3135</TR>
3136</TABLE></CENTER>
3137
3138<H3>Returns</H3>
3139
30eb152d 3140<P>The number of printer classes available.
3141
902da432 3142<H3>Description</H3>
3143
30eb152d 3144<P><CODE>cupsGetClasses()</CODE> gets a list of the available printer classes.
3145The returned array should be freed using the <CODE>free()</CODE> when it is
3146no longer needed.
3147
03efb52b 3148<H3>Example</H3>
902da432 3149
30eb152d 3150<PRE>
3151#include &lt;cups/cups.h&gt;
3152
3153int i;
3154int num_classes;
3155char **classes;
3156
3157...
3158
3159num_classes = cupsGetClasses(&classes);
3160
3161...
3162
3163if (num_classes > 0)
3164{
3165 for (i = 0; i < num_classes; i ++)
3166 free(classes[i]);
3167
3168 free(classes);
3169}
3170</PRE>
3171
902da432 3172<H3>See Also</H3>
3173
30eb152d 3174<P>
3175<A HREF="#cupsGetDefault">cupsGetDefault()</CODE>,
3176<A HREF="#cupsGetPrinters">cupsGetPrinters()</CODE>
902da432 3177
30eb152d 3178<!-- NEW PAGE --><H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2>
902da432 3179
3180<H3>Usage</H3>
3181
30eb152d 3182<PRE>
3183const char *
3184cupsGetDefault(void);
3185</PRE>
902da432 3186
3187<H3>Returns</H3>
3188
30eb152d 3189<P>A pointer to the default destination.
3190
902da432 3191<H3>Description</H3>
3192
30eb152d 3193<P><CODE>cupsGetDefault()</CODE> gets the default destination printer or class.
3194The default destination is stored in a static string and will be overwritten
3195(usually with the same value) after each call.
3196
03efb52b 3197<H3>Example</H3>
902da432 3198
30eb152d 3199<PRE>
3200#include &lt;cups/cups.h&gt;
3201
3202printf("The default destination is %s\n", cupsGetDefault());
3203</PRE>
3204
902da432 3205<H3>See Also</H3>
3206
30eb152d 3207<P>
3208<A HREF="#cupsGetClasses">cupsGetClasses()</CODE>,
3209<A HREF="#cupsGetPrinters">cupsGetPrinters()</CODE>
902da432 3210
30eb152d 3211<!-- NEW PAGE --><H2><A NAME="cupsGetOption">cupsGetOption()</A></H2>
902da432 3212
3213<H3>Usage</H3>
3214
30eb152d 3215<PRE>
3216const char *
3217cupsGetOption(const char *name,
3218 int num_options,
3219 cups_option_t *options);
3220</PRE>
3221
902da432 3222<H3>Arguments</H3>
3223
03efb52b 3224<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3225<TR>
3226 <TH>Argument</TH>
3227 <TH>Description</TH>
3228</TR>
3229<TR>
30eb152d 3230 <TD>name</TD>
3231 <TD>The name of the option.</TD>
3232</TR>
3233<TR>
3234 <TD>num_options</TD>
3235 <TD>The number of options in the array.</TD>
3236</TR>
3237<TR>
3238 <TD>options</TD>
3239 <TD>The options array.</TD>
902da432 3240</TR>
3241</TABLE></CENTER>
3242
3243<H3>Returns</H3>
3244
30eb152d 3245<P>A pointer to the option values or <CODE>NULL</CODE> if the option is
3246not defined.
3247
902da432 3248<H3>Description</H3>
3249
30eb152d 3250<P><CODE>cupsGetOption()</CODE> returns the first occurrence of the
3251named option. If the option is not included in the options array then a
3252<CODE>NULL</CODE> pointer is returned.
3253
3254<PRE>
3255#include &lt;cups/cups.h&gt;
3256
3257int num_options;
3258cups_option_t *options;
3259const char *media;
3260
3261...
3262
3263media = cupsGetOption("media", num_options, options);
3264</PRE>
902da432 3265
3266<H3>See Also</H3>
3267
30eb152d 3268<P>
3269<A HREF="#cupsAddOption">cupsAddOption()</A>,
3270<A HREF="#cupsFreeOptions">cupsFreeOptions()</A>,
3271<A HREF="#cupsMarkOptions">cupsMarkOptions()</A>,
3272<A HREF="#cupsParseOptions">cupsParseOptions()</A>
902da432 3273
30eb152d 3274<!-- NEW PAGE --><H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2>
902da432 3275
3276<H3>Usage</H3>
3277
30eb152d 3278<PRE>
3279const char *
3280cupsGetPassword(const char *prompt);
3281</PRE>
3282
902da432 3283<H3>Arguments</H3>
3284
03efb52b 3285<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3286<TR>
3287 <TH>Argument</TH>
3288 <TH>Description</TH>
3289</TR>
3290<TR>
30eb152d 3291 <TD>prompt</TD>
3292 <TD>The prompt to display to the user.</TD>
902da432 3293</TR>
3294</TABLE></CENTER>
3295
3296<H3>Returns</H3>
3297
30eb152d 3298<P>A pointer to the password that was entered or <CODE>NULL</CODE> if no
3299password was entered.
3300
902da432 3301<H3>Description</H3>
3302
30eb152d 3303<P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks the user
3304for a password. The password text is not echoed to the user.
3305
03efb52b 3306<H3>Example</H3>
902da432 3307
30eb152d 3308<PRE>
3309#include &lt;cups/cups.h&gt;
3310
3311char *password;
3312
3313...
3314
3315password = cupsGetPassword("Please enter a password:");
3316</PRE>
3317
902da432 3318<H3>See Also</H3>
3319
30eb152d 3320<P>
3321<A HREF="#cupsServer">cupsServer()</A>,
ebd737f3 3322<A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A>,
3323<A HREF="#cupsSetServer">cupsSetServer()</A>,
3324<A HREF="#cupsSetUser">cupsSetUser()</A>,
30eb152d 3325<A HREF="#cupsUser()">cupsUser()</A>
902da432 3326
30eb152d 3327<!-- NEW PAGE --><H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2>
902da432 3328
3329<H3>Usage</H3>
3330
30eb152d 3331<PRE>
3332const char *
3333cupsGetPPD(const char *printer);
3334</PRE>
3335
902da432 3336<H3>Arguments</H3>
3337
03efb52b 3338<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3339<TR>
3340 <TH>Argument</TH>
3341 <TH>Description</TH>
3342</TR>
3343<TR>
30eb152d 3344 <TD>printer</TD>
3345 <TD>The name of the printer.</TD>
902da432 3346</TR>
3347</TABLE></CENTER>
3348
3349<H3>Returns</H3>
3350
30eb152d 3351<P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE>
3352if the printer cannot be located or does not have a PPD file.
3353
902da432 3354<H3>Description</H3>
3355
30eb152d 3356<P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named printer.
3357The printer name can be of the form "printer" or "printer@hostname".
3358
3359<P>You should remove (unlink) the PPD file after you are done using it. The
3360filename is stored in a static buffer and will be overwritten with each call
3361to <CODE>cupsGetPPD()</CODE>.
3362
03efb52b 3363<H3>Example</H3>
902da432 3364
30eb152d 3365<PRE>
3366#include &lt;cups/cups.h&gt;
3367
3368char *ppd;
902da432 3369
30eb152d 3370...
902da432 3371
30eb152d 3372ppd = cupsGetPPD("printer@hostname");
3373
3374...
3375
3376unlink(ppd);
3377</PRE>
3378
3379<!-- NEW PAGE --><H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2>
902da432 3380
3381<H3>Usage</H3>
3382
30eb152d 3383<PRE>
3384int
3385cupsGetPrinters(char ***printers);
3386</PRE>
3387
902da432 3388<H3>Arguments</H3>
3389
03efb52b 3390<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3391<TR>
3392 <TH>Argument</TH>
3393 <TH>Description</TH>
3394</TR>
3395<TR>
30eb152d 3396 <TD>printers</TD>
3397 <TD>Pointer to character pointer array.</TD>
902da432 3398</TR>
3399</TABLE></CENTER>
3400
3401<H3>Returns</H3>
3402
30eb152d 3403<P>The number of printer printers available.
3404
902da432 3405<H3>Description</H3>
3406
30eb152d 3407<P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers.
3408The returned array should be freed using the <CODE>free()</CODE> when it is
3409no longer needed.
3410
03efb52b 3411<H3>Example</H3>
902da432 3412
30eb152d 3413<PRE>
3414#include &lt;cups/cups.h&gt;
3415
3416int i;
3417int num_printers;
3418char **printers;
3419
3420...
3421
3422num_printers = cupsGetPrinters(&printers);
3423
3424...
3425
3426if (num_printers > 0)
3427{
3428 for (i = 0; i < num_printers; i ++)
3429 free(printers[i]);
3430
3431 free(printers);
3432}
3433</PRE>
3434
902da432 3435<H3>See Also</H3>
3436
30eb152d 3437<P>
3438<A HREF="#cupsGetClasses">cupsGetClasses()</CODE>,
3439<A HREF="#cupsGetDefault">cupsGetDefault()</CODE>
902da432 3440
30eb152d 3441<!-- NEW PAGE --><H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2>
902da432 3442
3443<H3>Usage</H3>
3444
30eb152d 3445<PRE>
3446const char *
3447cupsLangDefault(void);
3448</PRE>
902da432 3449
3450<H3>Returns</H3>
3451
30eb152d 3452<P>A pointer to the default language structure.
3453
902da432 3454<H3>Description</H3>
3455
30eb152d 3456<P><CODE>cupsLangDefault()</CODE> returns a language structure for the default
3457language. The default language is defined by the <CODE>LANG</CODE> environment
3458variable. If the specified language cannot be located then the POSIX (English)
3459locale is used.
3460
3461<P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with the
3462language structure when you are done.
3463
03efb52b 3464<H3>Example</H3>
902da432 3465
30eb152d 3466<PRE>
3467#include &lt;cups/language.h&gt;
3468
3469cups_lang_t *language;
3470...
3471
3472language = cupsLangDefault();
3473
3474...
3475
3476cupsLangFree(language);
3477</PRE>
3478
902da432 3479<H3>See Also</H3>
3480
30eb152d 3481<P>
3482<A HREF="#cupsLangEncoding">cupsLangEncoding()</A>,
3483<A HREF="#cupsLangFlush">cupsLangFlush()</A>,
3484<A HREF="#cupsLangFree">cupsLangFree()</A>,
3485<A HREF="#cupsLangGet">cupsLangGet()</A>,
3486<A HREF="#cupsLangString">cupsLangString()</A>
902da432 3487
30eb152d 3488<!-- NEW PAGE --><H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2>
902da432 3489
3490<H3>Usage</H3>
3491
30eb152d 3492<PRE>
3493char *
3494cupsLangEncoding(cups_lang_t *language);
3495</PRE>
3496
902da432 3497<H3>Arguments</H3>
3498
03efb52b 3499<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3500<TR>
3501 <TH>Argument</TH>
3502 <TH>Description</TH>
3503</TR>
3504<TR>
30eb152d 3505 <TD>language</TD>
3506 <TD>The language structure.</TD>
902da432 3507</TR>
3508</TABLE></CENTER>
3509
3510<H3>Returns</H3>
3511
30eb152d 3512<P>A pointer to the encoding string.
3513
902da432 3514<H3>Description</H3>
3515
30eb152d 3516<P><CODE>cupsLangEncoding()</CODE> returns the language encoding used for the
3517specified language, e.g. "iso-8859-1", "utf-8", etc.
3518
03efb52b 3519<H3>Example</H3>
902da432 3520
30eb152d 3521<PRE>
3522#include &lt;cups/language.h&gt;
902da432 3523
30eb152d 3524cups_lang_t *language;
3525char *encoding;
3526...
902da432 3527
30eb152d 3528language = cupsLangDefault();
3529encoding = cupsLangEncoding(language);
3530...
902da432 3531
30eb152d 3532cupsLangFree(language);
3533</PRE>
902da432 3534
30eb152d 3535<H3>See Also</H3>
902da432 3536
30eb152d 3537<P>
3538<A HREF="#cupsLangDefault">cupsLangDefault()</A>,
3539<A HREF="#cupsLangFlush">cupsLangFlush()</A>,
3540<A HREF="#cupsLangFree">cupsLangFree()</A>,
3541<A HREF="#cupsLangGet">cupsLangGet()</A>,
3542<A HREF="#cupsLangString">cupsLangString()</A>
902da432 3543
30eb152d 3544<!-- NEW PAGE --><H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2>
3545
3546<H3>Usage</H3>
3547
3548<PRE>
3549void
3550cupsLangFlush(void);
3551</PRE>
902da432 3552
3553<H3>Description</H3>
3554
30eb152d 3555<P><CODE>cupsLangFlush()</CODE> frees all language structures that have been
3556allocated.
3557
03efb52b 3558<H3>Example</H3>
902da432 3559
30eb152d 3560<PRE>
3561#include &lt;cups/language.h&gt;
3562
3563...
3564
3565cupsLangFlush();
3566</PRE>
3567
902da432 3568<H3>See Also</H3>
3569
30eb152d 3570<P>
3571<A HREF="#cupsLangDefault">cupsLangDefault()</A>,
3572<A HREF="#cupsLangEncoding">cupsLangEncoding()</A>,
3573<A HREF="#cupsLangFree">cupsLangFree()</A>,
3574<A HREF="#cupsLangGet">cupsLangGet()</A>,
3575<A HREF="#cupsLangString">cupsLangString()</A>
902da432 3576
30eb152d 3577<!-- NEW PAGE --><H2><A NAME="cupsLangFree">cupsLangFree()</A></H2>
902da432 3578
3579<H3>Usage</H3>
3580
30eb152d 3581<PRE>
3582void
3583cupsLangFree(cups_lang_t *language);
3584</PRE>
3585
902da432 3586<H3>Arguments</H3>
3587
03efb52b 3588<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3589<TR>
3590 <TH>Argument</TH>
3591 <TH>Description</TH>
3592</TR>
3593<TR>
30eb152d 3594 <TD>language</TD>
3595 <TD>The language structure to free.</TD>
902da432 3596</TR>
3597</TABLE></CENTER>
3598
902da432 3599<H3>Description</H3>
3600
30eb152d 3601<P><CODE>cupsLangFree()</CODE> frees the specified language structure.
3602
03efb52b 3603<H3>Example</H3>
902da432 3604
30eb152d 3605<PRE>
3606#include &lt;cups/language.h&gt;
3607
3608cups_lang_t *language;
3609...
3610
3611cupsLangFree(language);
3612</PRE>
3613
902da432 3614<H3>See Also</H3>
3615
30eb152d 3616<P>
3617<A HREF="#cupsLangDefault">cupsLangDefault()</A>,
3618<A HREF="#cupsLangEncoding">cupsLangEncoding()</A>,
3619<A HREF="#cupsLangFlush">cupsLangFlush()</A>,
3620<A HREF="#cupsLangGet">cupsLangGet()</A>,
3621<A HREF="#cupsLangString">cupsLangString()</A>
902da432 3622
30eb152d 3623<!-- NEW PAGE --><H2><A NAME="cupsLangGet">cupsLangGet()</A></H2>
902da432 3624
3625<H3>Usage</H3>
3626
30eb152d 3627<PRE>
3628cups_lang_t *
3629cupsLangGet(const char *name);
3630</PRE>
3631
902da432 3632<H3>Arguments</H3>
3633
03efb52b 3634<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3635<TR>
3636 <TH>Argument</TH>
3637 <TH>Description</TH>
3638</TR>
3639<TR>
30eb152d 3640 <TD>name</TD>
3641 <TD>The name of the locale.</TD>
902da432 3642</TR>
3643</TABLE></CENTER>
3644
3645<H3>Returns</H3>
3646
30eb152d 3647<P>A pointer to a language structure.
3648
902da432 3649<H3>Description</H3>
3650
30eb152d 3651<P><CODE>cupsLangGet()</CODE> returns a language structure for the specified
3652locale. If the locale is not defined then the POSIX (English) locale is
3653substituted.
3654
03efb52b 3655<H3>Example</H3>
902da432 3656
30eb152d 3657<PRE>
3658#include &lt;cups/language.h&gt;
3659
3660cups_lang_t *language;
3661
3662...
3663
3664language = cupsLangGet("fr");
3665
3666...
3667
3668cupsLangFree(language);
3669</PRE>
3670
902da432 3671<H3>See Also</H3>
3672
30eb152d 3673<P>
3674<A HREF="#cupsLangDefault">cupsLangDefault()</A>,
3675<A HREF="#cupsLangEncoding">cupsLangEncoding()</A>,
3676<A HREF="#cupsLangFlush">cupsLangFlush()</A>,
3677<A HREF="#cupsLangFree">cupsLangFree()</A>,
3678<A HREF="#cupsLangString">cupsLangString()</A>
902da432 3679
30eb152d 3680<!-- NEW PAGE --><H2><A NAME="cupsLangString">cupsLangString()</A></H2>
902da432 3681
3682<H3>Usage</H3>
3683
30eb152d 3684<PRE>
3685char *
3686cupsLangString(cups_lang_t *language,
3687 int message);
3688</PRE>
3689
902da432 3690<H3>Arguments</H3>
3691
03efb52b 3692<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3693<TR>
3694 <TH>Argument</TH>
3695 <TH>Description</TH>
3696</TR>
3697<TR>
30eb152d 3698 <TD>language</TD>
3699 <TD>The language to query.</TD>
3700</TR>
3701<TR>
3702 <TD>message</TD>
3703 <TD>The message number.</TD>
902da432 3704</TR>
3705</TABLE></CENTER>
3706
3707<H3>Returns</H3>
3708
30eb152d 3709<P>A pointer to the message string or <CODE>NULL</CODE> if the message is
3710not defined.
3711
902da432 3712<H3>Description</H3>
3713
30eb152d 3714<P><CODE>cupsLangString()</CODE> returns a pointer to the specified message
3715string in the specified language.
3716
03efb52b 3717<H3>Example</H3>
902da432 3718
30eb152d 3719<PRE>
3720#include &lt;cups/language.h&gt;
3721
3722cups_lang_t *language;
3723char *s;
3724...
3725
3726language = cupsLangGet("fr");
3727
3728s = cupsLangString(language, CUPS_MSG_YES);
3729
3730...
3731
3732cupsLangFree(language);
3733</PRE>
3734
902da432 3735<H3>See Also</H3>
3736
30eb152d 3737<P>
3738<A HREF="#cupsLangDefault">cupsLangDefault()</A>,
3739<A HREF="#cupsLangEncoding">cupsLangEncoding()</A>,
3740<A HREF="#cupsLangFlush">cupsLangFlush()</A>,
3741<A HREF="#cupsLangFree">cupsLangFree()</A>,
3742<A HREF="#cupsLangGet">cupsLangGet()</A>
902da432 3743
30eb152d 3744<!-- NEW PAGE --><H2><A NAME="cupsLastError">cupsLastError()</A></H2>
902da432 3745
3746<H3>Usage</H3>
3747
30eb152d 3748<PRE>
3749ipp_status_t
3750cupsLastError(void);
3751</PRE>
902da432 3752
3753<H3>Returns</H3>
3754
30eb152d 3755<P>An enumeration containing the last IPP error.
3756
902da432 3757<H3>Description</H3>
3758
30eb152d 3759<P><CODE>cupsLastError()</CODE> returns the last IPP error that occurred.
3760If no error occurred then it will return <CODE>IPP_OK</CODE> or
3761<CODE>IPP_OK_CONFLICT</CODE>.
3762
03efb52b 3763<H3>Example</H3>
902da432 3764
30eb152d 3765<PRE>
3766#include &lt;cups/cups.h&gt;
3767
3768ipp_status_t status;
3769
3770...
3771
3772status = cupsLastError();
3773</PRE>
3774
902da432 3775<H3>See Also</H3>
3776
30eb152d 3777<P>
3778<A HREF="#cupsCancelJob">cupsCancelJob()</A>,
3779<A HREF="#cupsPrintFile">cupsPrintFile()</A>
902da432 3780
30eb152d 3781<!-- NEW PAGE --><H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2>
902da432 3782
3783<H3>Usage</H3>
3784
30eb152d 3785<PRE>
3786int
3787cupsMarkOptions(ppd_file_t *ppd,
3788 int num_options,
3789 cups_option_t *options);
3790</PRE>
3791
902da432 3792<H3>Arguments</H3>
3793
03efb52b 3794<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3795<TR>
3796 <TH>Argument</TH>
3797 <TH>Description</TH>
3798</TR>
3799<TR>
30eb152d 3800 <TD>ppd</TD>
3801 <TD>The PPD file to mark.</TD>
3802</TR>
3803<TR>
3804 <TD>num_options</TD>
3805 <TD>The number of options in the options array.</TD>
3806</TR>
3807<TR>
3808 <TD>options</TD>
3809 <TD>A pointer to the options array.</TD>
902da432 3810</TR>
3811</TABLE></CENTER>
3812
3813<H3>Returns</H3>
3814
30eb152d 3815<P>The number of conflicts found.
3816
902da432 3817<H3>Description</H3>
3818
30eb152d 3819<P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also
3820handles mapping of IPP option names and values to PPD option names.
3821
03efb52b 3822<H3>Example</H3>
902da432 3823
30eb152d 3824<PRE>
3825#include &lt;cups/cups.h&gt;
3826
3827int num_options;
3828cups_option_t *options;
3829ppd_file_t *ppd;
3830
3831...
3832
3833cupsMarkOptions(ppd, num_options, options);
3834</PRE>
3835
902da432 3836<H3>See Also</H3>
3837
30eb152d 3838<P>
3839<A HREF="#cupsAddOption">cupsAddOption()</A>,
3840<A HREF="#cupsFreeOptions">cupsFreeOptions()</A>,
3841<A HREF="#cupsGetOption">cupsGetOption()</A>,
3842<A HREF="#cupsParseOptions">cupsParseOptions()</A>
902da432 3843
30eb152d 3844<!-- NEW PAGE --><H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2>
902da432 3845
3846<H3>Usage</H3>
3847
30eb152d 3848<PRE>
3849int
3850cupsParseOptions(const char *arg,
3851 int num_options,
3852 cups_option_t **options);
3853</PRE>
3854
902da432 3855<H3>Arguments</H3>
3856
03efb52b 3857<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3858<TR>
3859 <TH>Argument</TH>
3860 <TH>Description</TH>
3861</TR>
3862<TR>
30eb152d 3863 <TD>arg</TD>
3864 <TD>The string containing one or more options.</TD>
3865</TR>
3866<TR>
3867 <TD>num_options</TD>
3868 <TD>The number of options in the options array.</TD>
3869</TR>
3870<TR>
3871 <TD>options</TD>
3872 <TD>A pointer to the options array pointer.</TD>
902da432 3873</TR>
3874</TABLE></CENTER>
3875
3876<H3>Returns</H3>
3877
30eb152d 3878<P>The new number of options in the array.
3879
902da432 3880<H3>Description</H3>
3881
30eb152d 3882<P><CODE>cupsParseOptions()</CODE> parses the specifies string for one
3883or more options of the form "name=value", "name", or "noname". It can
3884be called multiple times to combine the options from several strings.
3885
03efb52b 3886<H3>Example</H3>
902da432 3887
30eb152d 3888<PRE>
3889#include &lt;cups/cups.h&gt;
3890
3891int num_options;
3892cups_option_t *options;
3893
3894...
3895
3896num_options = 0;
3897options = (cups_option_t *)0;
3898num_options = cupsParseOptions(argv[5], num_options, &amp;options);
3899</PRE>
3900
902da432 3901<H3>See Also</H3>
3902
30eb152d 3903<P>
3904<A HREF="#cupsAddOption">cupsAddOption()</A>,
3905<A HREF="#cupsFreeOptions">cupsFreeOptions()</A>,
3906<A HREF="#cupsGetOption">cupsGetOption()</A>,
3907<A HREF="#cupsMarkOptions">cupsMarkOptions()</A>
902da432 3908
30eb152d 3909<!-- NEW PAGE --><H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2>
902da432 3910
3911<H3>Usage</H3>
3912
30eb152d 3913<PRE>
3914int
7bfde0bb 3915cupsPrintFile(const char *printer,
3916 const char *filename,
3917 const char *title,
3918 int num_options,
30eb152d 3919 cups_option_t *options);
3920</PRE>
3921
902da432 3922<H3>Arguments</H3>
3923
03efb52b 3924<CENTER><TABLE WIDTH="80%" BORDER>
902da432 3925<TR>
3926 <TH>Argument</TH>
3927 <TH>Description</TH>
3928</TR>
3929<TR>
30eb152d 3930 <TD>printer</TD>
3931 <TD>The printer or class to print to.</TD>
3932</TR>
3933<TR>
3934 <TD>filename</TD>
3935 <TD>The file to print.</TD>
3936</TR>
3937<TR>
3938 <TD>title</TD>
3939 <TD>The job title.</TD>
3940</TR>
3941<TR>
3942 <TD>num_options</TD>
3943 <TD>The number of options in the options array.</TD>
3944</TR>
3945<TR>
3946 <TD>options</TD>
3947 <TD>A pointer to the options array.</TD>
902da432 3948</TR>
3949</TABLE></CENTER>
3950
3951<H3>Returns</H3>
3952
30eb152d 3953<P>The new job ID number or 0 on error.
3954
902da432 3955<H3>Description</H3>
3956
30eb152d 3957<P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or
3958class for printing. If the job cannot be printed the error code can be
3959found by calling <CODE>cupsLastError()</CODE>.
3960
03efb52b 3961<H3>Example</H3>
902da432 3962
30eb152d 3963<PRE>
3964#include &lt;cups/cups.h&gt;
3965
3966int num_options;
3967cups_option_t *options;
7bfde0bb 3968int jobid;
3969
3970...
3971
3972jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
3973 num_options, options);
3974</PRE>
3975
3976<H3>See Also</H3>
3977
3978<P>
3979<A HREF="#cupsCancelJob">cupsCancelJob()</A>,
3980<A HREF="#cupsLastError">cupsLastError()</A>,
3981<A HREF="#cupsPrintFiles">cupsPrintFiles()</A>
3982
3983<!-- NEW PAGE --><H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2>
3984
3985<H3>Usage</H3>
3986
3987<PRE>
3988int
3989cupsPrintFiles(const char *printer,
3990 int num_files,
3991 const char **files,
3992 const char *title,
3993 int num_options,
3994 cups_option_t *options);
3995</PRE>
3996
3997<H3>Arguments</H3>
3998
3999<CENTER><TABLE WIDTH="80%" BORDER>
4000<TR>
4001 <TH>Argument</TH>
4002 <TH>Description</TH>
4003</TR>
4004<TR>
4005 <TD>printer</TD>
4006 <TD>The printer or class to print to.</TD>
4007</TR>
4008<TR>
4009 <TD>num_files</TD>
4010 <TD>The number of files to print.</TD>
4011</TR>
4012<TR>
4013 <TD>files</TD>
4014 <TD>The files to print.</TD>
4015</TR>
4016<TR>
4017 <TD>title</TD>
4018 <TD>The job title.</TD>
4019</TR>
4020<TR>
4021 <TD>num_options</TD>
4022 <TD>The number of options in the options array.</TD>
4023</TR>
4024<TR>
4025 <TD>options</TD>
4026 <TD>A pointer to the options array.</TD>
4027</TR>
4028</TABLE></CENTER>
4029
4030<H3>Returns</H3>
4031
4032<P>The new job ID number or 0 on error.
4033
4034<H3>Description</H3>
4035
4036<P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified
4037printer or class for printing. If the job cannot be printed the error
4038code can be found by calling <CODE>cupsLastError()</CODE>.
4039
4040<H3>Example</H3>
4041
4042<PRE>
4043#include &lt;cups/cups.h&gt;
4044
4045int num_files;
4046const char *files[100];
4047int num_options;
4048cups_option_t *options;
4049int jobid;
30eb152d 4050
4051...
4052
7bfde0bb 4053jobid = cupsPrintFiles("printer@hostname", num_files, files,
4054 "Job Title", num_options, options);
30eb152d 4055</PRE>
4056
902da432 4057<H3>See Also</H3>
4058
30eb152d 4059<P>
4060<A HREF="#cupsCancelJob">cupsCancelJob()</A>,
7bfde0bb 4061<A HREF="#cupsLastError">cupsLastError()</A>,
4062<A HREF="#cupsPrintFile">cupsPrintFile()</A>
902da432 4063
30eb152d 4064<!-- NEW PAGE --><H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2>
902da432 4065
4066<H3>Usage</H3>
4067
30eb152d 4068<PRE>
4069void
4070cupsRasterClose(cups_raster_t *ras);
4071</PRE>
4072
902da432 4073<H3>Arguments</H3>
4074
03efb52b 4075<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4076<TR>
4077 <TH>Argument</TH>
4078 <TH>Description</TH>
4079</TR>
4080<TR>
30eb152d 4081 <TD>ras</TD>
4082 <TD>The raster stream to close.</TD>
902da432 4083</TR>
4084</TABLE></CENTER>
4085
902da432 4086<H3>Description</H3>
4087
30eb152d 4088<P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.
4089
03efb52b 4090<H3>Example</H3>
902da432 4091
30eb152d 4092<PRE>
4093#include &lt;cups/raster.h&gt;
4094
4095cups_raster_t *ras;
4096
4097...
4098
4099cupsRasterClose(ras);
4100</PRE>
4101
902da432 4102<H3>See Also</H3>
4103
30eb152d 4104<P>
4105<A HREF="#cupsRasterOpen">cupsRasterOpen()</A>,
4106<A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A>,
4107<A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A>,
4108<A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A>,
4109<A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A>
4110
902da432 4111
30eb152d 4112<!-- NEW PAGE --><H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2>
902da432 4113
4114<H3>Usage</H3>
4115
30eb152d 4116<PRE>
4117cups_raster_t *
4118cupsRasterOpen(int fd,
4119 cups_mode_t mode);
4120</PRE>
4121
902da432 4122<H3>Arguments</H3>
4123
03efb52b 4124<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4125<TR>
4126 <TH>Argument</TH>
4127 <TH>Description</TH>
4128</TR>
4129<TR>
30eb152d 4130 <TD>fd</TD>
4131 <TD>The file descriptor to use.</TD>
4132</TR>
4133<TR>
4134 <TD>mode</TD>
4135 <TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or
4136 <CODE>CUPS_RASTER_WRITE</CODE>.</TD>
902da432 4137</TR>
4138</TABLE></CENTER>
4139
4140<H3>Returns</H3>
4141
30eb152d 4142<P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an error.
4143
902da432 4144<H3>Description</H3>
4145
30eb152d 4146<P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or writing.
4147
03efb52b 4148<H3>Example</H3>
902da432 4149
30eb152d 4150<PRE>
4151#include &lt;cups/raster.h&gt;
4152
4153cups_raster_t *ras;
4154
4155...
4156
4157ras = cupsRasterOpen(0, CUPS_RASTER_READ);
4158</PRE>
4159
902da432 4160<H3>See Also</H3>
4161
30eb152d 4162<P>
4163<A HREF="#cupsRasterClose">cupsRasterClose()</A>,
4164<A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A>,
4165<A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A>,
4166<A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A>,
4167<A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A>
902da432 4168
30eb152d 4169<!-- NEW PAGE --><H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2>
902da432 4170
4171<H3>Usage</H3>
4172
30eb152d 4173<PRE>
4174unsigned
4175cupsRasterReadHeader(cups_raster_t *ras,
4176 cups_page_header_t *header);
4177</PRE>
4178
902da432 4179<H3>Arguments</H3>
4180
03efb52b 4181<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4182<TR>
4183 <TH>Argument</TH>
4184 <TH>Description</TH>
4185</TR>
4186<TR>
30eb152d 4187 <TD>ras</TD>
4188 <TD>The raster stream to read from.</TD>
4189</TR>
4190<TR>
4191 <TD>header</TD>
4192 <TD>A pointer to a page header structure to read into.</TD>
902da432 4193</TR>
4194</TABLE></CENTER>
4195
4196<H3>Returns</H3>
4197
30eb152d 4198<P>1 on success, 0 on EOF or error.
4199
902da432 4200<H3>Description</H3>
4201
30eb152d 4202<P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the specified
4203raster stream.
4204
03efb52b 4205<H3>Example</H3>
902da432 4206
30eb152d 4207<PRE>
4208#include &lt;cups/raster.h&gt;
4209
4210int line;
4211cups_raster_t *ras;
4212cups_raster_header_t header;
4213unsigned char pixels[8192];
4214...
4215
4216while (cupsRasterReadHeader(ras, &amp;header))
4217{
4218 ...
4219
4220 for (line = 0; line &lt; header.cupsHeight; line ++)
4221 {
4222 cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
4223
4224 ...
4225 }
4226}
4227</PRE>
4228
902da432 4229<H3>See Also</H3>
4230
30eb152d 4231<P>
4232<A HREF="#cupsRasterClose">cupsRasterClose()</A>,
4233<A HREF="#cupsRasterOpen">cupsRasterOpen()</A>,
4234<A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A>,
4235<A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A>,
4236<A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A>
902da432 4237
30eb152d 4238<!-- NEW PAGE --><H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2>
902da432 4239
4240<H3>Usage</H3>
4241
30eb152d 4242<PRE>
4243unsigned
4244cupsRasterReadPixels(cups_raster_t *ras,
4245 unsigned char *pixels,
4246 unsigned length);
4247</PRE>
4248
902da432 4249<H3>Arguments</H3>
4250
03efb52b 4251<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4252<TR>
4253 <TH>Argument</TH>
4254 <TH>Description</TH>
4255</TR>
4256<TR>
30eb152d 4257 <TD>ras</TD>
4258 <TD>The raster stream to read from.</TD>
4259</TR>
4260<TR>
4261 <TD>pixels</TD>
4262 <TD>The pointer to a pixel buffer.</TD>
4263</TR>
4264<TR>
4265 <TD>length</TD>
4266 <TD>The number of bytes of pixel data to read.</TD>
902da432 4267</TR>
4268</TABLE></CENTER>
4269
4270<H3>Returns</H3>
4271
30eb152d 4272<P>The number of bytes read or 0 on EOF or error.
4273
902da432 4274<H3>Description</H3>
4275
30eb152d 4276<P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the specified
4277raster stream.
4278
03efb52b 4279<H3>Example</H3>
902da432 4280
30eb152d 4281<PRE>
4282#include &lt;cups/raster.h&gt;
4283
4284int line;
4285cups_raster_t *ras;
4286cups_raster_header_t header;
4287unsigned char pixels[8192];
4288...
4289
4290while (cupsRasterReadHeader(ras, &amp;header))
4291{
4292 ...
4293
4294 for (line = 0; line &lt; header.cupsHeight; line ++)
4295 {
4296 cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
4297
4298 ...
4299 }
4300}
4301</PRE>
4302
902da432 4303<H3>See Also</H3>
4304
30eb152d 4305<P>
4306<A HREF="#cupsRasterClose">cupsRasterClose()</A>,
4307<A HREF="#cupsRasterOpen">cupsRasterOpen()</A>,
4308<A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A>,
4309<A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A>,
4310<A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A>
902da432 4311
30eb152d 4312<!-- NEW PAGE --><H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2>
902da432 4313
4314<H3>Usage</H3>
4315
30eb152d 4316<PRE>
4317unsigned
4318cupsRasterWriteHeader(cups_raster_t *ras,
4319 cups_page_header_t *header);
4320</PRE>
4321
902da432 4322<H3>Arguments</H3>
4323
03efb52b 4324<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4325<TR>
4326 <TH>Argument</TH>
4327 <TH>Description</TH>
4328</TR>
4329<TR>
30eb152d 4330 <TD>ras</TD>
4331 <TD>The raster stream to write to.</TD>
4332</TR>
4333<TR>
4334 <TD>header</TD>
4335 <TD>A pointer to the page header to write.</TD>
902da432 4336</TR>
4337</TABLE></CENTER>
4338
4339<H3>Returns</H3>
4340
30eb152d 4341<P>1 on success, 0 on error.
4342
902da432 4343<H3>Description</H3>
4344
30eb152d 4345<P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header to
4346a raster stream.
4347
03efb52b 4348<H3>Example</H3>
902da432 4349
30eb152d 4350<PRE>
4351#include &lt;cups/raster.h&gt;
4352
4353int line;
4354cups_raster_t *ras;
4355cups_raster_header_t header;
4356unsigned char pixels[8192];
4357...
4358
4359cupsRasterWriteHeader(ras, &amp;header);
4360
4361for (line = 0; line &lt; header.cupsHeight; line ++)
4362{
4363 ...
4364
4365 cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
4366}
4367</PRE>
4368
902da432 4369<H3>See Also</H3>
4370
30eb152d 4371<P>
4372<A HREF="#cupsRasterClose">cupsRasterClose()</A>,
4373<A HREF="#cupsRasterOpen">cupsRasterOpen()</A>,
4374<A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A>,
4375<A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A>,
4376<A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A>
902da432 4377
30eb152d 4378<!-- NEW PAGE --><H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2>
902da432 4379
4380<H3>Usage</H3>
4381
30eb152d 4382<PRE>
4383unsigned
4384cupsRasterWritePixels(cups_raster_t *ras,
4385 unsigned char *pixels,
4386 unsigned length);
4387</PRE>
4388
902da432 4389<H3>Arguments</H3>
4390
03efb52b 4391<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4392<TR>
4393 <TH>Argument</TH>
4394 <TH>Description</TH>
4395</TR>
4396<TR>
30eb152d 4397 <TD>ras</TD>
4398 <TD>The raster stream to write to.</TD>
4399</TR>
4400<TR>
4401 <TD>pixels</TD>
4402 <TD>The pixel data to write.</TD>
4403</TR>
4404<TR>
4405 <TD>length</TD>
4406 <TD>The number of bytes to write.</TD>
902da432 4407</TR>
4408</TABLE></CENTER>
4409
4410<H3>Returns</H3>
4411
30eb152d 4412<P>The number of bytes written.
4413
902da432 4414<H3>Description</H3>
4415
30eb152d 4416<P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data to a
4417raster stream.
4418
03efb52b 4419<H3>Example</H3>
902da432 4420
30eb152d 4421<PRE>
4422#include &lt;cups/raster.h&gt;
4423
4424int line;
4425cups_raster_t *ras;
4426cups_raster_header_t header;
4427unsigned char pixels[8192];
4428...
4429
4430cupsRasterWriteHeader(ras, &amp;header);
4431
4432for (line = 0; line &lt; header.cupsHeight; line ++)
4433{
4434 ...
4435
4436 cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
4437}
4438</PRE>
4439
902da432 4440<H3>See Also</H3>
4441
30eb152d 4442<P>
4443<A HREF="#cupsRasterClose">cupsRasterClose()</A>,
4444<A HREF="#cupsRasterOpen">cupsRasterOpen()</A>,
4445<A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A>,
4446<A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A>,
4447<A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A>
4448
4449<!-- NEW PAGE --><H2><A NAME="cupsServer">cupsServer()</A></H2>
4450
4451<H3>Usage</H3>
4452
4453<PRE>
4454const char *
4455cupsServer(void);
4456</PRE>
4457
4458<H3>Returns</H3>
4459
4460<P>A pointer to the default server name.
4461
4462<H3>Description</H3>
4463
4464<P><CODE>cupsServer()</CODE> returns a pointer to the default server name.
4465The server name is stored in a static location and will be overwritten with
4466every call to <CODE>cupsServer()</CODE>
902da432 4467
30eb152d 4468<P>The default server is determined from the following locations:
902da432 4469
30eb152d 4470<OL>
902da432 4471
30eb152d 4472 <LI>The <CODE>CUPS_SERVER</CODE> environment variable,
902da432 4473
30eb152d 4474 <LI>The <CODE>ServerName</CODE> directive in the
70bb1290 4475 <VAR>client.conf</VAR> file,
902da432 4476
30eb152d 4477 <LI>The default host, "localhost".
902da432 4478
30eb152d 4479</OL>
902da432 4480
03efb52b 4481<H3>Example</H3>
902da432 4482
30eb152d 4483<PRE>
4484#include &lt;cups/cups.h&gt;
4485
4486const char *server;
4487
4488server = cupsServer();
4489</PRE>
4490
902da432 4491<H3>See Also</H3>
4492
30eb152d 4493<P>
4494<A HREF="#cupsGetPassword">cupsGetPassword()</A>,
ebd737f3 4495<A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A>,
4496<A HREF="#cupsSetServer">cupsSetServer()</A>,
4497<A HREF="#cupsSetUser">cupsSetUser()</A>,
30eb152d 4498<A HREF="#cupsUser">cupsUser()</A>
902da432 4499
ebd737f3 4500<!-- NEW PAGE --><H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2>
4501
4502<H3>Usage</H3>
4503
4504<PRE>
4505void
4506cupsSetPasswordCB(const char *(*cb)(const char *prompt));
4507</PRE>
4508
4509<H3>Arguments</H3>
4510
4511<CENTER><TABLE WIDTH="80%" BORDER>
4512<TR>
4513 <TH>Argument</TH>
4514 <TH>Description</TH>
4515</TR>
4516<TR>
4517 <TD>cb</TD>
4518 <TD>The password callback function.</TD>
4519</TR>
4520</TABLE></CENTER>
4521
4522<H3>Description</H3>
4523
4524<P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use when
4525asking the user for a password. The callback function must accept a single
4526character string pointer (the prompt string) and return <CODE>NULL</CODE>
4527if the user did not enter a password string or a pointer to the password
4528string otherwise.
4529
4530<H3>Example</H3>
4531
4532<PRE>
4533#include &lt;cups/cups.h&gt;
4534
4535const char *
4536my_password_cb(const char *prompt)
4537{
4538 return (getpass(prompt));
4539}
4540
4541...
4542
4543char *password;
4544
4545...
4546
4547cupsSetPasswordCB(my_password_cb);
4548password = cupsGetPassword("Please enter a password:");
4549</PRE>
4550
4551<H3>See Also</H3>
4552
4553<P>
4554<A HREF="#cupsServer">cupsServer()</A>,
4555<A HREF="#cupsSetServer">cupsSetServer()</A>,
4556<A HREF="#cupsSetUser">cupsSetUser()</A>,
4557<A HREF="#cupsUser()">cupsUser()</A>
4558
4559<!-- NEW PAGE --><H2><A NAME="cupsSetServer">cupsSetServer()</A></H2>
4560
4561<H3>Usage</H3>
4562
4563<PRE>
4564void
4565cupsSetServer(const char *server);
4566</PRE>
4567
4568<H3>Arguments</H3>
4569
4570<CENTER><TABLE WIDTH="80%" BORDER>
4571<TR>
4572 <TH>Argument</TH>
4573 <TH>Description</TH>
4574</TR>
4575<TR>
4576 <TD>server</TD>
4577 <TD>The default server to use.</TD>
4578</TR>
4579</TABLE></CENTER>
4580
4581<H3>Description</H3>
4582
4583<P><CODE>cupsSetServer()</CODE> sets the default server to use for
4584the CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>,
4585the default server is used.
4586
4587<H3>Example</H3>
4588
4589<PRE>
4590#include &lt;cups/cups.h&gt;
4591
4592cupsSetServer("foo.bar.com");
4593</PRE>
4594
4595<H3>See Also</H3>
4596
4597<P>
4598<A HREF="#cupsServer">cupsServer()</A>,
4599<A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A>,
4600<A HREF="#cupsSetUser">cupsSetUser()</A>,
4601<A HREF="#cupsUser()">cupsUser()</A>
4602
4603<!-- NEW PAGE --><H2><A NAME="cupsSetUser">cupsSetUser()</A></H2>
4604
4605<H3>Usage</H3>
4606
4607<PRE>
4608void
4609cupsSetUser(const char *user);
4610</PRE>
4611
4612<H3>Arguments</H3>
4613
4614<CENTER><TABLE WIDTH="80%" BORDER>
4615<TR>
4616 <TH>Argument</TH>
4617 <TH>Description</TH>
4618</TR>
4619<TR>
4620 <TD>user</TD>
4621 <TD>The user name string to use.</TD>
4622</TR>
4623</TABLE></CENTER>
4624
4625<H3>Description</H3>
4626
4627<P><CODE>cupsSetUser()</CODE> sets the default user name for authentication.
4628If the <CODE>user</CODE> argument is <CODE>NULL</CODE> then the current
4629login user is used.
4630
4631<H3>Example</H3>
4632
4633<PRE>
4634#include &lt;cups/cups.h&gt;
4635
4636...
4637
4638cupsSetUser("root");
4639</PRE>
4640
4641<H3>See Also</H3>
4642
4643<P>
4644<A HREF="#cupsServer">cupsServer()</A>,
4645<A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A>,
4646<A HREF="#cupsSetServer">cupsSetServer()</A>,
4647<A HREF="#cupsUser()">cupsUser()</A>
4648
30eb152d 4649<!-- NEW PAGE --><H2><A NAME="cupsTempFile">cupsTempFile()</A></H2>
902da432 4650
4651<H3>Usage</H3>
4652
30eb152d 4653<PRE>
4654char *
4655cupsTempFile(char *filename,
4656 int length);
4657</PRE>
4658
902da432 4659<H3>Arguments</H3>
4660
03efb52b 4661<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4662<TR>
4663 <TH>Argument</TH>
4664 <TH>Description</TH>
4665</TR>
4666<TR>
30eb152d 4667 <TD>filename</TD>
4668 <TD>The character string to hold the temporary filename.</TD>
4669</TR>
4670<TR>
4671 <TD>length</TD>
4672 <TD>The size of the filename string in bytes.</TD>
902da432 4673</TR>
4674</TABLE></CENTER>
4675
4676<H3>Returns</H3>
4677
30eb152d 4678<P>A pointer to <CODE>filename</CODE>.
4679
902da432 4680<H3>Description</H3>
4681
30eb152d 4682<P><CODE>cupsTempFile()</CODE> generates a temporary filename for the
4683<VAR>/var/tmp</VAR> directory or the directory specified by the
4684<CODE>TMPDIR</CODE> environment variable.
4685
03efb52b 4686<H3>Example</H3>
902da432 4687
30eb152d 4688<PRE>
4689#include &lt;cups/cups.h&gt;
902da432 4690
30eb152d 4691char filename[256];
902da432 4692
30eb152d 4693cupsTempFile(filename, sizeof(filename));
4694</PRE>
902da432 4695
30eb152d 4696<!-- NEW PAGE --><H2><A NAME="cupsUser">cupsUser()</A></H2>
902da432 4697
30eb152d 4698<H3>Usage</H3>
902da432 4699
30eb152d 4700<PRE>
4701const char *
4702cupsUser(void);
4703</PRE>
902da432 4704
4705<H3>Returns</H3>
4706
30eb152d 4707<P>A pointer to the current username or <CODE>NULL</CODE> if the user ID is
4708undefined.
4709
902da432 4710<H3>Description</H3>
4711
30eb152d 4712<P><CODE>cupsUser()</CODE> returns the name associated with the current
4713user ID as reported by the <CODE>getuid()</CODE> system call.
4714
03efb52b 4715<H3>Example</H3>
902da432 4716
30eb152d 4717<PRE>
4718#include &lt;cups/cups.h&gt;
4719
4720const char *user;
4721
4722user = cupsUser();
4723</PRE>
4724
902da432 4725<H3>See Also</H3>
4726
30eb152d 4727<P>
4728<A HREF="#cupsGetPassword">cupsGetPassword()</A>,
4729<A HREF="#cupsServer">cupsServer()</A>
902da432 4730
30eb152d 4731<!-- NEW PAGE --><H2><A NAME="httpBlocking">httpBlocking()</A></H2>
902da432 4732
4733<H3>Usage</H3>
4734
30eb152d 4735<PRE>
70bb1290 4736void httpBlocking(http_t *http, int blocking)
30eb152d 4737</PRE>
4738
902da432 4739<H3>Arguments</H3>
4740
03efb52b 4741<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4742<TR>
4743 <TH>Argument</TH>
4744 <TH>Description</TH>
4745</TR>
4746<TR>
70bb1290 4747 <TD>http</TD>
4748 <TD>The HTTP connection</TD>
4749</TR>
4750<TR>
4751 <TD>blocking</TD>
4752 <TD>0 if the connection should be non-blocking, 1 if it should
4753 be blocking</TD>
902da432 4754</TR>
4755</TABLE></CENTER>
4756
902da432 4757<H3>Description</H3>
4758
70bb1290 4759<P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for the
4760HTTP connection. By default HTTP connections will block (stop) the client
4761program until data is available or can be sent to the server.
4762
03efb52b 4763<H3>Example</H3>
902da432 4764
30eb152d 4765<PRE>
70bb1290 4766#include &lt;cups/http.h&gt;
4767
4768http_t *http;
4769
4770http = httpConnect("server", port);
4771httpBlocking(http, 0);
30eb152d 4772</PRE>
4773
902da432 4774<H3>See Also</H3>
4775
70bb1290 4776<A HREF="#httpCheck"><CODE>httpCheck()</CODE></A>,
4777<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
902da432 4778
30eb152d 4779<!-- NEW PAGE --><H2><A NAME="httpCheck">httpCheck()</A></H2>
902da432 4780
4781<H3>Usage</H3>
4782
30eb152d 4783<PRE>
70bb1290 4784int httpCheck(http_t *http);
30eb152d 4785</PRE>
4786
902da432 4787<H3>Arguments</H3>
4788
03efb52b 4789<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4790<TR>
4791 <TH>Argument</TH>
4792 <TH>Description</TH>
4793</TR>
4794<TR>
70bb1290 4795 <TD>http</TD>
4796 <TD>The HTTP connection</TD>
902da432 4797</TR>
4798</TABLE></CENTER>
4799
4800<H3>Returns</H3>
4801
70bb1290 4802<P>0 if there is no data pending, 1 otherwise.
4803
902da432 4804<H3>Description</H3>
4805
70bb1290 4806<P>The <CODE>httpCheck()</CODE> function checks to see if there is any data
4807pending on an HTTP connection.
4808
03efb52b 4809<H3>Example</H3>
902da432 4810
30eb152d 4811<PRE>
70bb1290 4812#include &lt;cups/http.h&gt;
4813
4814http_t *http;
4815
4816if (httpCheck(http))
4817{
4818 ... do something ...
4819}
30eb152d 4820</PRE>
4821
902da432 4822<H3>See Also</H3>
4823
70bb1290 4824<A HREF="#httpBlocking"><CODE>httpBlocking()</CODE></A>,
4825<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
4826<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
4827<A HREF="#httpRead"><CODE>httpRead()</CODE></A>
4828
902da432 4829
30eb152d 4830<!-- NEW PAGE --><H2><A NAME="httpClearFields">httpClearFields()</A></H2>
902da432 4831
4832<H3>Usage</H3>
4833
30eb152d 4834<PRE>
70bb1290 4835void httpClearFields(http_t *http)
30eb152d 4836</PRE>
4837
902da432 4838<H3>Arguments</H3>
4839
03efb52b 4840<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4841<TR>
4842 <TH>Argument</TH>
4843 <TH>Description</TH>
4844</TR>
4845<TR>
70bb1290 4846 <TD>http</TD>
4847 <TD>The HTTP connection</TD>
902da432 4848</TR>
4849</TABLE></CENTER>
4850
902da432 4851<H3>Description</H3>
4852
70bb1290 4853<P>The <CODE>httpClearFields()</CODE> function clears all HTTP request fields
4854for the HTTP connection.
4855
03efb52b 4856<H3>Example</H3>
902da432 4857
30eb152d 4858<PRE>
70bb1290 4859#include &lt;cups/http.h&gt;
4860
4861http_t *http;
4862
4863httpClearFields(http);
30eb152d 4864</PRE>
4865
902da432 4866<H3>See Also</H3>
4867
70bb1290 4868<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
4869<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>,
4870<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
902da432 4871
30eb152d 4872<!-- NEW PAGE --><H2><A NAME="httpClose">httpClose()</A></H2>
902da432 4873
4874<H3>Usage</H3>
4875
30eb152d 4876<PRE>
70bb1290 4877void httpClose(http_t *http);
30eb152d 4878</PRE>
4879
902da432 4880<H3>Arguments</H3>
4881
03efb52b 4882<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4883<TR>
4884 <TH>Argument</TH>
4885 <TH>Description</TH>
4886</TR>
4887<TR>
70bb1290 4888 <TD>http</TD>
4889 <TD>The HTTP connection</TD>
902da432 4890</TR>
4891</TABLE></CENTER>
4892
902da432 4893<H3>Description</H3>
4894
70bb1290 4895<P>The <CODE>httpClose()</CODE> function closes an active HTTP connection.
4896
03efb52b 4897<H3>Example</H3>
902da432 4898
30eb152d 4899<PRE>
70bb1290 4900#include &lt;cups/http.h&gt;
4901
4902http_t *http;
4903
4904httpClose(http);
30eb152d 4905</PRE>
4906
902da432 4907<H3>See Also</H3>
4908
70bb1290 4909<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
902da432 4910
30eb152d 4911<!-- NEW PAGE --><H2><A NAME="httpConnect">httpConnect()</A></H2>
902da432 4912
4913<H3>Usage</H3>
4914
30eb152d 4915<PRE>
70bb1290 4916http_t *httpConnect(const char *hostname, int port);
30eb152d 4917</PRE>
4918
902da432 4919<H3>Arguments</H3>
4920
03efb52b 4921<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4922<TR>
4923 <TH>Argument</TH>
4924 <TH>Description</TH>
4925</TR>
4926<TR>
70bb1290 4927 <TD>hostname</TD>
4928 <TD>The name or IP address of the server to connect to</TD>
4929</TR>
4930<TR>
4931 <TD>port</TD>
4932 <TD>The port number to use</TD>
902da432 4933</TR>
4934</TABLE></CENTER>
4935
4936<H3>Returns</H3>
4937
70bb1290 4938<P>A pointer to a HTTP connection structure or NULL if the connection could
4939not be made.
4940
902da432 4941<H3>Description</H3>
4942
70bb1290 4943<P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to the
4944specified server and port.
4945
03efb52b 4946<H3>Example</H3>
902da432 4947
30eb152d 4948<PRE>
70bb1290 4949#include &lt;cups/http.h&gt;
4950
4951http_t *http;
4952
4953http = httpConnect(cupsServer(), ippPort());
30eb152d 4954</PRE>
4955
902da432 4956<H3>See Also</H3>
4957
70bb1290 4958<A HREF="#httpClose"><CODE>httpClose()</CODE></A>,
4959<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
4960<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
4961<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
4962<A HREF="#httpRead"><CODE>httpRead()</CODE></A>,
4963<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
4964
902da432 4965
30eb152d 4966<!-- NEW PAGE --><H2><A NAME="httpDecode64">httpDecode64()</A></H2>
902da432 4967
4968<H3>Usage</H3>
4969
30eb152d 4970<PRE>
70bb1290 4971char *httpDecode64(char *out, const char *in);
30eb152d 4972</PRE>
4973
902da432 4974<H3>Arguments</H3>
4975
03efb52b 4976<CENTER><TABLE WIDTH="80%" BORDER>
902da432 4977<TR>
4978 <TH>Argument</TH>
4979 <TH>Description</TH>
4980</TR>
4981<TR>
70bb1290 4982 <TD>out</TD>
4983 <TD>The output string</TD>
902da432 4984</TR>
4985<TR>
70bb1290 4986 <TD>in</TD>
4987 <TD>The input string</TD>
902da432 4988</TR>
4989</TABLE></CENTER>
4990
4991<H3>Returns</H3>
4992
70bb1290 4993<P>A pointer to the decoded string.
4994
902da432 4995<H3>Description</H3>
4996
70bb1290 4997<P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded string
4998to the original string.
4999
03efb52b 5000<H3>Example</H3>
902da432 5001
30eb152d 5002<PRE>
70bb1290 5003#include &lt;cups/http.h&gt;
5004
5005char encoded_string[255];
5006char original_string[255];
5007
5008httpDecode64(original_string, encoded_string);
30eb152d 5009</PRE>
5010
902da432 5011<H3>See Also</H3>
5012
70bb1290 5013<A HREF="#httpEncode64"><CODE>httpEncode64()</CODE></A>
902da432 5014
70bb1290 5015<!-- NEW PAGE --><H2><A NAME="httpDelete">httpDelete()</A></H2>
902da432 5016
5017<H3>Usage</H3>
5018
30eb152d 5019<PRE>
70bb1290 5020int httpDelete(http_t *http, const char *uri);
30eb152d 5021</PRE>
5022
902da432 5023<H3>Arguments</H3>
5024
03efb52b 5025<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5026<TR>
5027 <TH>Argument</TH>
5028 <TH>Description</TH>
5029</TR>
5030<TR>
70bb1290 5031 <TD>http</TD>
5032 <TD>The HTTP connection</TD>
5033</TR>
5034<TR>
5035 <TD>uri</TD>
5036 <TD>The URI to delete</TD>
902da432 5037</TR>
5038</TABLE></CENTER>
5039
5040<H3>Returns</H3>
5041
70bb1290 5042<P>0 on success, non-zero on failure.
5043
902da432 5044<H3>Description</H3>
5045
70bb1290 5046<P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to
5047the server.
5048
03efb52b 5049<H3>Example</H3>
902da432 5050
30eb152d 5051<PRE>
70bb1290 5052#include &lt;cups/http.h&gt;
5053
5054http_t *http;
5055
5056httpDelete(http, "/some/uri");
30eb152d 5057</PRE>
5058
902da432 5059<H3>See Also</H3>
5060
70bb1290 5061<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5062<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
5063<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
902da432 5064
70bb1290 5065<!-- NEW PAGE --><H2><A NAME="httpEncode64">httpEncode64()</A></H2>
902da432 5066
5067<H3>Usage</H3>
5068
30eb152d 5069<PRE>
70bb1290 5070char *httpEncode64(char *out, const char *in);
30eb152d 5071</PRE>
5072
902da432 5073<H3>Arguments</H3>
5074
03efb52b 5075<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5076<TR>
5077 <TH>Argument</TH>
5078 <TH>Description</TH>
5079</TR>
5080<TR>
70bb1290 5081 <TD>out</TD>
5082 <TD>The output string</TD>
5083</TR>
5084<TR>
5085 <TD>in</TD>
5086 <TD>The input string</TD>
902da432 5087</TR>
5088</TABLE></CENTER>
5089
5090<H3>Returns</H3>
5091
70bb1290 5092<P>A pointer to the encoded string.
5093
902da432 5094<H3>Description</H3>
5095
70bb1290 5096<P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded string
5097to the original string.
5098
03efb52b 5099<H3>Example</H3>
902da432 5100
30eb152d 5101<PRE>
70bb1290 5102#include &lt;cups/http.h&gt;
5103
5104char encoded_string[255];
5105char original_string[255];
5106
5107httpEncode64(encoded_string, original_string);
30eb152d 5108</PRE>
5109
902da432 5110<H3>See Also</H3>
5111
70bb1290 5112<A HREF="#httpDecode64"><CODE>httpDecode64()</CODE></A>
902da432 5113
70bb1290 5114<!-- NEW PAGE --><H2><A NAME="httpError">httpError()</A></H2>
902da432 5115
5116<H3>Usage</H3>
5117
30eb152d 5118<PRE>
70bb1290 5119int httpError(http_t *http);
30eb152d 5120</PRE>
5121
902da432 5122<H3>Arguments</H3>
5123
03efb52b 5124<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5125<TR>
5126 <TH>Argument</TH>
5127 <TH>Description</TH>
5128</TR>
5129<TR>
70bb1290 5130 <TD>http</TD>
5131 <TD>The HTTP connection</TD>
902da432 5132</TR>
5133</TABLE></CENTER>
5134
5135<H3>Returns</H3>
5136
70bb1290 5137<P>The last error that occurred or 0 if no error has occurred.
5138
902da432 5139<H3>Description</H3>
5140
70bb1290 5141<P>The <CODE>httpError()</CODE> function returns the last error that occurred
5142on the HTTP connection.
5143
03efb52b 5144<H3>Example</H3>
902da432 5145
30eb152d 5146<PRE>
70bb1290 5147#include &lt;cups/http.h&gt;
5148
5149http_t *http;
5150
5151if (httpError(http))
5152{
5153 ... show an error message ...
5154}
30eb152d 5155</PRE>
5156
902da432 5157<H3>See Also</H3>
5158
70bb1290 5159<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
902da432 5160
70bb1290 5161<!-- NEW PAGE --><H2><A NAME="httpFlush">httpFlush()</A></H2>
902da432 5162
5163<H3>Usage</H3>
5164
30eb152d 5165<PRE>
70bb1290 5166void httpFlush(http_t *http);
30eb152d 5167</PRE>
5168
902da432 5169<H3>Arguments</H3>
5170
03efb52b 5171<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5172<TR>
5173 <TH>Argument</TH>
5174 <TH>Description</TH>
5175</TR>
5176<TR>
70bb1290 5177 <TD>http</TD>
5178 <TD>The HTTP connection</TD>
902da432 5179</TR>
5180</TABLE></CENTER>
5181
902da432 5182<H3>Description</H3>
5183
70bb1290 5184<P>The <CODE>httpFlush()</CODE> function flushes any remaining data left from
5185a GET or POST operation.
5186
03efb52b 5187<H3>Example</H3>
902da432 5188
30eb152d 5189<PRE>
70bb1290 5190#include &lt;cups/http.h&gt;
5191
5192http_t *http;
5193
5194httpFlush(http);
30eb152d 5195</PRE>
5196
902da432 5197<H3>See Also</H3>
5198
70bb1290 5199<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
902da432 5200
70bb1290 5201<!-- NEW PAGE --><H2><A NAME="httpGet">httpGet()</A></H2>
902da432 5202
5203<H3>Usage</H3>
5204
30eb152d 5205<PRE>
70bb1290 5206int httpGet(http_t *http, const char *uri);
30eb152d 5207</PRE>
5208
902da432 5209<H3>Arguments</H3>
5210
03efb52b 5211<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5212<TR>
5213 <TH>Argument</TH>
5214 <TH>Description</TH>
5215</TR>
5216<TR>
70bb1290 5217 <TD>http</TD>
5218 <TD>The HTTP connection</TD>
5219</TR>
5220<TR>
5221 <TD>uri</TD>
5222 <TD>The URI to get</TD>
902da432 5223</TR>
5224</TABLE></CENTER>
5225
5226<H3>Returns</H3>
5227
70bb1290 5228<P>0 on success, non-zero on failure.
5229
902da432 5230<H3>Description</H3>
5231
70bb1290 5232<P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the
5233server.
5234
03efb52b 5235<H3>Example</H3>
902da432 5236
30eb152d 5237<PRE>
70bb1290 5238#include &lt;cups/http.h&gt;
5239
5240http_t *http;
5241
5242httpGet(http, "/some/uri");
30eb152d 5243</PRE>
5244
902da432 5245<H3>See Also</H3>
5246
70bb1290 5247<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5248<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
5249<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
902da432 5250
70bb1290 5251
5252<!-- NEW PAGE --><H2><A NAME="httpGets">httpGets()</A></H2>
902da432 5253
5254<H3>Usage</H3>
5255
30eb152d 5256<PRE>
70bb1290 5257char *httpGets(char *line, int length, http_t *http)
30eb152d 5258</PRE>
5259
902da432 5260<H3>Arguments</H3>
5261
03efb52b 5262<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5263<TR>
5264 <TH>Argument</TH>
5265 <TH>Description</TH>
5266</TR>
5267<TR>
70bb1290 5268 <TD>line</TD>
5269 <TD>The string to fill with a line from the HTTP connection</TD>
5270</TR>
5271<TR>
5272 <TD>length</TD>
5273 <TD>The maximum length of the string</TD>
5274</TR>
5275<TR>
5276 <TD>http</TD>
5277 <TD>The HTTP connection</TD>
902da432 5278</TR>
5279</TABLE></CENTER>
5280
5281<H3>Returns</H3>
5282
70bb1290 5283<P>A pointer to the string or NULL if no line could be retrieved.
5284
902da432 5285<H3>Description</H3>
5286
70bb1290 5287<P>The <CODE>httpGets()</CODE> function is used to read a request line from
5288the HTTP connection. It is not normally used by a client program.
5289
03efb52b 5290<H3>Example</H3>
902da432 5291
30eb152d 5292<PRE>
70bb1290 5293#include &lt;cups/http.h&gt;
5294
5295http_t *http;
5296char line[1024];
5297
5298if (httpGets(line, sizeof(line), http))
5299{
5300 ... process the line ...
5301}
30eb152d 5302</PRE>
5303
902da432 5304<H3>See Also</H3>
5305
70bb1290 5306<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5307<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
902da432 5308
70bb1290 5309<!-- NEW PAGE --><H2><A NAME="httpGetDateString">httpGetDateString()</A></H2>
902da432 5310
5311<H3>Usage</H3>
5312
30eb152d 5313<PRE>
70bb1290 5314const char *httpGetDateString(time_t time)
30eb152d 5315</PRE>
5316
902da432 5317<H3>Arguments</H3>
5318
03efb52b 5319<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5320<TR>
5321 <TH>Argument</TH>
5322 <TH>Description</TH>
5323</TR>
5324<TR>
70bb1290 5325 <TD>time</TD>
5326 <TD>The UNIX date/time value</TD>
902da432 5327</TR>
5328</TABLE></CENTER>
5329
5330<H3>Returns</H3>
5331
70bb1290 5332<P>A pointer to a static string containing the HTTP date/time string for
5333the specified UNIX time value.
5334
902da432 5335<H3>Description</H3>
5336
70bb1290 5337<P>The <CODE>httpGetDateString()</CODE> function generates a date/time string
5338suitable for HTTP requests from a UNIX time value.
5339
03efb52b 5340<H3>Example</H3>
902da432 5341
30eb152d 5342<PRE>
70bb1290 5343#include &lt;cups/http.h&gt;
5344
5345puts(httpGetDateString(time(NULL)));
30eb152d 5346</PRE>
5347
902da432 5348<H3>See Also</H3>
5349
70bb1290 5350<A HREF="#httpGetDateTime"><CODE>httpGetDateTime()</CODE></A>
902da432 5351
70bb1290 5352
5353<!-- NEW PAGE --><H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2>
902da432 5354
5355<H3>Usage</H3>
5356
30eb152d 5357<PRE>
70bb1290 5358time_t httpGetDateTime(const char *date)
30eb152d 5359</PRE>
5360
902da432 5361<H3>Arguments</H3>
5362
03efb52b 5363<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5364<TR>
5365 <TH>Argument</TH>
5366 <TH>Description</TH>
5367</TR>
5368<TR>
70bb1290 5369 <TD>date</TD>
5370 <TD>The HTTP date/time string</TD>
902da432 5371</TR>
5372</TABLE></CENTER>
5373
5374<H3>Returns</H3>
5375
70bb1290 5376<P>A UNIX time value.
5377
902da432 5378<H3>Description</H3>
5379
70bb1290 5380<P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP
5381date/time string to a UNIX time value.
5382
03efb52b 5383<H3>Example</H3>
902da432 5384
30eb152d 5385<PRE>
70bb1290 5386#include &lt;cups/http.h&gt;
5387
5388printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
30eb152d 5389</PRE>
5390
902da432 5391<H3>See Also</H3>
5392
70bb1290 5393<A HREF="#httpGetDateString"><CODE>httpGetDateString()</CODE></A>
902da432 5394
70bb1290 5395
5396<!-- NEW PAGE --><H2><A NAME="httpGetField">httpGetField()</A></H2>
902da432 5397
5398<H3>Usage</H3>
5399
30eb152d 5400<PRE>
70bb1290 5401const char *httpGetField(http_t *http, http_field_t field);
30eb152d 5402</PRE>
5403
902da432 5404<H3>Arguments</H3>
5405
03efb52b 5406<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5407<TR>
5408 <TH>Argument</TH>
5409 <TH>Description</TH>
5410</TR>
5411<TR>
70bb1290 5412 <TD>http</TD>
5413 <TD>The HTTP connection</TD>
5414</TR>
5415<TR>
5416 <TD>field</TD>
5417 <TD>The HTTP field</TD>
902da432 5418</TR>
5419</TABLE></CENTER>
5420
5421<H3>Returns</H3>
5422
70bb1290 5423<P>A pointer to the field value string.
5424
902da432 5425<H3>Description</H3>
5426
70bb1290 5427<P>The <CODE>httpGetField()</CODE> function returns the current value for
5428the specified HTTP field.
5429
03efb52b 5430<H3>Example</H3>
902da432 5431
30eb152d 5432<PRE>
70bb1290 5433#include &lt;cups/http.h&gt;
5434
5435http_t *http;
5436
5437httpGet(http, "/some/uri");
5438while (httpUpdate(http) == HTTP_CONTINUE);
5439
5440puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
30eb152d 5441</PRE>
5442
902da432 5443<H3>See Also</H3>
5444
70bb1290 5445<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5446<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
5447
902da432 5448
30eb152d 5449<!-- NEW PAGE --><H2><A NAME="httpHead">httpHead()</A></H2>
902da432 5450
5451<H3>Usage</H3>
5452
30eb152d 5453<PRE>
70bb1290 5454int httpHead(http_t *http, const char *uri);
30eb152d 5455</PRE>
5456
902da432 5457<H3>Arguments</H3>
5458
03efb52b 5459<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5460<TR>
5461 <TH>Argument</TH>
5462 <TH>Description</TH>
5463</TR>
5464<TR>
70bb1290 5465 <TD>http</TD>
5466 <TD>The HTTP connection</TD>
5467</TR>
5468<TR>
5469 <TD>uri</TD>
5470 <TD>The URI to head</TD>
902da432 5471</TR>
5472</TABLE></CENTER>
5473
5474<H3>Returns</H3>
5475
70bb1290 5476<P>0 on success, non-zero on failure.
5477
902da432 5478<H3>Description</H3>
5479
70bb1290 5480<P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the
5481server.
5482
03efb52b 5483<H3>Example</H3>
902da432 5484
30eb152d 5485<PRE>
70bb1290 5486#include &lt;cups/http.h&gt;
5487
5488http_t *http;
5489
5490httpHead(http, "/some/uri");
30eb152d 5491</PRE>
5492
902da432 5493<H3>See Also</H3>
5494
70bb1290 5495<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5496<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
5497<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
5498
902da432 5499
30eb152d 5500<!-- NEW PAGE --><H2><A NAME="httpInitialize">httpInitialize()</A></H2>
902da432 5501
5502<H3>Usage</H3>
5503
30eb152d 5504<PRE>
70bb1290 5505void httpInitialize(void);
30eb152d 5506</PRE>
5507
902da432 5508<H3>Description</H3>
5509
70bb1290 5510<P>The <CODE>httpInitialize()</CODE> function initializes the networking
5511code as needed by the underlying platform. It is called automatically by
5512the <CODE>httpConnect()</CODE> function.
5513
03efb52b 5514<H3>Example</H3>
902da432 5515
30eb152d 5516<PRE>
70bb1290 5517#include &lt;cups/http.h&gt;
5518
5519httpInitialize();
30eb152d 5520</PRE>
5521
902da432 5522<H3>See Also</H3>
5523
70bb1290 5524<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
902da432 5525
30eb152d 5526<!-- NEW PAGE --><H2><A NAME="httpOptions">httpOptions()</A></H2>
902da432 5527
5528<H3>Usage</H3>
5529
30eb152d 5530<PRE>
70bb1290 5531int httpOptions(http_t *http, const char *uri);
30eb152d 5532</PRE>
5533
902da432 5534<H3>Arguments</H3>
5535
03efb52b 5536<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5537<TR>
5538 <TH>Argument</TH>
5539 <TH>Description</TH>
5540</TR>
5541<TR>
70bb1290 5542 <TD>http</TD>
5543 <TD>The HTTP connection</TD>
5544</TR>
5545<TR>
5546 <TD>uri</TD>
5547 <TD>The URI to check for options</TD>
902da432 5548</TR>
5549</TABLE></CENTER>
5550
5551<H3>Returns</H3>
5552
70bb1290 5553<P>0 on success, non-zero on failure.
5554
902da432 5555<H3>Description</H3>
5556
70bb1290 5557<P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request to the
5558server.
5559
03efb52b 5560<H3>Example</H3>
902da432 5561
30eb152d 5562<PRE>
70bb1290 5563#include &lt;cups/http.h&gt;
5564
5565http_t *http;
5566
5567httpOptions(http, "/some/uri");
30eb152d 5568</PRE>
5569
902da432 5570<H3>See Also</H3>
5571
70bb1290 5572<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5573<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
5574<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
5575
902da432 5576
30eb152d 5577<!-- NEW PAGE --><H2><A NAME="httpPost">httpPost()</A></H2>
902da432 5578
5579<H3>Usage</H3>
5580
30eb152d 5581<PRE>
70bb1290 5582int httpPost(http_t *http, const char *uri);
30eb152d 5583</PRE>
5584
902da432 5585<H3>Arguments</H3>
5586
03efb52b 5587<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5588<TR>
5589 <TH>Argument</TH>
5590 <TH>Description</TH>
5591</TR>
5592<TR>
70bb1290 5593 <TD>http</TD>
5594 <TD>The HTTP connection</TD>
5595</TR>
5596<TR>
5597 <TD>uri</TD>
5598 <TD>The URI to post to</TD>
902da432 5599</TR>
5600</TABLE></CENTER>
5601
5602<H3>Returns</H3>
5603
70bb1290 5604<P>0 on success, non-zero on failure.
5605
902da432 5606<H3>Description</H3>
5607
70bb1290 5608<P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the
5609server.
5610
03efb52b 5611<H3>Example</H3>
902da432 5612
30eb152d 5613<PRE>
70bb1290 5614#include &lt;cups/http.h&gt;
5615
5616http_t *http;
5617
5618httpPost(http, "/some/uri");
30eb152d 5619</PRE>
5620
902da432 5621<H3>See Also</H3>
5622
70bb1290 5623<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5624<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
5625<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
5626
902da432 5627
30eb152d 5628<!-- NEW PAGE --><H2><A NAME="httpPrintf">httpPrintf()</A></H2>
902da432 5629
5630<H3>Usage</H3>
5631
30eb152d 5632<PRE>
70bb1290 5633int httpPrintf(http_t *http, const char *format, ...);
30eb152d 5634</PRE>
5635
902da432 5636<H3>Arguments</H3>
5637
03efb52b 5638<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5639<TR>
5640 <TH>Argument</TH>
5641 <TH>Description</TH>
5642</TR>
5643<TR>
70bb1290 5644 <TD>http</TD>
5645 <TD>The HTTP connection</TD>
5646</TR>
5647<TR>
5648 <TD>format</TD>
5649 <TD>A printf-style format string</TD>
902da432 5650</TR>
5651</TABLE></CENTER>
5652
5653<H3>Returns</H3>
5654
70bb1290 5655<P>The number of bytes written.
5656
902da432 5657<H3>Description</H3>
5658
70bb1290 5659<P>The <CODE>httpPrintf()</CODE> function sends a formatted string to the
5660HTTP connection. It is normally only used by the CUPS API and scheduler.
5661
03efb52b 5662<H3>Example</H3>
902da432 5663
30eb152d 5664<PRE>
70bb1290 5665#include &lt;cups/http.h&gt;
5666
5667http_t *http;
5668
5669httpPrintf(http, "GET / HTTP/1.1 \r\n");
30eb152d 5670</PRE>
5671
902da432 5672<H3>See Also</H3>
5673
70bb1290 5674<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
902da432 5675
30eb152d 5676<!-- NEW PAGE --><H2><A NAME="httpPut">httpPut()</A></H2>
902da432 5677
5678<H3>Usage</H3>
5679
30eb152d 5680<PRE>
70bb1290 5681int httpPut(http_t *http, const char *uri);
30eb152d 5682</PRE>
5683
902da432 5684<H3>Arguments</H3>
5685
03efb52b 5686<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5687<TR>
5688 <TH>Argument</TH>
5689 <TH>Description</TH>
5690</TR>
5691<TR>
70bb1290 5692 <TD>http</TD>
5693 <TD>The HTTP connection</TD>
5694</TR>
5695<TR>
5696 <TD>uri</TD>
5697 <TD>The URI to put</TD>
902da432 5698</TR>
5699</TABLE></CENTER>
5700
5701<H3>Returns</H3>
5702
70bb1290 5703<P>0 on success, non-zero on failure.
5704
902da432 5705<H3>Description</H3>
5706
70bb1290 5707<P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the
5708server.
5709
03efb52b 5710<H3>Example</H3>
902da432 5711
30eb152d 5712<PRE>
70bb1290 5713#include &lt;cups/http.h&gt;
5714
5715http_t *http;
5716
5717httpDelete(http, "/some/uri");
30eb152d 5718</PRE>
5719
902da432 5720<H3>See Also</H3>
5721
70bb1290 5722<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5723<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
5724<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
5725
902da432 5726
30eb152d 5727<!-- NEW PAGE --><H2><A NAME="httpRead">httpRead()</A></H2>
902da432 5728
5729<H3>Usage</H3>
5730
30eb152d 5731<PRE>
70bb1290 5732int httpRead(http_t *http, char *buffer, int length);
30eb152d 5733</PRE>
5734
902da432 5735<H3>Arguments</H3>
5736
03efb52b 5737<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5738<TR>
5739 <TH>Argument</TH>
5740 <TH>Description</TH>
5741</TR>
5742<TR>
70bb1290 5743 <TD>http</TD>
5744 <TD>The HTTP connection</TD>
5745</TR>
5746<TR>
5747 <TD>buffer</TD>
5748 <TD>The buffer to read into</TD>
5749</TR>
5750<TR>
5751 <TD>length</TD>
5752 <TD>The number of bytes to read</TD>
902da432 5753</TR>
5754</TABLE></CENTER>
5755
5756<H3>Returns</H3>
5757
70bb1290 5758<P>The number of bytes read or -1 on error.
5759
902da432 5760<H3>Description</H3>
5761
70bb1290 5762<P>The <CODE>httpRead()</CODE> function reads data from the HTTP connection,
5763possibly the result of a GET or POST request.
5764
03efb52b 5765<H3>Example</H3>
902da432 5766
30eb152d 5767<PRE>
70bb1290 5768#include &lt;cups/http.h&gt;
5769
5770http_t *http;
5771char buffer[1024];
5772int bytes;
5773
5774httpGet(http, "/");
5775while (httpUpdate(http) != HTTP_CONTINUE);
5776while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
5777{
5778 buffer[bytes] = '\0';
5779 fputs(buffer, stdout);
5780}
30eb152d 5781</PRE>
5782
902da432 5783<H3>See Also</H3>
5784
70bb1290 5785<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5786<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
902da432 5787
30eb152d 5788<!-- NEW PAGE --><H2><A NAME="httpReconnect">httpReconnect()</A></H2>
902da432 5789
5790<H3>Usage</H3>
5791
30eb152d 5792<PRE>
70bb1290 5793int httpReconnect(http_t *http);
30eb152d 5794</PRE>
5795
902da432 5796<H3>Arguments</H3>
5797
03efb52b 5798<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5799<TR>
5800 <TH>Argument</TH>
5801 <TH>Description</TH>
5802</TR>
5803<TR>
70bb1290 5804 <TD>http</TD>
5805 <TD>The HTTP connection</TD>
902da432 5806</TR>
5807</TABLE></CENTER>
5808
5809<H3>Returns</H3>
5810
70bb1290 5811<P>0 on success, non-zero on failure.
5812
902da432 5813<H3>Description</H3>
5814
70bb1290 5815<P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP server.
5816This is usually done automatically if the HTTP functions detect that the
5817server connection has terminated.
5818
03efb52b 5819<H3>Example</H3>
902da432 5820
30eb152d 5821<PRE>
70bb1290 5822#include &lt;cups/http.h&gt;
5823
5824http_t *http;
5825
5826httpReconnect(http);
30eb152d 5827</PRE>
5828
902da432 5829<H3>See Also</H3>
5830
70bb1290 5831<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
902da432 5832
30eb152d 5833<!-- NEW PAGE --><H2><A NAME="httpSeparate">httpSeparate()</A></H2>
902da432 5834
5835<H3>Usage</H3>
5836
30eb152d 5837<PRE>
70bb1290 5838void httpSeparate(const char *uri, char *method,
5839 char *username, char *host, int *port,
5840 char *resource);
30eb152d 5841</PRE>
5842
902da432 5843<H3>Arguments</H3>
5844
03efb52b 5845<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5846<TR>
5847 <TH>Argument</TH>
5848 <TH>Description</TH>
5849</TR>
5850<TR>
70bb1290 5851 <TD>uri</TD>
5852 <TD>The URI to separate</TD>
5853</TR>
5854<TR>
5855 <TD>method</TD>
5856 <TD>The method (scheme) of the URI</TD>
5857</TR>
5858<TR>
5859 <TD>username</TD>
5860 <TD>The username (and password) portion of the URI, if any</TD>
5861</TR>
5862<TR>
5863 <TD>host</TD>
5864 <TD>The hostname portion of the URI, if any</TD>
5865</TR>
5866<TR>
5867 <TD>port</TD>
5868 <TD>The port number for the URI, either as specified or as
5869 default for the method/scheme</TD>
5870</TR>
5871<TR>
5872 <TD>resource</TD>
5873 <TD>The resource string, usually a filename on the server</TD>
902da432 5874</TR>
5875</TABLE></CENTER>
5876
902da432 5877<H3>Description</H3>
5878
70bb1290 5879<P>The <CODE>httpSeparate()</CODE> function separates the specified URI into
5880its component parts. The method, username, hostname, and resource strings should
5881be at least <CODE>HTTP_MAX_URI</CODE> characters long to avoid potential
5882buffer overflow problems.
5883
03efb52b 5884<H3>Example</H3>
902da432 5885
30eb152d 5886<PRE>
70bb1290 5887char uri[HTTP_MAX_URI];
5888char method[HTTP_MAX_URI];
5889char username[HTTP_MAX_URI];
5890char host[HTTP_MAX_URI];
5891char resource[HTTP_MAX_URI];
5892int port;
5893
5894httpSeparate(uri, method, username, host, &amp;port, resource);
30eb152d 5895</PRE>
5896
902da432 5897<H3>See Also</H3>
5898
70bb1290 5899<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
902da432 5900
30eb152d 5901<!-- NEW PAGE --><H2><A NAME="httpSetField">httpSetField()</A></H2>
902da432 5902
5903<H3>Usage</H3>
5904
30eb152d 5905<PRE>
70bb1290 5906void httpSetField(http_t *http, http_field_t field, const char *value);
30eb152d 5907</PRE>
5908
902da432 5909<H3>Arguments</H3>
5910
03efb52b 5911<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5912<TR>
5913 <TH>Argument</TH>
5914 <TH>Description</TH>
5915</TR>
5916<TR>
70bb1290 5917 <TD>http</TD>
5918 <TD>The HTTP connection</TD>
5919</TR>
5920<TR>
5921 <TD>field</TD>
5922 <TD>The HTTP field</TD>
5923</TR>
5924<TR>
5925 <TD>value</TD>
5926 <TD>The string value for the field</TD>
902da432 5927</TR>
5928</TABLE></CENTER>
5929
902da432 5930<H3>Description</H3>
5931
70bb1290 5932<P>The <CODE>httpSetField()</CODE> function sets the current value for
5933the specified HTTP field.
5934
03efb52b 5935<H3>Example</H3>
902da432 5936
30eb152d 5937<PRE>
70bb1290 5938#include &lt;cups/http.h&gt;
5939
5940http_t *http;
5941
5942httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
5943httpGet(http, "/some/uri");
5944while (httpUpdate(http) == HTTP_CONTINUE);
30eb152d 5945</PRE>
5946
902da432 5947<H3>See Also</H3>
5948
70bb1290 5949<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5950<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>
5951
902da432 5952
30eb152d 5953<!-- NEW PAGE --><H2><A NAME="httpTrace">httpTrace()</A></H2>
902da432 5954
5955<H3>Usage</H3>
5956
30eb152d 5957<PRE>
70bb1290 5958int httpTrace(http_t *http, const char *uri);
30eb152d 5959</PRE>
5960
902da432 5961<H3>Arguments</H3>
5962
03efb52b 5963<CENTER><TABLE WIDTH="80%" BORDER>
902da432 5964<TR>
5965 <TH>Argument</TH>
5966 <TH>Description</TH>
5967</TR>
5968<TR>
70bb1290 5969 <TD>http</TD>
5970 <TD>The HTTP connection</TD>
5971</TR>
5972<TR>
5973 <TD>uri</TD>
5974 <TD>The URI to trace</TD>
902da432 5975</TR>
5976</TABLE></CENTER>
5977
5978<H3>Returns</H3>
5979
70bb1290 5980<P>0 on success, non-zero on failure.
5981
902da432 5982<H3>Description</H3>
5983
70bb1290 5984<P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to the
5985server.
5986
03efb52b 5987<H3>Example</H3>
902da432 5988
30eb152d 5989<PRE>
70bb1290 5990#include &lt;cups/http.h&gt;
5991
5992http_t *http;
5993
5994httpTrace(http, "/some/uri");
30eb152d 5995</PRE>
5996
902da432 5997<H3>See Also</H3>
5998
70bb1290 5999<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6000<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
6001<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6002
902da432 6003
30eb152d 6004<!-- NEW PAGE --><H2><A NAME="httpUpdate">httpUpdate()</A></H2>
902da432 6005
6006<H3>Usage</H3>
6007
30eb152d 6008<PRE>
70bb1290 6009http_status_t httpUpdate(http_t *http);
30eb152d 6010</PRE>
6011
902da432 6012<H3>Arguments</H3>
6013
03efb52b 6014<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6015<TR>
6016 <TH>Argument</TH>
6017 <TH>Description</TH>
6018</TR>
6019<TR>
70bb1290 6020 <TD>http</TD>
6021 <TD>The HTTP connection</TD>
902da432 6022</TR>
6023</TABLE></CENTER>
6024
6025<H3>Returns</H3>
6026
70bb1290 6027<P>The HTTP status of the current request.
6028
902da432 6029<H3>Description</H3>
6030
70bb1290 6031<P>The <CODE>httpUpdate()</CODE> function updates the current request status.
6032It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE
6033request to finalize the HTTP request and retrieve the request status.
6034
6035<P>Since proxies and the current blocking mode can cause the request to
6036take longer, programs should continue calling <CODE>httpUpdate()</CODE>
6037until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>.
6038
03efb52b 6039<H3>Example</H3>
902da432 6040
30eb152d 6041<PRE>
70bb1290 6042#include &lt;cups/http.h&gt;
6043
6044http_t *http;
6045http_status_t status;
6046
6047httpGet(http, "/some/uri");
6048while ((status = httpUpdate(http)) == HTTP_CONTINUE);
6049printf("Request status is %d\n", status);
30eb152d 6050</PRE>
6051
902da432 6052<H3>See Also</H3>
6053
70bb1290 6054<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6055<A HREF="#httpDelete"><CODE>httpDelete()</CODE></A>,
6056<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
6057<A HREF="#httpHead"><CODE>httpHead()</CODE></A>,
6058<A HREF="#httpOptions"><CODE>httpOptions()</CODE></A>,
6059<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
6060<A HREF="#httpPut"><CODE>httpPut()</CODE></A>,
6061<A HREF="#httpTrace"><CODE>httpTrace()</CODE></A>
902da432 6062
30eb152d 6063<!-- NEW PAGE --><H2><A NAME="httpWrite">httpWrite()</A></H2>
902da432 6064
6065<H3>Usage</H3>
6066
30eb152d 6067<PRE>
70bb1290 6068int httpWrite(http_t *http, char *buffer, int length);
30eb152d 6069</PRE>
6070
902da432 6071<H3>Arguments</H3>
6072
03efb52b 6073<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6074<TR>
6075 <TH>Argument</TH>
6076 <TH>Description</TH>
6077</TR>
6078<TR>
70bb1290 6079 <TD>http</TD>
6080 <TD>The HTTP connection</TD>
6081</TR>
6082<TR>
6083 <TD>buffer</TD>
6084 <TD>The buffer to read into</TD>
6085</TR>
6086<TR>
6087 <TD>length</TD>
6088 <TD>The number of bytes to read</TD>
902da432 6089</TR>
6090</TABLE></CENTER>
6091
6092<H3>Returns</H3>
6093
70bb1290 6094<P>The number of bytes read or -1 on error.
6095
902da432 6096<H3>Description</H3>
6097
70bb1290 6098<P>The <CODE>httpWrite()</CODE> function reads data from the HTTP connection,
6099possibly the result of a GET or POST request.
6100
03efb52b 6101<H3>Example</H3>
902da432 6102
30eb152d 6103<PRE>
70bb1290 6104#include &lt;cups/http.h&gt;
6105
6106http_t *http;
6107FILE *fp;
6108char buffer[1024];
6109int bytes;
6110
6111httpPost(http, "/");
6112
6113while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
6114 httpWrite(http, buffer, bytes);
6115
6116while (httpUpdate(http) != HTTP_CONTINUE);
6117
6118while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
6119{
6120 buffer[bytes] = '\0';
6121 fputs(buffer, stdout);
6122}
30eb152d 6123</PRE>
6124
902da432 6125<H3>See Also</H3>
6126
70bb1290 6127<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6128<A HREF="#httpRead"><CODE>httpRead()</CODE></A>
902da432 6129
30eb152d 6130<!-- NEW PAGE --><H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2>
902da432 6131
6132<H3>Usage</H3>
6133
30eb152d 6134<PRE>
70bb1290 6135ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group,
6136 const char *name, char value);
30eb152d 6137</PRE>
6138
902da432 6139<H3>Arguments</H3>
6140
03efb52b 6141<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6142<TR>
6143 <TH>Argument</TH>
6144 <TH>Description</TH>
6145</TR>
6146<TR>
70bb1290 6147 <TD>ipp</TD>
6148 <TD>The IPP request</TD>
6149</TR>
6150<TR>
6151 <TD>group</TD>
6152 <TD>The IPP group</TD>
6153</TR>
6154<TR>
6155 <TD>name</TD>
6156 <TD>The name of attribute</TD>
6157</TR>
6158<TR>
6159 <TD>value</TD>
6160 <TD>The boolean value</TD>
902da432 6161</TR>
6162</TABLE></CENTER>
6163
6164<H3>Returns</H3>
6165
70bb1290 6166<P>A pointer to the new attribute or NULL if the attribute could not be
6167created.
6168
902da432 6169<H3>Description</H3>
6170
70bb1290 6171<P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean attribute
6172value to the specified IPP request.
6173
03efb52b 6174<H3>Example</H3>
902da432 6175
30eb152d 6176<PRE>
70bb1290 6177#include &lt;cups/ipp.h>
6178
6179ipp_t *ipp;
6180
6181ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
30eb152d 6182</PRE>
6183
902da432 6184<H3>See Also</H3>
6185
70bb1290 6186<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6187<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6188<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6189<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6190<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6191<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6192<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6193<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6194<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6195<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6196<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6197
902da432 6198
30eb152d 6199<!-- NEW PAGE --><H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2>
902da432 6200
6201<H3>Usage</H3>
6202
30eb152d 6203<PRE>
70bb1290 6204ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group,
6205 const char *name, int num_values,
6206 const char *values);
30eb152d 6207</PRE>
6208
902da432 6209<H3>Arguments</H3>
6210
03efb52b 6211<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6212<TR>
6213 <TH>Argument</TH>
6214 <TH>Description</TH>
6215</TR>
6216<TR>
70bb1290 6217 <TD>ipp</TD>
6218 <TD>The IPP request</TD>
6219</TR>
6220<TR>
6221 <TD>group</TD>
6222 <TD>The IPP group</TD>
6223</TR>
6224<TR>
6225 <TD>name</TD>
6226 <TD>The name of attribute</TD>
6227</TR>
6228<TR>
6229 <TD>num_values</TD>
6230 <TD>The number of values</TD>
6231</TR>
6232<TR>
6233 <TD>values</TD>
6234 <TD>The boolean values</TD>
902da432 6235</TR>
6236</TABLE></CENTER>
6237
6238<H3>Returns</H3>
6239
70bb1290 6240<P>A pointer to the new attribute or NULL if the attribute could not be
6241created.
6242
902da432 6243<H3>Description</H3>
6244
70bb1290 6245<P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean
6246attribute values to the specified IPP request. If the
6247<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
6248<CODE>num_values</CODE> false values is created.
6249
03efb52b 6250<H3>Example</H3>
902da432 6251
30eb152d 6252<PRE>
70bb1290 6253#include &lt;cups/ipp.h>
6254
6255ipp_t *ipp;
6256char values[10];
6257
6258ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
30eb152d 6259</PRE>
6260
902da432 6261<H3>See Also</H3>
6262
70bb1290 6263<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6264<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6265<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6266<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6267<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6268<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6269<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6270<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6271<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6272<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6273<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6274
902da432 6275
30eb152d 6276<!-- NEW PAGE --><H2><A NAME="ippAddDate">ippAddDate()</A></H2>
902da432 6277
6278<H3>Usage</H3>
6279
30eb152d 6280<PRE>
70bb1290 6281ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group,
6282 const char *name, ipp_uchar_t *value);
30eb152d 6283</PRE>
6284
902da432 6285<H3>Arguments</H3>
6286
03efb52b 6287<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6288<TR>
6289 <TH>Argument</TH>
6290 <TH>Description</TH>
6291</TR>
6292<TR>
70bb1290 6293 <TD>ipp</TD>
6294 <TD>The IPP request</TD>
6295</TR>
6296<TR>
6297 <TD>group</TD>
6298 <TD>The IPP group</TD>
6299</TR>
6300<TR>
6301 <TD>name</TD>
6302 <TD>The name of attribute</TD>
6303</TR>
6304<TR>
6305 <TD>value</TD>
6306 <TD>The date value</TD>
902da432 6307</TR>
6308</TABLE></CENTER>
6309
6310<H3>Returns</H3>
6311
70bb1290 6312<P>A pointer to the new attribute or NULL if the attribute could not be
6313created.
6314
902da432 6315<H3>Description</H3>
6316
70bb1290 6317<P>The <CODE>ippAddDate()</CODE> function adds a single date-time attribute
6318value to the specified IPP request.
6319
03efb52b 6320<H3>Example</H3>
902da432 6321
30eb152d 6322<PRE>
70bb1290 6323#include &lt;cups/ipp.h>
6324
6325ipp_t *ipp;
6326
6327ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute",
6328 ippTimeToDate(time(NULL));
30eb152d 6329</PRE>
6330
902da432 6331<H3>See Also</H3>
6332
70bb1290 6333<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6334<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6335<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6336<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6337<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6338<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6339<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6340<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6341<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6342<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6343<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>,
6344<A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
6345
902da432 6346
30eb152d 6347<!-- NEW PAGE --><H2><A NAME="ippAddInteger">ippAddInteger()</A></H2>
902da432 6348
6349<H3>Usage</H3>
6350
30eb152d 6351<PRE>
70bb1290 6352ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group,
6353 ipp_tag_t tag, const char *name,
6354 int value);
30eb152d 6355</PRE>
6356
902da432 6357<H3>Arguments</H3>
6358
03efb52b 6359<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6360<TR>
6361 <TH>Argument</TH>
6362 <TH>Description</TH>
6363</TR>
6364<TR>
70bb1290 6365 <TD>ipp</TD>
6366 <TD>The IPP request</TD>
6367</TR>
6368<TR>
6369 <TD>group</TD>
6370 <TD>The IPP group</TD>
6371</TR>
6372<TR>
6373 <TD>tag</TD>
6374 <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
6375</TR>
6376<TR>
6377 <TD>name</TD>
6378 <TD>The name of attribute</TD>
6379</TR>
6380<TR>
6381 <TD>value</TD>
6382 <TD>The integer value</TD>
902da432 6383</TR>
6384</TABLE></CENTER>
6385
6386<H3>Returns</H3>
6387
70bb1290 6388<P>A pointer to the new attribute or NULL if the attribute could not be
6389created.
6390
902da432 6391<H3>Description</H3>
6392
70bb1290 6393<P>The <CODE>ippAddInteger()</CODE> function adds a single integer attribute
6394value to the specified IPP request.
6395
03efb52b 6396<H3>Example</H3>
902da432 6397
30eb152d 6398<PRE>
70bb1290 6399#include &lt;cups/ipp.h>
6400
6401ipp_t *ipp;
6402
6403ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
30eb152d 6404</PRE>
6405
902da432 6406<H3>See Also</H3>
6407
70bb1290 6408<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6409<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6410<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6411<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6412<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6413<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6414<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6415<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6416<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6417<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6418<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6419
902da432 6420
30eb152d 6421<!-- NEW PAGE --><H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2>
902da432 6422
6423<H3>Usage</H3>
6424
30eb152d 6425<PRE>
70bb1290 6426ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group,
6427 ipp_tag_t tag, const char *name,
6428 int num_values, const int *values);
30eb152d 6429</PRE>
6430
902da432 6431<H3>Arguments</H3>
6432
03efb52b 6433<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6434<TR>
6435 <TH>Argument</TH>
6436 <TH>Description</TH>
6437</TR>
6438<TR>
70bb1290 6439 <TD>ipp</TD>
6440 <TD>The IPP request</TD>
6441</TR>
6442<TR>
6443 <TD>group</TD>
6444 <TD>The IPP group</TD>
6445</TR>
6446<TR>
6447 <TD>tag</TD>
6448 <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
6449</TR>
6450<TR>
6451 <TD>name</TD>
6452 <TD>The name of attribute</TD>
6453</TR>
6454<TR>
6455 <TD>num_values</TD>
6456 <TD>The number of values</TD>
6457</TR>
6458<TR>
6459 <TD>values</TD>
6460 <TD>The integer values</TD>
902da432 6461</TR>
6462</TABLE></CENTER>
6463
6464<H3>Returns</H3>
6465
70bb1290 6466<P>A pointer to the new attribute or NULL if the attribute could not be
6467created.
6468
902da432 6469<H3>Description</H3>
6470
70bb1290 6471<P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer
6472attribute values to the specified IPP request. If the
6473<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
6474<CODE>num_values</CODE> 0 values is created.
6475
03efb52b 6476<H3>Example</H3>
902da432 6477
30eb152d 6478<PRE>
70bb1290 6479#include &lt;cups/ipp.h>
6480
6481ipp_t *ipp;
6482int values[100];
6483
6484ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
30eb152d 6485</PRE>
6486
902da432 6487<H3>See Also</H3>
6488
70bb1290 6489<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6490<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6491<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6492<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6493<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6494<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6495<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6496<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6497<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6498<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6499<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6500
902da432 6501
30eb152d 6502<!-- NEW PAGE --><H2><A NAME="ippAddRange">ippAddRange()</A></H2>
902da432 6503
6504<H3>Usage</H3>
6505
30eb152d 6506<PRE>
70bb1290 6507ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group,
6508 const char *name, int low,
6509 int high);
30eb152d 6510</PRE>
6511
902da432 6512<H3>Arguments</H3>
6513
03efb52b 6514<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6515<TR>
6516 <TH>Argument</TH>
6517 <TH>Description</TH>
6518</TR>
6519<TR>
70bb1290 6520 <TD>ipp</TD>
6521 <TD>The IPP request</TD>
6522</TR>
6523<TR>
6524 <TD>group</TD>
6525 <TD>The IPP group</TD>
6526</TR>
6527<TR>
6528 <TD>name</TD>
6529 <TD>The name of attribute</TD>
6530</TR>
6531<TR>
6532 <TD>low</TD>
6533 <TD>The lower value</TD>
6534</TR>
6535<TR>
6536 <TD>high</TD>
6537 <TD>The higher value</TD>
902da432 6538</TR>
6539</TABLE></CENTER>
6540
6541<H3>Returns</H3>
6542
70bb1290 6543<P>A pointer to the new attribute or NULL if the attribute could not be
6544created.
6545
902da432 6546<H3>Description</H3>
6547
70bb1290 6548<P>The <CODE>ippAddRange()</CODE> function adds a single range attribute
6549value to the specified IPP request.
6550
03efb52b 6551<H3>Example</H3>
902da432 6552
30eb152d 6553<PRE>
70bb1290 6554#include &lt;cups/ipp.h>
6555
6556ipp_t *ipp;
6557
6558ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
30eb152d 6559</PRE>
6560
902da432 6561<H3>See Also</H3>
6562
70bb1290 6563<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6564<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6565<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6566<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6567<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6568<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6569<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6570<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6571<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6572<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6573<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6574
902da432 6575
30eb152d 6576<!-- NEW PAGE --><H2><A NAME="ippAddRanges">ippAddRanges()</A></H2>
902da432 6577
6578<H3>Usage</H3>
6579
30eb152d 6580<PRE>
70bb1290 6581ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group,
6582 const char *name, int num_values,
6583 const int *lows, const int *highs);
30eb152d 6584</PRE>
6585
902da432 6586<H3>Arguments</H3>
6587
03efb52b 6588<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6589<TR>
6590 <TH>Argument</TH>
6591 <TH>Description</TH>
6592</TR>
6593<TR>
70bb1290 6594 <TD>ipp</TD>
6595 <TD>The IPP request</TD>
6596</TR>
6597<TR>
6598 <TD>group</TD>
6599 <TD>The IPP group</TD>
6600</TR>
6601<TR>
6602 <TD>name</TD>
6603 <TD>The name of attribute</TD>
6604</TR>
6605<TR>
6606 <TD>num_values</TD>
6607 <TD>The number of range values</TD>
6608</TR>
6609<TR>
6610 <TD>lows</TD>
6611 <TD>The lower values</TD>
6612</TR>
6613<TR>
6614 <TD>highs</TD>
6615 <TD>The higher values</TD>
902da432 6616</TR>
6617</TABLE></CENTER>
6618
6619<H3>Returns</H3>
6620
70bb1290 6621<P>A pointer to the new attribute or NULL if the attribute could not be
6622created.
6623
902da432 6624<H3>Description</H3>
6625
70bb1290 6626<P>The <CODE>ippAddRanges()</CODE> function adds one or more range
6627attribute values to the specified IPP request. If the
6628<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
6629<CODE>num_values</CODE> 0,0 ranges is created.
6630
03efb52b 6631<H3>Example</H3>
902da432 6632
30eb152d 6633<PRE>
70bb1290 6634#include &lt;cups/ipp.h>
6635
6636ipp_t *ipp;
6637int lows[2];
6638int highs[2];
6639
6640ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
30eb152d 6641</PRE>
6642
902da432 6643<H3>See Also</H3>
6644
70bb1290 6645<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6646<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6647<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6648<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6649<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6650<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6651<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6652<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6653<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6654<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6655<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6656
902da432 6657
30eb152d 6658<!-- NEW PAGE --><H2><A NAME="ippAddResolution">ippAddResolution()</A></H2>
902da432 6659
6660<H3>Usage</H3>
6661
30eb152d 6662<PRE>
70bb1290 6663ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group,
6664 const char *name, int xres,
6665 int yres, ipp_res_t units);
30eb152d 6666</PRE>
6667
902da432 6668<H3>Arguments</H3>
6669
03efb52b 6670<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6671<TR>
6672 <TH>Argument</TH>
6673 <TH>Description</TH>
6674</TR>
6675<TR>
70bb1290 6676 <TD>ipp</TD>
6677 <TD>The IPP request</TD>
6678</TR>
6679<TR>
6680 <TD>group</TD>
6681 <TD>The IPP group</TD>
6682</TR>
6683<TR>
6684 <TD>name</TD>
6685 <TD>The name of attribute</TD>
6686</TR>
6687<TR>
6688 <TD>xres</TD>
6689 <TD>The horizontal resolution</TD>
6690</TR>
6691<TR>
6692 <TD>yres</TD>
6693 <TD>The vertical resolution</TD>
6694</TR>
6695<TR>
6696 <TD>units</TD>
6697 <TD>The resolution units</TD>
902da432 6698</TR>
6699</TABLE></CENTER>
6700
6701<H3>Returns</H3>
6702
70bb1290 6703<P>A pointer to the new attribute or NULL if the attribute could not be
6704created.
6705
902da432 6706<H3>Description</H3>
6707
70bb1290 6708<P>The <CODE>ippAddResolution()</CODE> function adds a single resolution attribute
6709value to the specified IPP request.
6710
03efb52b 6711<H3>Example</H3>
902da432 6712
30eb152d 6713<PRE>
70bb1290 6714#include &lt;cups/ipp.h>
6715
6716ipp_t *ipp;
6717
6718ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
6719 720, 720, IPP_RES_PER_INCH);
30eb152d 6720</PRE>
6721
902da432 6722<H3>See Also</H3>
6723
70bb1290 6724<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6725<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6726<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6727<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6728<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6729<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6730<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6731<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6732<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6733<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6734<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6735
902da432 6736
30eb152d 6737<!-- NEW PAGE --><H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2>
902da432 6738
6739<H3>Usage</H3>
6740
30eb152d 6741<PRE>
70bb1290 6742ipp_attribute_t *ippAddResolutions(ipp_t *ipp, ipp_tag_t group,
6743 const char *name, int num_values,
6744 const int *xres, const int *yres,
6745 const ipp_res_t *units);
30eb152d 6746</PRE>
6747
902da432 6748<H3>Arguments</H3>
6749
03efb52b 6750<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6751<TR>
6752 <TH>Argument</TH>
6753 <TH>Description</TH>
6754</TR>
6755<TR>
70bb1290 6756 <TD>ipp</TD>
6757 <TD>The IPP request</TD>
6758</TR>
6759<TR>
6760 <TD>group</TD>
6761 <TD>The IPP group</TD>
6762</TR>
6763<TR>
6764 <TD>name</TD>
6765 <TD>The name of attribute</TD>
6766</TR>
6767<TR>
6768 <TD>num_values</TD>
6769 <TD>The number of resolution values</TD>
6770</TR>
6771<TR>
6772 <TD>xres</TD>
6773 <TD>The horizontal resolutions</TD>
6774</TR>
6775<TR>
6776 <TD>yres</TD>
6777 <TD>The vertical resolutions</TD>
6778</TR>
6779<TR>
6780 <TD>units</TD>
6781 <TD>The resolution units</TD>
902da432 6782</TR>
6783</TABLE></CENTER>
6784
6785<H3>Returns</H3>
6786
70bb1290 6787<P>A pointer to the new attribute or NULL if the attribute could not be
6788created.
6789
902da432 6790<H3>Description</H3>
6791
70bb1290 6792<P>The <CODE>ippAddResolutions()</CODE> function adds one or more
6793resolution attribute values to the specified IPP request. If the
6794<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
6795<CODE>num_values</CODE> 0,0 resolutions is created.
6796
03efb52b 6797<H3>Example</H3>
902da432 6798
30eb152d 6799<PRE>
70bb1290 6800#include &lt;cups/ipp.h>
6801
6802ipp_t *ipp;
6803int xres[5];
6804int yres[5];
6805ipp_res_t units[5];
6806
6807ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
6808 5, xres, yres, units);
30eb152d 6809</PRE>
6810
902da432 6811<H3>See Also</H3>
6812
70bb1290 6813<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6814<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6815<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6816<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6817<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6818<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6819<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6820<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6821<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6822<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6823<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6824
902da432 6825
30eb152d 6826<!-- NEW PAGE --><H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2>
902da432 6827
6828<H3>Usage</H3>
6829
30eb152d 6830<PRE>
70bb1290 6831ipp_attribute_t *ippAddSeparator(ipp_t *ipp);
30eb152d 6832</PRE>
6833
902da432 6834<H3>Arguments</H3>
6835
03efb52b 6836<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6837<TR>
6838 <TH>Argument</TH>
6839 <TH>Description</TH>
6840</TR>
6841<TR>
70bb1290 6842 <TD>ipp</TD>
6843 <TD>The IPP request</TD>
902da432 6844</TR>
6845</TABLE></CENTER>
6846
6847<H3>Returns</H3>
6848
70bb1290 6849<P>A pointer to the new separator or NULL if the separator could not be
6850created.
6851
902da432 6852<H3>Description</H3>
6853
70bb1290 6854<P>The <CODE>ippAddSeparator()</CODE> function adds a group separator
6855to the specified IPP request.
6856
03efb52b 6857<H3>Example</H3>
902da432 6858
30eb152d 6859<PRE>
70bb1290 6860#include &lt;cups/ipp.h>
6861
6862ipp_t *ipp;
6863
6864ippAddSeparator(ipp);
30eb152d 6865</PRE>
6866
902da432 6867<H3>See Also</H3>
6868
70bb1290 6869<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6870<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6871<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6872<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6873<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6874<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6875<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6876<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6877<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6878<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
6879<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6880
902da432 6881
30eb152d 6882<!-- NEW PAGE --><H2><A NAME="ippAddString">ippAddString()</A></H2>
902da432 6883
6884<H3>Usage</H3>
6885
30eb152d 6886<PRE>
70bb1290 6887ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group,
6888 ipp_tag_t tag, const char *name,
6889 const char *charset, const char *value);
30eb152d 6890</PRE>
6891
902da432 6892<H3>Arguments</H3>
6893
03efb52b 6894<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6895<TR>
6896 <TH>Argument</TH>
6897 <TH>Description</TH>
6898</TR>
6899<TR>
70bb1290 6900 <TD>ipp</TD>
6901 <TD>The IPP request</TD>
6902</TR>
6903<TR>
6904 <TD>group</TD>
6905 <TD>The IPP group</TD>
6906</TR>
6907<TR>
6908 <TD>tag</TD>
6909 <TD>The type of string value</TD>
6910</TR>
6911<TR>
6912 <TD>name</TD>
6913 <TD>The name of attribute</TD>
6914</TR>
6915<TR>
6916 <TD>charset</TD>
6917 <TD>The character set for the string</TD>
6918</TR>
6919<TR>
6920 <TD>value</TD>
6921 <TD>The string value</TD>
902da432 6922</TR>
6923</TABLE></CENTER>
6924
6925<H3>Returns</H3>
6926
70bb1290 6927<P>A pointer to the new attribute or NULL if the attribute could not be
6928created.
6929
902da432 6930<H3>Description</H3>
6931
70bb1290 6932<P>The <CODE>ippAddString()</CODE> function adds a single string attribute
6933value to the specified IPP request. For <CODE>IPP_TAG_NAMELANG</CODE> and
6934<CODE>IPP_TAG_TEXTLANG</CODE> strings, the charset value is provided with
6935the string to identify the string encoding used. Otherwise the charset value
6936is ignored.
6937
03efb52b 6938<H3>Example</H3>
902da432 6939
30eb152d 6940<PRE>
70bb1290 6941#include &lt;cups/ipp.h>
6942
6943ipp_t *ipp;
6944
6945ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
6946 NULL, "abc123");
30eb152d 6947</PRE>
6948
902da432 6949<H3>See Also</H3>
6950
70bb1290 6951<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
6952<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
6953<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
6954<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
6955<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
6956<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
6957<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
6958<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
6959<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
6960<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
6961<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
6962
902da432 6963
30eb152d 6964<!-- NEW PAGE --><H2><A NAME="ippAddStrings">ippAddStrings()</A></H2>
902da432 6965
6966<H3>Usage</H3>
6967
30eb152d 6968<PRE>
70bb1290 6969ipp_attribute_t *ippAddStrings(ipp_t *ipp, ipp_tag_t group,
6970 ipp_tag_t tag, const char *name,
6971 int num_values, const char *charset,
6972 const char **values);
30eb152d 6973</PRE>
6974
902da432 6975<H3>Arguments</H3>
6976
03efb52b 6977<CENTER><TABLE WIDTH="80%" BORDER>
902da432 6978<TR>
6979 <TH>Argument</TH>
6980 <TH>Description</TH>
6981</TR>
6982<TR>
70bb1290 6983 <TD>ipp</TD>
6984 <TD>The IPP request</TD>
6985</TR>
6986<TR>
6987 <TD>group</TD>
6988 <TD>The IPP group</TD>
6989</TR>
6990<TR>
6991 <TD>tag</TD>
6992 <TD>The type of string value</TD>
6993</TR>
6994<TR>
6995 <TD>name</TD>
6996 <TD>The name of attribute</TD>
6997</TR>
6998<TR>
6999 <TD>num_values</TD>
7000 <TD>The number of strings</TD>
7001</TR>
7002<TR>
7003 <TD>charset</TD>
7004 <TD>The character set for the strings</TD>
7005</TR>
7006<TR>
7007 <TD>values</TD>
7008 <TD>The string values</TD>
902da432 7009</TR>
7010</TABLE></CENTER>
7011
7012<H3>Returns</H3>
7013
70bb1290 7014<P>A pointer to the new attribute or NULL if the attribute could not be
7015created.
7016
902da432 7017<H3>Description</H3>
7018
70bb1290 7019<P>The <CODE>ippAddStrings()</CODE> function adds one or more string
7020attribute values to the specified IPP request. For
7021<CODE>IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE>
7022strings, the charset value is provided with the strings to identify the
7023string encoding used. Otherwise the charset value is ignored. If the
7024<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
7025<CODE>num_values</CODE> NULL strings is created.
7026
03efb52b 7027<H3>Example</H3>
902da432 7028
30eb152d 7029<PRE>
70bb1290 7030#include &lt;cups/ipp.h>
7031
7032ipp_t *ipp;
7033char *values[2] = { "one", "two" };
7034
7035ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
7036 2, NULL, values);
30eb152d 7037</PRE>
7038
902da432 7039<H3>See Also</H3>
7040
70bb1290 7041<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
7042<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
7043<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
7044<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
7045<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
7046<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
7047<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
7048<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
7049<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
7050<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
7051<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>
7052
902da432 7053
30eb152d 7054<!-- NEW PAGE --><H2><A NAME="ippDateToTime">ippDateToTime()</A></H2>
902da432 7055
7056<H3>Usage</H3>
7057
30eb152d 7058<PRE>
70bb1290 7059time_t ippDateToTime(const ipp_uchar_t date[11]);
30eb152d 7060</PRE>
7061
902da432 7062<H3>Arguments</H3>
7063
03efb52b 7064<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7065<TR>
7066 <TH>Argument</TH>
7067 <TH>Description</TH>
7068</TR>
7069<TR>
70bb1290 7070 <TD>date</TD>
7071 <TD>The IPP date-time value</TD>
902da432 7072</TR>
7073</TABLE></CENTER>
7074
7075<H3>Returns</H3>
7076
70bb1290 7077<P>A UNIX time value.
7078
902da432 7079<H3>Description</H3>
7080
70bb1290 7081<P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time value
7082to a UNIX time value.
7083
03efb52b 7084<H3>Example</H3>
902da432 7085
30eb152d 7086<PRE>
70bb1290 7087#include &lt;cups/ipp.h>
7088
7089ipp_uchar_t date[11];
7090
7091printf("UNIX time is %d\n", ippDateToTime(date));
30eb152d 7092</PRE>
7093
902da432 7094<H3>See Also</H3>
7095
70bb1290 7096<A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
7097
902da432 7098
30eb152d 7099<!-- NEW PAGE --><H2><A NAME="ippDelete">ippDelete()</A></H2>
902da432 7100
7101<H3>Usage</H3>
7102
30eb152d 7103<PRE>
70bb1290 7104void ippDelete(ipp_t *ipp);
30eb152d 7105</PRE>
7106
902da432 7107<H3>Arguments</H3>
7108
03efb52b 7109<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7110<TR>
7111 <TH>Argument</TH>
7112 <TH>Description</TH>
7113</TR>
7114<TR>
70bb1290 7115 <TD>ipp</TD>
7116 <TD>The IPP request or response</TD>
902da432 7117</TR>
7118</TABLE></CENTER>
7119
902da432 7120<H3>Description</H3>
7121
70bb1290 7122<P>The <CODE>ippDelete()</CODE> function deletes all memory used by an IPP
7123request or response.
7124
03efb52b 7125<H3>Example</H3>
902da432 7126
30eb152d 7127<PRE>
70bb1290 7128#include &lt;cups/ipp.h>
7129
7130ipp_t *ipp;
7131
7132ippDelete(ipp);
30eb152d 7133</PRE>
7134
902da432 7135<H3>See Also</H3>
7136
70bb1290 7137<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
7138
902da432 7139
30eb152d 7140<!-- NEW PAGE --><H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2>
902da432 7141
7142<H3>Usage</H3>
7143
30eb152d 7144<PRE>
646faf5a 7145ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag);
30eb152d 7146</PRE>
7147
902da432 7148<H3>Arguments</H3>
7149
03efb52b 7150<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7151<TR>
7152 <TH>Argument</TH>
7153 <TH>Description</TH>
7154</TR>
7155<TR>
646faf5a 7156 <TD>ipp</TD>
7157 <TD>The IPP request or response</TD>
7158</TR>
7159<TR>
7160 <TD>name</TD>
7161 <TD>The name of the attribute</TD>
7162</TR>
7163<TR>
7164 <TD>tag</TD>
7165 <TD>The required value tag for the attribute or
7166 <CODE>IPP_TAG_ZERO</CODE> for any type of value.</TD>
902da432 7167</TR>
7168</TABLE></CENTER>
7169
7170<H3>Returns</H3>
7171
646faf5a 7172<P>A pointer to the first occurrence of the requested attribute, or
7173<CODE>NULL</CODE> if it was not found.
7174
902da432 7175<H3>Description</H3>
7176
646faf5a 7177<P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the named
7178attribute. The <CODE>tag</CODE> parameter restricts the search to a specific
7179value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.
7180
7181<P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
7182match the name/text values with or without the language code.
7183
03efb52b 7184<H3>Example</H3>
902da432 7185
30eb152d 7186<PRE>
646faf5a 7187ipp_attribute_t *attr;
7188
7189attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
30eb152d 7190</PRE>
7191
902da432 7192<H3>See Also</H3>
7193
646faf5a 7194<A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>,
7195<A HREF="#cupsDoRequest"><CODE>cupsDoRequest()</CODE></A>,
7196<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
7197<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
7198
902da432 7199
30eb152d 7200<!-- NEW PAGE --><H2><A NAME="ippLength">ippLength()</A></H2>
902da432 7201
7202<H3>Usage</H3>
7203
30eb152d 7204<PRE>
646faf5a 7205int ippLength(ipp_t *ipp);
30eb152d 7206</PRE>
7207
902da432 7208<H3>Arguments</H3>
7209
03efb52b 7210<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7211<TR>
7212 <TH>Argument</TH>
7213 <TH>Description</TH>
7214</TR>
7215<TR>
646faf5a 7216 <TD>ipp</TD>
7217 <TD>The IPP request or response</TD>
902da432 7218</TR>
7219</TABLE></CENTER>
7220
7221<H3>Returns</H3>
7222
646faf5a 7223<P>The total encoded length of the IPP request or response in bytes.
7224
902da432 7225<H3>Description</H3>
7226
646faf5a 7227<P><CODE>ippLength()</CODE> returns the length of the IPP request or
7228response in bytes.
7229
03efb52b 7230<H3>Example</H3>
902da432 7231
30eb152d 7232<PRE>
646faf5a 7233printf("The length of the response is %d bytes.\n", ippLength(response));
30eb152d 7234</PRE>
7235
902da432 7236<H3>See Also</H3>
7237
646faf5a 7238<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
7239<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
7240
70bb1290 7241
7242<!-- NEW PAGE --><H2><A NAME="ippNew">ippNew()</A></H2>
7243
7244<H3>Usage</H3>
7245
7246<PRE>
7247ipp_t *ippNew(void);
7248</PRE>
7249
902da432 7250<H3>Returns</H3>
7251
70bb1290 7252<P>A pointer to a new IPP request or response.
7253
902da432 7254<H3>Description</H3>
7255
70bb1290 7256<P>The <CODE>ippNew()</CODE> function creates a new IPP request or response.
7257
03efb52b 7258<H3>Example</H3>
902da432 7259
30eb152d 7260<PRE>
70bb1290 7261#include &lt;cups/ipp.h>
7262
7263ipp_t *ipp;
7264
7265ipp = ippNew();
30eb152d 7266</PRE>
7267
902da432 7268<H3>See Also</H3>
7269
70bb1290 7270<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>
7271
902da432 7272
30eb152d 7273<!-- NEW PAGE --><H2><A NAME="ippPort">ippPort()</A></H2>
902da432 7274
7275<H3>Usage</H3>
7276
30eb152d 7277<PRE>
70bb1290 7278int ippPort(void);
30eb152d 7279</PRE>
7280
902da432 7281<H3>Returns</H3>
7282
70bb1290 7283<P>The default TCP/IP port number for IPP requests.
7284
902da432 7285<H3>Description</H3>
7286
70bb1290 7287<P>The <CODE>ippPort()</CODE> function returns the default IPP port number
7288for requests.
7289
03efb52b 7290<H3>Example</H3>
902da432 7291
30eb152d 7292<PRE>
70bb1290 7293#include &lt;cups/http.h>
7294#include &lt;cups/ipp.h>
7295
7296http_t *http;
7297
7298http = httpConnect(cupsServer(), ippPort());
30eb152d 7299</PRE>
7300
902da432 7301<H3>See Also</H3>
7302
ebd737f3 7303<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
7304<A HREF="#ippSetPort"><CODE>ippSetPort()</CODE></A>
70bb1290 7305
902da432 7306
30eb152d 7307<!-- NEW PAGE --><H2><A NAME="ippRead">ippRead()</A></H2>
902da432 7308
7309<H3>Usage</H3>
7310
30eb152d 7311<PRE>
70bb1290 7312ipp_state_t ippRead(http_t *http, ipp_t *ipp);
30eb152d 7313</PRE>
7314
902da432 7315<H3>Arguments</H3>
7316
03efb52b 7317<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7318<TR>
7319 <TH>Argument</TH>
7320 <TH>Description</TH>
7321</TR>
7322<TR>
70bb1290 7323 <TD>http</TD>
7324 <TD>The HTTP connection</TD>
7325</TR>
7326<TR>
7327 <TD>ipp</TD>
7328 <TD>The IPP request or response</TD>
902da432 7329</TR>
7330</TABLE></CENTER>
7331
7332<H3>Returns</H3>
7333
70bb1290 7334<P>The current read state.
7335
902da432 7336<H3>Description</H3>
7337
70bb1290 7338<P>The <CODE>ippRead()</CODE> function reads IPP attributes from the specified
7339HTTP connection. Programs should continue calling <CODE>ippRead()</CODE> until
7340<CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
7341
03efb52b 7342<H3>Example</H3>
902da432 7343
30eb152d 7344<PRE>
70bb1290 7345#include &lt;cups/http.h>
7346#include &lt;cups/ipp.h>
7347
7348http_t *http;
7349ipp_t *ipp;
7350ipp_state_t status;
7351
7352ipp = ippNew();
7353
7354while ((status = ippRead(http, ipp)) != IPP_ERROR)
7355 if (status == IPP_DATA)
7356 break;
7357
7358if (status == IPP_DATA)
7359{
7360 ... read additional non-IPP data using httpRead() ...
7361}
30eb152d 7362</PRE>
7363
902da432 7364<H3>See Also</H3>
7365
70bb1290 7366<A HREF="#ippWrite"><CODE>ippWrite()</CODE></A>
7367
902da432 7368
ebd737f3 7369<!-- NEW PAGE --><H2><A NAME="ippSetPort">ippSetPort()</A></H2>
7370
7371<H3>Usage</H3>
7372
7373<PRE>
7374void
7375ippSetPort(int port);
7376</PRE>
7377
7378<H3>Arguments</H3>
7379
7380<CENTER><TABLE WIDTH="80%" BORDER>
7381<TR>
7382 <TH>Argument</TH>
7383 <TH>Description</TH>
7384</TR>
7385<TR>
7386 <TD>port</TD>
7387 <TD>The port number to use</TD>
7388</TR>
7389</TABLE></CENTER>
7390
7391<H3>Description</H3>
7392
7393<P>The <CODE>ippSetPort()</CODE> function sets the default IPP port number
7394for requests.
7395
7396<H3>Example</H3>
7397
7398<PRE>
7399#include &lt;cups/http.h>
7400#include &lt;cups/ipp.h>
7401
7402...
7403
7404ippSetPort(8631);
7405</PRE>
7406
7407<H3>See Also</H3>
7408
7409<A HREF="#ippPort"><CODE>ippPort()</CODE></A>
7410
7411
30eb152d 7412<!-- NEW PAGE --><H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2>
902da432 7413
7414<H3>Usage</H3>
7415
30eb152d 7416<PRE>
70bb1290 7417ipp_uchar_t *ippTimeToDate(time_t time);
30eb152d 7418</PRE>
7419
902da432 7420<H3>Arguments</H3>
7421
03efb52b 7422<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7423<TR>
7424 <TH>Argument</TH>
7425 <TH>Description</TH>
7426</TR>
7427<TR>
70bb1290 7428 <TD>time</TD>
7429 <TD>The UNIX time value</TD>
902da432 7430</TR>
7431</TABLE></CENTER>
7432
7433<H3>Returns</H3>
7434
70bb1290 7435<P>A static pointer to an IPP date-time value.
7436
902da432 7437<H3>Description</H3>
7438
70bb1290 7439<P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an IPP
7440date-time value.
7441
03efb52b 7442<H3>Example</H3>
902da432 7443
30eb152d 7444<PRE>
70bb1290 7445#include &lt;cups/ipp.h>
7446
7447ipp_uchar_t *date;
7448
7449date = ippTimeToDate(time(NULL));
30eb152d 7450</PRE>
7451
902da432 7452<H3>See Also</H3>
7453
70bb1290 7454<A HREF="#ippDateToTime"><CODE>ippDateToTime()</CODE></A>
7455
902da432 7456
30eb152d 7457<!-- NEW PAGE --><H2><A NAME="ippWrite">ippWrite()</A></H2>
902da432 7458
7459<H3>Usage</H3>
7460
30eb152d 7461<PRE>
70bb1290 7462ipp_state_t ippWrite(http_t *http, ipp_t *ipp);
30eb152d 7463</PRE>
7464
902da432 7465<H3>Arguments</H3>
7466
03efb52b 7467<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7468<TR>
7469 <TH>Argument</TH>
7470 <TH>Description</TH>
7471</TR>
7472<TR>
70bb1290 7473 <TD>http</TD>
7474 <TD>The HTTP connection</TD>
7475</TR>
7476<TR>
7477 <TD>ipp</TD>
7478 <TD>The IPP request or response</TD>
902da432 7479</TR>
7480</TABLE></CENTER>
7481
7482<H3>Returns</H3>
7483
70bb1290 7484<P>The current write state.
7485
902da432 7486<H3>Description</H3>
7487
70bb1290 7488<P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the specified
7489HTTP connection. Programs should continue calling <CODE>ippWrite()</CODE> until
7490<CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
7491
03efb52b 7492<H3>Example</H3>
902da432 7493
30eb152d 7494<PRE>
70bb1290 7495#include &lt;cups/http.h>
7496#include &lt;cups/ipp.h>
7497
7498http_t *http;
7499ipp_t *ipp;
7500ipp_state_t status;
7501
7502ipp = ippNew();
7503... add attributes ...
7504
7505while ((status = ippWrite(http, ipp)) != IPP_ERROR)
7506 if (status == IPP_DATA)
7507 break;
7508
7509if (status == IPP_DATA)
7510{
7511 ... read additional non-IPP data using httpWrite() ...
7512}
30eb152d 7513</PRE>
7514
902da432 7515<H3>See Also</H3>
7516
70bb1290 7517<A HREF="#ippRead"><CODE>ippRead()</CODE></A>
7518
902da432 7519
30eb152d 7520<!-- NEW PAGE --><H2><A NAME="ppdClose">ppdClose()</A></H2>
902da432 7521
7522<H3>Usage</H3>
7523
30eb152d 7524<PRE>
70bb1290 7525void ppdClose(ppd_file_t *ppd);
30eb152d 7526</PRE>
7527
902da432 7528<H3>Arguments</H3>
7529
03efb52b 7530<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7531<TR>
7532 <TH>Argument</TH>
7533 <TH>Description</TH>
7534</TR>
7535<TR>
70bb1290 7536 <TD>ppd</TD>
7537 <TD>The PPD file</TD>
902da432 7538</TR>
7539</TABLE></CENTER>
7540
902da432 7541<H3>Description</H3>
7542
70bb1290 7543<P>The <CODE>ppdClose()</CODE> function frees all memory associated with the
7544PPD file.
7545
03efb52b 7546<H3>Example</H3>
902da432 7547
30eb152d 7548<PRE>
70bb1290 7549#include &lt;cups/ppd.h>
7550
7551ppd_file_t *ppd;
7552
7553ppdClose(ppd);
30eb152d 7554</PRE>
7555
902da432 7556<H3>See Also</H3>
7557
70bb1290 7558<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
7559<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
7560<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
7561
902da432 7562
30eb152d 7563<!-- NEW PAGE --><H2><A NAME="ppdConflicts">ppdConflicts()</A></H2>
902da432 7564
7565<H3>Usage</H3>
7566
30eb152d 7567<PRE>
70bb1290 7568int ppdConflicts(ppd_file_t *ppd);
30eb152d 7569</PRE>
7570
902da432 7571<H3>Arguments</H3>
7572
03efb52b 7573<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7574<TR>
7575 <TH>Argument</TH>
7576 <TH>Description</TH>
7577</TR>
7578<TR>
70bb1290 7579 <TD>ppd</TD>
7580 <TD>The PPD file</TD>
902da432 7581</TR>
7582</TABLE></CENTER>
7583
7584<H3>Returns</H3>
7585
70bb1290 7586<P>The number of option conflicts in the file.
7587
902da432 7588<H3>Description</H3>
7589
70bb1290 7590<P>The <CODE>ppdConflicts()</CODE> function returns the number of conflicts
7591with the currently selected options.
7592
03efb52b 7593<H3>Example</H3>
902da432 7594
30eb152d 7595<PRE>
70bb1290 7596#include &lt;cups/ppd.h>
7597
7598ppd_file_t *ppd;
7599
7600printf("%d conflicts\n", ppdConflicts(ppd));
30eb152d 7601</PRE>
7602
902da432 7603<H3>See Also</H3>
7604
70bb1290 7605<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
7606<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
7607<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
7608<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
902da432 7609
70bb1290 7610
7611<!-- NEW PAGE --><H2><A NAME="ppdEmit">ppdEmit()</A></H2>
902da432 7612
7613<H3>Usage</H3>
7614
30eb152d 7615<PRE>
70bb1290 7616int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section);
30eb152d 7617</PRE>
7618
902da432 7619<H3>Arguments</H3>
7620
03efb52b 7621<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7622<TR>
7623 <TH>Argument</TH>
7624 <TH>Description</TH>
7625</TR>
7626<TR>
70bb1290 7627 <TD>ppd</TD>
7628 <TD>The PPD file</TD>
7629</TR>
7630<TR>
7631 <TD>file</TD>
7632 <TD>The file to write to</TD>
7633</TR>
7634<TR>
7635 <TD>section</TD>
7636 <TD>The option section to write</TD>
902da432 7637</TR>
7638</TABLE></CENTER>
7639
7640<H3>Returns</H3>
7641
70bb1290 7642<P>0 on success, -1 on error.
7643
902da432 7644<H3>Description</H3>
7645
70bb1290 7646<P>The <CODE>ppdEmit()</CODE> function sends printer-specific option
7647commands to the specified file.
7648
03efb52b 7649<H3>Example</H3>
902da432 7650
30eb152d 7651<PRE>
70bb1290 7652#include &lt;cups/ppd.h>
7653
7654ppd_file_t *ppd;
7655
7656ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
30eb152d 7657</PRE>
7658
902da432 7659<H3>See Also</H3>
7660
70bb1290 7661<A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A>
902da432 7662
70bb1290 7663
7664<!-- NEW PAGE --><H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2>
902da432 7665
7666<H3>Usage</H3>
7667
30eb152d 7668<PRE>
70bb1290 7669int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section);
30eb152d 7670</PRE>
7671
902da432 7672<H3>Arguments</H3>
7673
03efb52b 7674<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7675<TR>
7676 <TH>Argument</TH>
7677 <TH>Description</TH>
7678</TR>
7679<TR>
70bb1290 7680 <TD>ppd</TD>
7681 <TD>The PPD file</TD>
7682</TR>
7683<TR>
7684 <TD>fd</TD>
7685 <TD>The file descriptor to write to</TD>
7686</TR>
7687<TR>
7688 <TD>section</TD>
7689 <TD>The option section to write</TD>
902da432 7690</TR>
7691</TABLE></CENTER>
7692
7693<H3>Returns</H3>
7694
70bb1290 7695<P>0 on success, -1 on error.
7696
902da432 7697<H3>Description</H3>
7698
70bb1290 7699<P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option
7700commands to the specified file descriptor.
7701
03efb52b 7702<H3>Example</H3>
902da432 7703
30eb152d 7704<PRE>
70bb1290 7705#include &lt;cups/ppd.h>
7706
7707ppd_file_t *ppd;
7708
7709ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
30eb152d 7710</PRE>
7711
902da432 7712<H3>See Also</H3>
7713
70bb1290 7714<A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>
7715
902da432 7716
30eb152d 7717<!-- NEW PAGE --><H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2>
902da432 7718
7719<H3>Usage</H3>
7720
30eb152d 7721<PRE>
70bb1290 7722ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice);
30eb152d 7723</PRE>
7724
902da432 7725<H3>Arguments</H3>
7726
03efb52b 7727<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7728<TR>
7729 <TH>Argument</TH>
7730 <TH>Description</TH>
7731</TR>
7732<TR>
70bb1290 7733 <TD>option</TD>
7734 <TD>A pointer to the option</TD>
7735</TR>
7736<TR>
7737 <TD>choice</TD>
7738 <TD>The name of the choice</TD>
902da432 7739</TR>
7740</TABLE></CENTER>
7741
7742<H3>Returns</H3>
7743
70bb1290 7744<P>A pointer to the choice data or NULL if the choice does not exist.
7745
902da432 7746<H3>Description</H3>
7747
70bb1290 7748<P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the choice
7749data for the specified option.
7750
03efb52b 7751<H3>Example</H3>
902da432 7752
30eb152d 7753<PRE>
70bb1290 7754#include &lt;cups/ppd.h>
7755
7756ppd_file_t *ppd;
7757ppd_option_t *option;
7758ppd_choice_t *choice;
7759
7760option = ppdFindOption(ppd, "PageSize");
7761choice = ppdFindChoice(option, "Letter");
30eb152d 7762</PRE>
7763
902da432 7764<H3>See Also</H3>
7765
70bb1290 7766<A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>,
7767<A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
7768
902da432 7769
30eb152d 7770<!-- NEW PAGE --><H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2>
902da432 7771
7772<H3>Usage</H3>
7773
30eb152d 7774<PRE>
70bb1290 7775ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
30eb152d 7776</PRE>
7777
902da432 7778<H3>Arguments</H3>
7779
03efb52b 7780<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7781<TR>
7782 <TH>Argument</TH>
7783 <TH>Description</TH>
7784</TR>
7785<TR>
70bb1290 7786 <TD>ppd</TD>
7787 <TD>The PPD file</TD>
7788</TR>
7789<TR>
7790 <TD>keyword</TD>
7791 <TD>The name of the option</TD>
902da432 7792</TR>
7793</TABLE></CENTER>
7794
7795<H3>Returns</H3>
7796
70bb1290 7797<P>A pointer to the choice data or NULL if the choice does not exist or
7798is not marked.
7799
902da432 7800<H3>Description</H3>
7801
70bb1290 7802<P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to
7803the marked choice data for the specified option.
7804
03efb52b 7805<H3>Example</H3>
902da432 7806
30eb152d 7807<PRE>
70bb1290 7808#include &lt;cups/ppd.h>
7809
7810ppd_file_t *ppd;
7811ppd_choice_t *choice;
7812
7813choice = ppdFindMarkedChoice(ppd, "PageSize");
30eb152d 7814</PRE>
7815
902da432 7816<H3>See Also</H3>
7817
70bb1290 7818<A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
7819<A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
7820
902da432 7821
30eb152d 7822<!-- NEW PAGE --><H2><A NAME="ppdFindOption">ppdFindOption()</A></H2>
902da432 7823
7824<H3>Usage</H3>
7825
30eb152d 7826<PRE>
70bb1290 7827ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword);
30eb152d 7828</PRE>
7829
902da432 7830<H3>Arguments</H3>
7831
03efb52b 7832<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7833<TR>
7834 <TH>Argument</TH>
7835 <TH>Description</TH>
7836</TR>
7837<TR>
70bb1290 7838 <TD>ppd</TD>
7839 <TD>The PPD file</TD>
7840</TR>
7841<TR>
7842 <TD>keyword</TD>
7843 <TD>The name of the option</TD>
902da432 7844</TR>
7845</TABLE></CENTER>
7846
7847<H3>Returns</H3>
7848
70bb1290 7849<P>A pointer to the option data or NULL if the option does not exist.
7850
902da432 7851<H3>Description</H3>
7852
70bb1290 7853<P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the option
7854data for the specified option.
7855
03efb52b 7856<H3>Example</H3>
902da432 7857
30eb152d 7858<PRE>
70bb1290 7859#include &lt;cups/ppd.h>
7860
7861ppd_file_t *ppd;
7862ppd_option_t *option;
7863
7864option = ppdFindOption(ppd, "PageSize");
30eb152d 7865</PRE>
7866
902da432 7867<H3>See Also</H3>
7868
70bb1290 7869<A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
7870<A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>
7871
902da432 7872
30eb152d 7873<!-- NEW PAGE --><H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2>
902da432 7874
7875<H3>Usage</H3>
7876
30eb152d 7877<PRE>
70bb1290 7878int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice);
30eb152d 7879</PRE>
7880
902da432 7881<H3>Arguments</H3>
7882
03efb52b 7883<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7884<TR>
7885 <TH>Argument</TH>
7886 <TH>Description</TH>
7887</TR>
7888<TR>
70bb1290 7889 <TD>ppd</TD>
7890 <TD>The PPD file</TD>
7891</TR>
7892<TR>
7893 <TD>keyword</TD>
7894 <TD>The name of the option</TD>
7895</TR>
7896<TR>
7897 <TD>choice</TD>
7898 <TD>The name of the option choice</TD>
902da432 7899</TR>
7900</TABLE></CENTER>
7901
7902<H3>Returns</H3>
7903
70bb1290 7904<P>1 if the choice is marked, 0 otherwise.
7905
902da432 7906<H3>Description</H3>
7907
70bb1290 7908<P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the
7909specified option choice is marked.
7910
03efb52b 7911<H3>Example</H3>
902da432 7912
30eb152d 7913<PRE>
70bb1290 7914#include &lt;cups/ppd.h>
7915
7916ppd_file_t *ppd;
7917
7918printf("Letter size %s selected.\n",
7919 ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
30eb152d 7920</PRE>
7921
902da432 7922<H3>See Also</H3>
7923
70bb1290 7924<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
7925<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
7926<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
7927<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
7928<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
7929
902da432 7930
30eb152d 7931<!-- NEW PAGE --><H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2>
902da432 7932
7933<H3>Usage</H3>
7934
30eb152d 7935<PRE>
70bb1290 7936void ppdMarkDefaults(ppd_file_t *ppd);
30eb152d 7937</PRE>
7938
902da432 7939<H3>Arguments</H3>
7940
03efb52b 7941<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7942<TR>
7943 <TH>Argument</TH>
7944 <TH>Description</TH>
7945</TR>
7946<TR>
70bb1290 7947 <TD>ppd</TD>
7948 <TD>The PPD file</TD>
902da432 7949</TR>
7950</TABLE></CENTER>
7951
902da432 7952<H3>Description</H3>
7953
70bb1290 7954<P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default
7955choices in the PPD file.
7956
03efb52b 7957<H3>Example</H3>
902da432 7958
30eb152d 7959<PRE>
70bb1290 7960#include &lt;cups/ppd.h>
7961
7962ppd_file_t *ppd;
7963
7964ppdMarkDefaults(ppd);
30eb152d 7965</PRE>
7966
902da432 7967<H3>See Also</H3>
7968
70bb1290 7969<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
7970<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
7971<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
7972<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
7973<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
7974
902da432 7975
30eb152d 7976<!-- NEW PAGE --><H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2>
902da432 7977
7978<H3>Usage</H3>
7979
30eb152d 7980<PRE>
70bb1290 7981int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice);
30eb152d 7982</PRE>
7983
902da432 7984<H3>Arguments</H3>
7985
03efb52b 7986<CENTER><TABLE WIDTH="80%" BORDER>
902da432 7987<TR>
7988 <TH>Argument</TH>
7989 <TH>Description</TH>
7990</TR>
7991<TR>
70bb1290 7992 <TD>ppd</TD>
7993 <TD>The PPD file</TD>
7994</TR>
7995<TR>
7996 <TD>keyword</TD>
7997 <TD>The name of the option</TD>
7998</TR>
7999<TR>
8000 <TD>choice</TD>
8001 <TD>The name of the choice</TD>
902da432 8002</TR>
8003</TABLE></CENTER>
8004
8005<H3>Returns</H3>
8006
70bb1290 8007<P>The number of conflicts in the PPD file.
8008
902da432 8009<H3>Description</H3>
8010
70bb1290 8011<P>The <CODE>ppdMarkOption()</CODE> function marks the specified option
8012choice.
8013
03efb52b 8014<H3>Example</H3>
902da432 8015
30eb152d 8016<PRE>
70bb1290 8017#include &lt;cups/ppd.h>
8018
8019ppd_file_t *ppd;
8020
8021ppdMarkOption(ppd, "PageSize", "Letter");
30eb152d 8022</PRE>
8023
902da432 8024<H3>See Also</H3>
8025
70bb1290 8026<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
8027<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
8028<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
8029<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
8030<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
902da432 8031
70bb1290 8032
8033<!-- NEW PAGE --><H2><A NAME="ppdOpen">ppdOpen()</A></H2>
902da432 8034
8035<H3>Usage</H3>
8036
30eb152d 8037<PRE>
70bb1290 8038ppd_file_t *ppdOpen(FILE *file);
30eb152d 8039</PRE>
8040
902da432 8041<H3>Arguments</H3>
8042
03efb52b 8043<CENTER><TABLE WIDTH="80%" BORDER>
902da432 8044<TR>
8045 <TH>Argument</TH>
8046 <TH>Description</TH>
8047</TR>
8048<TR>
70bb1290 8049 <TD>file</TD>
8050 <TD>The file to read from</TD>
902da432 8051</TR>
8052</TABLE></CENTER>
8053
8054<H3>Returns</H3>
8055
70bb1290 8056<P>A pointer to a PPD file structure or NULL if the PPD file could not be
8057read.
8058
902da432 8059<H3>Description</H3>
8060
70bb1290 8061<P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the specified
8062file into memory.
8063
03efb52b 8064<H3>Example</H3>
902da432 8065
30eb152d 8066<PRE>
70bb1290 8067#include &lt;cups/ppd.h>
8068
8069ppd_file_t *ppd;
8070FILE *file;
8071
8072file = fopen("filename.ppd", "rb");
8073ppd = ppdOpen(file);
8074fclose(file);
30eb152d 8075</PRE>
8076
902da432 8077<H3>See Also</H3>
8078
70bb1290 8079<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
8080<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
8081<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
902da432 8082
70bb1290 8083
8084<!-- NEW PAGE --><H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2>
902da432 8085
8086<H3>Usage</H3>
8087
30eb152d 8088<PRE>
70bb1290 8089ppd_file_t *ppdOpenFd(int fd);
30eb152d 8090</PRE>
8091
902da432 8092<H3>Arguments</H3>
8093
03efb52b 8094<CENTER><TABLE WIDTH="80%" BORDER>
902da432 8095<TR>
8096 <TH>Argument</TH>
8097 <TH>Description</TH>
8098</TR>
8099<TR>
70bb1290 8100 <TD>fd</TD>
8101 <TD>The file descriptor to read from</TD>
902da432 8102</TR>
8103</TABLE></CENTER>
8104
8105<H3>Returns</H3>
8106
70bb1290 8107<P>A pointer to a PPD file structure or NULL if the PPD file could not be
8108read.
8109
902da432 8110<H3>Description</H3>
8111
70bb1290 8112<P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the specified
8113file descriptor into memory.
8114
03efb52b 8115<H3>Example</H3>
902da432 8116
30eb152d 8117<PRE>
70bb1290 8118#include &lt;cups/ppd.h>
8119
8120ppd_file_t *ppd;
8121int fd;
8122
8123fd = open("filename.ppd", O_RDONLY);
8124ppd = ppdOpenFd(fd);
8125close(fd);
30eb152d 8126</PRE>
8127
902da432 8128<H3>See Also</H3>
8129
70bb1290 8130<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
8131<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
8132<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
902da432 8133
70bb1290 8134
8135<!-- NEW PAGE --><H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2>
902da432 8136
8137<H3>Usage</H3>
8138
30eb152d 8139<PRE>
70bb1290 8140ppd_file_t *ppdOpenFile(const char *filename);
30eb152d 8141</PRE>
8142
902da432 8143<H3>Arguments</H3>
8144
03efb52b 8145<CENTER><TABLE WIDTH="80%" BORDER>
902da432 8146<TR>
8147 <TH>Argument</TH>
8148 <TH>Description</TH>
8149</TR>
8150<TR>
70bb1290 8151 <TD>filename</TD>
8152 <TD>The name of the file to read from</TD>
902da432 8153</TR>
8154</TABLE></CENTER>
8155
8156<H3>Returns</H3>
8157
70bb1290 8158<P>A pointer to a PPD file structure or NULL if the PPD file could not be
8159read.
8160
902da432 8161<H3>Description</H3>
8162
70bb1290 8163<P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the named
8164file into memory.
8165
03efb52b 8166<H3>Example</H3>
902da432 8167
30eb152d 8168<PRE>
70bb1290 8169#include &lt;cups/ppd.h>
8170
8171ppd_file_t *ppd;
8172
8173ppd = ppdOpenFile("filename.ppd");
30eb152d 8174</PRE>
8175
902da432 8176<H3>See Also</H3>
8177
70bb1290 8178<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
8179<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
8180<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>
8181
902da432 8182
30eb152d 8183<!-- NEW PAGE --><H2><A NAME="ppdPageLength">ppdPageLength()</A></H2>
902da432 8184
8185<H3>Usage</H3>
8186
30eb152d 8187<PRE>
70bb1290 8188float ppdPageLength(ppd_file_t *ppd, const char *name);
30eb152d 8189</PRE>
8190
902da432 8191<H3>Arguments</H3>
8192
03efb52b 8193<CENTER><TABLE WIDTH="80%" BORDER>
902da432 8194<TR>
8195 <TH>Argument</TH>
8196 <TH>Description</TH>
8197</TR>
8198<TR>
70bb1290 8199 <TD>ppd</TD>
8200 <TD>The PPD file</TD>
8201</TR>
8202<TR>
8203 <TD>name</TD>
8204 <TD>The name of the page size</TD>
902da432 8205</TR>
8206</TABLE></CENTER>
8207
8208<H3>Returns</H3>
8209
70bb1290 8210<P>The length of the specified page size in points or 0 if the page size
8211does not exist.
8212
902da432 8213<H3>Description</H3>
8214
70bb1290 8215<P>The <CODE>ppdPageLength()</CODE> function returns the page length of the
8216specified page size.
8217
03efb52b 8218<H3>Example</H3>
902da432 8219
30eb152d 8220<PRE>
70bb1290 8221#include &lt;cups/ppd.h>
8222
8223ppd_file_t *ppd;
8224
8225printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
30eb152d 8226</PRE>
8227
902da432 8228<H3>See Also</H3>
8229
70bb1290 8230<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
8231<A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>,
8232<A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
8233
902da432 8234
30eb152d 8235<!-- NEW PAGE --><H2><A NAME="ppdPageSize">ppdPageSize()</A></H2>
902da432 8236
8237<H3>Usage</H3>
8238
30eb152d 8239<PRE>
70bb1290 8240ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name);
30eb152d 8241</PRE>
8242
902da432 8243<H3>Arguments</H3>
8244
03efb52b 8245<CENTER><TABLE WIDTH="80%" BORDER>
902da432 8246<TR>
8247 <TH>Argument</TH>
8248 <TH>Description</TH>
8249</TR>
8250<TR>
70bb1290 8251 <TD>ppd</TD>
8252 <TD>The PPD file</TD>
8253</TR>
8254<TR>
8255 <TD>name</TD>
8256 <TD>The name of the page size</TD>
902da432 8257</TR>
8258</TABLE></CENTER>
8259
8260<H3>Returns</H3>
8261
70bb1290 8262<P>A pointer to the page size record of the specified page size in
8263points or NULL if the page size does not exist.
8264
902da432 8265<H3>Description</H3>
8266
70bb1290 8267<P>The <CODE>ppdPageSize()</CODE> function returns the page size record for the
8268specified page size.
8269
03efb52b 8270<H3>Example</H3>
902da432 8271
30eb152d 8272<PRE>
70bb1290 8273#include &lt;cups/ppd.h>
8274
8275ppd_file_t *ppd;
8276ppd_size_t *size;
8277
8278size = ppdPageSize(ppd, "Letter");
8279if (size != NULL)
8280{
8281 printf(" Width = %.0f\n", size->width);
8282 printf("Length = %.0f\n", size->length);
8283 printf(" Left = %.0f\n", size->left);
8284 printf(" Right = %.0f\n", size->right);
8285 printf("Bottom = %.0f\n", size->bottom);
8286 printf(" Top = %.0f\n", size->top);
8287}
30eb152d 8288</PRE>
8289
902da432 8290<H3>See Also</H3>
8291
70bb1290 8292<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
8293<A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
8294
902da432 8295
30eb152d 8296<!-- NEW PAGE --><H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2>
902da432 8297
8298<H3>Usage</H3>
8299
30eb152d 8300<PRE>
70bb1290 8301float ppdPageWidth(ppd_file_t *ppd, const char *name);
30eb152d 8302</PRE>
8303
902da432 8304<H3>Arguments</H3>
8305
03efb52b 8306<CENTER><TABLE WIDTH="80%" BORDER>
902da432 8307<TR>
8308 <TH>Argument</TH>
8309 <TH>Description</TH>
8310</TR>
8311<TR>
70bb1290 8312 <TD>ppd</TD>
8313 <TD>The PPD file</TD>
8314</TR>
8315<TR>
8316 <TD>name</TD>
8317 <TD>The name of the page size</TD>
902da432 8318</TR>
8319</TABLE></CENTER>
8320
8321<H3>Returns</H3>
8322
70bb1290 8323<P>The width of the specified page size in points or 0 if the page size
8324does not exist.
8325
902da432 8326<H3>Description</H3>
8327
70bb1290 8328<P>The <CODE>ppdPageWidth()</CODE> function returns the page width of the
8329specified page size.
8330
03efb52b 8331<H3>Example</H3>
902da432 8332
30eb152d 8333<PRE>
70bb1290 8334#include &lt;cups/ppd.h>
8335
8336ppd_file_t *ppd;
8337
8338printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));
30eb152d 8339</PRE>
8340
902da432 8341<H3>See Also</H3>
8342
70bb1290 8343<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
8344<A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>
8345
902da432 8346
8347</BODY>
8348</HTML>
Unnamed repository; edit this file 'description' to name the repository.