]> 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
Load cups into easysw/current.
[thirdparty/cups.git] / doc / spm.shtml
CommitLineData
ef416fc2 1<HTML>
2<HEAD>
3 <META NAME="COPYRIGHT" CONTENT="Copyright 1997-2003, All Rights Reserved">
4 <META NAME="DOCNUMBER" CONTENT="CUPS-SPM-1.2.0">
5 <META NAME="Author" CONTENT="Easy Software Products">
6 <TITLE>CUPS Software Programmers Manual</TITLE>
7</HEAD>
8<BODY>
9
10<H1 ALIGN="RIGHT">Preface</H1>
11
12<P>This software programmers manual provides software
13programming information for the Common UNIX Printing System
14("CUPS") Version 1.2.0.
15
16<EMBED SRC="system-overview.shtml">
17
18<!-- NEED 2in -->
19<H2>Document Overview</H2>
20
21<P>This software programmers manual is organized into the following sections:
22
23<UL>
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>
33</UL>
34
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</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>
135
136<P>This chapter describes the CUPS Application Programmers Interface ("API").
137
138<H2>The CUPS API Library</H2>
139
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.
143
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.
147
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</VAR> 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.
197
198<H3>Include Files</H3>
199
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>
206
207<H3>Printing a File</H3>
208
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.
255
256<H3>Cancelling Jobs</H3>
257
258<P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:
259
260<UL><PRE>
261#include &lt;cups/cups.h&gt;
262
263...
264
265int jobid;
266int status;
267...
268
269status = cupsCancelJob("<I>name</I>", <I>jobid</I>);
270</PRE></UL>
271
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.
276
277<P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
278successfully cancelled and <CODE>0</CODE> if there was an error.
279
280<H3>Getting the Available Printers and Classes</H3>
281
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:
284
285<UL><PRE>
286#include &lt;cups/cups.h&gt;
287
288...
289
290int num_dests;
291cups_dest_t *dests;
292
293...
294
295num_dests = cupsGetDests(&amp;dests);
296</PRE></UL>
297
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:
302
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;
320
321...
322
323int num_dests;
324cups_dest_t *dests;
325cups_dest_t *mydest;
326
327...
328
329mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests);
330</PRE></UL>
331
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.
334
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".
338
339<H3>Printing with Options</H3>
340
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</PRE></UL>
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...
423
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...
445
446int jobid;
447
448...
449
450if (jobid == 0)
451 puts(cupsErrorString(cupsLastError()));
452</PRE></UL>
453
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
513<H2>PPD Services</H2>
514
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
522<H3>Include Files</H3>
523
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
556<H3>Loading a PPD File</H3>
557
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>
593
594<H3>The PPD File Structure</H3>
595
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>
819
820<H3>Marking Options</H3>
821
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
879<H3>Checking for Conflicts</H3>
880
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>
899
900<P>The return value is the number of conflicting options, or 0 if there
901are no conflicts.
902
903
904<H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
905
906<P>This chapter describes how to write a file filter for CUPS.
907
908<H2>Overview</H2>
909
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
915<H3>Security Considerations</H3>
916
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
921<H3>Users and Groups</H3>
922
923<P>The default CUPS configuration runs filters as user "lp" and group "other".
924
925<H3>Temporary Files</H3>
926
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
961<H3>Page Accounting</H3>
962
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>
985
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.
1015
1016<H3>Copy Generation</H3>
1017
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
1061
1062 <LI><CODE>USER</CODE> - The name of the current user
1063
1064</UL>
1065
1066<H2>Dissecting the HP-GL/2 Filter</H2>
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 */
1097
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:
1117
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.
1180
1181<H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A></H1>
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
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
1208<H3>Page Accounting</H3>
1209
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
1214<H3>Color Management</H3>
1215
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.
1226
1227<H3>Device and Bitmap Variables</H3>
1228
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:
1233
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</PRE></UL>
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:
1454
1455<UL><PRE>
1456cups_raster_header_t header;
1457int y;
1458unsigned char data[8192];
1459
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>
1470
1471<P>After you have processed all pages, close the raster stream and
1472return:
1473
1474<UL><PRE>
1475cupsRasterClose(ras);
1476
1477return (0);
1478</PRE></UL>
1479
1480<H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
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
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
1492<H3>Security Considerations</H3>
1493
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.
1498
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.
1511
1512<H3>Page Accounting</H3>
1513
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
1525<H3>Retries</H3>
1526
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.
1531
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.
1535
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:
1629
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 }
1642
1643 nbytes -= wbytes;
1644 bufptr += wbytes;
1645}
1646</PRE></UL>
1647
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.
1650
1651<H3>Finishing Up</H3>
1652
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.
1657
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>
1664
1665<P>This appendix lists all of the constants that are defined by the CUPS
1666API.
1667
1668<H2>CUPS Constants</H2>
1669
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 <LI><CODE>CUPS_KOI8_R</CODE> - Russian code page koi8-r.
1786
1787 <LI><CODE>CUPS_KOI8_U</CODE> - Ukrainian code page koi8-r.
1788
1789</UL>
1790
1791<H2>HTTP Constants</H2>
1792
1793<H3>Limits</H3>
1794
1795<P>The following constants define the limits for strings:
1796
1797<UL>
1798
1799 <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.
1800
1801 <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.
1802
1803 <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.
1804
1805 <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.
1806
1807</UL>
1808
1809<H3>Status Codes</H3>
1810
1811<P>The following status codes can be returned by <CODE>httpUpdate()</CODE>:
1812
1813<UL>
1814
1815 <LI><CODE>HTTP_ERROR</CODE> - A network error occurred
1816
1817 <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy
1818
1819 <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was successful
1820
1821 <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful
1822
1823 <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful
1824
1825 <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't authoritative
1826
1827 <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command
1828
1829 <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated
1830
1831 <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was recieved/sent
1832
1833 <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request
1834
1835 <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently
1836
1837 <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily
1838
1839 <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...
1840
1841 <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified
1842
1843 <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI
1844
1845 <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request
1846
1847 <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host
1848
1849 <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required
1850
1851 <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI
1852
1853 <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found
1854
1855 <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed
1856
1857 <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable
1858
1859 <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is Required
1860
1861 <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out
1862
1863 <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting
1864
1865 <LI><CODE>HTTP_GONE</CODE> - Server has gone away
1866
1867 <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is required
1868
1869 <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed
1870
1871 <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large
1872
1873 <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long
1874
1875 <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type is unsupported
1876
1877 <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error
1878
1879 <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented
1880
1881 <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway
1882
1883 <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable
1884
1885 <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out
1886
1887 <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported
1888
1889</UL>
1890
1891<H3>Fields</H3>
1892
1893<P>The following fields are indices for each of the standard HTTP fields in
1894HTTP 1/1:
1895
1896<UL>
1897
1898 <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language
1899
1900 <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges
1901
1902 <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization
1903
1904 <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection
1905
1906 <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding
1907
1908 <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language
1909
1910 <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length
1911
1912 <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location
1913
1914 <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5
1915
1916 <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range
1917
1918 <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type
1919
1920 <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version
1921
1922 <LI><CODE>HTTP_FIELD_DATE</CODE> - Date
1923
1924 <LI><CODE>HTTP_FIELD_HOST</CODE> - Host
1925
1926 <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since
1927
1928 <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since
1929
1930 <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive
1931
1932 <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified
1933
1934 <LI><CODE>HTTP_FIELD_LINK</CODE> - Link
1935
1936 <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location
1937
1938 <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range
1939
1940 <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer
1941
1942 <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After
1943
1944 <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding
1945
1946 <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade
1947
1948 <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent
1949
1950 <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate
1951
1952
1953</UL>
1954
1955<H2>IPP Constants</H2>
1956
1957<H3>Limits</H3>
1958
1959<P>The following constants define array limits for IPP data:
1960
1961<UL>
1962
1963 <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name
1964
1965 <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values
1966 that can be read in a request.
1967
1968</UL>
1969
1970<H3>Tags</H3>
1971
1972<UL>
1973
1974 <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
1975 used to separate groups of attributes
1976
1977 <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation
1978
1979 <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job
1980
1981 <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end
1982
1983 <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer
1984
1985 <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type unsupported_group
1986
1987 <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type unsupported_value
1988
1989 <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default
1990
1991 <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown
1992
1993 <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue
1994
1995 <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type notsettable
1996
1997 <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr
1998
1999 <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue
2000
2001 <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer
2002
2003 <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean
2004
2005 <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum
2006
2007 <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string
2008
2009 <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date
2010
2011 <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution
2012
2013 <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range
2014
2015 <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection
2016
2017 <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang
2018
2019 <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang
2020
2021 <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text
2022
2023 <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name
2024
2025 <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword
2026
2027 <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri
2028
2029 <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme
2030
2031 <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset
2032
2033 <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language
2034
2035 <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype
2036
2037</UL>
2038
2039<H3>Resolution Units</H3>
2040
2041<P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE> constants
2042specify dots per inch and dots per centimeter, respectively.
2043
2044<H3>Finishings</H3>
2045
2046<P>The finishing values specify special finishing operations to be
2047performed on the job.
2048
2049<UL>
2050
2051 <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing
2052
2053 <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job
2054
2055 <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job
2056
2057 <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job
2058
2059 <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job
2060
2061</UL>
2062
2063<H3>Orientations</H3>
2064
2065<P>The orientation values specify the orientation of the job.
2066
2067<UL>
2068
2069 <LI><CODE>IPP_PORTRAIT</CODE> - No rotation
2070
2071 <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise
2072
2073 <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise
2074
2075 <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees
2076
2077</UL>
2078
2079<H3>Qualities</H3>
2080
2081<P>The quality values specify the desired quality of the print.
2082<UL>
2083
2084 <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality
2085
2086 <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality
2087
2088 <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality
2089
2090</UL>
2091
2092<H3>Job States</H3>
2093
2094<P>The job state values are used to represent the current job state.
2095
2096<UL>
2097
2098 <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending
2099
2100 <LI><CODE>IPP_JOB_HELD</CODE> - Job is held
2101
2102 <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing
2103
2104 <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped
2105
2106 <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled
2107
2108 <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted
2109
2110 <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed
2111
2112</UL>
2113
2114<H3>Printer States</H3>
2115
2116<P>The printer state values are used to represent the current printer
2117state.
2118
2119<UL>
2120
2121 <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle
2122
2123 <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing
2124
2125 <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped
2126
2127</UL>
2128
2129<H3>Operations</H3>
2130
2131<P>The operation values represent the available IPP operations.
2132
2133<UL>
2134
2135 <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file
2136
2137 <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI
2138
2139 <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes
2140
2141 <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job
2142
2143 <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job
2144
2145 <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job
2146
2147 <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job
2148
2149 <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes
2150
2151 <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs
2152
2153 <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes
2154
2155 <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job
2156
2157 <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job
2158
2159 <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job
2160
2161 <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer
2162
2163 <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer
2164
2165 <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue
2166
2167 <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes
2168
2169 <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes
2170
2171 <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer supported values
2172
2173 <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination
2174
2175 <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers
2176
2177 <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer
2178
2179 <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer
2180
2181 <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes
2182
2183 <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class
2184
2185 <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class
2186
2187 <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class
2188
2189 <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class
2190
2191 <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination
2192
2193 <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices
2194
2195 <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs
2196
2197 <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination
2198
2199</UL>
2200
2201<H3>Status Codes</H3>
2202
2203<P>Status codes are returned by all IPP requests.
2204
2205<UL>
2206
2207 <LI><CODE>IPP_OK</CODE> - Request completed with no errors
2208
2209 <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute
2210 values were substituted
2211
2212 <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes
2213 conflicted
2214
2215 <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad
2216
2217 <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource
2218
2219 <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for
2220 the resource
2221
2222 <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access
2223 the resource
2224
2225 <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be
2226 completed
2227
2228 <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred
2229
2230 <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found
2231
2232 <LI><CODE>IPP_GONE</CODE> - The resource has gone away
2233
2234 <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large
2235
2236 <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value
2237 that was unknown to the server
2238
2239 <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not
2240 supported by the server
2241
2242 <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing
2243
2244 <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported
2245
2246 <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported
2247
2248 <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict
2249
2250 <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified
2251 compression is not supported
2252
2253 <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data
2254 contained an error
2255
2256 <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data
2257 contained an error in it
2258
2259 <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document
2260 could not be accessed
2261
2262 <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an
2263 internal error
2264
2265 <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation
2266 is not supported
2267
2268 <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service
2269 is unavailable
2270
2271 <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request
2272 version is not supported
2273
2274 <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered
2275 an error
2276
2277 <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred
2278
2279 <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting
2280 jobs
2281
2282 <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy
2283
2284 <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been
2285 cancelled
2286
2287 <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server
2288 does not support multiple jobs
2289
2290</UL>
2291
2292<H2>PPD Constants</H2>
2293
2294<H3>PPD Format Version</H3>
2295
2296<P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number
2297representing the newest format version that is supported by CUPS, currently
22984.3.
2299
2300<H3>PPD User-Interface Types</H3>
2301
2302<P>Each printer option has a type associated with it:
2303
2304<UL>
2305
2306 <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or off
2307
2308 <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value
2309 to use.
2310
2311 <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more
2312 option values.
2313
2314</UL>
2315
2316<H3>PPD Sections</H3>
2317
2318<P>Some options must be output before others, or in different sections of
2319the output document. The <CODE>ppd_section_t</CODE> enumeration defines
2320which section the option must be output in:
2321
2322<UL>
2323
2324 <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of
2325 the document, page, or prolog sections of the document
2326
2327 <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in
2328 the DocumentSetup section of the document
2329
2330 <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before
2331 the document
2332
2333 <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the
2334 job control section of the document
2335
2336 <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the
2337 PageSetup section of the document
2338
2339 <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the
2340 Prolog section of the document
2341
2342</UL>
2343
2344<H3>PPD Colorspaces</H3>
2345
2346<P>Each printer has a default colorspace:
2347
2348<UL>
2349
2350 <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default
2351
2352 <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default
2353
2354 <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default
2355
2356 <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default
2357
2358 <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default
2359
2360 <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace
2361 by default
2362
2363</UL>
2364
2365<H2>Raster Constants</H2>
2366
2367<H3>Raster Sync Words</H3>
2368
2369<P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE>
2370constants define the standard sync words at the beginning of each CUPS
2371raster file.
2372
2373<H3>Raster Stream Modes</H3>
2374
2375<P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE>
2376constants are used with the
2377<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function to
2378specify a stream for reading or writing.
2379
2380<H3>Raster Boolean Constants</H3>
2381
2382<P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants
2383represent boolean values in the page header.
2384
2385<H3>Raster Jog Values</H3>
2386
2387<P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the
2388Jog page device dictionary variable:
2389
2390<UL>
2391
2392 <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging
2393
2394 <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file
2395
2396 <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job
2397
2398 <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs
2399
2400</UL>
2401
2402<H3>Raster Orientation Values</H3>
2403
2404<P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the
2405Orientation page device dictionary variable:
2406
2407<UL>
2408
2409 <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation
2410
2411 <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation
2412
2413 <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation
2414
2415 <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation
2416
2417</UL>
2418
2419<H3>Raster CutMedia Values</H3>
2420
2421<P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the
2422CutMedia page device dictionary variable:
2423
2424<UL>
2425
2426 <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging
2427
2428 <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file
2429
2430 <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job
2431
2432 <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs
2433
2434 <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page
2435
2436</UL>
2437
2438<H3>Raster AdvanceMedia Values</H3>
2439
2440<P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the
2441AdvanceMedia page device dictionary variable:
2442
2443<UL>
2444
2445 <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging
2446
2447 <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file
2448
2449 <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job
2450
2451 <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs
2452
2453 <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page
2454
2455</UL>
2456
2457<H3>Raster LeadingEdge Values</H3>
2458
2459<P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the
2460LeadingEdge page device dictionary variable:
2461
2462<UL>
2463
2464 <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading
2465 edge
2466
2467 <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading
2468 edge
2469
2470 <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the
2471 leading edge
2472
2473 <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading
2474 edge
2475
2476</UL>
2477
2478<H3>Raster Color Order Values</H3>
2479
2480<P>The <CODE>cups_order_t</CODE> enumeration defines the possible color
2481value orderings:
2482
2483<UL>
2484
2485 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK
2486
2487 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK
2488
2489 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...
2490
2491</UL>
2492
2493<H3>Raster Colorspace Values</H3>
2494
2495<P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible colorspaces:
2496
2497<UL>
2498
2499 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)
2500
2501 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue
2502
2503 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha
2504
2505 <LI><CODE>CUPS_CSPACE_K</CODE> - Black
2506
2507 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow
2508
2509 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan
2510
2511 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black
2512
2513 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black
2514
2515 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow
2516
2517 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
2518 light cyan, light magenta
2519
2520 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic magenta,
2521 metallic cyan, black
2522
2523 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic magenta,
2524 metallic cyan, metallic grey (silver)
2525
2526 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white pigment)
2527
2528 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)
2529
2530 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)
2531
2532</UL>
2533
2534<H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1>
2535
2536<P>This appendix describes all of the structures that are
2537defined by the CUPS API.
2538
2539<H2>CUPS Structures</H2>
2540
2541<H3><A NAME="cups_dest_t">CUPS Destinations</A></H3>
2542
2543<P>The CUPS destination structure (<CODE>cups_dest_t</CODE>)
2544contains information on a specific destination or instance:
2545
2546<CENTER><TABLE WIDTH="90%" BORDER="1">
2547<TR>
2548 <TH>Member</TH>
2549 <TH>Type</TH>
2550 <TH>Description</TH>
2551</TR>
2552<TR>
2553 <TD>name</TD>
2554 <TD>char *</TD>
2555 <TD>The name of the printer or class.</TD>
2556</TR>
2557<TR>
2558 <TD>instance</TD>
2559 <TD>char *</TD>
2560 <TD>The instance of the printer or class; NULL for the primary
2561 instance.</TD>
2562</TR>
2563<TR>
2564 <TD>is_default</TD>
2565 <TD>int</TD>
2566 <TD>1 if the destination is set as the default, 0 otherwise.</TD>
2567</TR>
2568<TR>
2569 <TD>num_options</TD>
2570 <TD>int</TD>
2571 <TD>The number of options associated with this destination.</TD>
2572</TR>
2573<TR>
2574 <TD>options</TD>
2575 <TD><A HREF="#cups_option_t">cups_option_t *</A></TD>
2576 <TD>The options associated with this destination.</TD>
2577</TR>
2578</TABLE></CENTER>
2579
2580<H3><A NAME="cups_job_t">CUPS Jobs</A></H3>
2581
2582<P>The CUPS job structure (<CODE>cups_job_t</CODE>) contains
2583information on a specific job:
2584
2585<CENTER><TABLE WIDTH="90%" BORDER="1">
2586<TR>
2587 <TH>Member</TH>
2588 <TH>Type</TH>
2589 <TH>Description</TH>
2590</TR>
2591<TR>
2592 <TD>id</TD>
2593 <TD>int</TD>
2594 <TD>The job ID for this job.</TD>
2595</TR>
2596<TR>
2597 <TD>dest</TD>
2598 <TD>char *</TD>
2599 <TD>The destination for this job (printer or class name).</TD>
2600</TR>
2601<TR>
2602 <TD>title</TD>
2603 <TD>char *</TD>
2604 <TD>The job-name for this job (title).</TD>
2605</TR>
2606<TR>
2607 <TD>user</TD>
2608 <TD>char *</TD>
2609 <TD>The job-originating-user-name for this job (username).</TD>
2610</TR>
2611<TR>
2612 <TD>format</TD>
2613 <TD>char *</TD>
2614 <TD>The document-format for this job (MIME type string).</TD>
2615</TR>
2616<TR>
2617 <TD>state</TD>
2618 <TD>ipp_jstate</TD>
2619 <TD>The current state of the job.</TD>
2620</TR>
2621<TR>
2622 <TD>size</TD>
2623 <TD>int</TD>
2624 <TD>The size of this job in kilobytes.</TD>
2625</TR>
2626<TR>
2627 <TD>priority</TD>
2628 <TD>int</TD>
2629 <TD>The priority of this job from 1 to 100 (50 is normal).</TD>
2630</TR>
2631<TR>
2632 <TD>completed_time</TD>
2633 <TD>time_t</TD>
2634 <TD>The time the job was completed, or 0 if not yet completed.</TD>
2635</TR>
2636<TR>
2637 <TD>creation_time</TD>
2638 <TD>time_t</TD>
2639 <TD>The time the job was queued.</TD>
2640</TR>
2641<TR>
2642 <TD>processing_time</TD>
2643 <TD>time_t</TD>
2644 <TD>The time the job started printing.</TD>
2645</TR>
2646</TABLE></CENTER>
2647
2648<H3><A NAME="cups_lang_t">CUPS Messages</A></H3>
2649
2650<P>The CUPS messages structure (<CODE>cups_lang_t</CODE>)
2651contains the character set, locale name, and messages array:
2652
2653<CENTER><TABLE WIDTH="90%" BORDER="1">
2654<TR>
2655 <TH>Member</TH>
2656 <TH>Type</TH>
2657 <TH>Description</TH>
2658</TR>
2659<TR>
2660 <TD>next</TD>
2661 <TD>cups_lang_t *</TD>
2662 <TD>Pointer to the next messages structure in memory.</TD>
2663</TR>
2664<TR>
2665 <TD>used</TD>
2666 <TD>int</TD>
2667 <TD>The number of active users of this messages structure.</TD>
2668</TR>
2669<TR>
2670 <TD>encoding</TD>
2671 <TD>cups_encoding_t</TD>
2672 <TD>The character encoding of the message strings.</TD>
2673</TR>
2674<TR>
2675 <TD>language</TD>
2676 <TD>char [16]</TD>
2677 <TD>The language/locale name.</TD>
2678</TR>
2679<TR>
2680 <TD>messages</TD>
2681 <TD>char *[]</TD>
2682 <TD>The array of message strings.</TD>
2683</TR>
2684</TABLE></CENTER>
2685
2686<H3><A NAME="cups_option_t">CUPS Options</A></H3>
2687
2688<P>The CUPS option structure (<CODE>cups_option_t</CODE>)
2689contains the option name and string value:
2690
2691<CENTER><TABLE WIDTH="90%" BORDER="1">
2692<TR>
2693 <TH>Member</TH>
2694 <TH>Type</TH>
2695 <TH>Description</TH>
2696</TR>
2697<TR>
2698 <TD>name</TD>
2699 <TD>char *</TD>
2700 <TD>The name of the option.</TD>
2701</TR>
2702<TR>
2703 <TD>value</TD>
2704 <TD>char *</TD>
2705 <TD>The string value of the option.</TD>
2706</TR>
2707</TABLE></CENTER>
2708
2709<H2>Networking Structures</H2>
2710
2711<H3><A NAME="http_t">HTTP State</A></H3>
2712
2713<P>The HTTP state structure (<CODE>http_t</CODE>) contains the
2714current state of a HTTP request or response:
2715
2716<CENTER><TABLE WIDTH="90%" BORDER="1">
2717<TR>
2718 <TH>Member</TH>
2719 <TH>Type</TH>
2720 <TH>Description</TH>
2721</TR>
2722<TR>
2723 <TD>fd</TD>
2724 <TD>int</TD>
2725 <TD>The socket for the HTTP connection.</TD>
2726</TR>
2727<TR>
2728 <TD>blocking</TD>
2729 <TD>int</TD>
2730 <TD>1 if the HTTP functions should block, 0 if not.</TD>
2731</TR>
2732<TR>
2733 <TD>error</TD>
2734 <TD>int</TD>
2735 <TD>The last OS error that occurred on the socket.</TD>
2736</TR>
2737<TR>
2738 <TD>activity</TD>
2739 <TD>time_t</TD>
2740 <TD>The last time the HTTP connection was used.</TD>
2741</TR>
2742<TR>
2743 <TD>state</TD>
2744 <TD>http_state_t</TD>
2745 <TD>The current HTTP request/response state.</TD>
2746</TR>
2747<TR>
2748 <TD>status</TD>
2749 <TD>int</TD>
2750 <TD>The last HTTP status seen.</TD>
2751</TR>
2752<TR>
2753 <TD>version</TD>
2754 <TD>http_version_t</TD>
2755 <TD>The HTTP protocol version in use.</TD>
2756</TR>
2757<TR>
2758 <TD>keep_alive</TD>
2759 <TD>http_keep_alive_t</TD>
2760 <TD>Whether or not to use Keep-Alive</TD>
2761</TR>
2762<TR>
2763 <TD>hostaddr</TD>
2764 <TD>struct sockaddr_in</TD>
2765 <TD>The IPv4 address of the HTTP server.</TD>
2766</TR>
2767<TR>
2768 <TD>hostname</TD>
2769 <TD>char []</TD>
2770 <TD>The hostname of the HTTP server.</TD>
2771</TR>
2772<TR>
2773 <TD>fields</TD>
2774 <TD>char [][]</TD>
2775 <TD>The string values of all HTTP request/response
2776 fields.</TD>
2777</TR>
2778<TR>
2779 <TD>data</TD>
2780 <TD>char *</TD>
2781 <TD>Current byte in data buffer.</TD>
2782</TR>
2783<TR>
2784 <TD>data_encoding</TD>
2785 <TD>http_encoding_t</TD>
2786 <TD>The transfer encoding for the request/response.</TD>
2787</TR>
2788<TR>
2789 <TD>data_remaining</TD>
2790 <TD>int</TD>
2791 <TD>The number of bytes remaining in the current request,
2792 response, or chunk.</TD>
2793</TR>
2794<TR>
2795 <TD>used</TD>
2796 <TD>int</TD>
2797 <TD>The number of bytes that are used in the buffer.</TD>
2798</TR>
2799<TR>
2800 <TD>buffer</TD>
2801 <TD>char []</TD>
2802 <TD>The read/write buffer.</TD>
2803</TR>
2804<TR>
2805 <TD>auth_type</TD>
2806 <TD>int</TD>
2807 <TD>The type of authentication in use.</TD>
2808</TR>
2809<TR>
2810 <TD>md5_state</TD>
2811 <TD>md5_state_t</TD>
2812 <TD>The current MD5 digest state.</TD>
2813</TR>
2814<TR>
2815 <TD>nonce</TD>
2816 <TD>char []</TD>
2817 <TD>The nonce value for Digest authentication.</TD>
2818</TR>
2819<TR>
2820 <TD>nonce_count</TD>
2821 <TD>int</TD>
2822 <TD>The nonce count value.</TD>
2823</TR>
2824<TR>
2825 <TD>tls</TD>
2826 <TD>void *</TD>
2827 <TD>A pointer to private encryption data.</TD>
2828</TR>
2829<TR>
2830 <TD>encryption</TD>
2831 <TD>http_encryption_t</TD>
2832 <TD>The current encryption mode.</TD>
2833</TR>
2834</TABLE></CENTER>
2835
2836<H3><A NAME="ipp_t">IPP State</A></H3>
2837
2838<P>The IPP state structure (<CODE>ipp_t</CODE>) contains the
2839current state of a IPP request or response:
2840
2841<CENTER><TABLE WIDTH="90%" BORDER="1">
2842<TR>
2843 <TH>Member</TH>
2844 <TH>Type</TH>
2845 <TH>Description</TH>
2846</TR>
2847<TR>
2848 <TD></TD>
2849 <TD></TD>
2850 <TD></TD>
2851</TR>
2852</TABLE></CENTER>
2853
2854<H2>Raster Structures</H2>
2855
2856<H3><A NAME="cups_raster_header_t">Raster Page Header</A></H3>
2857
2858<P>The raster page header (<CODE>cups_raster_header_t</CODE>)
2859consists of the PostScript page device dictionary for the page:
2860
2861<CENTER><TABLE WIDTH="90%" BORDER="1">
2862<TR>
2863 <TH>Member</TH>
2864 <TH>Type</TH>
2865 <TH>Description</TH>
2866</TR>
2867<TR>
2868 <TD>MediaClass</TD>
2869 <TD>char[64]</TD>
2870 <TD>The media class name</TD>
2871</TR>
2872<TR>
2873 <TD>MediaColor</TD>
2874 <TD>char[64]</TD>
2875 <TD>The media color name</TD>
2876</TR>
2877<TR>
2878 <TD>MediaType</TD>
2879 <TD>char[64]</TD>
2880 <TD>The media type name</TD>
2881</TR>
2882<TR>
2883 <TD>OutputType</TD>
2884 <TD>char[64]</TD>
2885 <TD>The output type name</TD>
2886</TR>
2887<TR>
2888 <TD>AdvanceDistance</TD>
2889 <TD>unsigned</TD>
2890 <TD>The distance to advance the media in points</TD>
2891</TR>
2892<TR>
2893 <TD>AdvanceMedia</TD>
2894 <TD>cups_adv_t</TD>
2895 <TD>When to advance the media</TD>
2896</TR>
2897<TR>
2898 <TD>Collate</TD>
2899 <TD>cups_bool_t</TD>
2900 <TD>Whether or not to produce collated copies</TD>
2901</TR>
2902<TR>
2903 <TD>CutMedia</TD>
2904 <TD>cups_cut_t</TD>
2905 <TD>When to cut the media</TD>
2906</TR>
2907<TR>
2908 <TD>Duplex</TD>
2909 <TD>cups_bool_t</TD>
2910 <TD>Whether or not to print on both sides of the paper</TD>
2911</TR>
2912<TR>
2913 <TD>HWResolution</TD>
2914 <TD>unsigned[2]</TD>
2915 <TD>The resolution of the page image in pixels per inch; the
2916 HWResolution[0] represents the horizontal resolution and
2917 HWResolution[1] represents the vertical resolution</TD>
2918</TR>
2919<TR>
2920 <TD>ImagingBoundingBox</TD>
2921 <TD>unsigned[4]</TD>
2922 <TD>The bounding box for the page in points; the elements
2923 represent the left, bottom, right, and top coordinates of the
2924 imaged area (if 0 then the whole page is imaged)</TD>
2925</TR>
2926<TR>
2927 <TD>InsertSheet</TD>
2928 <TD>cups_bool_t</TD>
2929 <TD>Whether or not to insert a sheet before this page</TD>
2930</TR>
2931<TR>
2932 <TD>Jog</TD>
2933 <TD>cups_jog_t</TD>
2934 <TD>When to jog copies of the page</TD>
2935</TR>
2936<TR>
2937 <TD>LeadingEdge</TD>
2938 <TD>cups_edge_t</TD>
2939 <TD>The leading edge of the page</TD>
2940</TR>
2941<TR>
2942 <TD>Margins</TD>
2943 <TD>unsigned[2]</TD>
2944 <TD>The lower-lefthand margin of the page in points</TD>
2945</TR>
2946<TR>
2947 <TD>ManualFeed</TD>
2948 <TD>cups_bool_t</TD>
2949 <TD>Whether or not to manually feed the page</TD>
2950</TR>
2951<TR>
2952 <TD>MediaPosition</TD>
2953 <TD>unsigned</TD>
2954 <TD>The input slot number to use</TD>
2955</TR>
2956<TR>
2957 <TD>MediaWeight</TD>
2958 <TD>unsigned</TD>
2959 <TD>The weight of the output media in grams/m<SUP>2</SUP></TD>
2960</TR>
2961<TR>
2962 <TD>MirrorPrint</TD>
2963 <TD>cups_bool_t</TD>
2964 <TD>Whether or not to mirror the print</TD>
2965</TR>
2966<TR>
2967 <TD>NegativePrint</TD>
2968 <TD>cups_bool_t</TD>
2969 <TD>Whether or not to invert the print</TD>
2970</TR>
2971<TR>
2972 <TD>NumCopies</TD>
2973 <TD>unsigned</TD>
2974 <TD>The number of copies to produce</TD>
2975</TR>
2976<TR>
2977 <TD>Orientation</TD>
2978 <TD>cups_orient_t</TD>
2979 <TD>The orientation of the page image</TD>
2980</TR>
2981<TR>
2982 <TD>OutputFaceUp</TD>
2983 <TD>cups_bool_t</TD>
2984 <TD>Whether or not to output the page face up</TD>
2985</TR>
2986<TR>
2987 <TD>PageSize</TD>
2988 <TD>unsigned[2]</TD>
2989 <TD>The width and height of the page in points</TD>
2990</TR>
2991<TR>
2992 <TD>Separations</TD>
2993 <TD>cups_bool_t</TD>
2994 <TD>Whether or not to output separations</TD>
2995</TR>
2996<TR>
2997 <TD>TraySwitch</TD>
2998 <TD>cups_bool_t</TD>
2999 <TD>Whether or not to automatically switch trays for the requested
3000 media size/type</TD>
3001</TR>
3002<TR>
3003 <TD>Tumble</TD>
3004 <TD>cups_bool_t</TD>
3005 <TD>Whether or not to rotate the back side of the page</TD>
3006</TR>
3007<TR>
3008 <TD>cupsWidth</TD>
3009 <TD>unsigned</TD>
3010 <TD>The width of the page image in pixels</TD>
3011</TR>
3012<TR>
3013 <TD>cupsHeight</TD>
3014 <TD>unsigned</TD>
3015 <TD>The height of the page image in pixels</TD>
3016</TR>
3017<TR>
3018 <TD>cupsMediaType</TD>
3019 <TD>unsigned</TD>
3020 <TD>The device-specific media type code</TD>
3021</TR>
3022<TR>
3023 <TD>cupsBitsPerColor</TD>
3024 <TD>unsigned</TD>
3025 <TD>The number of bits per color</TD>
3026</TR>
3027<TR>
3028 <TD>cupsBitsPerPixel</TD>
3029 <TD>unsigned</TD>
3030 <TD>The number of bits per pixel</TD>
3031</TR>
3032<TR>
3033 <TD>cupsBytesPerLine</TD>
3034 <TD>unsigned</TD>
3035 <TD>The number of bytes per line of image data</TD>
3036</TR>
3037<TR>
3038 <TD>cupsColorOrder</TD>
3039 <TD>cups_order_t</TD>
3040 <TD>The order of color values</TD>
3041</TR>
3042<TR>
3043 <TD>cupsColorSpace</TD>
3044 <TD>cups_cspace_t</TD>
3045 <TD>The type of color values</TD>
3046</TR>
3047<TR>
3048 <TD>cupsCompression</TD>
3049 <TD>unsigned</TD>
3050 <TD>The device-specific compression code</TD>
3051</TR>
3052<TR>
3053 <TD>cupsRowCount</TD>
3054 <TD>unsigned</TD>
3055 <TD>The device-specific row count</TD>
3056</TR>
3057<TR>
3058 <TD>cupsRowFeed</TD>
3059 <TD>unsigned</TD>
3060 <TD>The device-specific row feed</TD>
3061</TR>
3062<TR>
3063 <TD>cupsRowStep</TD>
3064 <TD>unsigned</TD>
3065 <TD>The device-specific row step</TD>
3066</TR>
3067</TABLE></CENTER>
3068
3069<H1 ALIGN="RIGHT"><A NAME="FUNCTIONS">D - Functions</A></H1>
3070
3071<P>This appendix provides a reference for all of the CUPS API functions.
3072
3073
3074<!-- NEW PAGE --><H2><A NAME="cupsAddDest">cupsAddDest()</A></H2>
3075
3076<H3>Usage</H3>
3077
3078<PRE>
3079int
3080cupsAddDest(const char *name,
3081 const char *instance,
3082 int num_dests,
3083 cups_dest_t **dests);
3084</PRE>
3085
3086<H3>Arguments</H3>
3087
3088<CENTER><TABLE WIDTH="80%" BORDER>
3089<TR>
3090 <TH>Argument</TH>
3091 <TH>Description</TH>
3092</TR>
3093<TR>
3094 <TD>name</TD>
3095 <TD>The name of the destination.</TD>
3096</TR>
3097<TR>
3098 <TD>instance</TD>
3099 <TD>The instance of the destination, or NULL for the primary instance.</TD>
3100</TR>
3101<TR>
3102 <TD>num_dests</TD>
3103 <TD>The number of destinations in the array.</TD>
3104</TR>
3105<TR>
3106 <TD>dest</TD>
3107 <TD>A pointer to the destination array pointer.</TD>
3108</TR>
3109</TABLE></CENTER>
3110
3111<H3>Returns</H3>
3112
3113<P>The new number of destinations in the array.
3114
3115<H3>Description</H3>
3116
3117<P><CODE>cupsAddDest()</CODE> adds the named destination to the destination
3118array if it does not already exist.
3119
3120<H3>Example</H3>
3121
3122<PRE>
3123#include &lt;cups/cups.h&gt;
3124
3125int num_dests;
3126<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3127
3128
3129num_dests = cupsAddDests("foo", "bar", num_dests, &amp;dests);
3130</PRE>
3131
3132<H3>See Also</H3>
3133
3134<P>
3135<A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>,
3136<A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
3137<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
3138
3139
3140<!-- NEW PAGE --><H2><A NAME="cupsAddOption">cupsAddOption()</A></H2>
3141
3142<H3>Usage</H3>
3143
3144<PRE>
3145int
3146cupsAddOption(const char *name,
3147 const char *value,
3148 int num_options,
3149 cups_option_t **options);
3150</PRE>
3151
3152<H3>Arguments</H3>
3153
3154<CENTER><TABLE WIDTH="80%" BORDER>
3155<TR>
3156 <TH>Argument</TH>
3157 <TH>Description</TH>
3158</TR>
3159<TR>
3160 <TD>name</TD>
3161 <TD>The name of the option.</TD>
3162</TR>
3163<TR>
3164 <TD>value</TD>
3165 <TD>The value of the option.</TD>
3166</TR>
3167<TR>
3168 <TD>num_options</TD>
3169 <TD>Number of options currently in the array.</TD>
3170</TR>
3171<TR>
3172 <TD>options</TD>
3173 <TD>Pointer to the options array.</TD>
3174</TR>
3175</TABLE></CENTER>
3176
3177<H3>Returns</H3>
3178
3179<P>The new number of options.
3180
3181<H3>Description</H3>
3182
3183<P><CODE>cupsAddOption()</CODE> adds an option to the specified array.
3184
3185<H3>Example</H3>
3186
3187<PRE>
3188#include &lt;cups.h&gt;
3189
3190...
3191
3192/* Declare the options array */
3193int num_options;
3194<A HREF="#cups_option_t">cups_option_t</A> *options;
3195
3196/* Initialize the options array */
3197num_options = 0;
3198options = (cups_option_t *)0;
3199
3200/* Add options using cupsAddOption() */
3201num_options = cupsAddOption("media", "letter", num_options, &amp;options);
3202num_options = cupsAddOption("resolution", "300dpi", num_options, &amp;options);
3203</PRE>
3204
3205<H3>See Also</H3>
3206
3207<A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
3208<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
3209<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
3210<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
3211
3212
3213<!-- NEW PAGE --><H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2>
3214
3215<H3>Usage</H3>
3216
3217<PRE>
3218int
3219cupsCancelJob(const char *dest,
3220 int job);
3221</PRE>
3222
3223<H3>Arguments</H3>
3224
3225<CENTER><TABLE WIDTH="80%" BORDER>
3226<TR>
3227 <TH>Argument</TH>
3228 <TH>Description</TH>
3229</TR>
3230<TR>
3231 <TD>dest</TD>
3232 <TD>Printer or class name</TD>
3233</TR>
3234<TR>
3235 <TD>job</TD>
3236 <TD>Job ID</TD>
3237</TR>
3238</TABLE></CENTER>
3239
3240<H3>Returns</H3>
3241
3242<P>1 on success, 0 on failure. On failure the error can be found by calling
3243<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
3244
3245<H3>Description</H3>
3246
3247<P><CODE>cupsCancelJob()</CODE> cancels the specifies job.
3248
3249<H3>Example</H3>
3250
3251<PRE>
3252#include &lt;cups.h&gt;
3253
3254cupsCancelJob("LaserJet", 1);
3255</PRE>
3256
3257<H3>See Also</H3>
3258
3259<P>
3260<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
3261<A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>,
3262<A HREF="#cupsPrintFiles"><CODE>cupsPrintFiles()</CODE></A>
3263
3264
3265<!-- NEW PAGE --><H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2>
3266
3267<H3>Usage</H3>
3268
3269<PRE>
3270ipp_t *
3271cupsDoFileRequest(http_t *http,
3272 ipp_t *request,
3273 const char *resource,
3274 const char *filename);
3275</PRE>
3276
3277<H3>Arguments</H3>
3278
3279<CENTER><TABLE WIDTH="80%" BORDER>
3280<TR>
3281 <TH>Argument</TH>
3282 <TH>Description</TH>
3283</TR>
3284<TR>
3285 <TD>http</TD>
3286 <TD>HTTP connection to server.</TD>
3287</TR>
3288<TR>
3289 <TD>request</TD>
3290 <TD>IPP request data.</TD>
3291</TR>
3292<TR>
3293 <TD>resource</TD>
3294 <TD>HTTP resource name for POST.</TD>
3295</TR>
3296<TR>
3297 <TD>filename</TD>
3298 <TD>File to send with POST request (<CODE>NULL</CODE> pointer if none.)</TD>
3299</TR>
3300</TABLE></CENTER>
3301
3302<H3>Returns</H3>
3303
3304<P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
3305the error can be found by calling
3306<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
3307
3308<H3>Description</H3>
3309
3310<P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and provides the
3311IPP request and optionally the contents of a file to the IPP server. It also
3312handles resubmitting the request and performing password authentication as
3313needed.
3314
3315<H3>Example</H3>
3316
3317<PRE>
3318#include &lt;cups.h&gt;
3319
3320<A HREF="#http_t">http_t</A> *http;
3321<A HREF="#cups_lang_t">cups_lang_t</A> *language;
3322<A HREF="#ipp_t">ipp_t</A> *request;
3323ipp_t *response;
3324
3325...
3326
3327/* Get the default language */
3328language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3329
3330/* Create a new IPP request */
3331request = <A HREF="#ippNew">ippNew()</A>;
3332
3333request-&gt;request.op.operation_id = IPP_PRINT_FILE;
3334request-&gt;request.op.request_id = 1;
3335
3336/* Add required attributes */
3337<A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3338 "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3339
3340ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3341 "attributes-natural-language", NULL,
3342 language != NULL ? language-&gt;language : "C");
3343
3344ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
3345 NULL, "ipp://hostname/resource");
3346
3347ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name",
3348 NULL, <A HREF="#cupsUser">cupsUser()</A>);
3349
3350/* Do the request... */
3351response = cupsDoFileRequest(http, request, "/resource", "filename.txt");
3352</PRE>
3353
3354<H3>See Also</H3>
3355
3356<P>
3357<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
3358<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
3359<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
3360<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
3361<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
3362<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
3363
3364
3365<!-- NEW PAGE --><H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2>
3366
3367<H3>Usage</H3>
3368
3369<PRE>
3370ipp_t *
3371cupsDoRequest(http_t *http,
3372 ipp_t *request,
3373 const char *resource);
3374</PRE>
3375
3376<H3>Arguments</H3>
3377
3378<CENTER><TABLE WIDTH="80%" BORDER>
3379<TR>
3380 <TH>Argument</TH>
3381 <TH>Description</TH>
3382</TR>
3383<TR>
3384 <TD>http</TD>
3385 <TD>HTTP connection to server.</TD>
3386</TR>
3387<TR>
3388 <TD>request</TD>
3389 <TD>IPP request data.</TD>
3390</TR>
3391<TR>
3392 <TD>resource</TD>
3393 <TD>HTTP resource name for POST.</TD>
3394</TR>
3395</TABLE></CENTER>
3396
3397<H3>Returns</H3>
3398
3399<P>IPP response data or <CODE>NULL</CODE> if the request fails. On failure
3400the error can be found by calling
3401<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>.
3402
3403<H3>Description</H3>
3404
3405<P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides
3406the IPP request to the IPP server. It also handles resubmitting the
3407request and performing password authentication as needed.
3408
3409<H3>Example</H3>
3410
3411<PRE>
3412#include &lt;cups.h&gt;
3413
3414<A HREF="#http_t">http_t</A> *http;
3415<A HREF="#cups_lang_t">cups_lang_t</A> *language;
3416<A HREF="#ipp_t">ipp_t</A> *request;
3417ipp_t *response;
3418
3419...
3420
3421/* Get the default language */
3422language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3423
3424/* Create a new IPP request */
3425request = <A HREF="#ippNew">ippNew()</A>;
3426
3427request-&gt;request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
3428request-&gt;request.op.request_id = 1;
3429
3430/* Add required attributes */
3431<A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3432 "attributes-charset", NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3433
3434ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3435 "attributes-natural-language", NULL,
3436 language != NULL ? language-&gt;language : "C");
3437
3438ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri",
3439 NULL, "ipp://hostname/resource");
3440
3441/* Do the request... */
3442response = cupsDoRequest(http, request, "/resource");
3443</PRE>
3444
3445<H3>See Also</H3>
3446
3447<P>
3448<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
3449<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
3450<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>,
3451<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
3452<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
3453<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
3454
3455
3456<!-- NEW PAGE --><H2><A NAME="cupsEncodeOptions">cupsEncodeOptions()</A></H2>
3457
3458<H3>Usage</H3>
3459
3460<PRE>
3461void
3462cupsEncodeOptions(ipp_t *ipp,
3463 int num_options,
3464 cups_option_t *options);
3465</PRE>
3466
3467<H3>Arguments</H3>
3468
3469<CENTER><TABLE WIDTH="80%" BORDER>
3470<TR>
3471 <TH>Argument</TH>
3472 <TH>Description</TH>
3473</TR>
3474<TR>
3475 <TD>ipp</TD>
3476 <TD>The IPP request.</TD>
3477</TR>
3478<TR>
3479 <TD>num_options</TD>
3480 <TD>The number of options.</TD>
3481</TR>
3482<TR>
3483 <TD>options</TD>
3484 <TD>The options.</TD>
3485</TR>
3486</TABLE></CENTER>
3487
3488<H3>Description</H3>
3489
3490<P><CODE>cupsEncodeOptions()</CODE> encodes all of the options
3491in the specified array as IPP attributes and adds them to the
3492IPP request.
3493
3494<H3>Example</H3>
3495
3496<PRE>
3497#include &lt;cups/cups.h&gt;
3498
3499<A HREF="#ipp_t">ipp_t</A> *ipp;
3500int num_options;
3501<A HREF="#cups_option_t">cups_option_t</A> *options;
3502
3503
3504cupsEncodeOptions(ipp, num_options, options);
3505</PRE>
3506
3507<H3>See Also</H3>
3508
3509<P>
3510<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
3511<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>,
3512<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
3513
3514
3515<!-- NEW PAGE --><H2><A NAME="cupsEncryption">cupsEncryption()</A></H2>
3516
3517<H3>Usage</H3>
3518
3519<PRE>
3520http_encryption_t
3521cupsEncryption(void);
3522</PRE>
3523
3524<H3>Returns</H3>
3525
3526<P>The current encryption setting.
3527
3528<H3>Description</H3>
3529
3530<P><CODE>cupsEncryption()</CODE> returns the current encryption setting
3531for IPP requests such as printing.
3532
3533<H3>Example</H3>
3534
3535<PRE>
3536#include &lt;cups/cups.h&gt;
3537
3538<A HREF="#http_t">http_t</A> *http;
3539
3540printf("The current encryption setting is %d.\n", cupsEncryption());
3541
3542http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
3543</PRE>
3544
3545<H3>See Also</H3>
3546
3547<P>
3548<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
3549<A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>,
3550<A HREF="#ippPort"><CODE>ippPort()</CODE></A>
3551
3552
3553<!-- NEW PAGE --><H2><A NAME="cupsFreeDests">cupsFreeDests()</A></H2>
3554
3555<H3>Usage</H3>
3556
3557<PRE>
3558void
3559cupsFreeDests(int num_dests,
3560 cups_dest_t *dests);
3561</PRE>
3562
3563<H3>Arguments</H3>
3564
3565<CENTER><TABLE WIDTH="80%" BORDER>
3566<TR>
3567 <TH>Argument</TH>
3568 <TH>Description</TH>
3569</TR>
3570<TR>
3571 <TD>num_dests</TD>
3572 <TD>The number of destinations in the array.</TD>
3573</TR>
3574<TR>
3575 <TD>dests</TD>
3576 <TD>The destination array.</TD>
3577</TR>
3578</TABLE></CENTER>
3579
3580<H3>Description</H3>
3581
3582<P><CODE>cupsFreeDests()</CODE> frees a destination array that was
3583created using <CODE>cupsGetDests()</CODE>.
3584
3585<H3>Example</H3>
3586
3587<PRE>
3588#include &lt;cups/cups.h&gt;
3589
3590int num_dests;
3591<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3592cups_dest_t *dest;
3593
3594num_dests = cupsGetDests(&amp;dests);
3595dest = cupsGetDest(NULL, NULL, num_dests, dests);
3596
3597if (dest)
3598 printf("The default destination is %s\n", dest->name);
3599else
3600 puts("No default destination.");
3601
3602cupsFreeDests(num_dests, dests);
3603</PRE>
3604
3605<H3>See Also</H3>
3606
3607<P>
3608<A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
3609<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
3610
3611
3612<!-- NEW PAGE --><H2><A NAME="cupsFreeJobs">cupsFreeJobs()</A></H2>
3613
3614<H3>Usage</H3>
3615
3616<PRE>
3617void
3618cupsFreeJobs(int num_jobs,
3619 cups_job_t *jobs);
3620</PRE>
3621
3622<H3>Arguments</H3>
3623
3624<CENTER><TABLE WIDTH="80%" BORDER>
3625<TR>
3626 <TH>Argument</TH>
3627 <TH>Description</TH>
3628</TR>
3629<TR>
3630 <TD>num_jobs</TD>
3631 <TD>The number of jobs.</TD>
3632</TR>
3633<TR>
3634 <TD>jobs</TD>
3635 <TD>The job array.</TD>
3636</TR>
3637</TABLE></CENTER>
3638
3639<H3>Description</H3>
3640
3641<P><CODE>cupsFreeJobs()</CODE> frees an array of print jobs created by
3642the <CODE>cupsGetJobs()</CODE> function.
3643
3644<H3>Example</H3>
3645
3646<PRE>
3647#include &lt;cups/cups.h&gt;
3648
3649int i;
3650int num_jobs;
3651<A HREF="#cups_job_t">cups_job_t</A> *jobs;
3652
3653
3654num_jobs = cupsGetJobs(&amp;jobs, NULL, 0, 0);
3655
3656printf("%d active job(s):\n", num_jobs);
3657for (i = 0; i &lt; num_jobs; i ++)
3658 printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
3659 jobs[i].user, jobs[i].title,
3660 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
3661
3662cupsFreeJobs(num_jobs, jobs);
3663</PRE>
3664
3665<H3>See Also</H3>
3666
3667<P>
3668<A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>,
3669<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
3670
3671
3672<!-- NEW PAGE --><H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2>
3673
3674<H3>Usage</H3>
3675
3676<PRE>
3677void
3678cupsFreeOptions(int num_options,
3679 cups_option_t *options);
3680</PRE>
3681
3682<H3>Arguments</H3>
3683
3684<CENTER><TABLE WIDTH="80%" BORDER>
3685<TR>
3686 <TH>Argument</TH>
3687 <TH>Description</TH>
3688</TR>
3689<TR>
3690 <TD>num_options</TD>
3691 <TD>Number of options in array.</TD>
3692</TR>
3693<TR>
3694 <TD>options</TD>
3695 <TD>Pointer to options array.</TD>
3696</TR>
3697</TABLE></CENTER>
3698
3699<H3>Description</H3>
3700
3701<P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the
3702option array specified.
3703
3704<H3>Example</H3>
3705
3706<PRE>
3707#include &lt;cups/cups.h&gt;
3708
3709int num_options;
3710<A HREF="#cups_option_t">cups_option_t</A> *options;
3711
3712...
3713
3714cupsFreeOptions(num_options, options);
3715</PRE>
3716
3717<H3>See Also</H3>
3718
3719<P>
3720<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
3721<A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
3722<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
3723<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
3724<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
3725
3726
3727<!-- NEW PAGE --><H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2>
3728
3729<H3>Usage</H3>
3730
3731<PRE>
3732int
3733cupsGetClasses(char ***classes);
3734</PRE>
3735
3736<H3>Arguments</H3>
3737
3738<CENTER><TABLE WIDTH="80%" BORDER>
3739<TR>
3740 <TH>Argument</TH>
3741 <TH>Description</TH>
3742</TR>
3743<TR>
3744 <TD>classes</TD>
3745 <TD>Pointer to character pointer array.</TD>
3746</TR>
3747</TABLE></CENTER>
3748
3749<H3>Returns</H3>
3750
3751<P>The number of printer classes available.
3752
3753<H3>Description</H3>
3754
3755<P><CODE>cupsGetClasses()</CODE> gets a list of the available printer classes.
3756The returned array should be freed using the <CODE>free()</CODE> when it is
3757no longer needed.
3758
3759<H3>Example</H3>
3760
3761<PRE>
3762#include &lt;cups/cups.h&gt;
3763
3764int i;
3765int num_classes;
3766char **classes;
3767
3768...
3769
3770num_classes = cupsGetClasses(&classes);
3771
3772...
3773
3774if (num_classes > 0)
3775{
3776 for (i = 0; i &lt; num_classes; i ++)
3777 free(classes[i]);
3778
3779 free(classes);
3780}
3781</PRE>
3782
3783<H3>See Also</H3>
3784
3785<P>
3786<A HREF="#cupsGetDefault"><CODE>cupsGetDefault()</CODE></A>,
3787<A HREF="#cupsGetPrinters"><CODE>cupsGetPrinters()</CODE></A>
3788
3789
3790<!-- NEW PAGE --><H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2>
3791
3792<H3>Usage</H3>
3793
3794<PRE>
3795const char *
3796cupsGetDefault(void);
3797</PRE>
3798
3799<H3>Returns</H3>
3800
3801<P>A pointer to the default destination.
3802
3803<H3>Description</H3>
3804
3805<P><CODE>cupsGetDefault()</CODE> gets the default destination printer or class.
3806The default destination is stored in a static string and will be overwritten
3807(usually with the same value) after each call.
3808
3809<H3>Example</H3>
3810
3811<PRE>
3812#include &lt;cups/cups.h&gt;
3813
3814printf("The default destination is %s\n", cupsGetDefault());
3815</PRE>
3816
3817<H3>See Also</H3>
3818
3819<P>
3820<A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A>,
3821<A HREF="#cupsGetPrinters"><CODE>cupsGetPrinters()</CODE></A>
3822
3823
3824<!-- NEW PAGE --><H2><A NAME="cupsGetDest">cupsGetDest()</A></H2>
3825
3826<H3>Usage</H3>
3827
3828<PRE>
3829cups_dest_t *
3830cupsGetDest(const char *name,
3831 const char *instance,
3832 int num_dests,
3833 cups_dest_t *dests);
3834</PRE>
3835
3836<H3>Arguments</H3>
3837
3838<CENTER><TABLE WIDTH="80%" BORDER>
3839<TR>
3840 <TH>Argument</TH>
3841 <TH>Description</TH>
3842</TR>
3843<TR>
3844 <TD>name</TD>
3845 <TD>The name of the destination, or NULL for the default destination.</TD>
3846</TR>
3847<TR>
3848 <TD>instance</TD>
3849 <TD>The instance of the destination, or NULL for the primary instance.</TD>
3850</TR>
3851<TR>
3852 <TD>num_dests</TD>
3853 <TD>The number of destinations.</TD>
3854</TR>
3855<TR>
3856 <TD>dests</TD>
3857 <TD>The destination array.</TD>
3858</TR>
3859</TABLE></CENTER>
3860
3861<H3>Returns</H3>
3862
3863<P>A pointer to the specified destination, or NULL if none exists.
3864
3865<H3>Description</H3>
3866
3867<P><CODE>cupsGetDest()</CODE> finds the specified destination in the array
3868of destinations created by the <CODE>cupsGetDests()</CODE> function.
3869
3870<H3>Example</H3>
3871
3872<PRE>
3873#include &lt;cups/cups.h&gt;
3874
3875int num_dests;
3876<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3877cups_dest_t *dest;
3878
3879num_dests = cupsGetDests(&amp;dests);
3880dest = cupsGetDest(NULL, NULL, num_dests, dests);
3881
3882if (dest)
3883 printf("The default destination is %s\n", dest->name);
3884else
3885 puts("No default destination.");
3886
3887cupsFreeDests(num_dests, dests);
3888</PRE>
3889
3890<H3>See Also</H3>
3891
3892<P>
3893<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>,
3894<A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>
3895
3896
3897<!-- NEW PAGE --><H2><A NAME="cupsGetDests">cupsGetDests()</A></H2>
3898
3899<H3>Usage</H3>
3900
3901<PRE>
3902int
3903cupsGetDests(cups_dest_t **dests);
3904</PRE>
3905
3906<H3>Arguments</H3>
3907
3908<CENTER><TABLE WIDTH="80%" BORDER>
3909<TR>
3910 <TH>Argument</TH>
3911 <TH>Description</TH>
3912</TR>
3913<TR>
3914 <TD>dests</TD>
3915 <TD>A pointer to a destination array pointer.</TD>
3916</TR>
3917</TABLE></CENTER>
3918
3919<H3>Returns</H3>
3920
3921<P>The number of available destinations.
3922
3923<H3>Description</H3>
3924
3925<P><CODE>cupsGetDests()</CODE> creates an array of available
3926destinations that the user can print to. The array should be
3927freed using the <CODE>cupsFreeDests()</CODE> function.
3928
3929<H3>Example</H3>
3930
3931<PRE>
3932#include &lt;cups/cups.h&gt;
3933
3934int num_dests;
3935<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
3936cups_dest_t *dest;
3937
3938num_dests = cupsGetDests(&amp;dests);
3939dest = cupsGetDest(NULL, NULL, num_dests, dests);
3940
3941if (dest)
3942 printf("The default destination is %s\n", dest->name);
3943else
3944 puts("No default destination.");
3945
3946cupsFreeDests(num_dests, dests);
3947</PRE>
3948
3949<H3>See Also</H3>
3950
3951<P>
3952<A HREF="#cupsFreeDests"><CODE>cupsFreeDests()</CODE></A>,
3953<A HREF="#cupsGetDest"><CODE>cupsGetDest()</CODE></A>,
3954<A HREF="#cupsGetJobs"><CODE>cupsGetJobs()</CODE></A>
3955
3956
3957<!-- NEW PAGE --><H2><A NAME="cupsGetJobs">cupsGetJobs()</A></H2>
3958
3959<H3>Usage</H3>
3960
3961<PRE>
3962int
3963cupsGetJobs(cups_job_t **jobs,
3964 const char *dest,
3965 int myjobs,
3966 int completed);
3967</PRE>
3968
3969<H3>Arguments</H3>
3970
3971<CENTER><TABLE WIDTH="80%" BORDER>
3972<TR>
3973 <TH>Argument</TH>
3974 <TH>Description</TH>
3975</TR>
3976<TR>
3977 <TD>jobs</TD>
3978 <TD>A pointer to the job array pointer.</TD>
3979</TR>
3980<TR>
3981 <TD>dest</TD>
3982 <TD>The destination name, or NULL if jobs for all destinations are requested.</TD>
3983</TR>
3984<TR>
3985 <TD>myjobs</TD>
3986 <TD>1 if only those jobs submitted by the current
3987 <CODE>cupsUser()</CODE> should be returned, 0 for jobs
3988 submitted by all users.</TD>
3989</TR>
3990<TR>
3991 <TD>completed</TD>
3992 <TD>1 if only completed jobs should be returned, 0 if only
3993 pending/processing jobs should be returned.</TD>
3994</TR>
3995</TABLE></CENTER>
3996
3997<H3>Returns</H3>
3998
3999<P>The number of jobs.
4000
4001<H3>Description</H3>
4002
4003<P><CODE>cupsGetJobs()</CODE> creates an array of print jobs based on the
4004arguments supplied in the function call. The returned array should be freed
4005using the <CODE>cupsFreeJobs()</CODE> function.
4006
4007<H3>Example</H3>
4008
4009<PRE>
4010#include &lt;cups/cups.h&gt;
4011
4012int i;
4013int num_jobs;
4014<A HREF="#cups_job_t">cups_job_t</A> *jobs;
4015
4016
4017num_jobs = cupsGetJobs(&amp;jobs, NULL, 0, 0);
4018
4019printf("%d active job(s):\n", num_jobs);
4020for (i = 0; i &lt; num_jobs; i ++)
4021 printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id,
4022 jobs[i].user, jobs[i].title,
4023 jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending");
4024
4025cupsFreeJobs(num_jobs, jobs);
4026</PRE>
4027
4028<H3>See Also</H3>
4029
4030<P>
4031<A HREF="#cupsFreeJobs"><CODE>cupsFreeJobs()</CODE></A>,
4032<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
4033
4034
4035<!-- NEW PAGE --><H2><A NAME="cupsGetOption">cupsGetOption()</A></H2>
4036
4037<H3>Usage</H3>
4038
4039<PRE>
4040const char *
4041cupsGetOption(const char *name,
4042 int num_options,
4043 cups_option_t *options);
4044</PRE>
4045
4046<H3>Arguments</H3>
4047
4048<CENTER><TABLE WIDTH="80%" BORDER>
4049<TR>
4050 <TH>Argument</TH>
4051 <TH>Description</TH>
4052</TR>
4053<TR>
4054 <TD>name</TD>
4055 <TD>The name of the option.</TD>
4056</TR>
4057<TR>
4058 <TD>num_options</TD>
4059 <TD>The number of options in the array.</TD>
4060</TR>
4061<TR>
4062 <TD>options</TD>
4063 <TD>The options array.</TD>
4064</TR>
4065</TABLE></CENTER>
4066
4067<H3>Returns</H3>
4068
4069<P>A pointer to the option values or <CODE>NULL</CODE> if the option is
4070not defined.
4071
4072<H3>Description</H3>
4073
4074<P><CODE>cupsGetOption()</CODE> returns the first occurrence of the
4075named option. If the option is not included in the options array then a
4076<CODE>NULL</CODE> pointer is returned.
4077
4078<PRE>
4079#include &lt;cups/cups.h&gt;
4080
4081int num_options;
4082cups_option_t *options;
4083const char *media;
4084
4085...
4086
4087media = cupsGetOption("media", num_options, options);
4088</PRE>
4089
4090<H3>See Also</H3>
4091
4092<P>
4093<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
4094<A HREF="#cupsEncodeOptions"><CODE>cupsEncodeOptions()</CODE></A>,
4095<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
4096<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
4097<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
4098
4099
4100<!-- NEW PAGE --><H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2>
4101
4102<H3>Usage</H3>
4103
4104<PRE>
4105const char *
4106cupsGetPassword(const char *prompt);
4107</PRE>
4108
4109<H3>Arguments</H3>
4110
4111<CENTER><TABLE WIDTH="80%" BORDER>
4112<TR>
4113 <TH>Argument</TH>
4114 <TH>Description</TH>
4115</TR>
4116<TR>
4117 <TD>prompt</TD>
4118 <TD>The prompt to display to the user.</TD>
4119</TR>
4120</TABLE></CENTER>
4121
4122<H3>Returns</H3>
4123
4124<P>A pointer to the password that was entered or <CODE>NULL</CODE> if no
4125password was entered.
4126
4127<H3>Description</H3>
4128
4129<P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks the user
4130for a password. The password text is not echoed to the user.
4131
4132<H3>Example</H3>
4133
4134<PRE>
4135#include &lt;cups/cups.h&gt;
4136
4137char *password;
4138
4139...
4140
4141password = cupsGetPassword("Please enter a password:");
4142</PRE>
4143
4144<H3>See Also</H3>
4145
4146<P>
4147<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
4148<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
4149<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
4150<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
4151<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
4152
4153
4154<!-- NEW PAGE --><H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2>
4155
4156<H3>Usage</H3>
4157
4158<PRE>
4159const char *
4160cupsGetPPD(const char *printer);
4161</PRE>
4162
4163<H3>Arguments</H3>
4164
4165<CENTER><TABLE WIDTH="80%" BORDER>
4166<TR>
4167 <TH>Argument</TH>
4168 <TH>Description</TH>
4169</TR>
4170<TR>
4171 <TD>printer</TD>
4172 <TD>The name of the printer.</TD>
4173</TR>
4174</TABLE></CENTER>
4175
4176<H3>Returns</H3>
4177
4178<P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE>
4179if the printer cannot be located or does not have a PPD file.
4180
4181<H3>Description</H3>
4182
4183<P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named printer.
4184The printer name can be of the form "printer" or "printer@hostname".
4185
4186<P>You should remove (unlink) the PPD file after you are done using it. The
4187filename is stored in a static buffer and will be overwritten with each call
4188to <CODE>cupsGetPPD()</CODE>.
4189
4190<H3>Example</H3>
4191
4192<PRE>
4193#include &lt;cups/cups.h&gt;
4194
4195char *ppd;
4196
4197...
4198
4199ppd = cupsGetPPD("printer@hostname");
4200
4201...
4202
4203unlink(ppd);
4204</PRE>
4205
4206
4207<!-- NEW PAGE --><H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2>
4208
4209<H3>Usage</H3>
4210
4211<PRE>
4212int
4213cupsGetPrinters(char ***printers);
4214</PRE>
4215
4216<H3>Arguments</H3>
4217
4218<CENTER><TABLE WIDTH="80%" BORDER>
4219<TR>
4220 <TH>Argument</TH>
4221 <TH>Description</TH>
4222</TR>
4223<TR>
4224 <TD>printers</TD>
4225 <TD>Pointer to character pointer array.</TD>
4226</TR>
4227</TABLE></CENTER>
4228
4229<H3>Returns</H3>
4230
4231<P>The number of printer printers available.
4232
4233<H3>Description</H3>
4234
4235<P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers.
4236The returned array should be freed using the <CODE>free()</CODE> when it is
4237no longer needed.
4238
4239<H3>Example</H3>
4240
4241<PRE>
4242#include &lt;cups/cups.h&gt;
4243
4244int i;
4245int num_printers;
4246char **printers;
4247
4248...
4249
4250num_printers = cupsGetPrinters(&printers);
4251
4252...
4253
4254if (num_printers > 0)
4255{
4256 for (i = 0; i &lt; num_printers; i ++)
4257 free(printers[i]);
4258
4259 free(printers);
4260}
4261</PRE>
4262
4263<H3>See Also</H3>
4264
4265<P>
4266<A HREF="#cupsGetClasses"><CODE>cupsGetClasses()</CODE></A>
4267<A HREF="#cupsGetDefault"><CODE>cupsGetDefault()</CODE></A>
4268
4269
4270<!-- NEW PAGE --><H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2>
4271
4272<H3>Usage</H3>
4273
4274<PRE>
4275const char *
4276cupsLangDefault(void);
4277</PRE>
4278
4279<H3>Returns</H3>
4280
4281<P>A pointer to the default language structure.
4282
4283<H3>Description</H3>
4284
4285<P><CODE>cupsLangDefault()</CODE> returns a language structure for the default
4286language. The default language is defined by the <CODE>LANG</CODE> environment
4287variable. If the specified language cannot be located then the POSIX (English)
4288locale is used.
4289
4290<P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with the
4291language structure when you are done.
4292
4293<H3>Example</H3>
4294
4295<PRE>
4296#include &lt;cups/language.h&gt;
4297
4298<A HREF="#cups_lang_t">cups_lang_t</A> *language;
4299...
4300
4301language = cupsLangDefault();
4302
4303...
4304
4305cupsLangFree(language);
4306</PRE>
4307
4308<H3>See Also</H3>
4309
4310<P>
4311<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4312<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4313<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4314<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4315<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4316
4317
4318<!-- NEW PAGE --><H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2>
4319
4320<H3>Usage</H3>
4321
4322<PRE>
4323char *
4324cupsLangEncoding(cups_lang_t *language);
4325</PRE>
4326
4327<H3>Arguments</H3>
4328
4329<CENTER><TABLE WIDTH="80%" BORDER>
4330<TR>
4331 <TH>Argument</TH>
4332 <TH>Description</TH>
4333</TR>
4334<TR>
4335 <TD>language</TD>
4336 <TD>The language structure.</TD>
4337</TR>
4338</TABLE></CENTER>
4339
4340<H3>Returns</H3>
4341
4342<P>A pointer to the encoding string.
4343
4344<H3>Description</H3>
4345
4346<P><CODE>cupsLangEncoding()</CODE> returns the language encoding used for the
4347specified language, e.g. "iso-8859-1", "utf-8", etc.
4348
4349<H3>Example</H3>
4350
4351<PRE>
4352#include &lt;cups/language.h&gt;
4353
4354<A HREF="#cups_lang_t">cups_lang_t</A> *language;
4355char *encoding;
4356...
4357
4358language = cupsLangDefault();
4359encoding = cupsLangEncoding(language);
4360...
4361
4362cupsLangFree(language);
4363</PRE>
4364
4365<H3>See Also</H3>
4366
4367<P>
4368<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4369<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4370<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4371<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4372<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4373
4374
4375<!-- NEW PAGE --><H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2>
4376
4377<H3>Usage</H3>
4378
4379<PRE>
4380void
4381cupsLangFlush(void);
4382</PRE>
4383
4384<H3>Description</H3>
4385
4386<P><CODE>cupsLangFlush()</CODE> frees all language structures that have been
4387allocated.
4388
4389<H3>Example</H3>
4390
4391<PRE>
4392#include &lt;cups/language.h&gt;
4393
4394...
4395
4396cupsLangFlush();
4397</PRE>
4398
4399<H3>See Also</H3>
4400
4401<P>
4402<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4403<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4404<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4405<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4406<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4407
4408
4409<!-- NEW PAGE --><H2><A NAME="cupsLangFree">cupsLangFree()</A></H2>
4410
4411<H3>Usage</H3>
4412
4413<PRE>
4414void
4415cupsLangFree(cups_lang_t *language);
4416</PRE>
4417
4418<H3>Arguments</H3>
4419
4420<CENTER><TABLE WIDTH="80%" BORDER>
4421<TR>
4422 <TH>Argument</TH>
4423 <TH>Description</TH>
4424</TR>
4425<TR>
4426 <TD>language</TD>
4427 <TD>The language structure to free.</TD>
4428</TR>
4429</TABLE></CENTER>
4430
4431<H3>Description</H3>
4432
4433<P><CODE>cupsLangFree()</CODE> frees the specified language structure.
4434
4435<H3>Example</H3>
4436
4437<PRE>
4438#include &lt;cups/language.h&gt;
4439
4440<A HREF="#cups_lang_t">cups_lang_t</A> *language;
4441...
4442
4443cupsLangFree(language);
4444</PRE>
4445
4446<H3>See Also</H3>
4447
4448<P>
4449<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4450<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4451<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4452<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>,
4453<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4454
4455
4456<!-- NEW PAGE --><H2><A NAME="cupsLangGet">cupsLangGet()</A></H2>
4457
4458<H3>Usage</H3>
4459
4460<PRE>
4461cups_lang_t *
4462cupsLangGet(const char *name);
4463</PRE>
4464
4465<H3>Arguments</H3>
4466
4467<CENTER><TABLE WIDTH="80%" BORDER>
4468<TR>
4469 <TH>Argument</TH>
4470 <TH>Description</TH>
4471</TR>
4472<TR>
4473 <TD>name</TD>
4474 <TD>The name of the locale.</TD>
4475</TR>
4476</TABLE></CENTER>
4477
4478<H3>Returns</H3>
4479
4480<P>A pointer to a language structure.
4481
4482<H3>Description</H3>
4483
4484<P><CODE>cupsLangGet()</CODE> returns a language structure for the specified
4485locale. If the locale is not defined then the POSIX (English) locale is
4486substituted.
4487
4488<H3>Example</H3>
4489
4490<PRE>
4491#include &lt;cups/language.h&gt;
4492
4493<A HREF="#cups_lang_t">cups_lang_t</A> *language;
4494
4495...
4496
4497language = cupsLangGet("fr");
4498
4499...
4500
4501cupsLangFree(language);
4502</PRE>
4503
4504<H3>See Also</H3>
4505
4506<P>
4507<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4508<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4509<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4510<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4511<A HREF="#cupsLangString"><CODE>cupsLangString()</CODE></A>
4512
4513
4514<!-- NEW PAGE --><H2><A NAME="cupsLangString">cupsLangString()</A></H2>
4515
4516<H3>Usage</H3>
4517
4518<PRE>
4519char *
4520cupsLangString(cups_lang_t *language,
4521 int message);
4522</PRE>
4523
4524<H3>Arguments</H3>
4525
4526<CENTER><TABLE WIDTH="80%" BORDER>
4527<TR>
4528 <TH>Argument</TH>
4529 <TH>Description</TH>
4530</TR>
4531<TR>
4532 <TD>language</TD>
4533 <TD>The language to query.</TD>
4534</TR>
4535<TR>
4536 <TD>message</TD>
4537 <TD>The message number.</TD>
4538</TR>
4539</TABLE></CENTER>
4540
4541<H3>Returns</H3>
4542
4543<P>A pointer to the message string or <CODE>NULL</CODE> if the message is
4544not defined.
4545
4546<H3>Description</H3>
4547
4548<P><CODE>cupsLangString()</CODE> returns a pointer to the specified message
4549string in the specified language.
4550
4551<H3>Example</H3>
4552
4553<PRE>
4554#include &lt;cups/language.h&gt;
4555
4556<A HREF="#cups_lang_t">cups_lang_t</A> *language;
4557char *s;
4558...
4559
4560language = cupsLangGet("fr");
4561
4562s = cupsLangString(language, CUPS_MSG_YES);
4563
4564...
4565
4566cupsLangFree(language);
4567</PRE>
4568
4569<H3>See Also</H3>
4570
4571<P>
4572<A HREF="#cupsLangDefault"><CODE>cupsLangDefault()</CODE></A>,
4573<A HREF="#cupsLangEncoding"><CODE>cupsLangEncoding()</CODE></A>,
4574<A HREF="#cupsLangFlush"><CODE>cupsLangFlush()</CODE></A>,
4575<A HREF="#cupsLangFree"><CODE>cupsLangFree()</CODE></A>,
4576<A HREF="#cupsLangGet"><CODE>cupsLangGet()</CODE></A>
4577
4578
4579<!-- NEW PAGE --><H2><A NAME="cupsLastError">cupsLastError()</A></H2>
4580
4581<H3>Usage</H3>
4582
4583<PRE>
4584ipp_status_t
4585cupsLastError(void);
4586</PRE>
4587
4588<H3>Returns</H3>
4589
4590<P>An enumeration containing the last IPP error.
4591
4592<H3>Description</H3>
4593
4594<P><CODE>cupsLastError()</CODE> returns the last IPP error that occurred.
4595If no error occurred then it will return <CODE>IPP_OK</CODE> or
4596<CODE>IPP_OK_CONFLICT</CODE>.
4597
4598<H3>Example</H3>
4599
4600<PRE>
4601#include &lt;cups/cups.h&gt;
4602
4603ipp_status_t status;
4604
4605...
4606
4607status = cupsLastError();
4608</PRE>
4609
4610<H3>See Also</H3>
4611
4612<P>
4613<A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
4614<A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>
4615
4616
4617<!-- NEW PAGE --><H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2>
4618
4619<H3>Usage</H3>
4620
4621<PRE>
4622int
4623cupsMarkOptions(ppd_file_t *ppd,
4624 int num_options,
4625 cups_option_t *options);
4626</PRE>
4627
4628<H3>Arguments</H3>
4629
4630<CENTER><TABLE WIDTH="80%" BORDER>
4631<TR>
4632 <TH>Argument</TH>
4633 <TH>Description</TH>
4634</TR>
4635<TR>
4636 <TD>ppd</TD>
4637 <TD>The PPD file to mark.</TD>
4638</TR>
4639<TR>
4640 <TD>num_options</TD>
4641 <TD>The number of options in the options array.</TD>
4642</TR>
4643<TR>
4644 <TD>options</TD>
4645 <TD>A pointer to the options array.</TD>
4646</TR>
4647</TABLE></CENTER>
4648
4649<H3>Returns</H3>
4650
4651<P>The number of conflicts found.
4652
4653<H3>Description</H3>
4654
4655<P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also
4656handles mapping of IPP option names and values to PPD option names.
4657
4658<H3>Example</H3>
4659
4660<PRE>
4661#include &lt;cups/cups.h&gt;
4662
4663int num_options;
4664<A HREF="#cups_option_t">cups_option_t</A> *options;
4665<A HREF="#ppd_file_t">ppd_file_t</A> *ppd;
4666
4667...
4668
4669cupsMarkOptions(ppd, num_options, options);
4670</PRE>
4671
4672<H3>See Also</H3>
4673
4674<P>
4675<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
4676<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
4677<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
4678<A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A>
4679
4680
4681<!-- NEW PAGE --><H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2>
4682
4683<H3>Usage</H3>
4684
4685<PRE>
4686int
4687cupsParseOptions(const char *arg,
4688 int num_options,
4689 cups_option_t **options);
4690</PRE>
4691
4692<H3>Arguments</H3>
4693
4694<CENTER><TABLE WIDTH="80%" BORDER>
4695<TR>
4696 <TH>Argument</TH>
4697 <TH>Description</TH>
4698</TR>
4699<TR>
4700 <TD>arg</TD>
4701 <TD>The string containing one or more options.</TD>
4702</TR>
4703<TR>
4704 <TD>num_options</TD>
4705 <TD>The number of options in the options array.</TD>
4706</TR>
4707<TR>
4708 <TD>options</TD>
4709 <TD>A pointer to the options array pointer.</TD>
4710</TR>
4711</TABLE></CENTER>
4712
4713<H3>Returns</H3>
4714
4715<P>The new number of options in the array.
4716
4717<H3>Description</H3>
4718
4719<P><CODE>cupsParseOptions()</CODE> parses the specifies string for one
4720or more options of the form "name=value", "name", or "noname". It can
4721be called multiple times to combine the options from several strings.
4722
4723<H3>Example</H3>
4724
4725<PRE>
4726#include &lt;cups/cups.h&gt;
4727
4728int num_options;
4729<A HREF="#cups_options_t">cups_option_t</A> *options;
4730
4731...
4732
4733num_options = 0;
4734options = (cups_option_t *)0;
4735num_options = cupsParseOptions(argv[5], num_options, &amp;options);
4736</PRE>
4737
4738<H3>See Also</H3>
4739
4740<P>
4741<A HREF="#cupsAddOption"><CODE>cupsAddOption()</CODE></A>,
4742<A HREF="#cupsFreeOptions"><CODE>cupsFreeOptions()</CODE></A>,
4743<A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A>,
4744<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>
4745
4746
4747<!-- NEW PAGE --><H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2>
4748
4749<H3>Usage</H3>
4750
4751<PRE>
4752int
4753cupsPrintFile(const char *printer,
4754 const char *filename,
4755 const char *title,
4756 int num_options,
4757 cups_option_t *options);
4758</PRE>
4759
4760<H3>Arguments</H3>
4761
4762<CENTER><TABLE WIDTH="80%" BORDER>
4763<TR>
4764 <TH>Argument</TH>
4765 <TH>Description</TH>
4766</TR>
4767<TR>
4768 <TD>printer</TD>
4769 <TD>The printer or class to print to.</TD>
4770</TR>
4771<TR>
4772 <TD>filename</TD>
4773 <TD>The file to print.</TD>
4774</TR>
4775<TR>
4776 <TD>title</TD>
4777 <TD>The job title.</TD>
4778</TR>
4779<TR>
4780 <TD>num_options</TD>
4781 <TD>The number of options in the options array.</TD>
4782</TR>
4783<TR>
4784 <TD>options</TD>
4785 <TD>A pointer to the options array.</TD>
4786</TR>
4787</TABLE></CENTER>
4788
4789<H3>Returns</H3>
4790
4791<P>The new job ID number or 0 on error.
4792
4793<H3>Description</H3>
4794
4795<P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or
4796class for printing. If the job cannot be printed the error code can be
4797found by calling <CODE>cupsLastError()</CODE>.
4798
4799<H3>Example</H3>
4800
4801<PRE>
4802#include &lt;cups/cups.h&gt;
4803
4804int num_options;
4805<A HREF="#cups_option_t">cups_option_t</A> *options;
4806int jobid;
4807
4808...
4809
4810jobid = cupsPrintFile("printer@hostname", "filename.ps", "Job Title",
4811 num_options, options);
4812</PRE>
4813
4814<H3>See Also</H3>
4815
4816<P>
4817<A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
4818<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
4819<A HREF="#cupsPrintFiles"><CODE>cupsPrintFiles()</CODE></A>
4820
4821
4822<!-- NEW PAGE --><H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2>
4823
4824<H3>Usage</H3>
4825
4826<PRE>
4827int
4828cupsPrintFiles(const char *printer,
4829 int num_files,
4830 const char **files,
4831 const char *title,
4832 int num_options,
4833 cups_option_t *options);
4834</PRE>
4835
4836<H3>Arguments</H3>
4837
4838<CENTER><TABLE WIDTH="80%" BORDER>
4839<TR>
4840 <TH>Argument</TH>
4841 <TH>Description</TH>
4842</TR>
4843<TR>
4844 <TD>printer</TD>
4845 <TD>The printer or class to print to.</TD>
4846</TR>
4847<TR>
4848 <TD>num_files</TD>
4849 <TD>The number of files to print.</TD>
4850</TR>
4851<TR>
4852 <TD>files</TD>
4853 <TD>The files to print.</TD>
4854</TR>
4855<TR>
4856 <TD>title</TD>
4857 <TD>The job title.</TD>
4858</TR>
4859<TR>
4860 <TD>num_options</TD>
4861 <TD>The number of options in the options array.</TD>
4862</TR>
4863<TR>
4864 <TD>options</TD>
4865 <TD>A pointer to the options array.</TD>
4866</TR>
4867</TABLE></CENTER>
4868
4869<H3>Returns</H3>
4870
4871<P>The new job ID number or 0 on error.
4872
4873<H3>Description</H3>
4874
4875<P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified
4876printer or class for printing. If the job cannot be printed the error
4877code can be found by calling <CODE>cupsLastError()</CODE>.
4878
4879<H3>Example</H3>
4880
4881<PRE>
4882#include &lt;cups/cups.h&gt;
4883
4884int num_files;
4885const char *files[100];
4886int num_options;
4887<A HREF="#cups_option_t">cups_option_t</A> *options;
4888int jobid;
4889
4890...
4891
4892jobid = cupsPrintFiles("printer@hostname", num_files, files,
4893 "Job Title", num_options, options);
4894</PRE>
4895
4896<H3>See Also</H3>
4897
4898<P>
4899<A HREF="#cupsCancelJob"><CODE>cupsCancelJob()</CODE></A>,
4900<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>,
4901<A HREF="#cupsPrintFile"><CODE>cupsPrintFile()</CODE></A>
4902
4903
4904<!-- NEW PAGE --><H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2>
4905
4906<H3>Usage</H3>
4907
4908<PRE>
4909void
4910cupsRasterClose(cups_raster_t *ras);
4911</PRE>
4912
4913<H3>Arguments</H3>
4914
4915<CENTER><TABLE WIDTH="80%" BORDER>
4916<TR>
4917 <TH>Argument</TH>
4918 <TH>Description</TH>
4919</TR>
4920<TR>
4921 <TD>ras</TD>
4922 <TD>The raster stream to close.</TD>
4923</TR>
4924</TABLE></CENTER>
4925
4926<H3>Description</H3>
4927
4928<P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.
4929
4930<H3>Example</H3>
4931
4932<PRE>
4933#include &lt;cups/raster.h&gt;
4934
4935<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
4936
4937...
4938
4939cupsRasterClose(ras);
4940</PRE>
4941
4942<H3>See Also</H3>
4943
4944<P>
4945<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
4946<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
4947<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
4948<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
4949<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
4950
4951
4952<!-- NEW PAGE --><H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2>
4953
4954<H3>Usage</H3>
4955
4956<PRE>
4957cups_raster_t *
4958cupsRasterOpen(int fd,
4959 cups_mode_t mode);
4960</PRE>
4961
4962<H3>Arguments</H3>
4963
4964<CENTER><TABLE WIDTH="80%" BORDER>
4965<TR>
4966 <TH>Argument</TH>
4967 <TH>Description</TH>
4968</TR>
4969<TR>
4970 <TD>fd</TD>
4971 <TD>The file descriptor to use.</TD>
4972</TR>
4973<TR>
4974 <TD>mode</TD>
4975 <TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or
4976 <CODE>CUPS_RASTER_WRITE</CODE>.</TD>
4977</TR>
4978</TABLE></CENTER>
4979
4980<H3>Returns</H3>
4981
4982<P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an error.
4983
4984<H3>Description</H3>
4985
4986<P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or writing.
4987
4988<H3>Example</H3>
4989
4990<PRE>
4991#include &lt;cups/raster.h&gt;
4992
4993<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
4994
4995...
4996
4997ras = cupsRasterOpen(0, CUPS_RASTER_READ);
4998</PRE>
4999
5000<H3>See Also</H3>
5001
5002<P>
5003<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5004<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5005<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5006<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
5007<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5008
5009
5010<!-- NEW PAGE --><H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2>
5011
5012<H3>Usage</H3>
5013
5014<PRE>
5015unsigned
5016cupsRasterReadHeader(cups_raster_t *ras,
5017 cups_page_header_t *header);
5018</PRE>
5019
5020<H3>Arguments</H3>
5021
5022<CENTER><TABLE WIDTH="80%" BORDER>
5023<TR>
5024 <TH>Argument</TH>
5025 <TH>Description</TH>
5026</TR>
5027<TR>
5028 <TD>ras</TD>
5029 <TD>The raster stream to read from.</TD>
5030</TR>
5031<TR>
5032 <TD>header</TD>
5033 <TD>A pointer to a page header structure to read into.</TD>
5034</TR>
5035</TABLE></CENTER>
5036
5037<H3>Returns</H3>
5038
5039<P>1 on success, 0 on EOF or error.
5040
5041<H3>Description</H3>
5042
5043<P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the specified
5044raster stream.
5045
5046<H3>Example</H3>
5047
5048<PRE>
5049#include &lt;cups/raster.h&gt;
5050
5051int line;
5052<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5053<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5054unsigned char pixels[8192];
5055...
5056
5057while (cupsRasterReadHeader(ras, &amp;header))
5058{
5059 ...
5060
5061 for (line = 0; line &lt; header.cupsHeight; line ++)
5062 {
5063 cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
5064
5065 ...
5066 }
5067}
5068</PRE>
5069
5070<H3>See Also</H3>
5071
5072<P>
5073<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5074<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5075<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5076<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
5077<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5078
5079
5080<!-- NEW PAGE --><H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2>
5081
5082<H3>Usage</H3>
5083
5084<PRE>
5085unsigned
5086cupsRasterReadPixels(cups_raster_t *ras,
5087 unsigned char *pixels,
5088 unsigned length);
5089</PRE>
5090
5091<H3>Arguments</H3>
5092
5093<CENTER><TABLE WIDTH="80%" BORDER>
5094<TR>
5095 <TH>Argument</TH>
5096 <TH>Description</TH>
5097</TR>
5098<TR>
5099 <TD>ras</TD>
5100 <TD>The raster stream to read from.</TD>
5101</TR>
5102<TR>
5103 <TD>pixels</TD>
5104 <TD>The pointer to a pixel buffer.</TD>
5105</TR>
5106<TR>
5107 <TD>length</TD>
5108 <TD>The number of bytes of pixel data to read.</TD>
5109</TR>
5110</TABLE></CENTER>
5111
5112<H3>Returns</H3>
5113
5114<P>The number of bytes read or 0 on EOF or error.
5115
5116<H3>Description</H3>
5117
5118<P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the specified
5119raster stream.
5120
5121<H3>Example</H3>
5122
5123<PRE>
5124#include &lt;cups/raster.h&gt;
5125
5126int line;
5127<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5128<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5129unsigned char pixels[8192];
5130...
5131
5132while (cupsRasterReadHeader(ras, &amp;header))
5133{
5134 ...
5135
5136 for (line = 0; line &lt; header.cupsHeight; line ++)
5137 {
5138 cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
5139
5140 ...
5141 }
5142}
5143</PRE>
5144
5145<H3>See Also</H3>
5146
5147<P>
5148<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5149<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5150<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5151<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>,
5152<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5153
5154
5155<!-- NEW PAGE --><H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2>
5156
5157<H3>Usage</H3>
5158
5159<PRE>
5160unsigned
5161cupsRasterWriteHeader(cups_raster_t *ras,
5162 cups_page_header_t *header);
5163</PRE>
5164
5165<H3>Arguments</H3>
5166
5167<CENTER><TABLE WIDTH="80%" BORDER>
5168<TR>
5169 <TH>Argument</TH>
5170 <TH>Description</TH>
5171</TR>
5172<TR>
5173 <TD>ras</TD>
5174 <TD>The raster stream to write to.</TD>
5175</TR>
5176<TR>
5177 <TD>header</TD>
5178 <TD>A pointer to the page header to write.</TD>
5179</TR>
5180</TABLE></CENTER>
5181
5182<H3>Returns</H3>
5183
5184<P>1 on success, 0 on error.
5185
5186<H3>Description</H3>
5187
5188<P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header to
5189a raster stream.
5190
5191<H3>Example</H3>
5192
5193<PRE>
5194#include &lt;cups/raster.h&gt;
5195
5196int line;
5197<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5198<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5199unsigned char pixels[8192];
5200...
5201
5202cupsRasterWriteHeader(ras, &amp;header);
5203
5204for (line = 0; line &lt; header.cupsHeight; line ++)
5205{
5206 ...
5207
5208 cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
5209}
5210</PRE>
5211
5212<H3>See Also</H3>
5213
5214<P>
5215<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5216<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5217<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5218<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5219<A HREF="#cupsRasterWritePixels"><CODE>cupsRasterWritePixels()</CODE></A>
5220
5221
5222<!-- NEW PAGE --><H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2>
5223
5224<H3>Usage</H3>
5225
5226<PRE>
5227unsigned
5228cupsRasterWritePixels(cups_raster_t *ras,
5229 unsigned char *pixels,
5230 unsigned length);
5231</PRE>
5232
5233<H3>Arguments</H3>
5234
5235<CENTER><TABLE WIDTH="80%" BORDER>
5236<TR>
5237 <TH>Argument</TH>
5238 <TH>Description</TH>
5239</TR>
5240<TR>
5241 <TD>ras</TD>
5242 <TD>The raster stream to write to.</TD>
5243</TR>
5244<TR>
5245 <TD>pixels</TD>
5246 <TD>The pixel data to write.</TD>
5247</TR>
5248<TR>
5249 <TD>length</TD>
5250 <TD>The number of bytes to write.</TD>
5251</TR>
5252</TABLE></CENTER>
5253
5254<H3>Returns</H3>
5255
5256<P>The number of bytes written.
5257
5258<H3>Description</H3>
5259
5260<P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data to a
5261raster stream.
5262
5263<H3>Example</H3>
5264
5265<PRE>
5266#include &lt;cups/raster.h&gt;
5267
5268int line;
5269<A HREF="#cups_raster_t">cups_raster_t</A> *ras;
5270<A HREF="#cups_raster_header_t">cups_raster_header_t</A> header;
5271unsigned char pixels[8192];
5272...
5273
5274cupsRasterWriteHeader(ras, &amp;header);
5275
5276for (line = 0; line &lt; header.cupsHeight; line ++)
5277{
5278 ...
5279
5280 cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
5281}
5282</PRE>
5283
5284<H3>See Also</H3>
5285
5286<P>
5287<A HREF="#cupsRasterClose"><CODE>cupsRasterClose()</CODE></A>,
5288<A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A>,
5289<A HREF="#cupsRasterReadHeader"><CODE>cupsRasterReadHeader()</CODE></A>,
5290<A HREF="#cupsRasterReadPixels"><CODE>cupsRasterReadPixels()</CODE></A>,
5291<A HREF="#cupsRasterWriteHeader"><CODE>cupsRasterWriteHeader()</CODE></A>
5292
5293
5294<!-- NEW PAGE --><H2><A NAME="cupsServer">cupsServer()</A></H2>
5295
5296<H3>Usage</H3>
5297
5298<PRE>
5299const char *
5300cupsServer(void);
5301</PRE>
5302
5303<H3>Returns</H3>
5304
5305<P>A pointer to the default server name.
5306
5307<H3>Description</H3>
5308
5309<P><CODE>cupsServer()</CODE> returns a pointer to the default server name.
5310The server name is stored in a static location and will be overwritten with
5311every call to <CODE>cupsServer()</CODE>.
5312
5313<P>The default server is determined from the following locations:
5314
5315<OL>
5316
5317 <LI>The <CODE>CUPS_SERVER</CODE> environment variable,
5318
5319 <LI>The <CODE>ServerName</CODE> directive in the
5320 <VAR>client.conf</VAR> file,
5321
5322 <LI>The default host, "localhost".
5323
5324</OL>
5325
5326<H3>Example</H3>
5327
5328<PRE>
5329#include &lt;cups/cups.h&gt;
5330
5331const char *server;
5332
5333server = cupsServer();
5334</PRE>
5335
5336<H3>See Also</H3>
5337
5338<P>
5339<A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>,
5340<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
5341<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
5342<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
5343<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5344
5345
5346<!-- NEW PAGE --><H2><A NAME="cupsSetDests">cupsSetDests()</A></H2>
5347
5348<H3>Usage</H3>
5349
5350<PRE>
5351void
5352cupsSetDests(int num_dests,
5353 cups_dest_t *dests);
5354</PRE>
5355
5356<H3>Arguments</H3>
5357
5358<CENTER><TABLE WIDTH="80%" BORDER>
5359<TR>
5360 <TH>Argument</TH>
5361 <TH>Description</TH>
5362</TR>
5363<TR>
5364 <TD>num_dests</TD>
5365 <TD>Number of destinations.</TD>
5366</TR>
5367<TR>
5368 <TD>dests</TD>
5369 <TD>Array of destinations.</TD>
5370</TR>
5371</TABLE></CENTER>
5372
5373<H3>Description</H3>
5374
5375<P><CODE>cupsSetDests()</CODE> saves the destination array to
5376disk. If the current UID is 0, the destinations are saved in the
5377<VAR>/etc/cups/lpoptions</VAR> file, otherwise they are saved
5378in the <VAR>~/.lpoptions</VAR> file. This function is typically used
5379to save the default options and instances that are set by the user.
5380
5381<H3>Example</H3>
5382
5383<PRE>
5384#include &lt;cups/cups.h&gt;
5385
5386int num_dests;
5387<A HREF="#cups_dest_t">cups_dest_t</A> *dests;
5388
5389...
5390
5391cupsSetDests(num_dests, dests);
5392</PRE>
5393
5394<H3>See Also</H3>
5395
5396<P>
5397<A HREF="#cupsGetDests"><CODE>cupsGetDests()</CODE></A>
5398
5399
5400<!-- NEW PAGE --><H2><A NAME="cupsSetEncryption">cupsSetEncryption()</A></H2>
5401
5402<H3>Usage</H3>
5403
5404<PRE>
5405void
5406cupsSetEncryption(http_encryption_t encryption);
5407</PRE>
5408
5409<H3>Arguments</H3>
5410
5411<CENTER><TABLE WIDTH="80%" BORDER>
5412<TR>
5413 <TH>Argument</TH>
5414 <TH>Description</TH>
5415</TR>
5416<TR>
5417 <TD>encryption</TD>
5418 <TD>The type of encryption to use.</TD>
5419</TR>
5420</TABLE></CENTER>
5421
5422<H3>Description</H3>
5423
5424<P><CODE>cupsSetEncryption()</CODE> sets the default type of encryption to
5425use when connecting with the print server.
5426
5427<H3>Example</H3>
5428
5429<PRE>
5430#include &lt;cups/cups.h&gt;
5431
5432cupsSetEncryption(HTTP_ENCRYPT_REQUIRED);
5433</PRE>
5434
5435<H3>See Also</H3>
5436
5437<P>
5438<A HREF="#cupsEncryption"><CODE>cupsEncryption()</CODE></A>
5439
5440
5441<!-- NEW PAGE --><H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2>
5442
5443<H3>Usage</H3>
5444
5445<PRE>
5446void
5447cupsSetPasswordCB(const char *(*cb)(const char *prompt));
5448</PRE>
5449
5450<H3>Arguments</H3>
5451
5452<CENTER><TABLE WIDTH="80%" BORDER>
5453<TR>
5454 <TH>Argument</TH>
5455 <TH>Description</TH>
5456</TR>
5457<TR>
5458 <TD>cb</TD>
5459 <TD>The password callback function.</TD>
5460</TR>
5461</TABLE></CENTER>
5462
5463<H3>Description</H3>
5464
5465<P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use when
5466asking the user for a password. The callback function must accept a single
5467character string pointer (the prompt string) and return <CODE>NULL</CODE>
5468if the user did not enter a password string or a pointer to the password
5469string otherwise.
5470
5471<H3>Example</H3>
5472
5473<PRE>
5474#include &lt;cups/cups.h&gt;
5475
5476const char *
5477my_password_cb(const char *prompt)
5478{
5479 return (getpass(prompt));
5480}
5481
5482...
5483
5484char *password;
5485
5486...
5487
5488cupsSetPasswordCB(my_password_cb);
5489password = cupsGetPassword("Please enter a password:");
5490</PRE>
5491
5492<H3>See Also</H3>
5493
5494<P>
5495<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
5496<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
5497<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
5498<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5499
5500
5501<!-- NEW PAGE --><H2><A NAME="cupsSetServer">cupsSetServer()</A></H2>
5502
5503<H3>Usage</H3>
5504
5505<PRE>
5506void
5507cupsSetServer(const char *server);
5508</PRE>
5509
5510<H3>Arguments</H3>
5511
5512<CENTER><TABLE WIDTH="80%" BORDER>
5513<TR>
5514 <TH>Argument</TH>
5515 <TH>Description</TH>
5516</TR>
5517<TR>
5518 <TD>server</TD>
5519 <TD>The default server to use.</TD>
5520</TR>
5521</TABLE></CENTER>
5522
5523<H3>Description</H3>
5524
5525<P><CODE>cupsSetServer()</CODE> sets the default server to use for
5526the CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>,
5527the default server is used.
5528
5529<H3>Example</H3>
5530
5531<PRE>
5532#include &lt;cups/cups.h&gt;
5533
5534cupsSetServer("foo.bar.com");
5535</PRE>
5536
5537<H3>See Also</H3>
5538
5539<P>
5540<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
5541<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
5542<A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A>,
5543<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5544
5545
5546<!-- NEW PAGE --><H2><A NAME="cupsSetUser">cupsSetUser()</A></H2>
5547
5548<H3>Usage</H3>
5549
5550<PRE>
5551void
5552cupsSetUser(const char *user);
5553</PRE>
5554
5555<H3>Arguments</H3>
5556
5557<CENTER><TABLE WIDTH="80%" BORDER>
5558<TR>
5559 <TH>Argument</TH>
5560 <TH>Description</TH>
5561</TR>
5562<TR>
5563 <TD>user</TD>
5564 <TD>The user name string to use.</TD>
5565</TR>
5566</TABLE></CENTER>
5567
5568<H3>Description</H3>
5569
5570<P><CODE>cupsSetUser()</CODE> sets the default user name for authentication.
5571If the <CODE>user</CODE> argument is <CODE>NULL</CODE> then the current
5572login user is used.
5573
5574<H3>Example</H3>
5575
5576<PRE>
5577#include &lt;cups/cups.h&gt;
5578
5579...
5580
5581cupsSetUser("root");
5582</PRE>
5583
5584<H3>See Also</H3>
5585
5586<P>
5587<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
5588<A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A>,
5589<A HREF="#cupsSetServer"><CODE>cupsSetServer()</CODE></A>,
5590<A HREF="#cupsUser"><CODE>cupsUser()</CODE></A>
5591
5592
5593<!-- NEW PAGE --><H2><A NAME="cupsTempFd">cupsTempFd()</A></H2>
5594
5595<H3>Usage</H3>
5596
5597<PRE>
5598int
5599cupsTempFd(char *filename,
5600 int length);
5601</PRE>
5602
5603<H3>Arguments</H3>
5604
5605<CENTER><TABLE WIDTH="80%" BORDER>
5606<TR>
5607 <TH>Argument</TH>
5608 <TH>Description</TH>
5609</TR>
5610<TR>
5611 <TD>filename</TD>
5612 <TD>The character string to hold the temporary filename.</TD>
5613</TR>
5614<TR>
5615 <TD>length</TD>
5616 <TD>The size of the filename string in bytes.</TD>
5617</TR>
5618</TABLE></CENTER>
5619
5620<H3>Returns</H3>
5621
5622<P>A file descriptor open for reading and writing.
5623
5624<H3>Description</H3>
5625
5626<P><CODE>cupsTempFd()</CODE> create a temporary filename in the
5627<VAR>/var/tmp</VAR> directory or the directory specified by the
5628<CODE>TMPDIR</CODE> environment variable.
5629
5630<H3>Example</H3>
5631
5632<PRE>
5633#include &lt;cups/cups.h&gt;
5634
5635int fd;
5636char filename[256];
5637
5638fd = cupsTempFd(filename, sizeof(filename));
5639</PRE>
5640
5641<H3>See Also</H3>
5642
5643<P>
5644<A HREF="#cupsTempFile"><CODE>cupsTempFile()</CODE></A>
5645
5646
5647<!-- NEW PAGE --><H2><A NAME="cupsTempFile">cupsTempFile()</A></H2>
5648
5649<H3>Usage</H3>
5650
5651<PRE>
5652char *
5653cupsTempFile(char *filename,
5654 int length);
5655</PRE>
5656
5657<H3>Arguments</H3>
5658
5659<CENTER><TABLE WIDTH="80%" BORDER>
5660<TR>
5661 <TH>Argument</TH>
5662 <TH>Description</TH>
5663</TR>
5664<TR>
5665 <TD>filename</TD>
5666 <TD>The character string to hold the temporary filename.</TD>
5667</TR>
5668<TR>
5669 <TD>length</TD>
5670 <TD>The size of the filename string in bytes.</TD>
5671</TR>
5672</TABLE></CENTER>
5673
5674<H3>Returns</H3>
5675
5676<P>A pointer to <CODE>filename</CODE>.
5677
5678<H3>Description</H3>
5679
5680<P><CODE>cupsTempFile()</CODE> creates a temporary filename in the
5681<VAR>/var/tmp</VAR> directory or the directory specified by the
5682<CODE>TMPDIR</CODE> environment variable.
5683
5684<H3>Example</H3>
5685
5686<PRE>
5687#include &lt;cups/cups.h&gt;
5688
5689char filename[256];
5690
5691cupsTempFile(filename, sizeof(filename));
5692</PRE>
5693
5694<H3>See Also</H3>
5695
5696<P>
5697<A HREF="#cupsTempFd"><CODE>cupsTempFd()</CODE></A>
5698
5699
5700<!-- NEW PAGE --><H2><A NAME="cupsUser">cupsUser()</A></H2>
5701
5702<H3>Usage</H3>
5703
5704<PRE>
5705const char *
5706cupsUser(void);
5707</PRE>
5708
5709<H3>Returns</H3>
5710
5711<P>A pointer to the current username or <CODE>NULL</CODE> if the user ID is
5712undefined.
5713
5714<H3>Description</H3>
5715
5716<P><CODE>cupsUser()</CODE> returns the name associated with the current
5717user ID as reported by the <CODE>getuid()</CODE> system call.
5718
5719<H3>Example</H3>
5720
5721<PRE>
5722#include &lt;cups/cups.h&gt;
5723
5724const char *user;
5725
5726user = cupsUser();
5727</PRE>
5728
5729<H3>See Also</H3>
5730
5731<P>
5732<A HREF="#cupsGetPassword"><CODE>cupsGetPassword()</CODE></A>,
5733<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>
5734
5735
5736<!-- NEW PAGE --><H2><A NAME="httpBlocking">httpBlocking()</A></H2>
5737
5738<H3>Usage</H3>
5739
5740<PRE>
5741void
5742httpBlocking(http_t *http,
5743 int blocking)
5744</PRE>
5745
5746<H3>Arguments</H3>
5747
5748<CENTER><TABLE WIDTH="80%" BORDER>
5749<TR>
5750 <TH>Argument</TH>
5751 <TH>Description</TH>
5752</TR>
5753<TR>
5754 <TD>http</TD>
5755 <TD>The HTTP connection</TD>
5756</TR>
5757<TR>
5758 <TD>blocking</TD>
5759 <TD>0 if the connection should be non-blocking, 1 if it should
5760 be blocking</TD>
5761</TR>
5762</TABLE></CENTER>
5763
5764<H3>Description</H3>
5765
5766<P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for the
5767HTTP connection. By default HTTP connections will block (stop) the client
5768program until data is available or can be sent to the server.
5769
5770<H3>Example</H3>
5771
5772<PRE>
5773#include &lt;cups/http.h&gt;
5774
5775http_t *http;
5776
5777http = httpConnect("server", port);
5778httpBlocking(http, 0);
5779</PRE>
5780
5781<H3>See Also</H3>
5782
5783<A HREF="#httpCheck"><CODE>httpCheck()</CODE></A>,
5784<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
5785
5786
5787<!-- NEW PAGE --><H2><A NAME="httpCheck">httpCheck()</A></H2>
5788
5789<H3>Usage</H3>
5790
5791<PRE>
5792int
5793httpCheck(http_t *http);
5794</PRE>
5795
5796<H3>Arguments</H3>
5797
5798<CENTER><TABLE WIDTH="80%" BORDER>
5799<TR>
5800 <TH>Argument</TH>
5801 <TH>Description</TH>
5802</TR>
5803<TR>
5804 <TD>http</TD>
5805 <TD>The HTTP connection</TD>
5806</TR>
5807</TABLE></CENTER>
5808
5809<H3>Returns</H3>
5810
5811<P>0 if there is no data pending, 1 otherwise.
5812
5813<H3>Description</H3>
5814
5815<P>The <CODE>httpCheck()</CODE> function checks to see if there is any data
5816pending on an HTTP connection.
5817
5818<H3>Example</H3>
5819
5820<PRE>
5821#include &lt;cups/http.h&gt;
5822
5823http_t *http;
5824
5825if (httpCheck(http))
5826{
5827 ... do something ...
5828}
5829</PRE>
5830
5831<H3>See Also</H3>
5832
5833<A HREF="#httpBlocking"><CODE>httpBlocking()</CODE></A>,
5834<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5835<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
5836<A HREF="#httpRead"><CODE>httpRead()</CODE></A>
5837
5838
5839<!-- NEW PAGE --><H2><A NAME="httpClearFields">httpClearFields()</A></H2>
5840
5841<H3>Usage</H3>
5842
5843<PRE>
5844void
5845httpClearFields(http_t *http)
5846</PRE>
5847
5848<H3>Arguments</H3>
5849
5850<CENTER><TABLE WIDTH="80%" BORDER>
5851<TR>
5852 <TH>Argument</TH>
5853 <TH>Description</TH>
5854</TR>
5855<TR>
5856 <TD>http</TD>
5857 <TD>The HTTP connection</TD>
5858</TR>
5859</TABLE></CENTER>
5860
5861<H3>Description</H3>
5862
5863<P>The <CODE>httpClearFields()</CODE> function clears all HTTP request fields
5864for the HTTP connection.
5865
5866<H3>Example</H3>
5867
5868<PRE>
5869#include &lt;cups/http.h&gt;
5870
5871http_t *http;
5872
5873httpClearFields(http);
5874</PRE>
5875
5876<H3>See Also</H3>
5877
5878<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
5879<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>,
5880<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
5881
5882
5883<!-- NEW PAGE --><H2><A NAME="httpClose">httpClose()</A></H2>
5884
5885<H3>Usage</H3>
5886
5887<PRE>
5888void
5889httpClose(http_t *http);
5890</PRE>
5891
5892<H3>Arguments</H3>
5893
5894<CENTER><TABLE WIDTH="80%" BORDER>
5895<TR>
5896 <TH>Argument</TH>
5897 <TH>Description</TH>
5898</TR>
5899<TR>
5900 <TD>http</TD>
5901 <TD>The HTTP connection</TD>
5902</TR>
5903</TABLE></CENTER>
5904
5905<H3>Description</H3>
5906
5907<P>The <CODE>httpClose()</CODE> function closes an active HTTP connection.
5908
5909<H3>Example</H3>
5910
5911<PRE>
5912#include &lt;cups/http.h&gt;
5913
5914http_t *http;
5915
5916httpClose(http);
5917</PRE>
5918
5919<H3>See Also</H3>
5920
5921<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
5922
5923
5924<!-- NEW PAGE --><H2><A NAME="httpConnect">httpConnect()</A></H2>
5925
5926<H3>Usage</H3>
5927
5928<PRE>
5929http_t *
5930httpConnect(const char *hostname,
5931 int port);
5932</PRE>
5933
5934<H3>Arguments</H3>
5935
5936<CENTER><TABLE WIDTH="80%" BORDER>
5937<TR>
5938 <TH>Argument</TH>
5939 <TH>Description</TH>
5940</TR>
5941<TR>
5942 <TD>hostname</TD>
5943 <TD>The name or IP address of the server to connect to</TD>
5944</TR>
5945<TR>
5946 <TD>port</TD>
5947 <TD>The port number to use</TD>
5948</TR>
5949</TABLE></CENTER>
5950
5951<H3>Returns</H3>
5952
5953<P>A pointer to a HTTP connection structure or NULL if the connection could
5954not be made.
5955
5956<H3>Description</H3>
5957
5958<P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to the
5959specified server and port.
5960
5961<H3>Example</H3>
5962
5963<PRE>
5964#include &lt;cups/http.h&gt;
5965
5966<A HREF="#http_t">http_t</A> *http;
5967
5968http = httpConnect(cupsServer(), ippPort());
5969</PRE>
5970
5971<H3>See Also</H3>
5972
5973<A HREF="#httpClose"><CODE>httpClose()</CODE></A>,
5974<A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>,
5975<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
5976<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
5977<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
5978<A HREF="#httpRead"><CODE>httpRead()</CODE></A>,
5979<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
5980
5981
5982<!-- NEW PAGE --><H2><A NAME="httpConnectEncrypt">httpConnectEncrypt()</A></H2>
5983
5984<H3>Usage</H3>
5985
5986<PRE>
5987http_t *
5988httpConnectEncrypt(const char *hostname,
5989 int port,
5990 http_encryption_t encryption);
5991</PRE>
5992
5993<H3>Arguments</H3>
5994
5995<CENTER><TABLE WIDTH="80%" BORDER>
5996<TR>
5997 <TH>Argument</TH>
5998 <TH>Description</TH>
5999</TR>
6000<TR>
6001 <TD>hostname</TD>
6002 <TD>The name or IP address of the server to connect to</TD>
6003</TR>
6004<TR>
6005 <TD>port</TD>
6006 <TD>The port number to use</TD>
6007</TR>
6008<TR>
6009 <TD>encryption</TD>
6010 <TD>The level of encryption to use</TD>
6011</TR>
6012</TABLE></CENTER>
6013
6014<H3>Returns</H3>
6015
6016<P>A pointer to a HTTP connection structure or NULL if the connection could
6017not be made.
6018
6019<H3>Description</H3>
6020
6021<P>The <CODE>httpConnectEncrypt()</CODE> function opens a HTTP
6022connection to the specified server, port, and encryption.
6023
6024<H3>Example</H3>
6025
6026<PRE>
6027#include &lt;cups/http.h&gt;
6028
6029<A HREF="#http_t">http_t</A> *http;
6030
6031http = httpConnectEncrypt(cupsServer(), ippPort(), cupsEncryption());
6032</PRE>
6033
6034<H3>See Also</H3>
6035
6036<A HREF="#httpClose"><CODE>httpClose()</CODE></A>,
6037<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6038<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
6039<A HREF="#httpGets"><CODE>httpGets()</CODE></A>,
6040<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
6041<A HREF="#httpRead"><CODE>httpRead()</CODE></A>,
6042<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
6043
6044
6045<!-- NEW PAGE --><H2><A NAME="httpDecode64">httpDecode64()</A></H2>
6046
6047<H3>Usage</H3>
6048
6049<PRE>
6050char *
6051httpDecode64(char *out,
6052 const char *in);
6053</PRE>
6054
6055<H3>Arguments</H3>
6056
6057<CENTER><TABLE WIDTH="80%" BORDER>
6058<TR>
6059 <TH>Argument</TH>
6060 <TH>Description</TH>
6061</TR>
6062<TR>
6063 <TD>out</TD>
6064 <TD>The output string</TD>
6065</TR>
6066<TR>
6067 <TD>in</TD>
6068 <TD>The input string</TD>
6069</TR>
6070</TABLE></CENTER>
6071
6072<H3>Returns</H3>
6073
6074<P>A pointer to the decoded string.
6075
6076<H3>Description</H3>
6077
6078<P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded string
6079to the original string.
6080
6081<H3>Example</H3>
6082
6083<PRE>
6084#include &lt;cups/http.h&gt;
6085
6086char encoded_string[255];
6087char original_string[255];
6088
6089httpDecode64(original_string, encoded_string);
6090</PRE>
6091
6092<H3>See Also</H3>
6093
6094<A HREF="#httpEncode64"><CODE>httpEncode64()</CODE></A>
6095
6096
6097<!-- NEW PAGE --><H2><A NAME="httpDelete">httpDelete()</A></H2>
6098
6099<H3>Usage</H3>
6100
6101<PRE>
6102int
6103httpDelete(http_t *http,
6104 const char *uri);
6105</PRE>
6106
6107<H3>Arguments</H3>
6108
6109<CENTER><TABLE WIDTH="80%" BORDER>
6110<TR>
6111 <TH>Argument</TH>
6112 <TH>Description</TH>
6113</TR>
6114<TR>
6115 <TD>http</TD>
6116 <TD>The HTTP connection</TD>
6117</TR>
6118<TR>
6119 <TD>uri</TD>
6120 <TD>The URI to delete</TD>
6121</TR>
6122</TABLE></CENTER>
6123
6124<H3>Returns</H3>
6125
6126<P>0 on success, non-zero on failure.
6127
6128<H3>Description</H3>
6129
6130<P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to
6131the server.
6132
6133<H3>Example</H3>
6134
6135<PRE>
6136#include &lt;cups/http.h&gt;
6137
6138http_t *http;
6139
6140httpDelete(http, "/some/uri");
6141</PRE>
6142
6143<H3>See Also</H3>
6144
6145<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6146<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
6147<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6148
6149
6150<!-- NEW PAGE --><H2><A NAME="httpEncode64">httpEncode64()</A></H2>
6151
6152<H3>Usage</H3>
6153
6154<PRE>
6155char *
6156httpEncode64(char *out,
6157 const char *in);
6158</PRE>
6159
6160<H3>Arguments</H3>
6161
6162<CENTER><TABLE WIDTH="80%" BORDER>
6163<TR>
6164 <TH>Argument</TH>
6165 <TH>Description</TH>
6166</TR>
6167<TR>
6168 <TD>out</TD>
6169 <TD>The output string</TD>
6170</TR>
6171<TR>
6172 <TD>in</TD>
6173 <TD>The input string</TD>
6174</TR>
6175</TABLE></CENTER>
6176
6177<H3>Returns</H3>
6178
6179<P>A pointer to the encoded string.
6180
6181<H3>Description</H3>
6182
6183<P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded string
6184to the original string.
6185
6186<H3>Example</H3>
6187
6188<PRE>
6189#include &lt;cups/http.h&gt;
6190
6191char encoded_string[255];
6192char original_string[255];
6193
6194httpEncode64(encoded_string, original_string);
6195</PRE>
6196
6197<H3>See Also</H3>
6198
6199<A HREF="#httpDecode64"><CODE>httpDecode64()</CODE></A>
6200
6201
6202<!-- NEW PAGE --><H2><A NAME="httpEncryption">httpEncryption()</A></H2>
6203
6204<H3>Usage</H3>
6205
6206<PRE>
6207int
6208httpEncryption(http_t *http,
6209 http_encryption_t encryption);
6210</PRE>
6211
6212<H3>Arguments</H3>
6213
6214<CENTER><TABLE WIDTH="80%" BORDER>
6215<TR>
6216 <TH>Argument</TH>
6217 <TH>Description</TH>
6218</TR>
6219<TR>
6220 <TD>http</TD>
6221 <TD>The HTTP connection.</TD>
6222</TR>
6223<TR>
6224 <TD>encryption</TD>
6225 <TD>The desired level of encryption.</TD>
6226</TR>
6227</TABLE></CENTER>
6228
6229<H3>Returns</H3>
6230
6231<P>0 on success, -1 on error.
6232
6233<H3>Description</H3>
6234
6235<P><CODE>httpEncryption()</CODE> sets the encryption level for the HTTP
6236connection.
6237
6238<H3>Example</H3>
6239
6240<PRE>
6241#include &lt;cups/http.h&gt;
6242
6243<A HREF="#http_t">http_t</A> *http;
6244
6245...
6246
6247httpEncryption(http, HTTP_ENCRYPT_REQUIRED);
6248</PRE>
6249
6250<H3>See Also</H3>
6251
6252<P>
6253<A HREF="#httpConnectEncrypt"><CODE>httpConnectEncrypt()</CODE></A>
6254
6255
6256<!-- NEW PAGE --><H2><A NAME="httpError">httpError()</A></H2>
6257
6258<H3>Usage</H3>
6259
6260<PRE>
6261int
6262httpError(http_t *http);
6263</PRE>
6264
6265<H3>Arguments</H3>
6266
6267<CENTER><TABLE WIDTH="80%" BORDER>
6268<TR>
6269 <TH>Argument</TH>
6270 <TH>Description</TH>
6271</TR>
6272<TR>
6273 <TD>http</TD>
6274 <TD>The HTTP connection</TD>
6275</TR>
6276</TABLE></CENTER>
6277
6278<H3>Returns</H3>
6279
6280<P>The last error that occurred or 0 if no error has occurred.
6281
6282<H3>Description</H3>
6283
6284<P>The <CODE>httpError()</CODE> function returns the last error that occurred
6285on the HTTP connection.
6286
6287<H3>Example</H3>
6288
6289<PRE>
6290#include &lt;cups/http.h&gt;
6291
6292http_t *http;
6293
6294if (httpError(http))
6295{
6296 ... show an error message ...
6297}
6298</PRE>
6299
6300<H3>See Also</H3>
6301
6302<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
6303
6304
6305<!-- NEW PAGE --><H2><A NAME="httpFlush">httpFlush()</A></H2>
6306
6307<H3>Usage</H3>
6308
6309<PRE>
6310void
6311httpFlush(http_t *http);
6312</PRE>
6313
6314<H3>Arguments</H3>
6315
6316<CENTER><TABLE WIDTH="80%" BORDER>
6317<TR>
6318 <TH>Argument</TH>
6319 <TH>Description</TH>
6320</TR>
6321<TR>
6322 <TD>http</TD>
6323 <TD>The HTTP connection</TD>
6324</TR>
6325</TABLE></CENTER>
6326
6327<H3>Description</H3>
6328
6329<P>The <CODE>httpFlush()</CODE> function flushes any remaining data left from
6330a GET or POST operation.
6331
6332<H3>Example</H3>
6333
6334<PRE>
6335#include &lt;cups/http.h&gt;
6336
6337http_t *http;
6338
6339httpFlush(http);
6340</PRE>
6341
6342<H3>See Also</H3>
6343
6344<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6345
6346
6347<!-- NEW PAGE --><H2><A NAME="httpGet">httpGet()</A></H2>
6348
6349<H3>Usage</H3>
6350
6351<PRE>
6352int
6353httpGet(http_t *http,
6354 const char *uri);
6355</PRE>
6356
6357<H3>Arguments</H3>
6358
6359<CENTER><TABLE WIDTH="80%" BORDER>
6360<TR>
6361 <TH>Argument</TH>
6362 <TH>Description</TH>
6363</TR>
6364<TR>
6365 <TD>http</TD>
6366 <TD>The HTTP connection</TD>
6367</TR>
6368<TR>
6369 <TD>uri</TD>
6370 <TD>The URI to get</TD>
6371</TR>
6372</TABLE></CENTER>
6373
6374<H3>Returns</H3>
6375
6376<P>0 on success, non-zero on failure.
6377
6378<H3>Description</H3>
6379
6380<P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the
6381server.
6382
6383<H3>Example</H3>
6384
6385<PRE>
6386#include &lt;cups/http.h&gt;
6387
6388<A HREF="#http_t">http_t</A> *http;
6389
6390httpGet(http, "/some/uri");
6391</PRE>
6392
6393<H3>See Also</H3>
6394
6395<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6396<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
6397<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6398
6399
6400<!-- NEW PAGE --><H2><A NAME="httpGets">httpGets()</A></H2>
6401
6402<H3>Usage</H3>
6403
6404<PRE>
6405char *
6406httpGets(char *line,
6407 int length,
6408 http_t *http)
6409</PRE>
6410
6411<H3>Arguments</H3>
6412
6413<CENTER><TABLE WIDTH="80%" BORDER>
6414<TR>
6415 <TH>Argument</TH>
6416 <TH>Description</TH>
6417</TR>
6418<TR>
6419 <TD>line</TD>
6420 <TD>The string to fill with a line from the HTTP connection</TD>
6421</TR>
6422<TR>
6423 <TD>length</TD>
6424 <TD>The maximum length of the string</TD>
6425</TR>
6426<TR>
6427 <TD>http</TD>
6428 <TD>The HTTP connection</TD>
6429</TR>
6430</TABLE></CENTER>
6431
6432<H3>Returns</H3>
6433
6434<P>A pointer to the string or NULL if no line could be retrieved.
6435
6436<H3>Description</H3>
6437
6438<P>The <CODE>httpGets()</CODE> function is used to read a request line from
6439the HTTP connection. It is not normally used by a client program.
6440
6441<H3>Example</H3>
6442
6443<PRE>
6444#include &lt;cups/http.h&gt;
6445
6446<A HREF="#http_t">http_t</A> *http;
6447char line[1024];
6448
6449if (httpGets(line, sizeof(line), http))
6450{
6451 ... process the line ...
6452}
6453</PRE>
6454
6455<H3>See Also</H3>
6456
6457<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6458<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6459
6460
6461<!-- NEW PAGE --><H2><A NAME="httpGetDateString">httpGetDateString()</A></H2>
6462
6463<H3>Usage</H3>
6464
6465<PRE>
6466const char *
6467httpGetDateString(time_t time)
6468</PRE>
6469
6470<H3>Arguments</H3>
6471
6472<CENTER><TABLE WIDTH="80%" BORDER>
6473<TR>
6474 <TH>Argument</TH>
6475 <TH>Description</TH>
6476</TR>
6477<TR>
6478 <TD>time</TD>
6479 <TD>The UNIX date/time value</TD>
6480</TR>
6481</TABLE></CENTER>
6482
6483<H3>Returns</H3>
6484
6485<P>A pointer to a static string containing the HTTP date/time string for
6486the specified UNIX time value.
6487
6488<H3>Description</H3>
6489
6490<P>The <CODE>httpGetDateString()</CODE> function generates a date/time string
6491suitable for HTTP requests from a UNIX time value.
6492
6493<H3>Example</H3>
6494
6495<PRE>
6496#include &lt;cups/http.h&gt;
6497
6498puts(httpGetDateString(time(NULL)));
6499</PRE>
6500
6501<H3>See Also</H3>
6502
6503<A HREF="#httpGetDateTime"><CODE>httpGetDateTime()</CODE></A>
6504
6505
6506<!-- NEW PAGE --><H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2>
6507
6508<H3>Usage</H3>
6509
6510<PRE>
6511time_t
6512httpGetDateTime(const char *date)
6513</PRE>
6514
6515<H3>Arguments</H3>
6516
6517<CENTER><TABLE WIDTH="80%" BORDER>
6518<TR>
6519 <TH>Argument</TH>
6520 <TH>Description</TH>
6521</TR>
6522<TR>
6523 <TD>date</TD>
6524 <TD>The HTTP date/time string</TD>
6525</TR>
6526</TABLE></CENTER>
6527
6528<H3>Returns</H3>
6529
6530<P>A UNIX time value.
6531
6532<H3>Description</H3>
6533
6534<P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP
6535date/time string to a UNIX time value.
6536
6537<H3>Example</H3>
6538
6539<PRE>
6540#include &lt;cups/http.h&gt;
6541
6542printf("%d\n", httpGetDateTime("Fri, 30 June 2000 12:34:56 GMT"));
6543</PRE>
6544
6545<H3>See Also</H3>
6546
6547<A HREF="#httpGetDateString"><CODE>httpGetDateString()</CODE></A>
6548
6549
6550<!-- NEW PAGE --><H2><A NAME="httpGetField">httpGetField()</A></H2>
6551
6552<H3>Usage</H3>
6553
6554<PRE>
6555const char *
6556httpGetField(http_t *http,
6557 http_field_t field);
6558</PRE>
6559
6560<H3>Arguments</H3>
6561
6562<CENTER><TABLE WIDTH="80%" BORDER>
6563<TR>
6564 <TH>Argument</TH>
6565 <TH>Description</TH>
6566</TR>
6567<TR>
6568 <TD>http</TD>
6569 <TD>The HTTP connection</TD>
6570</TR>
6571<TR>
6572 <TD>field</TD>
6573 <TD>The HTTP field</TD>
6574</TR>
6575</TABLE></CENTER>
6576
6577<H3>Returns</H3>
6578
6579<P>A pointer to the field value string.
6580
6581<H3>Description</H3>
6582
6583<P>The <CODE>httpGetField()</CODE> function returns the current value for
6584the specified HTTP field.
6585
6586<H3>Example</H3>
6587
6588<PRE>
6589#include &lt;cups/http.h&gt;
6590
6591<A HREF="#http_t">http_t</A> *http;
6592
6593httpGet(http, "/some/uri");
6594while (httpUpdate(http) == HTTP_CONTINUE);
6595
6596puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
6597</PRE>
6598
6599<H3>See Also</H3>
6600
6601<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6602<A HREF="#httpGetSubField"><CODE>httpGetSubField()</CODE></A>,
6603<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
6604
6605
6606<!-- NEW PAGE --><H2><A NAME="httpGetHostByName">httpGetHostByName()</A></H2>
6607
6608<H3>Usage</H3>
6609
6610<PRE>
6611struct hostent *
6612httpGetHostByName(const char *name);
6613</PRE>
6614
6615<H3>Arguments</H3>
6616
6617<CENTER><TABLE WIDTH="80%" BORDER>
6618<TR>
6619 <TH>Argument</TH>
6620 <TH>Description</TH>
6621</TR>
6622<TR>
6623 <TD>name</TD>
6624 <TD>Name or IP address to lookup.</TD>
6625</TR>
6626</TABLE></CENTER>
6627
6628<H3>Returns</H3>
6629
6630<P>NULL if the host could not be found or a pointer to a host entry
6631containing one or more addresses.
6632
6633<H3>Description</H3>
6634
6635<P><CODE>httpGetHostByName()</CODE> is a portable wrapper around the
6636<CODE>gethostbyname()</CODE> function which handles both hostnames
6637and IP addresses.
6638
6639<H3>Example</H3>
6640
6641<PRE>
6642#include &lt;cups/http.h&gt;
6643
6644struct hostent *hostaddr;
6645
6646hostaddr = httpGetHostByName("foo.bar.com");
6647</PRE>
6648
6649
6650<!-- NEW PAGE --><H2><A NAME="httpGetLength">httpGetLength()</A></H2>
6651
6652<H3>Usage</H3>
6653
6654<PRE>
6655int
6656httpGetLength(http_t *http);
6657</PRE>
6658
6659<H3>Arguments</H3>
6660
6661<CENTER><TABLE WIDTH="80%" BORDER>
6662<TR>
6663 <TH>Argument</TH>
6664 <TH>Description</TH>
6665</TR>
6666<TR>
6667 <TD>http</TD>
6668 <TD>The HTTP connection.</TD>
6669</TR>
6670</TABLE></CENTER>
6671
6672<H3>Returns</H3>
6673
6674<P>The content length of the response or MAX_INT if chunking is used.
6675
6676<H3>Description</H3>
6677
6678<P><CODE>httpGetLength()</CODE> returns the content length of a response.
6679
6680<H3>Example</H3>
6681
6682<PRE>
6683#include &lt;cups/http.h&gt;
6684
6685<A HREF="#http_t">http_t</A> *http;
6686
6687...
6688
6689printf("The length of the response is %d bytes.\n", httpGetLength(http));
6690</PRE>
6691
6692<H3>See Also</H3>
6693
6694<P>
6695<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
6696<A HREF="#httpPost"><CODE>httpPost()</CODE></A>
6697
6698
6699<!-- NEW PAGE --><H2><A NAME="httpGetSubField">httpGetSubField()</A></H2>
6700
6701<H3>Usage</H3>
6702
6703<PRE>
6704const char *
6705httpGetSubField(http_t *http,
6706 http_field_t field,
6707 const char *name,
6708 char *value);
6709</PRE>
6710
6711<H3>Arguments</H3>
6712
6713<CENTER><TABLE WIDTH="80%" BORDER>
6714<TR>
6715 <TH>Argument</TH>
6716 <TH>Description</TH>
6717</TR>
6718<TR>
6719 <TD>http</TD>
6720 <TD>The HTTP connection.</TD>
6721</TR>
6722<TR>
6723 <TD>field</TD>
6724 <TD>The HTTP field.</TD>
6725</TR>
6726<TR>
6727 <TD>name</TD>
6728 <TD>The name of the subfield.</TD>
6729</TR>
6730<TR>
6731 <TD>value</TD>
6732 <TD>The string to hold the subfield value.</TD>
6733</TR>
6734</TABLE></CENTER>
6735
6736<H3>Returns</H3>
6737
6738<P>A pointer to the subfield value string or NULL if it does not exist.
6739
6740<H3>Description</H3>
6741
6742<P>The <CODE>httpGetSubField()</CODE> function returns a subfield value
6743from the specified HTTP field. The destination string buffer must be at
6744least <CODE>HTTP_MAX_VALUE</CODE> bytes in length.
6745
6746<H3>Example</H3>
6747
6748<PRE>
6749#include &lt;cups/http.h&gt;
6750
6751<A HREF="#http_t">http_t</A> *http;
6752char value[HTTP_MAX_VALUE];
6753
6754httpGet(http, "/some/uri");
6755while (httpUpdate(http) == HTTP_CONTINUE);
6756
6757puts(httpGetSubField(http, HTTP_FIELD_CONTENT_TYPE, "charset", value));
6758</PRE>
6759
6760<H3>See Also</H3>
6761
6762<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6763<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>,
6764<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>
6765
6766
6767<!-- NEW PAGE --><H2><A NAME="httpHead">httpHead()</A></H2>
6768
6769<H3>Usage</H3>
6770
6771<PRE>
6772int
6773httpHead(http_t *http,
6774 const char *uri);
6775</PRE>
6776
6777<H3>Arguments</H3>
6778
6779<CENTER><TABLE WIDTH="80%" BORDER>
6780<TR>
6781 <TH>Argument</TH>
6782 <TH>Description</TH>
6783</TR>
6784<TR>
6785 <TD>http</TD>
6786 <TD>The HTTP connection</TD>
6787</TR>
6788<TR>
6789 <TD>uri</TD>
6790 <TD>The URI to head</TD>
6791</TR>
6792</TABLE></CENTER>
6793
6794<H3>Returns</H3>
6795
6796<P>0 on success, non-zero on failure.
6797
6798<H3>Description</H3>
6799
6800<P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the
6801server.
6802
6803<H3>Example</H3>
6804
6805<PRE>
6806#include &lt;cups/http.h&gt;
6807
6808http_t *http;
6809
6810httpHead(http, "/some/uri");
6811</PRE>
6812
6813<H3>See Also</H3>
6814
6815<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
6816<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
6817<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
6818
6819
6820<!-- NEW PAGE --><H2><A NAME="httpInitialize">httpInitialize()</A></H2>
6821
6822<H3>Usage</H3>
6823
6824<PRE>
6825void httpInitialize(void);
6826</PRE>
6827
6828<H3>Description</H3>
6829
6830<P>The <CODE>httpInitialize()</CODE> function initializes the networking
6831code as needed by the underlying platform. It is called automatically by
6832the <CODE>httpConnect()</CODE> function.
6833
6834<H3>Example</H3>
6835
6836<PRE>
6837#include &lt;cups/http.h&gt;
6838
6839httpInitialize();
6840</PRE>
6841
6842<H3>See Also</H3>
6843
6844<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
6845
6846
6847<!-- NEW PAGE --><H2><A NAME="httpMD5">httpMD5()</A></H2>
6848
6849<H3>Usage</H3>
6850
6851<PRE>
6852char *
6853httpMD5(const char *username,
6854 const char *realm,
6855 const char *passwd,
6856 char md5[33]);
6857</PRE>
6858
6859<H3>Arguments</H3>
6860
6861<CENTER><TABLE WIDTH="80%" BORDER>
6862<TR>
6863 <TH>Argument</TH>
6864 <TH>Description</TH>
6865</TR>
6866<TR>
6867 <TD>username</TD>
6868 <TD>The authenticating user name.</TD>
6869</TR>
6870<TR>
6871 <TD>realm</TD>
6872 <TD>The authenticating realm name.</TD>
6873</TR>
6874<TR>
6875 <TD>passwd</TD>
6876 <TD>The authenticating password.</TD>
6877</TR>
6878<TR>
6879 <TD>md5</TD>
6880 <TD>The MD5 sum string.</TD>
6881</TR>
6882</TABLE></CENTER>
6883
6884<H3>Returns</H3>
6885
6886<P>A pointer to the MD5 sum string.
6887
6888<H3>Description</H3>
6889
6890<P><CODE>httpMD5()</CODE> computes the MD5 hash of the username,
6891realm, and password as required by the HTTP Digest specification.
6892
6893<H3>Example</H3>
6894
6895<PRE>
6896#include &lt;cups/http.h&gt;
6897
6898char md5[33];
6899
6900...
6901
6902httpMD5("user", "realm", "password", md5);
6903</PRE>
6904
6905<H3>See Also</H3>
6906
6907<P>
6908<A HREF="#httpMD5Final"><CODE>httpMD5Final()</CODE></A>,
6909<A HREF="#httpMD5String"><CODE>httpMD5String()</CODE></A>
6910
6911
6912<!-- NEW PAGE --><H2><A NAME="httpMD5Final">httpMD5Final()</A></H2>
6913
6914<H3>Usage</H3>
6915
6916<PRE>
6917char *
6918httpMD5Final(const char *nonce,
6919 const char *method,
6920 const char *resource,
6921 char md5[33]);
6922</PRE>
6923
6924<H3>Arguments</H3>
6925
6926<CENTER><TABLE WIDTH="80%" BORDER>
6927<TR>
6928 <TH>Argument</TH>
6929 <TH>Description</TH>
6930</TR>
6931<TR>
6932 <TD>nonce</TD>
6933 <TD>The server nonce value.</TD>
6934</TR>
6935<TR>
6936 <TD>method</TD>
6937 <TD>The HTTP method (GET, POST, etc.)</TD>
6938</TR>
6939<TR>
6940 <TD>resource</TD>
6941 <TD>The resource path.</TD>
6942</TR>
6943<TR>
6944 <TD>md5</TD>
6945 <TD>The MD5 sum string.</TD>
6946</TR>
6947</TABLE></CENTER>
6948
6949<H3>Returns</H3>
6950
6951<P>The MD5 sum string.
6952
6953<H3>Description</H3>
6954
6955<P><CODE>httpMD5Final()</CODE> appends the nonce, method, and resource
6956to the specified MD5 sum.
6957
6958<H3>Example</H3>
6959
6960<PRE>
6961#include &lt;cups/http.h&gt;
6962
6963char md5[33];
6964
6965...
6966
6967httpMD5Final("nonce", "GET", "/jobs", md5);
6968</PRE>
6969
6970<H3>See Also</H3>
6971
6972<P>
6973<A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>,
6974<A HREF="#httpMD5String"><CODE>httpMD5String()</CODE></A>
6975
6976
6977<!-- NEW PAGE --><H2><A NAME="httpMD5String">httpMD5String()</A></H2>
6978
6979<H3>Usage</H3>
6980
6981<PRE>
6982char *
6983httpMD5String(const md5_byte_t *sum,
6984 char md5[33]);
6985</PRE>
6986
6987<H3>Arguments</H3>
6988
6989<CENTER><TABLE WIDTH="80%" BORDER>
6990<TR>
6991 <TH>Argument</TH>
6992 <TH>Description</TH>
6993</TR>
6994<TR>
6995 <TD>sum</TD>
6996 <TD>The raw MD5 sum data.</TD>
6997</TR>
6998<TR>
6999 <TD>md5</TD>
7000 <TD>The MD5 sum string.</TD>
7001</TR>
7002</TABLE></CENTER>
7003
7004<H3>Returns</H3>
7005
7006<P>The MD5 sum string.
7007
7008<H3>Description</H3>
7009
7010<P><CODE>httpMD5String()</CODE> converts the raw MD5 sum value to a string.
7011
7012<H3>Example</H3>
7013
7014<PRE>
7015#include &lt;cups/http.h&gt;
7016
7017md5_byte_t sum[16];
7018char md5[33];
7019
7020...
7021
7022httpMD5String(sum, md5);
7023</PRE>
7024
7025<H3>See Also</H3>
7026
7027<P>
7028<A HREF="#httpMD5"><CODE>httpMD5()</CODE></A>,
7029<A HREF="#httpMD5Final"><CODE>httpMD5Final()</CODE></A>
7030
7031
7032<!-- NEW PAGE --><H2><A NAME="httpOptions">httpOptions()</A></H2>
7033
7034<H3>Usage</H3>
7035
7036<PRE>
7037int
7038httpOptions(http_t *http,
7039 const char *uri);
7040</PRE>
7041
7042<H3>Arguments</H3>
7043
7044<CENTER><TABLE WIDTH="80%" BORDER>
7045<TR>
7046 <TH>Argument</TH>
7047 <TH>Description</TH>
7048</TR>
7049<TR>
7050 <TD>http</TD>
7051 <TD>The HTTP connection</TD>
7052</TR>
7053<TR>
7054 <TD>uri</TD>
7055 <TD>The URI to check for options</TD>
7056</TR>
7057</TABLE></CENTER>
7058
7059<H3>Returns</H3>
7060
7061<P>0 on success, non-zero on failure.
7062
7063<H3>Description</H3>
7064
7065<P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request to the
7066server.
7067
7068<H3>Example</H3>
7069
7070<PRE>
7071#include &lt;cups/http.h&gt;
7072
7073http_t *http;
7074
7075httpOptions(http, "/some/uri");
7076</PRE>
7077
7078<H3>See Also</H3>
7079
7080<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7081<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7082<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7083
7084
7085<!-- NEW PAGE --><H2><A NAME="httpPost">httpPost()</A></H2>
7086
7087<H3>Usage</H3>
7088
7089<PRE>
7090int
7091httpPost(http_t *http,
7092 const char *uri);
7093</PRE>
7094
7095<H3>Arguments</H3>
7096
7097<CENTER><TABLE WIDTH="80%" BORDER>
7098<TR>
7099 <TH>Argument</TH>
7100 <TH>Description</TH>
7101</TR>
7102<TR>
7103 <TD>http</TD>
7104 <TD>The HTTP connection</TD>
7105</TR>
7106<TR>
7107 <TD>uri</TD>
7108 <TD>The URI to post to</TD>
7109</TR>
7110</TABLE></CENTER>
7111
7112<H3>Returns</H3>
7113
7114<P>0 on success, non-zero on failure.
7115
7116<H3>Description</H3>
7117
7118<P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the
7119server.
7120
7121<H3>Example</H3>
7122
7123<PRE>
7124#include &lt;cups/http.h&gt;
7125
7126http_t *http;
7127
7128httpPost(http, "/some/uri");
7129</PRE>
7130
7131<H3>See Also</H3>
7132
7133<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7134<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7135<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7136
7137
7138<!-- NEW PAGE --><H2><A NAME="httpPrintf">httpPrintf()</A></H2>
7139
7140<H3>Usage</H3>
7141
7142<PRE>
7143int
7144httpPrintf(http_t *http,
7145 const char *format,
7146 ...);
7147</PRE>
7148
7149<H3>Arguments</H3>
7150
7151<CENTER><TABLE WIDTH="80%" BORDER>
7152<TR>
7153 <TH>Argument</TH>
7154 <TH>Description</TH>
7155</TR>
7156<TR>
7157 <TD>http</TD>
7158 <TD>The HTTP connection</TD>
7159</TR>
7160<TR>
7161 <TD>format</TD>
7162 <TD>A printf-style format string</TD>
7163</TR>
7164</TABLE></CENTER>
7165
7166<H3>Returns</H3>
7167
7168<P>The number of bytes written.
7169
7170<H3>Description</H3>
7171
7172<P>The <CODE>httpPrintf()</CODE> function sends a formatted string to the
7173HTTP connection. It is normally only used by the CUPS API and scheduler.
7174
7175<H3>Example</H3>
7176
7177<PRE>
7178#include &lt;cups/http.h&gt;
7179
7180http_t *http;
7181
7182httpPrintf(http, "GET / HTTP/1.1 \r\n");
7183</PRE>
7184
7185<H3>See Also</H3>
7186
7187<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
7188
7189
7190<!-- NEW PAGE --><H2><A NAME="httpPut">httpPut()</A></H2>
7191
7192<H3>Usage</H3>
7193
7194<PRE>
7195int
7196httpPut(http_t *http,
7197 const char *uri);
7198</PRE>
7199
7200<H3>Arguments</H3>
7201
7202<CENTER><TABLE WIDTH="80%" BORDER>
7203<TR>
7204 <TH>Argument</TH>
7205 <TH>Description</TH>
7206</TR>
7207<TR>
7208 <TD>http</TD>
7209 <TD>The HTTP connection</TD>
7210</TR>
7211<TR>
7212 <TD>uri</TD>
7213 <TD>The URI to put</TD>
7214</TR>
7215</TABLE></CENTER>
7216
7217<H3>Returns</H3>
7218
7219<P>0 on success, non-zero on failure.
7220
7221<H3>Description</H3>
7222
7223<P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the
7224server.
7225
7226<H3>Example</H3>
7227
7228<PRE>
7229#include &lt;cups/http.h&gt;
7230
7231http_t *http;
7232
7233httpDelete(http, "/some/uri");
7234</PRE>
7235
7236<H3>See Also</H3>
7237
7238<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7239<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7240<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7241
7242
7243<!-- NEW PAGE --><H2><A NAME="httpRead">httpRead()</A></H2>
7244
7245<H3>Usage</H3>
7246
7247<PRE>
7248int
7249httpRead(http_t *http,
7250 char *buffer,
7251 int length);
7252</PRE>
7253
7254<H3>Arguments</H3>
7255
7256<CENTER><TABLE WIDTH="80%" BORDER>
7257<TR>
7258 <TH>Argument</TH>
7259 <TH>Description</TH>
7260</TR>
7261<TR>
7262 <TD>http</TD>
7263 <TD>The HTTP connection</TD>
7264</TR>
7265<TR>
7266 <TD>buffer</TD>
7267 <TD>The buffer to read into</TD>
7268</TR>
7269<TR>
7270 <TD>length</TD>
7271 <TD>The number of bytes to read</TD>
7272</TR>
7273</TABLE></CENTER>
7274
7275<H3>Returns</H3>
7276
7277<P>The number of bytes read or -1 on error.
7278
7279<H3>Description</H3>
7280
7281<P>The <CODE>httpRead()</CODE> function reads data from the HTTP connection,
7282possibly the result of a GET or POST request.
7283
7284<H3>Example</H3>
7285
7286<PRE>
7287#include &lt;cups/http.h&gt;
7288
7289http_t *http;
7290char buffer[1024];
7291int bytes;
7292
7293httpGet(http, "/");
7294while (httpUpdate(http) != HTTP_CONTINUE);
7295while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
7296{
7297 buffer[bytes] = '\0';
7298 fputs(buffer, stdout);
7299}
7300</PRE>
7301
7302<H3>See Also</H3>
7303
7304<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7305<A HREF="#httpWrite"><CODE>httpWrite()</CODE></A>
7306
7307
7308<!-- NEW PAGE --><H2><A NAME="httpReconnect">httpReconnect()</A></H2>
7309
7310<H3>Usage</H3>
7311
7312<PRE>
7313int
7314httpReconnect(http_t *http);
7315</PRE>
7316
7317<H3>Arguments</H3>
7318
7319<CENTER><TABLE WIDTH="80%" BORDER>
7320<TR>
7321 <TH>Argument</TH>
7322 <TH>Description</TH>
7323</TR>
7324<TR>
7325 <TD>http</TD>
7326 <TD>The HTTP connection</TD>
7327</TR>
7328</TABLE></CENTER>
7329
7330<H3>Returns</H3>
7331
7332<P>0 on success, non-zero on failure.
7333
7334<H3>Description</H3>
7335
7336<P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP server.
7337This is usually done automatically if the HTTP functions detect that the
7338server connection has terminated.
7339
7340<H3>Example</H3>
7341
7342<PRE>
7343#include &lt;cups/http.h&gt;
7344
7345http_t *http;
7346
7347httpReconnect(http);
7348</PRE>
7349
7350<H3>See Also</H3>
7351
7352<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
7353
7354
7355<!-- NEW PAGE --><H2><A NAME="httpSeparate">httpSeparate()</A></H2>
7356
7357<H3>Usage</H3>
7358
7359<PRE>
7360void
7361httpSeparate(const char *uri,
7362 char *method,
7363 char *username,
7364 char *host,
7365 int *port,
7366 char *resource);
7367</PRE>
7368
7369<H3>Arguments</H3>
7370
7371<CENTER><TABLE WIDTH="80%" BORDER>
7372<TR>
7373 <TH>Argument</TH>
7374 <TH>Description</TH>
7375</TR>
7376<TR>
7377 <TD>uri</TD>
7378 <TD>The URI to separate</TD>
7379</TR>
7380<TR>
7381 <TD>method</TD>
7382 <TD>The method (scheme) of the URI</TD>
7383</TR>
7384<TR>
7385 <TD>username</TD>
7386 <TD>The username (and password) portion of the URI, if any</TD>
7387</TR>
7388<TR>
7389 <TD>host</TD>
7390 <TD>The hostname portion of the URI, if any</TD>
7391</TR>
7392<TR>
7393 <TD>port</TD>
7394 <TD>The port number for the URI, either as specified or as
7395 default for the method/scheme</TD>
7396</TR>
7397<TR>
7398 <TD>resource</TD>
7399 <TD>The resource string, usually a filename on the server</TD>
7400</TR>
7401</TABLE></CENTER>
7402
7403<H3>Description</H3>
7404
7405<P>The <CODE>httpSeparate()</CODE> function separates the specified URI into
7406its component parts. The method, username, hostname, and resource strings should
7407be at least <CODE>HTTP_MAX_URI</CODE> characters long to avoid potential
7408buffer overflow problems.
7409
7410<H3>Example</H3>
7411
7412<PRE>
7413char uri[HTTP_MAX_URI];
7414char method[HTTP_MAX_URI];
7415char username[HTTP_MAX_URI];
7416char host[HTTP_MAX_URI];
7417char resource[HTTP_MAX_URI];
7418int port;
7419
7420...
7421
7422httpSeparate(uri, method, username, host, &amp;port, resource);
7423</PRE>
7424
7425<H3>See Also</H3>
7426
7427<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>
7428
7429
7430<!-- NEW PAGE --><H2><A NAME="httpSetField">httpSetField()</A></H2>
7431
7432<H3>Usage</H3>
7433
7434<PRE>
7435void
7436httpSetField(http_t *http,
7437 http_field_t field,
7438 const char *value);
7439</PRE>
7440
7441<H3>Arguments</H3>
7442
7443<CENTER><TABLE WIDTH="80%" BORDER>
7444<TR>
7445 <TH>Argument</TH>
7446 <TH>Description</TH>
7447</TR>
7448<TR>
7449 <TD>http</TD>
7450 <TD>The HTTP connection</TD>
7451</TR>
7452<TR>
7453 <TD>field</TD>
7454 <TD>The HTTP field</TD>
7455</TR>
7456<TR>
7457 <TD>value</TD>
7458 <TD>The string value for the field</TD>
7459</TR>
7460</TABLE></CENTER>
7461
7462<H3>Description</H3>
7463
7464<P>The <CODE>httpSetField()</CODE> function sets the current value for
7465the specified HTTP field.
7466
7467<H3>Example</H3>
7468
7469<PRE>
7470#include &lt;cups/http.h&gt;
7471
7472http_t *http;
7473
7474httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325"));
7475httpGet(http, "/some/uri");
7476while (httpUpdate(http) == HTTP_CONTINUE);
7477</PRE>
7478
7479<H3>See Also</H3>
7480
7481<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7482<A HREF="#httpGetField"><CODE>httpGetField()</CODE></A>
7483
7484
7485<!-- NEW PAGE --><H2><A NAME="httpStatus">httpStatus()</A></H2>
7486
7487<H3>Usage</H3>
7488
7489<PRE>
7490const char *
7491httpStatus(http_status_t status);
7492</PRE>
7493
7494<H3>Arguments</H3>
7495
7496<CENTER><TABLE WIDTH="80%" BORDER>
7497<TR>
7498 <TH>Argument</TH>
7499 <TH>Description</TH>
7500</TR>
7501<TR>
7502 <TD>status</TD>
7503 <TD>The HTTP status code from the server.</TD>
7504</TR>
7505</TABLE></CENTER>
7506
7507<H3>Returns</H3>
7508
7509<P>The standard HTTP status text associated with the status code.
7510
7511<H3>Description</H3>
7512
7513<P><CODE>httpStatus()</CODE> returns the standard HTTP status text
7514associated with the status code.
7515
7516<H3>Example</H3>
7517
7518<PRE>
7519#include &lt;cups/http.h&gt;
7520
7521<A HREF="#http_t">http_t</A> *http;
7522
7523...
7524
7525puts(httpStatus(http->status));
7526</PRE>
7527
7528
7529<!-- NEW PAGE --><H2><A NAME="httpTrace">httpTrace()</A></H2>
7530
7531<H3>Usage</H3>
7532
7533<PRE>
7534int
7535httpTrace(http_t *http,
7536 const char *uri);
7537</PRE>
7538
7539<H3>Arguments</H3>
7540
7541<CENTER><TABLE WIDTH="80%" BORDER>
7542<TR>
7543 <TH>Argument</TH>
7544 <TH>Description</TH>
7545</TR>
7546<TR>
7547 <TD>http</TD>
7548 <TD>The HTTP connection</TD>
7549</TR>
7550<TR>
7551 <TD>uri</TD>
7552 <TD>The URI to trace</TD>
7553</TR>
7554</TABLE></CENTER>
7555
7556<H3>Returns</H3>
7557
7558<P>0 on success, non-zero on failure.
7559
7560<H3>Description</H3>
7561
7562<P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to the
7563server.
7564
7565<H3>Example</H3>
7566
7567<PRE>
7568#include &lt;cups/http.h&gt;
7569
7570http_t *http;
7571
7572httpTrace(http, "/some/uri");
7573</PRE>
7574
7575<H3>See Also</H3>
7576
7577<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7578<A HREF="#httpSetField"><CODE>httpSetField()</CODE></A>,
7579<A HREF="#httpUpdate"><CODE>httpUpdate()</CODE></A>
7580
7581
7582<!-- NEW PAGE --><H2><A NAME="httpUpdate">httpUpdate()</A></H2>
7583
7584<H3>Usage</H3>
7585
7586<PRE>
7587http_status_t
7588httpUpdate(http_t *http);
7589</PRE>
7590
7591<H3>Arguments</H3>
7592
7593<CENTER><TABLE WIDTH="80%" BORDER>
7594<TR>
7595 <TH>Argument</TH>
7596 <TH>Description</TH>
7597</TR>
7598<TR>
7599 <TD>http</TD>
7600 <TD>The HTTP connection</TD>
7601</TR>
7602</TABLE></CENTER>
7603
7604<H3>Returns</H3>
7605
7606<P>The HTTP status of the current request.
7607
7608<H3>Description</H3>
7609
7610<P>The <CODE>httpUpdate()</CODE> function updates the current request status.
7611It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE
7612request to finalize the HTTP request and retrieve the request status.
7613
7614<P>Since proxies and the current blocking mode can cause the request to
7615take longer, programs should continue calling <CODE>httpUpdate()<CODE>
7616until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>.
7617
7618<H3>Example</H3>
7619
7620<PRE>
7621#include &lt;cups/http.h&gt;
7622
7623http_t *http;
7624http_status_t status;
7625
7626httpGet(http, "/some/uri");
7627while ((status = httpUpdate(http)) == HTTP_CONTINUE);
7628printf("Request status is %d\n", status);
7629</PRE>
7630
7631<H3>See Also</H3>
7632
7633<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7634<A HREF="#httpDelete"><CODE>httpDelete()</CODE></A>,
7635<A HREF="#httpGet"><CODE>httpGet()</CODE></A>,
7636<A HREF="#httpHead"><CODE>httpHead()</CODE></A>,
7637<A HREF="#httpOptions"><CODE>httpOptions()</CODE></A>,
7638<A HREF="#httpPost"><CODE>httpPost()</CODE></A>,
7639<A HREF="#httpPut"><CODE>httpPut()</CODE></A>,
7640<A HREF="#httpTrace"><CODE>httpTrace()</CODE></A>
7641
7642
7643<!-- NEW PAGE --><H2><A NAME="httpWrite">httpWrite()</A></H2>
7644
7645<H3>Usage</H3>
7646
7647<PRE>
7648int
7649httpWrite(http_t *http,
7650 char *buffer,
7651 int length);
7652</PRE>
7653
7654<H3>Arguments</H3>
7655
7656<CENTER><TABLE WIDTH="80%" BORDER>
7657<TR>
7658 <TH>Argument</TH>
7659 <TH>Description</TH>
7660</TR>
7661<TR>
7662 <TD>http</TD>
7663 <TD>The HTTP connection</TD>
7664</TR>
7665<TR>
7666 <TD>buffer</TD>
7667 <TD>The buffer to read into</TD>
7668</TR>
7669<TR>
7670 <TD>length</TD>
7671 <TD>The number of bytes to read</TD>
7672</TR>
7673</TABLE></CENTER>
7674
7675<H3>Returns</H3>
7676
7677<P>The number of bytes read or -1 on error.
7678
7679<H3>Description</H3>
7680
7681<P>The <CODE>httpWrite()</CODE> function reads data from the HTTP connection,
7682possibly the result of a GET or POST request.
7683
7684<H3>Example</H3>
7685
7686<PRE>
7687#include &lt;cups/http.h&gt;
7688
7689http_t *http;
7690FILE *fp;
7691char buffer[1024];
7692int bytes;
7693
7694httpPost(http, "/");
7695
7696while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0)
7697 httpWrite(http, buffer, bytes);
7698
7699while (httpUpdate(http) != HTTP_CONTINUE);
7700
7701while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) > 0)
7702{
7703 buffer[bytes] = '\0';
7704 fputs(buffer, stdout);
7705}
7706</PRE>
7707
7708<H3>See Also</H3>
7709
7710<A HREF="#httpConnect"><CODE>httpConnect()</CODE></A>,
7711<A HREF="#httpRead"><CODE>httpRead()</CODE></A>
7712
7713
7714<!-- NEW PAGE --><H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2>
7715
7716<H3>Usage</H3>
7717
7718<PRE>
7719ipp_attribute_t *
7720ippAddBoolean(ipp_t *ipp,
7721 ipp_tag_t group,
7722 const char *name,
7723 char value);
7724</PRE>
7725
7726<H3>Arguments</H3>
7727
7728<CENTER><TABLE WIDTH="80%" BORDER>
7729<TR>
7730 <TH>Argument</TH>
7731 <TH>Description</TH>
7732</TR>
7733<TR>
7734 <TD>ipp</TD>
7735 <TD>The IPP request</TD>
7736</TR>
7737<TR>
7738 <TD>group</TD>
7739 <TD>The IPP group</TD>
7740</TR>
7741<TR>
7742 <TD>name</TD>
7743 <TD>The name of attribute</TD>
7744</TR>
7745<TR>
7746 <TD>value</TD>
7747 <TD>The boolean value</TD>
7748</TR>
7749</TABLE></CENTER>
7750
7751<H3>Returns</H3>
7752
7753<P>A pointer to the new attribute or NULL if the attribute could not be
7754created.
7755
7756<H3>Description</H3>
7757
7758<P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean attribute
7759value to the specified IPP request.
7760
7761<H3>Example</H3>
7762
7763<PRE>
7764#include &lt;cups/ipp.h>
7765
7766ipp_t *ipp;
7767
7768ippAddBoolean(ipp, IPP_TAG_OPERATION, "my-jobs", 1);
7769</PRE>
7770
7771<H3>See Also</H3>
7772
7773<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
7774<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
7775<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
7776<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
7777<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
7778<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
7779<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
7780<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
7781<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
7782<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
7783<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
7784
7785
7786<!-- NEW PAGE --><H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2>
7787
7788<H3>Usage</H3>
7789
7790<PRE>
7791ipp_attribute_t *
7792ippAddBooleans(ipp_t *ipp,
7793 ipp_tag_t group,
7794 const char *name,
7795 int num_values,
7796 const char *values);
7797</PRE>
7798
7799<H3>Arguments</H3>
7800
7801<CENTER><TABLE WIDTH="80%" BORDER>
7802<TR>
7803 <TH>Argument</TH>
7804 <TH>Description</TH>
7805</TR>
7806<TR>
7807 <TD>ipp</TD>
7808 <TD>The IPP request</TD>
7809</TR>
7810<TR>
7811 <TD>group</TD>
7812 <TD>The IPP group</TD>
7813</TR>
7814<TR>
7815 <TD>name</TD>
7816 <TD>The name of attribute</TD>
7817</TR>
7818<TR>
7819 <TD>num_values</TD>
7820 <TD>The number of values</TD>
7821</TR>
7822<TR>
7823 <TD>values</TD>
7824 <TD>The boolean values</TD>
7825</TR>
7826</TABLE></CENTER>
7827
7828<H3>Returns</H3>
7829
7830<P>A pointer to the new attribute or NULL if the attribute could not be
7831created.
7832
7833<H3>Description</H3>
7834
7835<P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean
7836attribute values to the specified IPP request. If the
7837<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
7838<CODE>num_values</CODE> false values is created.
7839
7840<H3>Example</H3>
7841
7842<PRE>
7843#include &lt;cups/ipp.h>
7844
7845ipp_t *ipp;
7846char values[10];
7847
7848ippAddBooleans(ipp, IPP_TAG_OPERATION, "some-attribute", 10, values);
7849</PRE>
7850
7851<H3>See Also</H3>
7852
7853<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
7854<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
7855<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
7856<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
7857<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
7858<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
7859<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
7860<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
7861<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
7862<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
7863<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
7864
7865
7866<!-- NEW PAGE --><H2><A NAME="ippAddDate">ippAddDate()</A></H2>
7867
7868<H3>Usage</H3>
7869
7870<PRE>
7871ipp_attribute_t *
7872ippAddDate(ipp_t *ipp,
7873 ipp_tag_t group,
7874 const char *name,
7875 ipp_uchar_t *value);
7876</PRE>
7877
7878<H3>Arguments</H3>
7879
7880<CENTER><TABLE WIDTH="80%" BORDER>
7881<TR>
7882 <TH>Argument</TH>
7883 <TH>Description</TH>
7884</TR>
7885<TR>
7886 <TD>ipp</TD>
7887 <TD>The IPP request</TD>
7888</TR>
7889<TR>
7890 <TD>group</TD>
7891 <TD>The IPP group</TD>
7892</TR>
7893<TR>
7894 <TD>name</TD>
7895 <TD>The name of attribute</TD>
7896</TR>
7897<TR>
7898 <TD>value</TD>
7899 <TD>The date value</TD>
7900</TR>
7901</TABLE></CENTER>
7902
7903<H3>Returns</H3>
7904
7905<P>A pointer to the new attribute or NULL if the attribute could not be
7906created.
7907
7908<H3>Description</H3>
7909
7910<P>The <CODE>ippAddDate()</CODE> function adds a single date-time attribute
7911value to the specified IPP request.
7912
7913<H3>Example</H3>
7914
7915<PRE>
7916#include &lt;cups/ipp.h>
7917
7918ipp_t *ipp;
7919
7920ippAddDate(ipp, IPP_TAG_OPERATION, "some-attribute",
7921 ippTimeToDate(time(NULL));
7922</PRE>
7923
7924<H3>See Also</H3>
7925
7926<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
7927<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
7928<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
7929<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
7930<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
7931<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
7932<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
7933<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
7934<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
7935<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
7936<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>,
7937<A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
7938
7939
7940<!-- NEW PAGE --><H2><A NAME="ippAddInteger">ippAddInteger()</A></H2>
7941
7942<H3>Usage</H3>
7943
7944<PRE>
7945ipp_attribute_t *
7946ippAddInteger(ipp_t *ipp,
7947 ipp_tag_t group,
7948 ipp_tag_t tag,
7949 const char *name,
7950 int value);
7951</PRE>
7952
7953<H3>Arguments</H3>
7954
7955<CENTER><TABLE WIDTH="80%" BORDER>
7956<TR>
7957 <TH>Argument</TH>
7958 <TH>Description</TH>
7959</TR>
7960<TR>
7961 <TD>ipp</TD>
7962 <TD>The IPP request</TD>
7963</TR>
7964<TR>
7965 <TD>group</TD>
7966 <TD>The IPP group</TD>
7967</TR>
7968<TR>
7969 <TD>tag</TD>
7970 <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
7971</TR>
7972<TR>
7973 <TD>name</TD>
7974 <TD>The name of attribute</TD>
7975</TR>
7976<TR>
7977 <TD>value</TD>
7978 <TD>The integer value</TD>
7979</TR>
7980</TABLE></CENTER>
7981
7982<H3>Returns</H3>
7983
7984<P>A pointer to the new attribute or NULL if the attribute could not be
7985created.
7986
7987<H3>Description</H3>
7988
7989<P>The <CODE>ippAddInteger()</CODE> function adds a single integer attribute
7990value to the specified IPP request.
7991
7992<H3>Example</H3>
7993
7994<PRE>
7995#include &lt;cups/ipp.h>
7996
7997ipp_t *ipp;
7998
7999ippAddInteger(ipp, IPP_TAG_OPERATION, "limit", 100);
8000</PRE>
8001
8002<H3>See Also</H3>
8003
8004<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8005<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8006<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8007<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8008<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8009<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8010<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8011<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8012<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8013<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8014<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8015
8016
8017<!-- NEW PAGE --><H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2>
8018
8019<H3>Usage</H3>
8020
8021<PRE>
8022ipp_attribute_t *
8023ippAddIntegers(ipp_t *ipp,
8024 ipp_tag_t group,
8025 ipp_tag_t tag,
8026 const char *name,
8027 int num_values,
8028 const int *values);
8029</PRE>
8030
8031<H3>Arguments</H3>
8032
8033<CENTER><TABLE WIDTH="80%" BORDER>
8034<TR>
8035 <TH>Argument</TH>
8036 <TH>Description</TH>
8037</TR>
8038<TR>
8039 <TD>ipp</TD>
8040 <TD>The IPP request</TD>
8041</TR>
8042<TR>
8043 <TD>group</TD>
8044 <TD>The IPP group</TD>
8045</TR>
8046<TR>
8047 <TD>tag</TD>
8048 <TD>The type of integer value (IPP_TAG_INTEGER or IPP_TAG_ENUM)</TD>
8049</TR>
8050<TR>
8051 <TD>name</TD>
8052 <TD>The name of attribute</TD>
8053</TR>
8054<TR>
8055 <TD>num_values</TD>
8056 <TD>The number of values</TD>
8057</TR>
8058<TR>
8059 <TD>values</TD>
8060 <TD>The integer values</TD>
8061</TR>
8062</TABLE></CENTER>
8063
8064<H3>Returns</H3>
8065
8066<P>A pointer to the new attribute or NULL if the attribute could not be
8067created.
8068
8069<H3>Description</H3>
8070
8071<P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer
8072attribute values to the specified IPP request. If the
8073<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8074<CODE>num_values</CODE> 0 values is created.
8075
8076<H3>Example</H3>
8077
8078<PRE>
8079#include &lt;cups/ipp.h>
8080
8081ipp_t *ipp;
8082int values[100];
8083
8084ippAddIntegers(ipp, IPP_TAG_OPERATION, "some-attribute", 100, values);
8085</PRE>
8086
8087<H3>See Also</H3>
8088
8089<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8090<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8091<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8092<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8093<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8094<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8095<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8096<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8097<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8098<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8099<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8100
8101
8102<!-- NEW PAGE --><H2><A NAME="ippAddRange">ippAddRange()</A></H2>
8103
8104<H3>Usage</H3>
8105
8106<PRE>
8107ipp_attribute_t *
8108ippAddRange(ipp_t *ipp,
8109 ipp_tag_t group,
8110 const char *name,
8111 int low,
8112 int high);
8113</PRE>
8114
8115<H3>Arguments</H3>
8116
8117<CENTER><TABLE WIDTH="80%" BORDER>
8118<TR>
8119 <TH>Argument</TH>
8120 <TH>Description</TH>
8121</TR>
8122<TR>
8123 <TD>ipp</TD>
8124 <TD>The IPP request</TD>
8125</TR>
8126<TR>
8127 <TD>group</TD>
8128 <TD>The IPP group</TD>
8129</TR>
8130<TR>
8131 <TD>name</TD>
8132 <TD>The name of attribute</TD>
8133</TR>
8134<TR>
8135 <TD>low</TD>
8136 <TD>The lower value</TD>
8137</TR>
8138<TR>
8139 <TD>high</TD>
8140 <TD>The higher value</TD>
8141</TR>
8142</TABLE></CENTER>
8143
8144<H3>Returns</H3>
8145
8146<P>A pointer to the new attribute or NULL if the attribute could not be
8147created.
8148
8149<H3>Description</H3>
8150
8151<P>The <CODE>ippAddRange()</CODE> function adds a single range attribute
8152value to the specified IPP request.
8153
8154<H3>Example</H3>
8155
8156<PRE>
8157#include &lt;cups/ipp.h>
8158
8159ipp_t *ipp;
8160
8161ippAddRange(ipp, IPP_TAG_OPERATION, "page-ranges", 1, 10);
8162</PRE>
8163
8164<H3>See Also</H3>
8165
8166<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8167<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8168<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8169<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8170<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8171<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8172<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8173<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8174<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8175<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8176<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8177
8178
8179<!-- NEW PAGE --><H2><A NAME="ippAddRanges">ippAddRanges()</A></H2>
8180
8181<H3>Usage</H3>
8182
8183<PRE>
8184ipp_attribute_t *
8185ippAddRanges(ipp_t *ipp,
8186 ipp_tag_t group,
8187 const char *name,
8188 int num_values,
8189 const int *lows,
8190 const int *highs);
8191</PRE>
8192
8193<H3>Arguments</H3>
8194
8195<CENTER><TABLE WIDTH="80%" BORDER>
8196<TR>
8197 <TH>Argument</TH>
8198 <TH>Description</TH>
8199</TR>
8200<TR>
8201 <TD>ipp</TD>
8202 <TD>The IPP request</TD>
8203</TR>
8204<TR>
8205 <TD>group</TD>
8206 <TD>The IPP group</TD>
8207</TR>
8208<TR>
8209 <TD>name</TD>
8210 <TD>The name of attribute</TD>
8211</TR>
8212<TR>
8213 <TD>num_values</TD>
8214 <TD>The number of range values</TD>
8215</TR>
8216<TR>
8217 <TD>lows</TD>
8218 <TD>The lower values</TD>
8219</TR>
8220<TR>
8221 <TD>highs</TD>
8222 <TD>The higher values</TD>
8223</TR>
8224</TABLE></CENTER>
8225
8226<H3>Returns</H3>
8227
8228<P>A pointer to the new attribute or NULL if the attribute could not be
8229created.
8230
8231<H3>Description</H3>
8232
8233<P>The <CODE>ippAddRanges()</CODE> function adds one or more range
8234attribute values to the specified IPP request. If the
8235<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8236<CODE>num_values</CODE> 0,0 ranges is created.
8237
8238<H3>Example</H3>
8239
8240<PRE>
8241#include &lt;cups/ipp.h>
8242
8243ipp_t *ipp;
8244int lows[2];
8245int highs[2];
8246
8247ippAddRanges(ipp, IPP_TAG_OPERATION, "page-ranges", 2, lows, highs);
8248</PRE>
8249
8250<H3>See Also</H3>
8251
8252<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8253<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8254<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8255<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8256<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8257<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8258<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8259<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8260<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8261<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8262<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8263
8264
8265<!-- NEW PAGE --><H2><A NAME="ippAddResolution">ippAddResolution()</A></H2>
8266
8267<H3>Usage</H3>
8268
8269<PRE>
8270ipp_attribute_t *
8271ippAddResolution(ipp_t *ipp,
8272 ipp_tag_t group,
8273 const char *name,
8274 int xres,
8275 int yres,
8276 ipp_res_t units);
8277</PRE>
8278
8279<H3>Arguments</H3>
8280
8281<CENTER><TABLE WIDTH="80%" BORDER>
8282<TR>
8283 <TH>Argument</TH>
8284 <TH>Description</TH>
8285</TR>
8286<TR>
8287 <TD>ipp</TD>
8288 <TD>The IPP request</TD>
8289</TR>
8290<TR>
8291 <TD>group</TD>
8292 <TD>The IPP group</TD>
8293</TR>
8294<TR>
8295 <TD>name</TD>
8296 <TD>The name of attribute</TD>
8297</TR>
8298<TR>
8299 <TD>xres</TD>
8300 <TD>The horizontal resolution</TD>
8301</TR>
8302<TR>
8303 <TD>yres</TD>
8304 <TD>The vertical resolution</TD>
8305</TR>
8306<TR>
8307 <TD>units</TD>
8308 <TD>The resolution units</TD>
8309</TR>
8310</TABLE></CENTER>
8311
8312<H3>Returns</H3>
8313
8314<P>A pointer to the new attribute or NULL if the attribute could not be
8315created.
8316
8317<H3>Description</H3>
8318
8319<P>The <CODE>ippAddResolution()</CODE> function adds a single resolution attribute
8320value to the specified IPP request.
8321
8322<H3>Example</H3>
8323
8324<PRE>
8325#include &lt;cups/ipp.h>
8326
8327ipp_t *ipp;
8328
8329ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolution",
8330 720, 720, IPP_RES_PER_INCH);
8331</PRE>
8332
8333<H3>See Also</H3>
8334
8335<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8336<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8337<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8338<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8339<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8340<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8341<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8342<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8343<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8344<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8345<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8346
8347
8348<!-- NEW PAGE --><H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2>
8349
8350<H3>Usage</H3>
8351
8352<PRE>
8353ipp_attribute_t *
8354ippAddResolutions(ipp_t *ipp,
8355 ipp_tag_t group,
8356 const char *name,
8357 int num_values,
8358 const int *xres,
8359 const int *yres,
8360 const ipp_res_t *units);
8361</PRE>
8362
8363<H3>Arguments</H3>
8364
8365<CENTER><TABLE WIDTH="80%" BORDER>
8366<TR>
8367 <TH>Argument</TH>
8368 <TH>Description</TH>
8369</TR>
8370<TR>
8371 <TD>ipp</TD>
8372 <TD>The IPP request</TD>
8373</TR>
8374<TR>
8375 <TD>group</TD>
8376 <TD>The IPP group</TD>
8377</TR>
8378<TR>
8379 <TD>name</TD>
8380 <TD>The name of attribute</TD>
8381</TR>
8382<TR>
8383 <TD>num_values</TD>
8384 <TD>The number of resolution values</TD>
8385</TR>
8386<TR>
8387 <TD>xres</TD>
8388 <TD>The horizontal resolutions</TD>
8389</TR>
8390<TR>
8391 <TD>yres</TD>
8392 <TD>The vertical resolutions</TD>
8393</TR>
8394<TR>
8395 <TD>units</TD>
8396 <TD>The resolution units</TD>
8397</TR>
8398</TABLE></CENTER>
8399
8400<H3>Returns</H3>
8401
8402<P>A pointer to the new attribute or NULL if the attribute could not be
8403created.
8404
8405<H3>Description</H3>
8406
8407<P>The <CODE>ippAddResolutions()</CODE> function adds one or more
8408resolution attribute values to the specified IPP request. If the
8409<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8410<CODE>num_values</CODE> 0,0 resolutions is created.
8411
8412<H3>Example</H3>
8413
8414<PRE>
8415#include &lt;cups/ipp.h>
8416
8417ipp_t *ipp;
8418int xres[5];
8419int yres[5];
8420ipp_res_t units[5];
8421
8422ippAddBoolean(ipp, IPP_TAG_OPERATION, "printer-resolutions-supported",
8423 5, xres, yres, units);
8424</PRE>
8425
8426<H3>See Also</H3>
8427
8428<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8429<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8430<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8431<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8432<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8433<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8434<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8435<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8436<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8437<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8438<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8439
8440
8441<!-- NEW PAGE --><H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2>
8442
8443<H3>Usage</H3>
8444
8445<PRE>
8446ipp_attribute_t *
8447ippAddSeparator(ipp_t *ipp);
8448</PRE>
8449
8450<H3>Arguments</H3>
8451
8452<CENTER><TABLE WIDTH="80%" BORDER>
8453<TR>
8454 <TH>Argument</TH>
8455 <TH>Description</TH>
8456</TR>
8457<TR>
8458 <TD>ipp</TD>
8459 <TD>The IPP request</TD>
8460</TR>
8461</TABLE></CENTER>
8462
8463<H3>Returns</H3>
8464
8465<P>A pointer to the new separator or NULL if the separator could not be
8466created.
8467
8468<H3>Description</H3>
8469
8470<P>The <CODE>ippAddSeparator()</CODE> function adds a group separator
8471to the specified IPP request.
8472
8473<H3>Example</H3>
8474
8475<PRE>
8476#include &lt;cups/ipp.h>
8477
8478ipp_t *ipp;
8479
8480ippAddSeparator(ipp);
8481</PRE>
8482
8483<H3>See Also</H3>
8484
8485<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8486<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8487<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8488<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8489<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8490<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8491<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8492<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8493<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8494<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>,
8495<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8496
8497
8498<!-- NEW PAGE --><H2><A NAME="ippAddString">ippAddString()</A></H2>
8499
8500<H3>Usage</H3>
8501
8502<PRE>
8503ipp_attribute_t *
8504ippAddString(ipp_t *ipp,
8505 ipp_tag_t group,
8506 ipp_tag_t tag,
8507 const char *name,
8508 const char *charset,
8509 const char *value);
8510</PRE>
8511
8512<H3>Arguments</H3>
8513
8514<CENTER><TABLE WIDTH="80%" BORDER>
8515<TR>
8516 <TH>Argument</TH>
8517 <TH>Description</TH>
8518</TR>
8519<TR>
8520 <TD>ipp</TD>
8521 <TD>The IPP request</TD>
8522</TR>
8523<TR>
8524 <TD>group</TD>
8525 <TD>The IPP group</TD>
8526</TR>
8527<TR>
8528 <TD>tag</TD>
8529 <TD>The type of string value</TD>
8530</TR>
8531<TR>
8532 <TD>name</TD>
8533 <TD>The name of attribute</TD>
8534</TR>
8535<TR>
8536 <TD>charset</TD>
8537 <TD>The character set for the string</TD>
8538</TR>
8539<TR>
8540 <TD>value</TD>
8541 <TD>The string value</TD>
8542</TR>
8543</TABLE></CENTER>
8544
8545<H3>Returns</H3>
8546
8547<P>A pointer to the new attribute or NULL if the attribute could not be
8548created.
8549
8550<H3>Description</H3>
8551
8552<P>The <CODE>ippAddString()</CODE> function adds a single string attribute
8553value to the specified IPP request. For <CODE>IPP_TAG_NAMELANG</CODE> and
8554<CODE>IPP_TAG_TEXTLANG</CODE> strings, the charset value is provided with
8555the string to identify the string encoding used. Otherwise the charset value
8556is ignored.
8557
8558<H3>Example</H3>
8559
8560<PRE>
8561#include &lt;cups/ipp.h>
8562
8563ipp_t *ipp;
8564
8565ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, "job-name",
8566 NULL, "abc123");
8567</PRE>
8568
8569<H3>See Also</H3>
8570
8571<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8572<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8573<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8574<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8575<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8576<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8577<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8578<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8579<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8580<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8581<A HREF="#ippAddStrings"><CODE>ippAddStrings()</CODE></A>
8582
8583
8584<!-- NEW PAGE --><H2><A NAME="ippAddStrings">ippAddStrings()</A></H2>
8585
8586<H3>Usage</H3>
8587
8588<PRE>
8589ipp_attribute_t *
8590ippAddStrings(ipp_t *ipp,
8591 ipp_tag_t group,
8592 ipp_tag_t tag,
8593 const char *name,
8594 int num_values,
8595 const char *charset,
8596 const char **values);
8597</PRE>
8598
8599<H3>Arguments</H3>
8600
8601<CENTER><TABLE WIDTH="80%" BORDER>
8602<TR>
8603 <TH>Argument</TH>
8604 <TH>Description</TH>
8605</TR>
8606<TR>
8607 <TD>ipp</TD>
8608 <TD>The IPP request</TD>
8609</TR>
8610<TR>
8611 <TD>group</TD>
8612 <TD>The IPP group</TD>
8613</TR>
8614<TR>
8615 <TD>tag</TD>
8616 <TD>The type of string value</TD>
8617</TR>
8618<TR>
8619 <TD>name</TD>
8620 <TD>The name of attribute</TD>
8621</TR>
8622<TR>
8623 <TD>num_values</TD>
8624 <TD>The number of strings</TD>
8625</TR>
8626<TR>
8627 <TD>charset</TD>
8628 <TD>The character set for the strings</TD>
8629</TR>
8630<TR>
8631 <TD>values</TD>
8632 <TD>The string values</TD>
8633</TR>
8634</TABLE></CENTER>
8635
8636<H3>Returns</H3>
8637
8638<P>A pointer to the new attribute or NULL if the attribute could not be
8639created.
8640
8641<H3>Description</H3>
8642
8643<P>The <CODE>ippAddStrings()</CODE> function adds one or more string
8644attribute values to the specified IPP request. For
8645<CODE>IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE>
8646strings, the charset value is provided with the strings to identify the
8647string encoding used. Otherwise the charset value is ignored. If the
8648<CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of
8649<CODE>num_values</CODE> NULL strings is created.
8650
8651<H3>Example</H3>
8652
8653<PRE>
8654#include &lt;cups/ipp.h>
8655
8656ipp_t *ipp;
8657char *values[2] = { "one", "two" };
8658
8659ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, "attr-name",
8660 2, NULL, values);
8661</PRE>
8662
8663<H3>See Also</H3>
8664
8665<A HREF="#ippAddBoolean"><CODE>ippAddBoolean()</CODE></A>,
8666<A HREF="#ippAddBooleans"><CODE>ippAddBooleans()</CODE></A>,
8667<A HREF="#ippAddDate"><CODE>ippAddDate()</CODE></A>,
8668<A HREF="#ippAddInteger"><CODE>ippAddInteger()</CODE></A>,
8669<A HREF="#ippAddIntegers"><CODE>ippAddIntegers()</CODE></A>,
8670<A HREF="#ippAddRange"><CODE>ippAddRange()</CODE></A>,
8671<A HREF="#ippAddRanges"><CODE>ippAddRanges()</CODE></A>,
8672<A HREF="#ippAddResolution"><CODE>ippAddResolution()</CODE></A>,
8673<A HREF="#ippAddResolutions"><CODE>ippAddResolutions()</CODE></A>,
8674<A HREF="#ippAddSeparator"><CODE>ippAddSeparator()</CODE></A>,
8675<A HREF="#ippAddString"><CODE>ippAddString()</CODE></A>
8676
8677
8678<!-- NEW PAGE --><H2><A NAME="ippDateToTime">ippDateToTime()</A></H2>
8679
8680<H3>Usage</H3>
8681
8682<PRE>
8683time_t
8684ippDateToTime(const ipp_uchar_t date[11]);
8685</PRE>
8686
8687<H3>Arguments</H3>
8688
8689<CENTER><TABLE WIDTH="80%" BORDER>
8690<TR>
8691 <TH>Argument</TH>
8692 <TH>Description</TH>
8693</TR>
8694<TR>
8695 <TD>date</TD>
8696 <TD>The IPP date-time value</TD>
8697</TR>
8698</TABLE></CENTER>
8699
8700<H3>Returns</H3>
8701
8702<P>A UNIX time value.
8703
8704<H3>Description</H3>
8705
8706<P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time value
8707to a UNIX time value.
8708
8709<H3>Example</H3>
8710
8711<PRE>
8712#include &lt;cups/ipp.h>
8713
8714ipp_uchar_t date[11];
8715
8716printf("UNIX time is %d\n", ippDateToTime(date));
8717</PRE>
8718
8719<H3>See Also</H3>
8720
8721<A HREF="#ippTimeToDate"><CODE>ippTimeToDate()</CODE></A>
8722
8723
8724<!-- NEW PAGE --><H2><A NAME="ippDelete">ippDelete()</A></H2>
8725
8726<H3>Usage</H3>
8727
8728<PRE>
8729void
8730ippDelete(ipp_t *ipp);
8731</PRE>
8732
8733<H3>Arguments</H3>
8734
8735<CENTER><TABLE WIDTH="80%" BORDER>
8736<TR>
8737 <TH>Argument</TH>
8738 <TH>Description</TH>
8739</TR>
8740<TR>
8741 <TD>ipp</TD>
8742 <TD>The IPP request or response</TD>
8743</TR>
8744</TABLE></CENTER>
8745
8746<H3>Description</H3>
8747
8748<P>The <CODE>ippDelete()</CODE> function deletes all memory used by an IPP
8749request or response.
8750
8751<H3>Example</H3>
8752
8753<PRE>
8754#include &lt;cups/ipp.h>
8755
8756ipp_t *ipp;
8757
8758ippDelete(ipp);
8759</PRE>
8760
8761<H3>See Also</H3>
8762
8763<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8764
8765
8766<!-- NEW PAGE --><H2><A NAME="ippErrorString">ippErrorString()</A></H2>
8767
8768<H3>Usage</H3>
8769
8770<PRE>
8771const char *
8772ippErrorString(ipp_status_t error);
8773</PRE>
8774
8775<H3>Arguments</H3>
8776
8777<CENTER><TABLE WIDTH="80%" BORDER>
8778<TR>
8779 <TH>Argument</TH>
8780 <TH>Description</TH>
8781</TR>
8782<TR>
8783 <TD>error</TD>
8784 <TD>IPP error code.</TD>
8785</TR>
8786</TABLE></CENTER>
8787
8788<H3>Returns</H3>
8789
8790<P>The standard text representation of the IPP error code.
8791
8792<H3>Description</H3>
8793
8794<P><CODE>ippErrorString()</CODE> returns the standard text representation
8795of the IPP error code.
8796
8797<H3>Example</H3>
8798
8799<PRE>
8800#include &lt;cups/ipp.h&gt;
8801
8802puts(ippErrorString(IPP_OK));
8803</PRE>
8804
8805<H3>See Also</H3>
8806
8807<P>
8808<A HREF="#cupsLastError"><CODE>cupsLastError()</CODE></A>
8809
8810
8811<!-- NEW PAGE --><H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2>
8812
8813<H3>Usage</H3>
8814
8815<PRE>
8816ipp_attribute_t *
8817ippFindAttribute(ipp_t *ipp,
8818 const char *name,
8819 ipp_tag_t tag);
8820</PRE>
8821
8822<H3>Arguments</H3>
8823
8824<CENTER><TABLE WIDTH="80%" BORDER>
8825<TR>
8826 <TH>Argument</TH>
8827 <TH>Description</TH>
8828</TR>
8829<TR>
8830 <TD>ipp</TD>
8831 <TD>The IPP request or response</TD>
8832</TR>
8833<TR>
8834 <TD>name</TD>
8835 <TD>The name of the attribute</TD>
8836</TR>
8837<TR>
8838 <TD>tag</TD>
8839 <TD>The required value tag for the attribute or
8840 <CODE>IPP_TAG_ZERO</CODE> for any type of value.</TD>
8841</TR>
8842</TABLE></CENTER>
8843
8844<H3>Returns</H3>
8845
8846<P>A pointer to the first occurrence of the requested attribute, or
8847<CODE>NULL</CODE> if it was not found.
8848
8849<H3>Description</H3>
8850
8851<P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the named
8852attribute. The <CODE>tag</CODE> parameter restricts the search to a specific
8853value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.
8854
8855<P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
8856match the name/text values with or without the language code.
8857
8858<H3>Example</H3>
8859
8860<PRE>
8861<A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr;
8862
8863attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8864while (attr != NULL)
8865{
8866 puts(attr->values[0].string.text);
8867
8868 attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8869}
8870</PRE>
8871
8872<H3>See Also</H3>
8873
8874<A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>,
8875<A HREF="#cupsDoRequest"><CODE>cupsDoRequest()</CODE></A>,
8876<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
8877<A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE></A>,
8878<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8879
8880
8881<!-- NEW PAGE --><H2><A NAME="ippFindNextAttribute">ippFindNextAttribute()</A></H2>
8882
8883<H3>Usage</H3>
8884
8885<PRE>
8886ipp_attribute_t *
8887ippFindNextAttribute(ipp_t *ipp,
8888 const char *name,
8889 ipp_tag_t tag);
8890</PRE>
8891
8892<H3>Arguments</H3>
8893
8894<CENTER><TABLE WIDTH="80%" BORDER>
8895<TR>
8896 <TH>Argument</TH>
8897 <TH>Description</TH>
8898</TR>
8899<TR>
8900 <TD>ipp</TD>
8901 <TD>The IPP request or response</TD>
8902</TR>
8903<TR>
8904 <TD>name</TD>
8905 <TD>The name of the attribute</TD>
8906</TR>
8907<TR>
8908 <TD>tag</TD>
8909 <TD>The required value tag for the attribute or
8910 <CODE>IPP_TAG_ZERO</CODE> for any type of value.</TD>
8911</TR>
8912</TABLE></CENTER>
8913
8914<H3>Returns</H3>
8915
8916<P>A pointer to the next occurrence of the requested attribute, or
8917<CODE>NULL</CODE> if it was not found.
8918
8919<H3>Description</H3>
8920
8921<P><CODE>ippFindNextAttribute()</CODE> finds the next occurrence of the named
8922attribute. The <CODE>tag</CODE> parameter restricts the search to a specific
8923value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name.
8924
8925<P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
8926match the name/text values with or without the language code.
8927
8928<H3>Example</H3>
8929
8930<PRE>
8931<A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr;
8932
8933attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8934while (attr != NULL)
8935{
8936 puts(attr->values[0].string.text);
8937
8938 attr = ippFindNextAttribute(response, "printer-state-message", IPP_TAG_TEXT);
8939}
8940</PRE>
8941
8942<H3>See Also</H3>
8943
8944<A HREF="#cupsDoFileRequest"><CODE>cupsDoFileRequest()</CODE></A>,
8945<A HREF="#cupsDoRequest"><CODE>cupsDoRequest()</CODE></A>,
8946<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
8947<A HREF="#ippFindNextAttribute"><CODE>ippFindNextAttribute()</CODE></A>,
8948<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8949
8950
8951<!-- NEW PAGE --><H2><A NAME="ippLength">ippLength()</A></H2>
8952
8953<H3>Usage</H3>
8954
8955<PRE>
8956int
8957ippLength(ipp_t *ipp);
8958</PRE>
8959
8960<H3>Arguments</H3>
8961
8962<CENTER><TABLE WIDTH="80%" BORDER>
8963<TR>
8964 <TH>Argument</TH>
8965 <TH>Description</TH>
8966</TR>
8967<TR>
8968 <TD>ipp</TD>
8969 <TD>The IPP request or response</TD>
8970</TR>
8971</TABLE></CENTER>
8972
8973<H3>Returns</H3>
8974
8975<P>The total encoded length of the IPP request or response in bytes.
8976
8977<H3>Description</H3>
8978
8979<P><CODE>ippLength()</CODE> returns the length of the IPP request or
8980response in bytes.
8981
8982<H3>Example</H3>
8983
8984<PRE>
8985printf("The length of the response is %d bytes.\n", ippLength(response));
8986</PRE>
8987
8988<H3>See Also</H3>
8989
8990<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>,
8991<A HREF="#ippNew"><CODE>ippNew()</CODE></A>
8992
8993
8994<!-- NEW PAGE --><H2><A NAME="ippNew">ippNew()</A></H2>
8995
8996<H3>Usage</H3>
8997
8998<PRE>
8999ipp_t *
9000ippNew(void);
9001</PRE>
9002
9003<H3>Returns</H3>
9004
9005<P>A pointer to a new IPP request or response.
9006
9007<H3>Description</H3>
9008
9009<P>The <CODE>ippNew()</CODE> function creates a new IPP request or response.
9010
9011<H3>Example</H3>
9012
9013<PRE>
9014#include &lt;cups/ipp.h>
9015
9016ipp_t *ipp;
9017
9018ipp = ippNew();
9019</PRE>
9020
9021<H3>See Also</H3>
9022
9023<A HREF="#ippDelete"><CODE>ippDelete()</CODE></A>
9024
9025
9026<!-- NEW PAGE --><H2><A NAME="ippPort">ippPort()</A></H2>
9027
9028<H3>Usage</H3>
9029
9030<PRE>
9031int
9032ippPort(void);
9033</PRE>
9034
9035<H3>Returns</H3>
9036
9037<P>The default TCP/IP port number for IPP requests.
9038
9039<H3>Description</H3>
9040
9041<P>The <CODE>ippPort()</CODE> function returns the default IPP port number
9042for requests.
9043
9044<H3>Example</H3>
9045
9046<PRE>
9047#include &lt;cups/http.h>
9048#include &lt;cups/ipp.h>
9049
9050http_t *http;
9051
9052http = httpConnect(cupsServer(), ippPort());
9053</PRE>
9054
9055<H3>See Also</H3>
9056
9057<A HREF="#cupsServer"><CODE>cupsServer()</CODE></A>,
9058<A HREF="#ippSetPort"><CODE>ippSetPort()</CODE></A>
9059
9060
9061<!-- NEW PAGE --><H2><A NAME="ippRead">ippRead()</A></H2>
9062
9063<H3>Usage</H3>
9064
9065<PRE>
9066ipp_state_t
9067ippRead(http_t *http,
9068 ipp_t *ipp);
9069</PRE>
9070
9071<H3>Arguments</H3>
9072
9073<CENTER><TABLE WIDTH="80%" BORDER>
9074<TR>
9075 <TH>Argument</TH>
9076 <TH>Description</TH>
9077</TR>
9078<TR>
9079 <TD>http</TD>
9080 <TD>The HTTP connection</TD>
9081</TR>
9082<TR>
9083 <TD>ipp</TD>
9084 <TD>The IPP request or response</TD>
9085</TR>
9086</TABLE></CENTER>
9087
9088<H3>Returns</H3>
9089
9090<P>The current read state.
9091
9092<H3>Description</H3>
9093
9094<P>The <CODE>ippRead()</CODE> function reads IPP attributes from the specified
9095HTTP connection. Programs should continue calling <CODE>ippRead()</CODE> until
9096<CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
9097
9098<H3>Example</H3>
9099
9100<PRE>
9101#include &lt;cups/http.h>
9102#include &lt;cups/ipp.h>
9103
9104http_t *http;
9105ipp_t *ipp;
9106ipp_state_t status;
9107
9108ipp = ippNew();
9109
9110while ((status = ippRead(http, ipp)) != IPP_ERROR)
9111 if (status == IPP_DATA)
9112 break;
9113
9114if (status == IPP_DATA)
9115{
9116 ... read additional non-IPP data using httpRead() ...
9117}
9118</PRE>
9119
9120<H3>See Also</H3>
9121
9122<A HREF="#ippWrite"><CODE>ippWrite()</CODE></A>
9123
9124
9125<!-- NEW PAGE --><H2><A NAME="ippSetPort">ippSetPort()</A></H2>
9126
9127<H3>Usage</H3>
9128
9129<PRE>
9130void
9131ippSetPort(int port);
9132</PRE>
9133
9134<H3>Arguments</H3>
9135
9136<CENTER><TABLE WIDTH="80%" BORDER>
9137<TR>
9138 <TH>Argument</TH>
9139 <TH>Description</TH>
9140</TR>
9141<TR>
9142 <TD>port</TD>
9143 <TD>The port number to use</TD>
9144</TR>
9145</TABLE></CENTER>
9146
9147<H3>Description</H3>
9148
9149<P>The <CODE>ippSetPort()</CODE> function sets the default IPP port number
9150for requests.
9151
9152<H3>Example</H3>
9153
9154<PRE>
9155#include &lt;cups/http.h>
9156#include &lt;cups/ipp.h>
9157
9158...
9159
9160ippSetPort(8631);
9161</PRE>
9162
9163<H3>See Also</H3>
9164
9165<A HREF="#ippPort"><CODE>ippPort()</CODE></A>
9166
9167
9168<!-- NEW PAGE --><H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2>
9169
9170<H3>Usage</H3>
9171
9172<PRE>
9173ipp_uchar_t *
9174ippTimeToDate(time_t time);
9175</PRE>
9176
9177<H3>Arguments</H3>
9178
9179<CENTER><TABLE WIDTH="80%" BORDER>
9180<TR>
9181 <TH>Argument</TH>
9182 <TH>Description</TH>
9183</TR>
9184<TR>
9185 <TD>time</TD>
9186 <TD>The UNIX time value</TD>
9187</TR>
9188</TABLE></CENTER>
9189
9190<H3>Returns</H3>
9191
9192<P>A static pointer to an IPP date-time value.
9193
9194<H3>Description</H3>
9195
9196<P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an IPP
9197date-time value.
9198
9199<H3>Example</H3>
9200
9201<PRE>
9202#include &lt;cups/ipp.h>
9203
9204ipp_uchar_t *date;
9205
9206date = ippTimeToDate(time(NULL));
9207</PRE>
9208
9209<H3>See Also</H3>
9210
9211<A HREF="#ippDateToTime"><CODE>ippDateToTime()</CODE></A>
9212
9213
9214<!-- NEW PAGE --><H2><A NAME="ippWrite">ippWrite()</A></H2>
9215
9216<H3>Usage</H3>
9217
9218<PRE>
9219ipp_state_t
9220ippWrite(http_t *http,
9221 ipp_t *ipp);
9222</PRE>
9223
9224<H3>Arguments</H3>
9225
9226<CENTER><TABLE WIDTH="80%" BORDER>
9227<TR>
9228 <TH>Argument</TH>
9229 <TH>Description</TH>
9230</TR>
9231<TR>
9232 <TD>http</TD>
9233 <TD>The HTTP connection</TD>
9234</TR>
9235<TR>
9236 <TD>ipp</TD>
9237 <TD>The IPP request or response</TD>
9238</TR>
9239</TABLE></CENTER>
9240
9241<H3>Returns</H3>
9242
9243<P>The current write state.
9244
9245<H3>Description</H3>
9246
9247<P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the specified
9248HTTP connection. Programs should continue calling <CODE>ippWrite()</CODE> until
9249<CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE> is returned.
9250
9251<H3>Example</H3>
9252
9253<PRE>
9254#include &lt;cups/http.h>
9255#include &lt;cups/ipp.h>
9256
9257http_t *http;
9258ipp_t *ipp;
9259ipp_state_t status;
9260
9261ipp = ippNew();
9262... add attributes ...
9263
9264while ((status = ippWrite(http, ipp)) != IPP_ERROR)
9265 if (status == IPP_DATA)
9266 break;
9267
9268if (status == IPP_DATA)
9269{
9270 ... read additional non-IPP data using httpWrite() ...
9271}
9272</PRE>
9273
9274<H3>See Also</H3>
9275
9276<A HREF="#ippRead"><CODE>ippRead()</CODE></A>
9277
9278
9279<!-- NEW PAGE --><H2><A NAME="ppdClose">ppdClose()</A></H2>
9280
9281<H3>Usage</H3>
9282
9283<PRE>
9284void
9285ppdClose(ppd_file_t *ppd);
9286</PRE>
9287
9288<H3>Arguments</H3>
9289
9290<CENTER><TABLE WIDTH="80%" BORDER>
9291<TR>
9292 <TH>Argument</TH>
9293 <TH>Description</TH>
9294</TR>
9295<TR>
9296 <TD>ppd</TD>
9297 <TD>The PPD file</TD>
9298</TR>
9299</TABLE></CENTER>
9300
9301<H3>Description</H3>
9302
9303<P>The <CODE>ppdClose()</CODE> function frees all memory associated with the
9304PPD file.
9305
9306<H3>Example</H3>
9307
9308<PRE>
9309#include &lt;cups/ppd.h>
9310
9311ppd_file_t *ppd;
9312
9313ppdClose(ppd);
9314</PRE>
9315
9316<H3>See Also</H3>
9317
9318<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
9319<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
9320<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
9321
9322
9323<!-- NEW PAGE --><H2><A NAME="ppdCollect">ppdCollect()</A></H2>
9324
9325<H3>Usage</H3>
9326
9327<PRE>
9328int
9329ppdCollect(ppd_file_t *ppd,
9330 ppd_section_t section,
9331 ppd_choice_t ***choices);
9332</PRE>
9333
9334<H3>Arguments</H3>
9335
9336<CENTER><TABLE WIDTH="80%" BORDER>
9337<TR>
9338 <TH>Argument</TH>
9339 <TH>Description</TH>
9340</TR>
9341<TR>
9342 <TD>ppd</TD>
9343 <TD>The PPD file.</TD>
9344</TR>
9345<TR>
9346 <TD>section</TD>
9347 <TD>The document section to collect.</TD>
9348</TR>
9349<TR>
9350 <TD>choices</TD>
9351 <TD>The array of option choices that are marked.</TD>
9352</TR>
9353</TABLE></CENTER>
9354
9355<H3>Returns</H3>
9356
9357<P>The number of options collected.
9358
9359<H3>Description</H3>
9360
9361<P><CODE>ppdCollect()</CODE> collects all of the marked options in the
9362specified section, sorts them by their order dependency values, and
9363returns an array that can be used to emit option commands in the proper
9364order. It is normally used by the <CODE>ppdEmit*()</CODE> functions.
9365
9366<H3>Example</H3>
9367
9368<PRE>
9369#include &lt;cups/ppd.h&gt;
9370
9371<A HREF="#ppd_file_t">ppd_file_t</A> *ppd;
9372int num_choices;
9373<A HREF="#ppd_choice_t">ppd_choice_t</A> **choices;
9374
9375...
9376
9377num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &amp;choices);
9378</PRE>
9379
9380<H3>See Also</H3>
9381
9382<P>
9383<A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>,
9384<A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A>,
9385<A HREF="#ppdEmitJCL"><CODE>ppdEmitJCL()</CODE></A>
9386
9387
9388<!-- NEW PAGE --><H2><A NAME="ppdConflicts">ppdConflicts()</A></H2>
9389
9390<H3>Usage</H3>
9391
9392<PRE>
9393int
9394ppdConflicts(ppd_file_t *ppd);
9395</PRE>
9396
9397<H3>Arguments</H3>
9398
9399<CENTER><TABLE WIDTH="80%" BORDER>
9400<TR>
9401 <TH>Argument</TH>
9402 <TH>Description</TH>
9403</TR>
9404<TR>
9405 <TD>ppd</TD>
9406 <TD>The PPD file</TD>
9407</TR>
9408</TABLE></CENTER>
9409
9410<H3>Returns</H3>
9411
9412<P>The number of option conflicts in the file.
9413
9414<H3>Description</H3>
9415
9416<P>The <CODE>ppdConflicts()</CODE> function returns the number of conflicts
9417with the currently selected options.
9418
9419<H3>Example</H3>
9420
9421<PRE>
9422#include &lt;cups/ppd.h>
9423
9424ppd_file_t *ppd;
9425
9426printf("%d conflicts\n", ppdConflicts(ppd));
9427</PRE>
9428
9429<H3>See Also</H3>
9430
9431<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9432<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9433<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9434<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9435
9436
9437<!-- NEW PAGE --><H2><A NAME="ppdEmit">ppdEmit()</A></H2>
9438
9439<H3>Usage</H3>
9440
9441<PRE>
9442int
9443ppdEmit(ppd_file_t *ppd,
9444 FILE *file,
9445 ppd_section_t section);
9446</PRE>
9447
9448<H3>Arguments</H3>
9449
9450<CENTER><TABLE WIDTH="80%" BORDER>
9451<TR>
9452 <TH>Argument</TH>
9453 <TH>Description</TH>
9454</TR>
9455<TR>
9456 <TD>ppd</TD>
9457 <TD>The PPD file</TD>
9458</TR>
9459<TR>
9460 <TD>file</TD>
9461 <TD>The file to write to</TD>
9462</TR>
9463<TR>
9464 <TD>section</TD>
9465 <TD>The option section to write</TD>
9466</TR>
9467</TABLE></CENTER>
9468
9469<H3>Returns</H3>
9470
9471<P>0 on success, -1 on error.
9472
9473<H3>Description</H3>
9474
9475<P>The <CODE>ppdEmit()</CODE> function sends printer-specific option
9476commands to the specified file.
9477
9478<H3>Example</H3>
9479
9480<PRE>
9481#include &lt;cups/ppd.h>
9482
9483ppd_file_t *ppd;
9484
9485ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
9486</PRE>
9487
9488<H3>See Also</H3>
9489
9490<A HREF="#ppdEmitFd"><CODE>ppdEmitFd()</CODE></A>
9491
9492
9493<!-- NEW PAGE --><H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2>
9494
9495<H3>Usage</H3>
9496
9497<PRE>
9498int
9499ppdEmitFd(ppd_file_t *ppd,
9500 int fd,
9501 ppd_section_t section);
9502</PRE>
9503
9504<H3>Arguments</H3>
9505
9506<CENTER><TABLE WIDTH="80%" BORDER>
9507<TR>
9508 <TH>Argument</TH>
9509 <TH>Description</TH>
9510</TR>
9511<TR>
9512 <TD>ppd</TD>
9513 <TD>The PPD file</TD>
9514</TR>
9515<TR>
9516 <TD>fd</TD>
9517 <TD>The file descriptor to write to</TD>
9518</TR>
9519<TR>
9520 <TD>section</TD>
9521 <TD>The option section to write</TD>
9522</TR>
9523</TABLE></CENTER>
9524
9525<H3>Returns</H3>
9526
9527<P>0 on success, -1 on error.
9528
9529<H3>Description</H3>
9530
9531<P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option
9532commands to the specified file descriptor.
9533
9534<H3>Example</H3>
9535
9536<PRE>
9537#include &lt;cups/ppd.h>
9538
9539ppd_file_t *ppd;
9540
9541ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
9542</PRE>
9543
9544<H3>See Also</H3>
9545
9546<A HREF="#ppdEmit"><CODE>ppdEmit()</CODE></A>
9547
9548
9549<!-- NEW PAGE --><H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2>
9550
9551<H3>Usage</H3>
9552
9553<PRE>
9554ppd_choice_t *
9555ppdFindChoice(ppd_option_t *option,
9556 const char *choice);
9557</PRE>
9558
9559<H3>Arguments</H3>
9560
9561<CENTER><TABLE WIDTH="80%" BORDER>
9562<TR>
9563 <TH>Argument</TH>
9564 <TH>Description</TH>
9565</TR>
9566<TR>
9567 <TD>option</TD>
9568 <TD>A pointer to the option</TD>
9569</TR>
9570<TR>
9571 <TD>choice</TD>
9572 <TD>The name of the choice</TD>
9573</TR>
9574</TABLE></CENTER>
9575
9576<H3>Returns</H3>
9577
9578<P>A pointer to the choice data or NULL if the choice does not exist.
9579
9580<H3>Description</H3>
9581
9582<P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the choice
9583data for the specified option.
9584
9585<H3>Example</H3>
9586
9587<PRE>
9588#include &lt;cups/ppd.h>
9589
9590ppd_file_t *ppd;
9591ppd_option_t *option;
9592ppd_choice_t *choice;
9593
9594option = ppdFindOption(ppd, "PageSize");
9595choice = ppdFindChoice(option, "Letter");
9596</PRE>
9597
9598<H3>See Also</H3>
9599
9600<A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>,
9601<A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
9602
9603
9604<!-- NEW PAGE --><H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2>
9605
9606<H3>Usage</H3>
9607
9608<PRE>
9609ppd_choice_t *
9610ppdFindMarkedChoice(ppd_file_t *ppd,
9611 const char *keyword);
9612</PRE>
9613
9614<H3>Arguments</H3>
9615
9616<CENTER><TABLE WIDTH="80%" BORDER>
9617<TR>
9618 <TH>Argument</TH>
9619 <TH>Description</TH>
9620</TR>
9621<TR>
9622 <TD>ppd</TD>
9623 <TD>The PPD file</TD>
9624</TR>
9625<TR>
9626 <TD>keyword</TD>
9627 <TD>The name of the option</TD>
9628</TR>
9629</TABLE></CENTER>
9630
9631<H3>Returns</H3>
9632
9633<P>A pointer to the choice data or NULL if the choice does not exist or
9634is not marked.
9635
9636<H3>Description</H3>
9637
9638<P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to
9639the marked choice data for the specified option.
9640
9641<H3>Example</H3>
9642
9643<PRE>
9644#include &lt;cups/ppd.h>
9645
9646ppd_file_t *ppd;
9647ppd_choice_t *choice;
9648
9649choice = ppdFindMarkedChoice(ppd, "PageSize");
9650</PRE>
9651
9652<H3>See Also</H3>
9653
9654<A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
9655<A HREF="#ppdFindOption"><CODE>ppdFindOption()</CODE></A>
9656
9657
9658<!-- NEW PAGE --><H2><A NAME="ppdFindOption">ppdFindOption()</A></H2>
9659
9660<H3>Usage</H3>
9661
9662<PRE>
9663ppd_option_t *
9664ppdFindOption(ppd_file_t *ppd,
9665 const char *keyword);
9666</PRE>
9667
9668<H3>Arguments</H3>
9669
9670<CENTER><TABLE WIDTH="80%" BORDER>
9671<TR>
9672 <TH>Argument</TH>
9673 <TH>Description</TH>
9674</TR>
9675<TR>
9676 <TD>ppd</TD>
9677 <TD>The PPD file</TD>
9678</TR>
9679<TR>
9680 <TD>keyword</TD>
9681 <TD>The name of the option</TD>
9682</TR>
9683</TABLE></CENTER>
9684
9685<H3>Returns</H3>
9686
9687<P>A pointer to the option data or NULL if the option does not exist.
9688
9689<H3>Description</H3>
9690
9691<P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the option
9692data for the specified option.
9693
9694<H3>Example</H3>
9695
9696<PRE>
9697#include &lt;cups/ppd.h>
9698
9699ppd_file_t *ppd;
9700ppd_option_t *option;
9701
9702option = ppdFindOption(ppd, "PageSize");
9703</PRE>
9704
9705<H3>See Also</H3>
9706
9707<A HREF="#ppdFindChoice"><CODE>ppdFindChoice()</CODE></A>,
9708<A HREF="#ppdFindMarkedChoice"><CODE>ppdFindMarkedChoice()</CODE></A>
9709
9710
9711<!-- NEW PAGE --><H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2>
9712
9713<H3>Usage</H3>
9714
9715<PRE>
9716int
9717ppdIsMarked(ppd_file_t *ppd,
9718 const char *keyword,
9719 const char *choice);
9720</PRE>
9721
9722<H3>Arguments</H3>
9723
9724<CENTER><TABLE WIDTH="80%" BORDER>
9725<TR>
9726 <TH>Argument</TH>
9727 <TH>Description</TH>
9728</TR>
9729<TR>
9730 <TD>ppd</TD>
9731 <TD>The PPD file</TD>
9732</TR>
9733<TR>
9734 <TD>keyword</TD>
9735 <TD>The name of the option</TD>
9736</TR>
9737<TR>
9738 <TD>choice</TD>
9739 <TD>The name of the option choice</TD>
9740</TR>
9741</TABLE></CENTER>
9742
9743<H3>Returns</H3>
9744
9745<P>1 if the choice is marked, 0 otherwise.
9746
9747<H3>Description</H3>
9748
9749<P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the
9750specified option choice is marked.
9751
9752<H3>Example</H3>
9753
9754<PRE>
9755#include &lt;cups/ppd.h>
9756
9757ppd_file_t *ppd;
9758
9759printf("Letter size %s selected.\n",
9760 ppdIsMarked(ppd, "PageSize", "Letter") ? "is" : "is not");
9761</PRE>
9762
9763<H3>See Also</H3>
9764
9765<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9766<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
9767<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9768<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9769<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9770
9771
9772<!-- NEW PAGE --><H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2>
9773
9774<H3>Usage</H3>
9775
9776<PRE>
9777void
9778ppdMarkDefaults(ppd_file_t *ppd);
9779</PRE>
9780
9781<H3>Arguments</H3>
9782
9783<CENTER><TABLE WIDTH="80%" BORDER>
9784<TR>
9785 <TH>Argument</TH>
9786 <TH>Description</TH>
9787</TR>
9788<TR>
9789 <TD>ppd</TD>
9790 <TD>The PPD file</TD>
9791</TR>
9792</TABLE></CENTER>
9793
9794<H3>Description</H3>
9795
9796<P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default
9797choices in the PPD file.
9798
9799<H3>Example</H3>
9800
9801<PRE>
9802#include &lt;cups/ppd.h>
9803
9804ppd_file_t *ppd;
9805
9806ppdMarkDefaults(ppd);
9807</PRE>
9808
9809<H3>See Also</H3>
9810
9811<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9812<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
9813<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9814<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9815<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9816
9817
9818<!-- NEW PAGE --><H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2>
9819
9820<H3>Usage</H3>
9821
9822<PRE>
9823int
9824ppdMarkOption(ppd_file_t *ppd,
9825 const char *keyword,
9826 const char *choice);
9827</PRE>
9828
9829<H3>Arguments</H3>
9830
9831<CENTER><TABLE WIDTH="80%" BORDER>
9832<TR>
9833 <TH>Argument</TH>
9834 <TH>Description</TH>
9835</TR>
9836<TR>
9837 <TD>ppd</TD>
9838 <TD>The PPD file</TD>
9839</TR>
9840<TR>
9841 <TD>keyword</TD>
9842 <TD>The name of the option</TD>
9843</TR>
9844<TR>
9845 <TD>choice</TD>
9846 <TD>The name of the choice</TD>
9847</TR>
9848</TABLE></CENTER>
9849
9850<H3>Returns</H3>
9851
9852<P>The number of conflicts in the PPD file.
9853
9854<H3>Description</H3>
9855
9856<P>The <CODE>ppdMarkOption()</CODE> function marks the specified option
9857choice.
9858
9859<H3>Example</H3>
9860
9861<PRE>
9862#include &lt;cups/ppd.h>
9863
9864ppd_file_t *ppd;
9865
9866ppdMarkOption(ppd, "PageSize", "Letter");
9867</PRE>
9868
9869<H3>See Also</H3>
9870
9871<A HREF="#cupsMarkOptions"><CODE>cupsMarkOptions()</CODE></A>,
9872<A HREF="#ppdConflicts"><CODE>ppdConflicts()</CODE></A>,
9873<A HREF="#ppdIsMarked"><CODE>ppdIsMarked()</CODE></A>,
9874<A HREF="#ppdMarkDefaults"><CODE>ppdMarkDefaults()</CODE></A>,
9875<A HREF="#ppdMarkOption"><CODE>ppdMarkOption()</CODE></A>
9876
9877
9878<!-- NEW PAGE --><H2><A NAME="ppdOpen">ppdOpen()</A></H2>
9879
9880<H3>Usage</H3>
9881
9882<PRE>
9883ppd_file_t *
9884ppdOpen(FILE *file);
9885</PRE>
9886
9887<H3>Arguments</H3>
9888
9889<CENTER><TABLE WIDTH="80%" BORDER>
9890<TR>
9891 <TH>Argument</TH>
9892 <TH>Description</TH>
9893</TR>
9894<TR>
9895 <TD>file</TD>
9896 <TD>The file to read from</TD>
9897</TR>
9898</TABLE></CENTER>
9899
9900<H3>Returns</H3>
9901
9902<P>A pointer to a PPD file structure or NULL if the PPD file could not be
9903read.
9904
9905<H3>Description</H3>
9906
9907<P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the specified
9908file into memory.
9909
9910<H3>Example</H3>
9911
9912<PRE>
9913#include &lt;cups/ppd.h>
9914
9915ppd_file_t *ppd;
9916FILE *file;
9917
9918file = fopen("filename.ppd", "rb");
9919ppd = ppdOpen(file);
9920fclose(file);
9921</PRE>
9922
9923<H3>See Also</H3>
9924
9925<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
9926<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>,
9927<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
9928
9929
9930<!-- NEW PAGE --><H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2>
9931
9932<H3>Usage</H3>
9933
9934<PRE>
9935ppd_file_t *
9936ppdOpenFd(int fd);
9937</PRE>
9938
9939<H3>Arguments</H3>
9940
9941<CENTER><TABLE WIDTH="80%" BORDER>
9942<TR>
9943 <TH>Argument</TH>
9944 <TH>Description</TH>
9945</TR>
9946<TR>
9947 <TD>fd</TD>
9948 <TD>The file descriptor to read from</TD>
9949</TR>
9950</TABLE></CENTER>
9951
9952<H3>Returns</H3>
9953
9954<P>A pointer to a PPD file structure or NULL if the PPD file could not be
9955read.
9956
9957<H3>Description</H3>
9958
9959<P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the specified
9960file descriptor into memory.
9961
9962<H3>Example</H3>
9963
9964<PRE>
9965#include &lt;cups/ppd.h>
9966
9967ppd_file_t *ppd;
9968int fd;
9969
9970fd = open("filename.ppd", O_RDONLY);
9971ppd = ppdOpenFd(fd);
9972close(fd);
9973</PRE>
9974
9975<H3>See Also</H3>
9976
9977<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
9978<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
9979<A HREF="#ppdOpenFile"><CODE>ppdOpenFile()</CODE></A>
9980
9981
9982<!-- NEW PAGE --><H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2>
9983
9984<H3>Usage</H3>
9985
9986<PRE>
9987ppd_file_t *
9988ppdOpenFile(const char *filename);
9989</PRE>
9990
9991<H3>Arguments</H3>
9992
9993<CENTER><TABLE WIDTH="80%" BORDER>
9994<TR>
9995 <TH>Argument</TH>
9996 <TH>Description</TH>
9997</TR>
9998<TR>
9999 <TD>filename</TD>
10000 <TD>The name of the file to read from</TD>
10001</TR>
10002</TABLE></CENTER>
10003
10004<H3>Returns</H3>
10005
10006<P>A pointer to a PPD file structure or NULL if the PPD file could not be
10007read.
10008
10009<H3>Description</H3>
10010
10011<P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the named
10012file into memory.
10013
10014<H3>Example</H3>
10015
10016<PRE>
10017#include &lt;cups/ppd.h>
10018
10019ppd_file_t *ppd;
10020
10021ppd = ppdOpenFile("filename.ppd");
10022</PRE>
10023
10024<H3>See Also</H3>
10025
10026<A HREF="#ppdClose"><CODE>ppdClose()</CODE></A>,
10027<A HREF="#ppdOpen"><CODE>ppdOpen()</CODE></A>,
10028<A HREF="#ppdOpenFd"><CODE>ppdOpenFd()</CODE></A>
10029
10030
10031<!-- NEW PAGE --><H2><A NAME="ppdPageLength">ppdPageLength()</A></H2>
10032
10033<H3>Usage</H3>
10034
10035<PRE>
10036float
10037ppdPageLength(ppd_file_t *ppd,
10038 const char *name);
10039</PRE>
10040
10041<H3>Arguments</H3>
10042
10043<CENTER><TABLE WIDTH="80%" BORDER>
10044<TR>
10045 <TH>Argument</TH>
10046 <TH>Description</TH>
10047</TR>
10048<TR>
10049 <TD>ppd</TD>
10050 <TD>The PPD file</TD>
10051</TR>
10052<TR>
10053 <TD>name</TD>
10054 <TD>The name of the page size</TD>
10055</TR>
10056</TABLE></CENTER>
10057
10058<H3>Returns</H3>
10059
10060<P>The length of the specified page size in points or 0 if the page size
10061does not exist.
10062
10063<H3>Description</H3>
10064
10065<P>The <CODE>ppdPageLength()</CODE> function returns the page length of the
10066specified page size.
10067
10068<H3>Example</H3>
10069
10070<PRE>
10071#include &lt;cups/ppd.h>
10072
10073ppd_file_t *ppd;
10074
10075printf("Length = %.0f\n", ppdPageLength(ppd, "Letter"));
10076</PRE>
10077
10078<H3>See Also</H3>
10079
10080<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
10081<A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>,
10082<A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
10083
10084
10085<!-- NEW PAGE --><H2><A NAME="ppdPageSize">ppdPageSize()</A></H2>
10086
10087<H3>Usage</H3>
10088
10089<PRE>
10090ppd_size_t *
10091ppdPageSize(ppd_file_t *ppd,
10092 const char *name);
10093</PRE>
10094
10095<H3>Arguments</H3>
10096
10097<CENTER><TABLE WIDTH="80%" BORDER>
10098<TR>
10099 <TH>Argument</TH>
10100 <TH>Description</TH>
10101</TR>
10102<TR>
10103 <TD>ppd</TD>
10104 <TD>The PPD file</TD>
10105</TR>
10106<TR>
10107 <TD>name</TD>
10108 <TD>The name of the page size</TD>
10109</TR>
10110</TABLE></CENTER>
10111
10112<H3>Returns</H3>
10113
10114<P>A pointer to the page size record of the specified page size in
10115points or NULL if the page size does not exist.
10116
10117<H3>Description</H3>
10118
10119<P>The <CODE>ppdPageSize()</CODE> function returns the page size record for the
10120specified page size.
10121
10122<H3>Example</H3>
10123
10124<PRE>
10125#include &lt;cups/ppd.h>
10126
10127ppd_file_t *ppd;
10128ppd_size_t *size;
10129
10130size = ppdPageSize(ppd, "Letter");
10131if (size != NULL)
10132{
10133 printf(" Width = %.0f\n", size->width);
10134 printf("Length = %.0f\n", size->length);
10135 printf(" Left = %.0f\n", size->left);
10136 printf(" Right = %.0f\n", size->right);
10137 printf("Bottom = %.0f\n", size->bottom);
10138 printf(" Top = %.0f\n", size->top);
10139}
10140</PRE>
10141
10142<H3>See Also</H3>
10143
10144<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
10145<A HREF="#ppdPageWidth"><CODE>ppdPageWidth()</CODE></A>
10146
10147
10148<!-- NEW PAGE --><H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2>
10149
10150<H3>Usage</H3>
10151
10152<PRE>
10153float
10154ppdPageWidth(ppd_file_t *ppd,
10155 const char *name);
10156</PRE>
10157
10158<H3>Arguments</H3>
10159
10160<CENTER><TABLE WIDTH="80%" BORDER>
10161<TR>
10162 <TH>Argument</TH>
10163 <TH>Description</TH>
10164</TR>
10165<TR>
10166 <TD>ppd</TD>
10167 <TD>The PPD file</TD>
10168</TR>
10169<TR>
10170 <TD>name</TD>
10171 <TD>The name of the page size</TD>
10172</TR>
10173</TABLE></CENTER>
10174
10175<H3>Returns</H3>
10176
10177<P>The width of the specified page size in points or 0 if the page size
10178does not exist.
10179
10180<H3>Description</H3>
10181
10182<P>The <CODE>ppdPageWidth()</CODE> function returns the page width of the
10183specified page size.
10184
10185<H3>Example</H3>
10186
10187<PRE>
10188#include &lt;cups/ppd.h>
10189
10190ppd_file_t *ppd;
10191
10192printf("Width = %.0f\n", ppdPageWidth(ppd, "Letter"));
10193</PRE>
10194
10195<H3>See Also</H3>
10196
10197<A HREF="#ppdPageLength"><CODE>ppdPageLength()</CODE></A>,
10198<A HREF="#ppdPageSize"><CODE>ppdPageSize()</CODE></A>
10199
10200
10201</BODY>
10202</HTML>
Unnamed repository; edit this file 'description' to name the repository.