]>
Commit | Line | Data |
---|---|---|
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 | |
13 | programming 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 | |
38 | their meanings and uses are explained below: | |
39 | ||
40 | <CENTER><TABLE WIDTH="80%"> | |
41 | <TR> | |
42 | <TH>Example</TH> | |
43 | <TD> </TD> | |
44 | <TH>Description</TH> | |
45 | </TR> | |
46 | <TR><TD> </TD></TR> | |
47 | <TR VALIGN="TOP"> | |
48 | <TD><CODE>lpstat</CODE><BR> | |
49 | <CODE>lpstat(1)</CODE></TD> | |
50 | ||
51 | <TD> </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> </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> </TD> | |
63 | ||
64 | <TD>File and directory names.</TD> | |
65 | </TR> | |
66 | <TR><TD> </TD></TR> | |
67 | <TR VALIGN="TOP"> | |
68 | <TD NOWRAP><TT>Request ID is Printer-123</TT></TD> | |
69 | ||
70 | <TD> </TD> | |
71 | ||
72 | <TD>Screen output.</TD> | |
73 | </TR> | |
74 | <TR><TD> </TD></TR> | |
75 | <TR VALIGN="TOP"> | |
76 | <TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD> | |
77 | ||
78 | <TD> </TD> | |
79 | ||
80 | <TD>Literal user input; special keys like <KBD>ENTER</KBD> are | |
81 | in ALL CAPS.</TD> | |
82 | </TR> | |
83 | <TR><TD> </TD></TR> | |
84 | <TR VALIGN="TOP"> | |
85 | <TD>12.3</TD> | |
86 | ||
87 | <TD> </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 | ||
97 | The following abbreviations are used throughout this manual: | |
98 | ||
99 | <UL> | |
100 | <DL> | |
101 | ||
102 | <DT>kb | |
103 | <DD>Kilobytes, or 1024 bytes<BR> | |
104 | ||
105 | <DT>Mb | |
106 | <DD>Megabytes, or 1048576 bytes<BR> | |
107 | ||
108 | <DT>Gb | |
109 | <DD>Gigabytes, or 1073741824 bytes<BR> | |
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> | |
122 | ||
123 | <DT>CUPS Software Users Manual | |
124 | ||
125 | <DD>An end-user guide for using the CUPS software.<BR> | |
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 | |
141 | support the internal needs of the CUPS software as well as the needs of | |
142 | applications, filters, printer drivers, and backends. | |
143 | ||
144 | <P>Unlike the rest of CUPS, the CUPS API library is provided under the | |
145 | GNU Library General Public License. This means that you can use the | |
146 | CUPS API library in both proprietary and open-source programs. | |
147 | ||
148 | <P>Programs that use the CUPS API library typically will include the | |
149 | <CODE><cups/cups.h></CODE> header file: | |
150 | ||
151 | <UL><PRE> | |
152 | #include <cups/cups.h> | |
153 | ||
154 | ... | |
155 | ||
156 | jobid = 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 | |
161 | library: | |
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 | |
168 | operating 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. | |
173 | Add the following lines to your <VAR>configure.in</VAR> file to check | |
174 | for the CUPS API library in your configuration script: | |
175 | ||
176 | <UL><PRE> | |
177 | AC_CHECK_LIB(socket,socket, | |
178 | if test "$uname" != "IRIX"; then | |
179 | LIBS="-lsocket $LIBS" | |
180 | else | |
181 | echo "Not using -lsocket since you are running IRIX." | |
182 | fi) | |
183 | AC_CHECK_LIB(nsl,gethostbyaddr, | |
184 | if test "$uname" != "IRIX"; then | |
185 | LIBS="-lnsl $LIBS" | |
186 | else | |
187 | echo "Not using -lnsl since you are running IRIX." | |
188 | fi) | |
189 | ||
190 | AC_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 | |
196 | that 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><cups/cups.h></CODE>: | |
202 | ||
203 | <UL><PRE> | |
204 | #include <cups/cups.h> | |
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 <cups/cups.h> | |
214 | ||
215 | ... | |
216 | ||
217 | int jobid; | |
218 | ||
219 | ... | |
220 | ||
221 | jobid = 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 | |
225 | print to. The <CODE>filename</CODE> string is the name of the file to | |
226 | print. The <CODE>title</CODE> string is the name of the print job, e.g. | |
227 | "Acme Word Document". | |
228 | ||
229 | <P>The return value is a unique ID number for the print job or 0 if there | |
230 | was 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 <cups/cups.h> | |
238 | ||
239 | ... | |
240 | ||
241 | int jobid; | |
242 | int num_files; | |
243 | const char *files[100]; | |
244 | ... | |
245 | ||
246 | jobid = 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> | |
250 | you pass a file count (<CODE>num_files</CODE>) and filename pointer array | |
251 | (<CODE>files</CODE>) for each file that you want to print. | |
252 | ||
253 | <P>As with <CODE>cupsPrintFile()</CODE> the return value is a unique ID for | |
254 | the 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 <cups/cups.h> | |
262 | ||
263 | ... | |
264 | ||
265 | int jobid; | |
266 | int status; | |
267 | ... | |
268 | ||
269 | status = cupsCancelJob("<I>name</I>", <I>jobid</I>); | |
270 | </PRE></UL> | |
271 | ||
272 | <P>The <CODE>name</CODE> string specifies the destination and is used | |
273 | to determine the server to send the request to. The <CODE>jobid</CODE> | |
274 | value is the integer returned from a previous <CODE>cupsPrintFile()</CODE> | |
275 | or <CODE>cupsPrintFiles()</CODE> call. | |
276 | ||
277 | <P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was | |
278 | successfully cancelled and <CODE>0</CODE> if there was an error. | |
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 | |
283 | of the available printers, classes, and instances that a user has defined: | |
284 | ||
285 | <UL><PRE> | |
286 | #include <cups/cups.h> | |
287 | ||
288 | ... | |
289 | ||
290 | int num_dests; | |
291 | cups_dest_t *dests; | |
292 | ||
293 | ... | |
294 | ||
295 | num_dests = cupsGetDests(&dests); | |
296 | </PRE></UL> | |
297 | ||
298 | <P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure which | |
299 | defines the printer or class name, the instance name (if any), if it is the | |
300 | default destination, and the default options the user has defined for the | |
301 | destination: | |
302 | ||
303 | <UL><PRE> | |
304 | typedef 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. | |
315 | Once you have the list of available destinations, you can lookup a specific | |
316 | destination using the <CODE>cupsGetDest()</CODE> function: | |
317 | ||
318 | <UL><PRE> | |
319 | #include <cups/cups.h> | |
320 | ||
321 | ... | |
322 | ||
323 | int num_dests; | |
324 | cups_dest_t *dests; | |
325 | cups_dest_t *mydest; | |
326 | ||
327 | ... | |
328 | ||
329 | mydest = 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 | |
333 | a 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> | |
343 | and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments are the | |
344 | number of options and a pointer to the option array: | |
345 | ||
346 | <UL><PRE> | |
347 | int cupsPrintFile(const char *name, const char *filename, const char *title, | |
348 | int num_options, cups_option_t *options); | |
349 | int cupsPrintFiles(const char *name, int num_files, const char **files, | |
350 | const char *title, int num_options, | |
351 | cups_option_t *options); | |
352 | </PRE></UL> | |
353 | ||
354 | <P>The <CODE>cups_option_t</CODE> structure holds each option and its value. | |
355 | These are converted as needed and passed to the CUPS server when printing a | |
356 | file. | |
357 | ||
358 | <P>The simplest way of handling options is to use the <CODE>num_options</CODE> | |
359 | and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE> | |
360 | structure described earlier: | |
361 | ||
362 | <UL><PRE> | |
363 | #include <cups/cups.h> | |
364 | ||
365 | ... | |
366 | ||
367 | int jobid; | |
368 | int num_dests; | |
369 | cups_dest_t *dests; | |
370 | cups_dest_t *mydest; | |
371 | ||
372 | ... | |
373 | ||
374 | mydest = cupsGetDest("<I>name</I>", "<I>instance</I>", num_dests, dests); | |
375 | ||
376 | jobid = cupsPrintFile(mydest->name, "filename", "title", | |
377 | mydest->num_options, mydest->options); | |
378 | </PRE></UL> | |
379 | ||
380 | <P>This effectively uses the options a user has previous selected without a | |
381 | lot 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> | |
386 | function: | |
387 | ||
388 | <UL><PRE> | |
389 | #include <cups/cups.h> | |
390 | ||
391 | ... | |
392 | ||
393 | int num_options; | |
394 | cups_option_t *options; | |
395 | ||
396 | ... | |
397 | ||
398 | num_options = 0; | |
399 | options = NULL; | |
400 | ||
401 | ... | |
402 | ||
403 | num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); | |
404 | num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); | |
405 | num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); | |
406 | num_options = cupsAddOption("<I>name</I>", "<I>value</I>", num_options, &options); | |
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 | |
413 | options. Since adding two options with the same name overwrites the | |
414 | first value with the second, do not assume that calling | |
415 | <CODE>cupsAddOptions()</CODE> 20 times will result in 20 options. | |
416 | ||
417 | <P>Call <CODE>cupsFreeOptions</CODE> once you are done using the options: | |
418 | ||
419 | <UL><PRE> | |
420 | #include <cups/cups.h> | |
421 | ||
422 | ... | |
423 | ||
424 | int num_options; | |
425 | cups_option_t *options; | |
426 | ||
427 | ... | |
428 | ||
429 | cupsFreeOptions(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 | |
435 | that error can be found by calling <CODE>cupsLastError()</CODE> and | |
436 | <CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE> returns the | |
437 | last IPP error code that was encountered. <CODE>cupsErrorString()</CODE> | |
438 | converts the error code to a localized message string suitable for | |
439 | presentation to the user: | |
440 | ||
441 | <UL><PRE> | |
442 | #include <cups/cups.h> | |
443 | ||
444 | ... | |
445 | ||
446 | int jobid; | |
447 | ||
448 | ... | |
449 | ||
450 | if (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 | |
457 | submission of print jobs. The default mechanism for getting the | |
458 | username and password is to use the login user and a password | |
459 | from the console. | |
460 | ||
461 | <P>To support other types of applications, in particular | |
462 | Graphical User Interfaces ("GUIs"), the CUPS API provides | |
463 | functions to set the default username and to register a callback | |
464 | function that returns a password string. | |
465 | ||
466 | <P>The <A HREF="#cupsSetPasswordCB"><CODE>cupsSetPasswordCB()</CODE></A> | |
467 | function is used to set a password callback in your program. Only one | |
468 | function can be used at any time. | |
469 | ||
470 | <P>The <A HREF="#cupsSetUser"><CODE>cupsSetUser()</CODE></A> function sets | |
471 | the current username for authentication. This function can be called by | |
472 | your password callback function to change the current username as needed. | |
473 | ||
474 | <P>The following example shows a simple password callback that gets a | |
475 | username and password from the user: | |
476 | ||
477 | <UL><PRE> | |
478 | #include <cups/cups.h> | |
479 | ||
480 | const char * | |
481 | my_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 | ||
504 | cupsSetPasswordCB(my_password_cb); | |
505 | </PRE></UL> | |
506 | ||
507 | <P>Similarly, a GUI interface could display the prompt string in a | |
508 | window with input fields for the username and password. The username | |
509 | should probably default to the value of | |
510 | <A HREF="#cupsUser"><CODE>cupsUser()</CODE></A> to make things easier | |
511 | on the user. | |
512 | ||
513 | <H2>PPD Services</H2> | |
514 | ||
515 | <P>CUPS includes functions to access and manipulate PostScript Printer | |
516 | Description ("PPD") files that are used with the printer drivers in CUPS. | |
517 | ||
518 | <P>Each PPD file enumerates the available features provided by a | |
519 | printer, including conflict information for specific options (e.g. | |
520 | can't duplex output on envelopes.) | |
521 | ||
522 | <H3>Include Files</H3> | |
523 | ||
524 | <P>Include the <CODE><cups/ppd.h></CODE> header file to use the PPD | |
525 | functions: | |
526 | ||
527 | <UL><PRE> | |
528 | #include <cups/ppd.h> | |
529 | </PRE></UL> | |
530 | ||
531 | <P>This header file is also included by the | |
532 | <CODE><cups/cups.h></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 | |
537 | named printer or class: | |
538 | ||
539 | <UL><PRE> | |
540 | #include <cups/cups.h> | |
541 | ||
542 | ... | |
543 | ||
544 | const char *filename; | |
545 | ||
546 | filename = cupsGetPPD("<I>name</I>"); | |
547 | </PRE></UL> | |
548 | ||
549 | <P>The <CODE>name</CODE> string is the name of the printer or class, including | |
550 | the remote server name as appropriate (e.g. "printer@server".) | |
551 | ||
552 | <P>The return value is a pointer to a filename in static storage; this value | |
553 | is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If the printer | |
554 | or class does not exist, a <CODE>NULL</CODE> pointer will be returned. | |
555 | ||
556 | <H3>Loading a PPD File</H3> | |
557 | ||
558 | <P>The <CODE>ppdOpenFile()</CODE> function "opens" a PPD file and loads it | |
559 | into memory: | |
560 | ||
561 | <UL><PRE> | |
562 | #include <cups/ppd.h> | |
563 | ||
564 | ... | |
565 | ||
566 | ppd_file_t *ppd; | |
567 | ||
568 | ppd = 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 | |
572 | the 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 | |
575 | PPD 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 | |
580 | to free all memory that has been used: | |
581 | ||
582 | <UL><PRE> | |
583 | #include <cups/ppd.h> | |
584 | ||
585 | ... | |
586 | ||
587 | ppd_file_t *ppd; | |
588 | ||
589 | ... | |
590 | ||
591 | ppdClose(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, | |
597 | and conflict definitions. The page size options also include the physical | |
598 | margins for the printer and the minimum and maximum sizes for the printer. | |
599 | All of this information is stored in the <CODE>ppd_file_t</CODE> structure. | |
600 | ||
601 | <H4>Capabilities</H4> | |
602 | ||
603 | <P>Each PPD file contains a number of informational attributes that | |
604 | describe the capabilities of the printer. These are provided in the | |
605 | <CODE>ppd_file_t</CODE> structure in the following members: | |
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 | |
741 | the PPD functions. | |
742 | ||
743 | <P>Each option in turn is associated with a group | |
744 | stored in the <CODE>ppd_group_t</CODE> structure. Groups can be | |
745 | specified in the PPD file; if an option is not associated with a group | |
746 | then it is put in a "General" or "Extra" group depending on the option. | |
747 | ||
748 | <P>Groups can also have sub-groups; CUPS currently limits the depth of | |
749 | sub-groups to 1 level to reduce programming complexity. | |
750 | ||
751 | <H4>Conflicts</H4> | |
752 | ||
753 | <P>PPD files support specification of conflict conditions between | |
754 | different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE> | |
755 | structures which specify the options that conflict with each other. | |
756 | ||
757 | <H4>Page Sizes</H4> | |
758 | ||
759 | <P>PPD files specify all of the available pages sizes and the physical | |
760 | margins associated with them. These sizes are stored in | |
761 | <CODE>ppd_size_t</CODE> structures and are available in the | |
762 | <CODE>num_sizes</CODE> and <CODE>sizes</CODE> members of the | |
763 | <CODE>ppd_file_t</CODE> structure. You can lookup a particular page size | |
764 | with the <CODE>ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and | |
765 | <CODE>ppdPageSize()</CODE> functions: | |
766 | ||
767 | <UL><PRE> | |
768 | #include <cups/ppd.h> | |
769 | ||
770 | ... | |
771 | ||
772 | ppd_file_t *ppd; | |
773 | ppd_size_t *size; | |
774 | float width; | |
775 | float length; | |
776 | ||
777 | ... | |
778 | ||
779 | size = ppdPageSize(ppd, "<I>size</I>"); | |
780 | width = ppdPageWidth(ppd, "<I>size</I>"); | |
781 | length = ppdPageLength(ppd, "<I>size</I>"); | |
782 | </PRE></UL> | |
783 | ||
784 | <P>The <CODE>size</CODE> string is the named page size option. The | |
785 | width and length are in points; there are 72 points per inch. The | |
786 | <CODE>ppd_size_t</CODE> structure contains the width, length, and | |
787 | margin information: | |
788 | ||
789 | <UL><PRE> | |
790 | typedef 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 | |
806 | support variable or custom page sizes. If <CODE>variables_sizes</CODE> | |
807 | is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and | |
808 | <CODE>custom_margins</CODE> members of the <CODE>ppd_file_t</CODE> | |
809 | structure define the limits of the variable sizes. | |
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> | |
813 | and <CODE>length</CODE> are integer values in points: | |
814 | ||
815 | <UL><PRE> | |
816 | Custom.612x792 [8.5 inches wide, 11 inches long] | |
817 | Custom.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> | |
823 | function to mark the default options from the PPD file: | |
824 | ||
825 | <UL><PRE> | |
826 | #include <cups/ppd.h> | |
827 | ||
828 | ... | |
829 | ||
830 | ppd_file_t *ppd; | |
831 | ||
832 | ... | |
833 | ||
834 | ppdMarkDefaults(ppd); | |
835 | </PRE></UL> | |
836 | ||
837 | <P>Then call the <CODE>ppdMarkOption()</CODE> function to mark individual | |
838 | options: | |
839 | ||
840 | <UL><PRE> | |
841 | #include <cups/ppd.h> | |
842 | ||
843 | ... | |
844 | ||
845 | ppd_file_t *ppd; | |
846 | int conflicts; | |
847 | ||
848 | ... | |
849 | ||
850 | conflicts = 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 | |
854 | particular option and choice, respectively. The return value is 0 | |
855 | if there are not conflicts created by the selection. | |
856 | ||
857 | <P>CUPS also provides a convenience function for marking all options | |
858 | in the <CODE>cups_option_t</CODE> structure: | |
859 | ||
860 | <UL><PRE> | |
861 | #include <cups/cups.h> | |
862 | ||
863 | ... | |
864 | ||
865 | ppd_file_t *ppd; | |
866 | int num_options; | |
867 | cups_option_t *options; | |
868 | int conflicts; | |
869 | ||
870 | ... | |
871 | ||
872 | conflicts = cupsMarkOptions(ppd, num_options, options); | |
873 | </PRE></UL> | |
874 | ||
875 | <P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the | |
876 | IPP job template attributes to PPD options. The return value is the number | |
877 | of conflicts present. | |
878 | ||
879 | <H3>Checking for Conflicts</H3> | |
880 | ||
881 | <P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE> | |
882 | functions return the number of conflicts with the currently marked options. | |
883 | ||
884 | <P>Call the <CODE>ppdConflicts()</CODE> function to get the number of | |
885 | conflicts after you have marked all of the options: | |
886 | ||
887 | <UL><PRE> | |
888 | #include <cups/cups.h> | |
889 | ||
890 | ... | |
891 | ||
892 | ppd_file_t *ppd; | |
893 | int conflicts; | |
894 | ||
895 | ... | |
896 | ||
897 | conflicts = ppdConflicts(ppd); | |
898 | </PRE></UL> | |
899 | ||
900 | <P>The return value is the number of conflicting options, or 0 if there | |
901 | are 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 | |
911 | another type. Filters use a common command-line and environment interface | |
912 | that allows them to be joined as needed to print files to any type of | |
913 | printer. | |
914 | ||
915 | <H3>Security Considerations</H3> | |
916 | ||
917 | <P>Filters are normally run as a non-priviledged user, so the major | |
918 | security consideration is resource utilization - filters should not | |
919 | depend on unlimited amounts of memory and disk space. | |
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 | |
930 | used 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 | |
935 | by the filter. These messages are relayed to the user based upon the | |
936 | scheduler <CODE>LogLevel</CODE> directive. | |
937 | ||
938 | <P>The type of message is determined by an initial prefix sent on each | |
939 | line: | |
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 | |
956 | is treated as a debug message. Text following the prefix is copied to the | |
957 | <CODE>printer-state-message</CODE> attribute for the printer, and also | |
958 | added to the <VAR>error_log</VAR> unless it is an informational or page | |
959 | accounting message. | |
960 | ||
961 | <H3>Page Accounting</H3> | |
962 | ||
963 | <P>Page accounting messages are used to inform the server when one or more | |
964 | pages are printed. Each line has the form: | |
965 | ||
966 | <UL><PRE> | |
967 | PAGE: page-number copy-count | |
968 | </PRE></UL> | |
969 | ||
970 | <P>The <I>page-number</I> field is the current page number, starting at 1. | |
971 | The <I>copy-count</I> field specifies the number of copies of that page | |
972 | that was produced. | |
973 | ||
974 | <P>Page account messages are added to the <VAR>page_log</VAR> file and | |
975 | cause the <CODE>job-sheets-completed</CODE> attribute to be updated for | |
976 | the 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> | |
983 | printer 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 | |
1013 | chain; all filters <B>must</B> be prepared to read the print file from | |
1014 | the standard input if the <I>filename</I> argument is omitted. | |
1015 | ||
1016 | <H3>Copy Generation</H3> | |
1017 | ||
1018 | <P>The <I>copies</I> argument specifies the number of copies to produce | |
1019 | of the input file. In general, you should only generate copies if the | |
1020 | <I>filename</I> argument is supplied. The only exception to this are | |
1021 | filters that produce device-independent PostScript output (without any | |
1022 | printer commands from the printer's PPD file), since the PostScript | |
1023 | filter <CODE>pstops</CODE> is responsible for copy generation. | |
1024 | ||
1025 | <H3>Environment Variables</H3> | |
1026 | ||
1027 | <P>Every filter receives a fixed set of environment variables that can | |
1028 | be 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 | |
1069 | complex program that converts HP-GL/2 files into device-independent PostScript | |
1070 | output. Since it produces device-independent PostScript output, it does not | |
1071 | need to handle copy generation or writing printer options from the printer's | |
1072 | PPD 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 | |
1077 | command-line arguments are present: | |
1078 | ||
1079 | <UL><PRE> | |
1080 | if (argc < 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 | |
1088 | as needed: | |
1089 | ||
1090 | <UL><PRE> | |
1091 | FILE *fp; | |
1092 | ||
1093 | /* | |
1094 | * If we have 7 arguments, print the file named on the command-line. | |
1095 | * Otherwise, send stdin instead... | |
1096 | */ | |
1097 | ||
1098 | if (argc == 6) | |
1099 | fp = stdin; | |
1100 | else | |
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 | |
1115 | the <A HREF="#cupsParseOptions"><CODE>cupsParseOptions()</CODE></A> and | |
1116 | <A HREF="#cupsGetOption"><CODE>cupsGetOption()</CODE></A> functions: | |
1117 | ||
1118 | <UL><PRE> | |
1119 | int num_options; | |
1120 | cups_option_t *options; | |
1121 | const char *val; | |
1122 | ||
1123 | /* | |
1124 | * Process command-line options and write the prolog... | |
1125 | */ | |
1126 | ||
1127 | options = NULL; | |
1128 | num_options = cupsParseOptions(argv[5], 0, &options); | |
1129 | ||
1130 | if ((val = cupsGetOption("blackplot", num_options, options)) != NULL) | |
1131 | shading = 0; | |
1132 | ||
1133 | if ((val = cupsGetOption("fitplot", num_options, options)) != NULL) | |
1134 | FitPlot = 1; | |
1135 | ||
1136 | if ((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 | |
1141 | to the standard output based on the print file, closes the print file (as | |
1142 | needed), and returns 0 to the scheduler. | |
1143 | ||
1144 | <H2>PostScript Output</H2> | |
1145 | ||
1146 | <P>Filters that produce PostScript output must generate output conforming | |
1147 | to the Adobe Document Structuring Conventions, 3.0. In general this means | |
1148 | the beginning of each file must begin with: | |
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 | |
1158 | are 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 | |
1164 | gsave | |
1165 | ... | |
1166 | grestore | |
1167 | showpage | |
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 | |
1179 | accounting, 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 | |
1184 | special filter program that converts CUPS raster data into the | |
1185 | appropriate 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 | |
1190 | device-specific filters that handle converting print files for the | |
1191 | printer. The simplest raster printer drivers provide a single filter | |
1192 | that converts CUPS raster data to the printer's native format. | |
1193 | ||
1194 | <H3>CUPS Raster Data</H3> | |
1195 | ||
1196 | <P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists of | |
1197 | a stream of raster page descriptions produced by one of the RIP filters, | |
1198 | such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>. | |
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 | |
1202 | structure contains the colorspace, bits per color, media size, media type, | |
1203 | hardware resolution, and so forth. | |
1204 | ||
1205 | <P>After the page dictionary comes the page data which is a full-resolution, | |
1206 | uncompressed bitmap representing the page in the printer's output colorspace. | |
1207 | ||
1208 | <H3>Page Accounting</H3> | |
1209 | ||
1210 | <P>Printer drivers must handle all page accounting. This means they must | |
1211 | send "PAGE:" messages to the standard error file for each page (and in many | |
1212 | cases, copy) sent to the printer. | |
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 | |
1218 | in the driver from a device-independent colorspace. In general, color | |
1219 | management performed by the RIP filters is more efficient than that | |
1220 | performed inside printer drivers. | |
1221 | ||
1222 | <P>For example, the <CODE>pstoraster</CODE> filter often only has to | |
1223 | perform a color conversion once each time the color is used for | |
1224 | multiple output pixels, while the raster filter must convert every | |
1225 | pixel on the page. | |
1226 | ||
1227 | <H3>Device and Bitmap Variables</H3> | |
1228 | ||
1229 | <P>Besides the standard PostScript page device dictionary variables defined | |
1230 | in the Adobe PostScript Level 3 reference manual, the CUPS filters support | |
1231 | additional variables that are passed in the page device dictionary header for | |
1232 | the page and in some cases control the type of raster data that is generated: | |
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 CMYK CMYK | |
1277 | <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK | |
1278 | <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ... | |
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 | |
1331 | color are transmitted to the raster driver in KCMY colorspace; the driver | |
1332 | is responsible for producing the correct separation of normal and light | |
1333 | cyan and magenta inks. | |
1334 | ||
1335 | <H2>Dissecting the HP-PCL Driver</H2> | |
1336 | ||
1337 | <P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>) converts | |
1338 | bitmap data from the raster filters into HP-PCL commands for most | |
1339 | PCL-compatible printers. The actual format of the raster data is controlled | |
1340 | by the PPD file being used - <VAR>deskjet.ppd</VAR> or <VAR>laserjet.ppd</VAR>. | |
1341 | ||
1342 | <H3>PPD Files</H3> | |
1343 | ||
1344 | <P>PPD files play an important part of all raster printer drivers. Options | |
1345 | defined in the PPD file contain PostScript commands that control the raster | |
1346 | data that is sent to the printer driver. | |
1347 | ||
1348 | <P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>, | |
1349 | <CODE>InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>, | |
1350 | and <CODE>Resolution</CODE> options. Each option is shown using the | |
1351 | standard PPD format: | |
1352 | ||
1353 | <UL><PRE> | |
1354 | *OpenUI *PageSize/Media Size: PickOne | |
1355 | *OrderDependency: 10 AnySetup *PageSize | |
1356 | *DefaultPageSize: Letter | |
1357 | *PageSize Letter/US Letter: "<< | |
1358 | /PageSize [612 792] | |
1359 | /ImagingBBox null | |
1360 | >> setpagedevice" | |
1361 | *End | |
1362 | *PageSize Legal/US Legal: "<< | |
1363 | /PageSize [612 1008] | |
1364 | /ImagingBBox null | |
1365 | >> setpagedevice" | |
1366 | *End | |
1367 | *PageSize A4/A4: "<< | |
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 | |
1376 | name is the option with an asterisk (*) in front of it. The first name is | |
1377 | usually followed by a slash (/) and a human-readable version of the | |
1378 | option 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 | |
1384 | human-readable values. The PostScript commands follow these inside double | |
1385 | quotes. PostScript commands can be provided on a single line: | |
1386 | ||
1387 | <UL><PRE> | |
1388 | *PageSize A4/A4: "<</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 | |
1392 | terminate them: | |
1393 | ||
1394 | <UL><PRE> | |
1395 | *PageSize A4/A4: "<< | |
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 | |
1403 | a PPD file must not exceed 255 characters, so if your PostScript commands are | |
1404 | long you may need to break them up on separate lines. | |
1405 | ||
1406 | <H3>Reading Raster Data</H3> | |
1407 | ||
1408 | <P>As with any filter, your printer driver should handle raster data from | |
1409 | a filename specified on the command-line or from the standard input. The | |
1410 | <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function opens | |
1411 | a raster stream for printing: | |
1412 | ||
1413 | <UL><PRE> | |
1414 | int fd; /* File descriptor */ | |
1415 | cups_raster_t *ras; /* Raster stream for printing */ | |
1416 | ||
1417 | ||
1418 | /* | |
1419 | * Check for valid arguments... | |
1420 | */ | |
1421 | ||
1422 | if (argc < 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 | ||
1437 | if (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 | } | |
1446 | else | |
1447 | fd = 0; | |
1448 | ||
1449 | ras = cupsRasterOpen(fd, CUPS_RASTER_READ); | |
1450 | </PRE></UL> | |
1451 | ||
1452 | <P>Once you have opened the raster stream you just need to read each | |
1453 | page and print it: | |
1454 | ||
1455 | <UL><PRE> | |
1456 | cups_raster_header_t header; | |
1457 | int y; | |
1458 | unsigned char data[8192]; | |
1459 | ||
1460 | while (cupsRasterReadHeader(ras, &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 | |
1472 | return: | |
1473 | ||
1474 | <UL><PRE> | |
1475 | cupsRasterClose(ras); | |
1476 | ||
1477 | return (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 | |
1483 | communicate directly with printers and allow printer drivers and | |
1484 | filters 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. | |
1489 | They are treated slightly differently than filters, however, and have some | |
1490 | unique requirements. | |
1491 | ||
1492 | <H3>Security Considerations</H3> | |
1493 | ||
1494 | <P>Backends are run as the root user, so special care must be taken to | |
1495 | avoid potential security violations. In particular, remember that a backend | |
1496 | will be able to manipulate disk files, devices, and other resources that | |
1497 | potentially could damage a system or printer. | |
1498 | ||
1499 | <H3>Command-Line Arguments</H3> | |
1500 | ||
1501 | <P>Besides the standard filter arguments, backends are also run with no | |
1502 | arguments to get a list of available devices. This discovery process is | |
1503 | described later in this chapter. | |
1504 | ||
1505 | <H3>Copy Generation</H3> | |
1506 | ||
1507 | <P>Like filters, backends should send multiple copies of the print file only | |
1508 | if a filename is supplied on the command-line. Otherwise the backend should | |
1509 | assume that the upstream filter has already added the necessary commands or | |
1510 | data to produce the multiple copies. | |
1511 | ||
1512 | <H3>Page Accounting</H3> | |
1513 | ||
1514 | <P>Backend filters generally do not do page accounting, however they should | |
1515 | at a minimum produce a single page message for each copy that is produced | |
1516 | when a filename is present on the command-line. This is because the user | |
1517 | selected "raw" printing and no other accounting information is possible. | |
1518 | ||
1519 | <H3>Exclusive Access</H3> | |
1520 | ||
1521 | <P>Backends that talk to local character or block devices should open the | |
1522 | device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate with other | |
1523 | printers defined for the same device. | |
1524 | ||
1525 | <H3>Retries</H3> | |
1526 | ||
1527 | <P>All backends <B>must</B> retry connections to the device. This | |
1528 | includes backends that talk to local character or block devices, as the | |
1529 | user may define more than one printer queue pointing at the same | |
1530 | physical device. | |
1531 | ||
1532 | <P>To prevent excess CPU utilitization, the backend should go to sleep | |
1533 | for an amount of time between retries; the CUPS-supplied backends retry | |
1534 | once every 30 seconds. | |
1535 | ||
1536 | <H2>Dissecting the Serial Port Backend</H2> | |
1537 | ||
1538 | <P>The serial port backend provides support for serial printers. Since | |
1539 | it does everything a good backend needs to do, it provides an excellent | |
1540 | example of what to do. | |
1541 | ||
1542 | <H3>Supporting Device Discovery</H3> | |
1543 | ||
1544 | <P>As previously noted, backends are special filter programs that talk | |
1545 | to printer devices. Another task a backend must perform is to list the | |
1546 | available devices it supports. The backend lists the available devices | |
1547 | when no additioanl arguments are supplied on the command-line (i.e. | |
1548 | just the command name...) | |
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 | |
1552 | in 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 | |
1555 | the standard error file. Each line looks like this: | |
1556 | ||
1557 | <UL><PRE> | |
1558 | serial 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 | |
1562 | class of device which can be used to categorize it in user interfaces. CUPS | |
1563 | currently 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 | |
1582 | the user to select this port. For serial ports, the "baud=115200" | |
1583 | specifies the maximum baud rate supported by the port - the actual | |
1584 | value will vary based on the speed the user selects for the printer. | |
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 | |
1588 | are able to provide a make and model such as "HP DeskJet" that allows | |
1589 | users and software to choose an appropriate printer driver more easily. | |
1590 | Both the model and description must be enclosed inside double quotes. | |
1591 | ||
1592 | <H3>Opening the Serial Port</H3> | |
1593 | ||
1594 | <P>As noted previously, all backends should open device files in exclusive | |
1595 | mode, and retry as needed until the port is available. The serial port does | |
1596 | this using a <CODE>do-while</CODE> loop: | |
1597 | ||
1598 | <UL><PRE> | |
1599 | do | |
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 | } | |
1615 | while (fd < 0); | |
1616 | </PRE></UL> | |
1617 | ||
1618 | <P>If the port is busy or in use by another process, the backend will | |
1619 | go to sleep for 30 seconds and try again. If another error is detected | |
1620 | a message is sent to the user and the backend aborts the print job | |
1621 | until the problem can be corrected. | |
1622 | ||
1623 | <H3>Writing Data to the Port</H3> | |
1624 | ||
1625 | <P>Network and character devices pose an interesting problem when writing | |
1626 | data to the port - they may not be able to write all of the bytes in your | |
1627 | buffer before returning. To work around this problem you must loop until | |
1628 | all bytes have been written: | |
1629 | ||
1630 | <UL><PRE> | |
1631 | while (nbytes > 0) | |
1632 | { | |
1633 | if ((wbytes = write(fd, bufptr, nbytes)) < 0) | |
1634 | if (errno == ENOTTY) | |
1635 | wbytes = write(fd, bufptr, nbytes); | |
1636 | ||
1637 | if (wbytes < 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 | |
1649 | to 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 | |
1654 | successfully or 1 if it did not. This will allow the scheduler to stop | |
1655 | the print job if there is a device error, preserving the print job for | |
1656 | later printing once the problem has been corrected. | |
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 | |
1666 | API. | |
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 | |
1673 | representing the API version number. The current version number is | |
1674 | 1.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 | |
1679 | printers 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 | |
1894 | HTTP 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 | |
2042 | specify 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 | |
2047 | performed 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 | |
2117 | state. | |
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 | |
2297 | representing the newest format version that is supported by CUPS, currently | |
2298 | 4.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 | |
2319 | the output document. The <CODE>ppd_section_t</CODE> enumeration defines | |
2320 | which 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> | |
2370 | constants define the standard sync words at the beginning of each CUPS | |
2371 | raster file. | |
2372 | ||
2373 | <H3>Raster Stream Modes</H3> | |
2374 | ||
2375 | <P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE> | |
2376 | constants are used with the | |
2377 | <A HREF="#cupsRasterOpen"><CODE>cupsRasterOpen()</CODE></A> function to | |
2378 | specify a stream for reading or writing. | |
2379 | ||
2380 | <H3>Raster Boolean Constants</H3> | |
2381 | ||
2382 | <P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants | |
2383 | represent 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 | |
2388 | Jog 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 | |
2405 | Orientation 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 | |
2422 | CutMedia 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 | |
2441 | AdvanceMedia 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 | |
2460 | LeadingEdge 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 | |
2481 | value orderings: | |
2482 | ||
2483 | <UL> | |
2484 | ||
2485 | <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK CMYK CMYK | |
2486 | ||
2487 | <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC MMM YYY KKK | |
2488 | ||
2489 | <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC ... MMM ... YYY ... KKK ... | |
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 | |
2537 | defined 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>) | |
2544 | contains 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 | |
2583 | information 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>) | |
2651 | contains 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>) | |
2689 | contains 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 | |
2714 | current 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 | |
2839 | current 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>) | |
2859 | consists 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> | |
3079 | int | |
3080 | cupsAddDest(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 | |
3118 | array if it does not already exist. | |
3119 | ||
3120 | <H3>Example</H3> | |
3121 | ||
3122 | <PRE> | |
3123 | #include <cups/cups.h> | |
3124 | ||
3125 | int num_dests; | |
3126 | <A HREF="#cups_dest_t">cups_dest_t</A> *dests; | |
3127 | ||
3128 | ||
3129 | num_dests = cupsAddDests("foo", "bar", num_dests, &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> | |
3145 | int | |
3146 | cupsAddOption(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 <cups.h> | |
3189 | ||
3190 | ... | |
3191 | ||
3192 | /* Declare the options array */ | |
3193 | int num_options; | |
3194 | <A HREF="#cups_option_t">cups_option_t</A> *options; | |
3195 | ||
3196 | /* Initialize the options array */ | |
3197 | num_options = 0; | |
3198 | options = (cups_option_t *)0; | |
3199 | ||
3200 | /* Add options using cupsAddOption() */ | |
3201 | num_options = cupsAddOption("media", "letter", num_options, &options); | |
3202 | num_options = cupsAddOption("resolution", "300dpi", num_options, &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> | |
3218 | int | |
3219 | cupsCancelJob(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 <cups.h> | |
3253 | ||
3254 | cupsCancelJob("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> | |
3270 | ipp_t * | |
3271 | cupsDoFileRequest(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 | |
3305 | the 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 | |
3311 | IPP request and optionally the contents of a file to the IPP server. It also | |
3312 | handles resubmitting the request and performing password authentication as | |
3313 | needed. | |
3314 | ||
3315 | <H3>Example</H3> | |
3316 | ||
3317 | <PRE> | |
3318 | #include <cups.h> | |
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; | |
3323 | ipp_t *response; | |
3324 | ||
3325 | ... | |
3326 | ||
3327 | /* Get the default language */ | |
3328 | language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>; | |
3329 | ||
3330 | /* Create a new IPP request */ | |
3331 | request = <A HREF="#ippNew">ippNew()</A>; | |
3332 | ||
3333 | request->request.op.operation_id = IPP_PRINT_FILE; | |
3334 | request->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 | ||
3340 | ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE, | |
3341 | "attributes-natural-language", NULL, | |
3342 | language != NULL ? language->language : "C"); | |
3343 | ||
3344 | ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", | |
3345 | NULL, "ipp://hostname/resource"); | |
3346 | ||
3347 | ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, "requesting-user-name", | |
3348 | NULL, <A HREF="#cupsUser">cupsUser()</A>); | |
3349 | ||
3350 | /* Do the request... */ | |
3351 | response = 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> | |
3370 | ipp_t * | |
3371 | cupsDoRequest(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 | |
3400 | the 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 | |
3406 | the IPP request to the IPP server. It also handles resubmitting the | |
3407 | request and performing password authentication as needed. | |
3408 | ||
3409 | <H3>Example</H3> | |
3410 | ||
3411 | <PRE> | |
3412 | #include <cups.h> | |
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; | |
3417 | ipp_t *response; | |
3418 | ||
3419 | ... | |
3420 | ||
3421 | /* Get the default language */ | |
3422 | language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>; | |
3423 | ||
3424 | /* Create a new IPP request */ | |
3425 | request = <A HREF="#ippNew">ippNew()</A>; | |
3426 | ||
3427 | request->request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES; | |
3428 | request->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 | ||
3434 | ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE, | |
3435 | "attributes-natural-language", NULL, | |
3436 | language != NULL ? language->language : "C"); | |
3437 | ||
3438 | ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, "printer-uri", | |
3439 | NULL, "ipp://hostname/resource"); | |
3440 | ||
3441 | /* Do the request... */ | |
3442 | response = 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> | |
3461 | void | |
3462 | cupsEncodeOptions(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 | |
3491 | in the specified array as IPP attributes and adds them to the | |
3492 | IPP request. | |
3493 | ||
3494 | <H3>Example</H3> | |
3495 | ||
3496 | <PRE> | |
3497 | #include <cups/cups.h> | |
3498 | ||
3499 | <A HREF="#ipp_t">ipp_t</A> *ipp; | |
3500 | int num_options; | |
3501 | <A HREF="#cups_option_t">cups_option_t</A> *options; | |
3502 | ||
3503 | ||
3504 | cupsEncodeOptions(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> | |
3520 | http_encryption_t | |
3521 | cupsEncryption(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 | |
3531 | for IPP requests such as printing. | |
3532 | ||
3533 | <H3>Example</H3> | |
3534 | ||
3535 | <PRE> | |
3536 | #include <cups/cups.h> | |
3537 | ||
3538 | <A HREF="#http_t">http_t</A> *http; | |
3539 | ||
3540 | printf("The current encryption setting is %d.\n", cupsEncryption()); | |
3541 | ||
3542 | http = 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> | |
3558 | void | |
3559 | cupsFreeDests(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 | |
3583 | created using <CODE>cupsGetDests()</CODE>. | |
3584 | ||
3585 | <H3>Example</H3> | |
3586 | ||
3587 | <PRE> | |
3588 | #include <cups/cups.h> | |
3589 | ||
3590 | int num_dests; | |
3591 | <A HREF="#cups_dest_t">cups_dest_t</A> *dests; | |
3592 | cups_dest_t *dest; | |
3593 | ||
3594 | num_dests = cupsGetDests(&dests); | |
3595 | dest = cupsGetDest(NULL, NULL, num_dests, dests); | |
3596 | ||
3597 | if (dest) | |
3598 | printf("The default destination is %s\n", dest->name); | |
3599 | else | |
3600 | puts("No default destination."); | |
3601 | ||
3602 | cupsFreeDests(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> | |
3617 | void | |
3618 | cupsFreeJobs(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 | |
3642 | the <CODE>cupsGetJobs()</CODE> function. | |
3643 | ||
3644 | <H3>Example</H3> | |
3645 | ||
3646 | <PRE> | |
3647 | #include <cups/cups.h> | |
3648 | ||
3649 | int i; | |
3650 | int num_jobs; | |
3651 | <A HREF="#cups_job_t">cups_job_t</A> *jobs; | |
3652 | ||
3653 | ||
3654 | num_jobs = cupsGetJobs(&jobs, NULL, 0, 0); | |
3655 | ||
3656 | printf("%d active job(s):\n", num_jobs); | |
3657 | for (i = 0; i < num_jobs; i ++) | |
3658 | printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id, | |
3659 | jobs[i].user, jobs[i].title, | |
3660 | jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending"); | |
3661 | ||
3662 | cupsFreeJobs(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> | |
3677 | void | |
3678 | cupsFreeOptions(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 | |
3702 | option array specified. | |
3703 | ||
3704 | <H3>Example</H3> | |
3705 | ||
3706 | <PRE> | |
3707 | #include <cups/cups.h> | |
3708 | ||
3709 | int num_options; | |
3710 | <A HREF="#cups_option_t">cups_option_t</A> *options; | |
3711 | ||
3712 | ... | |
3713 | ||
3714 | cupsFreeOptions(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> | |
3732 | int | |
3733 | cupsGetClasses(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. | |
3756 | The returned array should be freed using the <CODE>free()</CODE> when it is | |
3757 | no longer needed. | |
3758 | ||
3759 | <H3>Example</H3> | |
3760 | ||
3761 | <PRE> | |
3762 | #include <cups/cups.h> | |
3763 | ||
3764 | int i; | |
3765 | int num_classes; | |
3766 | char **classes; | |
3767 | ||
3768 | ... | |
3769 | ||
3770 | num_classes = cupsGetClasses(&classes); | |
3771 | ||
3772 | ... | |
3773 | ||
3774 | if (num_classes > 0) | |
3775 | { | |
3776 | for (i = 0; i < 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> | |
3795 | const char * | |
3796 | cupsGetDefault(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. | |
3806 | The 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 <cups/cups.h> | |
3813 | ||
3814 | printf("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> | |
3829 | cups_dest_t * | |
3830 | cupsGetDest(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 | |
3868 | of destinations created by the <CODE>cupsGetDests()</CODE> function. | |
3869 | ||
3870 | <H3>Example</H3> | |
3871 | ||
3872 | <PRE> | |
3873 | #include <cups/cups.h> | |
3874 | ||
3875 | int num_dests; | |
3876 | <A HREF="#cups_dest_t">cups_dest_t</A> *dests; | |
3877 | cups_dest_t *dest; | |
3878 | ||
3879 | num_dests = cupsGetDests(&dests); | |
3880 | dest = cupsGetDest(NULL, NULL, num_dests, dests); | |
3881 | ||
3882 | if (dest) | |
3883 | printf("The default destination is %s\n", dest->name); | |
3884 | else | |
3885 | puts("No default destination."); | |
3886 | ||
3887 | cupsFreeDests(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> | |
3902 | int | |
3903 | cupsGetDests(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 | |
3926 | destinations that the user can print to. The array should be | |
3927 | freed using the <CODE>cupsFreeDests()</CODE> function. | |
3928 | ||
3929 | <H3>Example</H3> | |
3930 | ||
3931 | <PRE> | |
3932 | #include <cups/cups.h> | |
3933 | ||
3934 | int num_dests; | |
3935 | <A HREF="#cups_dest_t">cups_dest_t</A> *dests; | |
3936 | cups_dest_t *dest; | |
3937 | ||
3938 | num_dests = cupsGetDests(&dests); | |
3939 | dest = cupsGetDest(NULL, NULL, num_dests, dests); | |
3940 | ||
3941 | if (dest) | |
3942 | printf("The default destination is %s\n", dest->name); | |
3943 | else | |
3944 | puts("No default destination."); | |
3945 | ||
3946 | cupsFreeDests(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> | |
3962 | int | |
3963 | cupsGetJobs(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 | |
4004 | arguments supplied in the function call. The returned array should be freed | |
4005 | using the <CODE>cupsFreeJobs()</CODE> function. | |
4006 | ||
4007 | <H3>Example</H3> | |
4008 | ||
4009 | <PRE> | |
4010 | #include <cups/cups.h> | |
4011 | ||
4012 | int i; | |
4013 | int num_jobs; | |
4014 | <A HREF="#cups_job_t">cups_job_t</A> *jobs; | |
4015 | ||
4016 | ||
4017 | num_jobs = cupsGetJobs(&jobs, NULL, 0, 0); | |
4018 | ||
4019 | printf("%d active job(s):\n", num_jobs); | |
4020 | for (i = 0; i < num_jobs; i ++) | |
4021 | printf("%-16.16s %-6d %-12.12s %s (%s)\n", jobs[i].dest, jobs[i].id, | |
4022 | jobs[i].user, jobs[i].title, | |
4023 | jobs[i].state != IPP_JOB_PENDING ? "printing" : "pending"); | |
4024 | ||
4025 | cupsFreeJobs(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> | |
4040 | const char * | |
4041 | cupsGetOption(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 | |
4070 | not defined. | |
4071 | ||
4072 | <H3>Description</H3> | |
4073 | ||
4074 | <P><CODE>cupsGetOption()</CODE> returns the first occurrence of the | |
4075 | named option. If the option is not included in the options array then a | |
4076 | <CODE>NULL</CODE> pointer is returned. | |
4077 | ||
4078 | <PRE> | |
4079 | #include <cups/cups.h> | |
4080 | ||
4081 | int num_options; | |
4082 | cups_option_t *options; | |
4083 | const char *media; | |
4084 | ||
4085 | ... | |
4086 | ||
4087 | media = 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> | |
4105 | const char * | |
4106 | cupsGetPassword(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 | |
4125 | password was entered. | |
4126 | ||
4127 | <H3>Description</H3> | |
4128 | ||
4129 | <P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks the user | |
4130 | for a password. The password text is not echoed to the user. | |
4131 | ||
4132 | <H3>Example</H3> | |
4133 | ||
4134 | <PRE> | |
4135 | #include <cups/cups.h> | |
4136 | ||
4137 | char *password; | |
4138 | ||
4139 | ... | |
4140 | ||
4141 | password = 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> | |
4159 | const char * | |
4160 | cupsGetPPD(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> | |
4179 | if 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. | |
4184 | The 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 | |
4187 | filename is stored in a static buffer and will be overwritten with each call | |
4188 | to <CODE>cupsGetPPD()</CODE>. | |
4189 | ||
4190 | <H3>Example</H3> | |
4191 | ||
4192 | <PRE> | |
4193 | #include <cups/cups.h> | |
4194 | ||
4195 | char *ppd; | |
4196 | ||
4197 | ... | |
4198 | ||
4199 | ppd = cupsGetPPD("printer@hostname"); | |
4200 | ||
4201 | ... | |
4202 | ||
4203 | unlink(ppd); | |
4204 | </PRE> | |
4205 | ||
4206 | ||
4207 | <!-- NEW PAGE --><H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2> | |
4208 | ||
4209 | <H3>Usage</H3> | |
4210 | ||
4211 | <PRE> | |
4212 | int | |
4213 | cupsGetPrinters(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. | |
4236 | The returned array should be freed using the <CODE>free()</CODE> when it is | |
4237 | no longer needed. | |
4238 | ||
4239 | <H3>Example</H3> | |
4240 | ||
4241 | <PRE> | |
4242 | #include <cups/cups.h> | |
4243 | ||
4244 | int i; | |
4245 | int num_printers; | |
4246 | char **printers; | |
4247 | ||
4248 | ... | |
4249 | ||
4250 | num_printers = cupsGetPrinters(&printers); | |
4251 | ||
4252 | ... | |
4253 | ||
4254 | if (num_printers > 0) | |
4255 | { | |
4256 | for (i = 0; i < 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> | |
4275 | const char * | |
4276 | cupsLangDefault(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 | |
4286 | language. The default language is defined by the <CODE>LANG</CODE> environment | |
4287 | variable. If the specified language cannot be located then the POSIX (English) | |
4288 | locale is used. | |
4289 | ||
4290 | <P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with the | |
4291 | language structure when you are done. | |
4292 | ||
4293 | <H3>Example</H3> | |
4294 | ||
4295 | <PRE> | |
4296 | #include <cups/language.h> | |
4297 | ||
4298 | <A HREF="#cups_lang_t">cups_lang_t</A> *language; | |
4299 | ... | |
4300 | ||
4301 | language = cupsLangDefault(); | |
4302 | ||
4303 | ... | |
4304 | ||
4305 | cupsLangFree(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> | |
4323 | char * | |
4324 | cupsLangEncoding(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 | |
4347 | specified language, e.g. "iso-8859-1", "utf-8", etc. | |
4348 | ||
4349 | <H3>Example</H3> | |
4350 | ||
4351 | <PRE> | |
4352 | #include <cups/language.h> | |
4353 | ||
4354 | <A HREF="#cups_lang_t">cups_lang_t</A> *language; | |
4355 | char *encoding; | |
4356 | ... | |
4357 | ||
4358 | language = cupsLangDefault(); | |
4359 | encoding = cupsLangEncoding(language); | |
4360 | ... | |
4361 | ||
4362 | cupsLangFree(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> | |
4380 | void | |
4381 | cupsLangFlush(void); | |
4382 | </PRE> | |
4383 | ||
4384 | <H3>Description</H3> | |
4385 | ||
4386 | <P><CODE>cupsLangFlush()</CODE> frees all language structures that have been | |
4387 | allocated. | |
4388 | ||
4389 | <H3>Example</H3> | |
4390 | ||
4391 | <PRE> | |
4392 | #include <cups/language.h> | |
4393 | ||
4394 | ... | |
4395 | ||
4396 | cupsLangFlush(); | |
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> | |
4414 | void | |
4415 | cupsLangFree(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 <cups/language.h> | |
4439 | ||
4440 | <A HREF="#cups_lang_t">cups_lang_t</A> *language; | |
4441 | ... | |
4442 | ||
4443 | cupsLangFree(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> | |
4461 | cups_lang_t * | |
4462 | cupsLangGet(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 | |
4485 | locale. If the locale is not defined then the POSIX (English) locale is | |
4486 | substituted. | |
4487 | ||
4488 | <H3>Example</H3> | |
4489 | ||
4490 | <PRE> | |
4491 | #include <cups/language.h> | |
4492 | ||
4493 | <A HREF="#cups_lang_t">cups_lang_t</A> *language; | |
4494 | ||
4495 | ... | |
4496 | ||
4497 | language = cupsLangGet("fr"); | |
4498 | ||
4499 | ... | |
4500 | ||
4501 | cupsLangFree(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> | |
4519 | char * | |
4520 | cupsLangString(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 | |
4544 | not defined. | |
4545 | ||
4546 | <H3>Description</H3> | |
4547 | ||
4548 | <P><CODE>cupsLangString()</CODE> returns a pointer to the specified message | |
4549 | string in the specified language. | |
4550 | ||
4551 | <H3>Example</H3> | |
4552 | ||
4553 | <PRE> | |
4554 | #include <cups/language.h> | |
4555 | ||
4556 | <A HREF="#cups_lang_t">cups_lang_t</A> *language; | |
4557 | char *s; | |
4558 | ... | |
4559 | ||
4560 | language = cupsLangGet("fr"); | |
4561 | ||
4562 | s = cupsLangString(language, CUPS_MSG_YES); | |
4563 | ||
4564 | ... | |
4565 | ||
4566 | cupsLangFree(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> | |
4584 | ipp_status_t | |
4585 | cupsLastError(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. | |
4595 | If 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 <cups/cups.h> | |
4602 | ||
4603 | ipp_status_t status; | |
4604 | ||
4605 | ... | |
4606 | ||
4607 | status = 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> | |
4622 | int | |
4623 | cupsMarkOptions(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 | |
4656 | handles mapping of IPP option names and values to PPD option names. | |
4657 | ||
4658 | <H3>Example</H3> | |
4659 | ||
4660 | <PRE> | |
4661 | #include <cups/cups.h> | |
4662 | ||
4663 | int 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 | ||
4669 | cupsMarkOptions(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> | |
4686 | int | |
4687 | cupsParseOptions(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 | |
4720 | or more options of the form "name=value", "name", or "noname". It can | |
4721 | be called multiple times to combine the options from several strings. | |
4722 | ||
4723 | <H3>Example</H3> | |
4724 | ||
4725 | <PRE> | |
4726 | #include <cups/cups.h> | |
4727 | ||
4728 | int num_options; | |
4729 | <A HREF="#cups_options_t">cups_option_t</A> *options; | |
4730 | ||
4731 | ... | |
4732 | ||
4733 | num_options = 0; | |
4734 | options = (cups_option_t *)0; | |
4735 | num_options = cupsParseOptions(argv[5], num_options, &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> | |
4752 | int | |
4753 | cupsPrintFile(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 | |
4796 | class for printing. If the job cannot be printed the error code can be | |
4797 | found by calling <CODE>cupsLastError()</CODE>. | |
4798 | ||
4799 | <H3>Example</H3> | |
4800 | ||
4801 | <PRE> | |
4802 | #include <cups/cups.h> | |
4803 | ||
4804 | int num_options; | |
4805 | <A HREF="#cups_option_t">cups_option_t</A> *options; | |
4806 | int jobid; | |
4807 | ||
4808 | ... | |
4809 | ||
4810 | jobid = 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> | |
4827 | int | |
4828 | cupsPrintFiles(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 | |
4876 | printer or class for printing. If the job cannot be printed the error | |
4877 | code can be found by calling <CODE>cupsLastError()</CODE>. | |
4878 | ||
4879 | <H3>Example</H3> | |
4880 | ||
4881 | <PRE> | |
4882 | #include <cups/cups.h> | |
4883 | ||
4884 | int num_files; | |
4885 | const char *files[100]; | |
4886 | int num_options; | |
4887 | <A HREF="#cups_option_t">cups_option_t</A> *options; | |
4888 | int jobid; | |
4889 | ||
4890 | ... | |
4891 | ||
4892 | jobid = 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> | |
4909 | void | |
4910 | cupsRasterClose(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 <cups/raster.h> | |
4934 | ||
4935 | <A HREF="#cups_raster_t">cups_raster_t</A> *ras; | |
4936 | ||
4937 | ... | |
4938 | ||
4939 | cupsRasterClose(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> | |
4957 | cups_raster_t * | |
4958 | cupsRasterOpen(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 <cups/raster.h> | |
4992 | ||
4993 | <A HREF="#cups_raster_t">cups_raster_t</A> *ras; | |
4994 | ||
4995 | ... | |
4996 | ||
4997 | ras = 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> | |
5015 | unsigned | |
5016 | cupsRasterReadHeader(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 | |
5044 | raster stream. | |
5045 | ||
5046 | <H3>Example</H3> | |
5047 | ||
5048 | <PRE> | |
5049 | #include <cups/raster.h> | |
5050 | ||
5051 | int 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; | |
5054 | unsigned char pixels[8192]; | |
5055 | ... | |
5056 | ||
5057 | while (cupsRasterReadHeader(ras, &header)) | |
5058 | { | |
5059 | ... | |
5060 | ||
5061 | for (line = 0; line < 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> | |
5085 | unsigned | |
5086 | cupsRasterReadPixels(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 | |
5119 | raster stream. | |
5120 | ||
5121 | <H3>Example</H3> | |
5122 | ||
5123 | <PRE> | |
5124 | #include <cups/raster.h> | |
5125 | ||
5126 | int 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; | |
5129 | unsigned char pixels[8192]; | |
5130 | ... | |
5131 | ||
5132 | while (cupsRasterReadHeader(ras, &header)) | |
5133 | { | |
5134 | ... | |
5135 | ||
5136 | for (line = 0; line < 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> | |
5160 | unsigned | |
5161 | cupsRasterWriteHeader(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 | |
5189 | a raster stream. | |
5190 | ||
5191 | <H3>Example</H3> | |
5192 | ||
5193 | <PRE> | |
5194 | #include <cups/raster.h> | |
5195 | ||
5196 | int 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; | |
5199 | unsigned char pixels[8192]; | |
5200 | ... | |
5201 | ||
5202 | cupsRasterWriteHeader(ras, &header); | |
5203 | ||
5204 | for (line = 0; line < 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> | |
5227 | unsigned | |
5228 | cupsRasterWritePixels(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 | |
5261 | raster stream. | |
5262 | ||
5263 | <H3>Example</H3> | |
5264 | ||
5265 | <PRE> | |
5266 | #include <cups/raster.h> | |
5267 | ||
5268 | int 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; | |
5271 | unsigned char pixels[8192]; | |
5272 | ... | |
5273 | ||
5274 | cupsRasterWriteHeader(ras, &header); | |
5275 | ||
5276 | for (line = 0; line < 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> | |
5299 | const char * | |
5300 | cupsServer(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. | |
5310 | The server name is stored in a static location and will be overwritten with | |
5311 | every 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 <cups/cups.h> | |
5330 | ||
5331 | const char *server; | |
5332 | ||
5333 | server = 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> | |
5351 | void | |
5352 | cupsSetDests(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 | |
5376 | disk. If the current UID is 0, the destinations are saved in the | |
5377 | <VAR>/etc/cups/lpoptions</VAR> file, otherwise they are saved | |
5378 | in the <VAR>~/.lpoptions</VAR> file. This function is typically used | |
5379 | to save the default options and instances that are set by the user. | |
5380 | ||
5381 | <H3>Example</H3> | |
5382 | ||
5383 | <PRE> | |
5384 | #include <cups/cups.h> | |
5385 | ||
5386 | int num_dests; | |
5387 | <A HREF="#cups_dest_t">cups_dest_t</A> *dests; | |
5388 | ||
5389 | ... | |
5390 | ||
5391 | cupsSetDests(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> | |
5405 | void | |
5406 | cupsSetEncryption(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 | |
5425 | use when connecting with the print server. | |
5426 | ||
5427 | <H3>Example</H3> | |
5428 | ||
5429 | <PRE> | |
5430 | #include <cups/cups.h> | |
5431 | ||
5432 | cupsSetEncryption(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> | |
5446 | void | |
5447 | cupsSetPasswordCB(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 | |
5466 | asking the user for a password. The callback function must accept a single | |
5467 | character string pointer (the prompt string) and return <CODE>NULL</CODE> | |
5468 | if the user did not enter a password string or a pointer to the password | |
5469 | string otherwise. | |
5470 | ||
5471 | <H3>Example</H3> | |
5472 | ||
5473 | <PRE> | |
5474 | #include <cups/cups.h> | |
5475 | ||
5476 | const char * | |
5477 | my_password_cb(const char *prompt) | |
5478 | { | |
5479 | return (getpass(prompt)); | |
5480 | } | |
5481 | ||
5482 | ... | |
5483 | ||
5484 | char *password; | |
5485 | ||
5486 | ... | |
5487 | ||
5488 | cupsSetPasswordCB(my_password_cb); | |
5489 | password = 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> | |
5506 | void | |
5507 | cupsSetServer(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 | |
5526 | the CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>, | |
5527 | the default server is used. | |
5528 | ||
5529 | <H3>Example</H3> | |
5530 | ||
5531 | <PRE> | |
5532 | #include <cups/cups.h> | |
5533 | ||
5534 | cupsSetServer("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> | |
5551 | void | |
5552 | cupsSetUser(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. | |
5571 | If the <CODE>user</CODE> argument is <CODE>NULL</CODE> then the current | |
5572 | login user is used. | |
5573 | ||
5574 | <H3>Example</H3> | |
5575 | ||
5576 | <PRE> | |
5577 | #include <cups/cups.h> | |
5578 | ||
5579 | ... | |
5580 | ||
5581 | cupsSetUser("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> | |
5598 | int | |
5599 | cupsTempFd(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 <cups/cups.h> | |
5634 | ||
5635 | int fd; | |
5636 | char filename[256]; | |
5637 | ||
5638 | fd = 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> | |
5652 | char * | |
5653 | cupsTempFile(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 <cups/cups.h> | |
5688 | ||
5689 | char filename[256]; | |
5690 | ||
5691 | cupsTempFile(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> | |
5705 | const char * | |
5706 | cupsUser(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 | |
5712 | undefined. | |
5713 | ||
5714 | <H3>Description</H3> | |
5715 | ||
5716 | <P><CODE>cupsUser()</CODE> returns the name associated with the current | |
5717 | user ID as reported by the <CODE>getuid()</CODE> system call. | |
5718 | ||
5719 | <H3>Example</H3> | |
5720 | ||
5721 | <PRE> | |
5722 | #include <cups/cups.h> | |
5723 | ||
5724 | const char *user; | |
5725 | ||
5726 | user = 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> | |
5741 | void | |
5742 | httpBlocking(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 | |
5767 | HTTP connection. By default HTTP connections will block (stop) the client | |
5768 | program until data is available or can be sent to the server. | |
5769 | ||
5770 | <H3>Example</H3> | |
5771 | ||
5772 | <PRE> | |
5773 | #include <cups/http.h> | |
5774 | ||
5775 | http_t *http; | |
5776 | ||
5777 | http = httpConnect("server", port); | |
5778 | httpBlocking(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> | |
5792 | int | |
5793 | httpCheck(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 | |
5816 | pending on an HTTP connection. | |
5817 | ||
5818 | <H3>Example</H3> | |
5819 | ||
5820 | <PRE> | |
5821 | #include <cups/http.h> | |
5822 | ||
5823 | http_t *http; | |
5824 | ||
5825 | if (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> | |
5844 | void | |
5845 | httpClearFields(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 | |
5864 | for the HTTP connection. | |
5865 | ||
5866 | <H3>Example</H3> | |
5867 | ||
5868 | <PRE> | |
5869 | #include <cups/http.h> | |
5870 | ||
5871 | http_t *http; | |
5872 | ||
5873 | httpClearFields(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> | |
5888 | void | |
5889 | httpClose(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 <cups/http.h> | |
5913 | ||
5914 | http_t *http; | |
5915 | ||
5916 | httpClose(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> | |
5929 | http_t * | |
5930 | httpConnect(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 | |
5954 | not be made. | |
5955 | ||
5956 | <H3>Description</H3> | |
5957 | ||
5958 | <P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to the | |
5959 | specified server and port. | |
5960 | ||
5961 | <H3>Example</H3> | |
5962 | ||
5963 | <PRE> | |
5964 | #include <cups/http.h> | |
5965 | ||
5966 | <A HREF="#http_t">http_t</A> *http; | |
5967 | ||
5968 | http = 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> | |
5987 | http_t * | |
5988 | httpConnectEncrypt(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 | |
6017 | not be made. | |
6018 | ||
6019 | <H3>Description</H3> | |
6020 | ||
6021 | <P>The <CODE>httpConnectEncrypt()</CODE> function opens a HTTP | |
6022 | connection to the specified server, port, and encryption. | |
6023 | ||
6024 | <H3>Example</H3> | |
6025 | ||
6026 | <PRE> | |
6027 | #include <cups/http.h> | |
6028 | ||
6029 | <A HREF="#http_t">http_t</A> *http; | |
6030 | ||
6031 | http = 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> | |
6050 | char * | |
6051 | httpDecode64(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 | |
6079 | to the original string. | |
6080 | ||
6081 | <H3>Example</H3> | |
6082 | ||
6083 | <PRE> | |
6084 | #include <cups/http.h> | |
6085 | ||
6086 | char encoded_string[255]; | |
6087 | char original_string[255]; | |
6088 | ||
6089 | httpDecode64(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> | |
6102 | int | |
6103 | httpDelete(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 | |
6131 | the server. | |
6132 | ||
6133 | <H3>Example</H3> | |
6134 | ||
6135 | <PRE> | |
6136 | #include <cups/http.h> | |
6137 | ||
6138 | http_t *http; | |
6139 | ||
6140 | httpDelete(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> | |
6155 | char * | |
6156 | httpEncode64(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 | |
6184 | to the original string. | |
6185 | ||
6186 | <H3>Example</H3> | |
6187 | ||
6188 | <PRE> | |
6189 | #include <cups/http.h> | |
6190 | ||
6191 | char encoded_string[255]; | |
6192 | char original_string[255]; | |
6193 | ||
6194 | httpEncode64(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> | |
6207 | int | |
6208 | httpEncryption(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 | |
6236 | connection. | |
6237 | ||
6238 | <H3>Example</H3> | |
6239 | ||
6240 | <PRE> | |
6241 | #include <cups/http.h> | |
6242 | ||
6243 | <A HREF="#http_t">http_t</A> *http; | |
6244 | ||
6245 | ... | |
6246 | ||
6247 | httpEncryption(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> | |
6261 | int | |
6262 | httpError(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 | |
6285 | on the HTTP connection. | |
6286 | ||
6287 | <H3>Example</H3> | |
6288 | ||
6289 | <PRE> | |
6290 | #include <cups/http.h> | |
6291 | ||
6292 | http_t *http; | |
6293 | ||
6294 | if (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> | |
6310 | void | |
6311 | httpFlush(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 | |
6330 | a GET or POST operation. | |
6331 | ||
6332 | <H3>Example</H3> | |
6333 | ||
6334 | <PRE> | |
6335 | #include <cups/http.h> | |
6336 | ||
6337 | http_t *http; | |
6338 | ||
6339 | httpFlush(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> | |
6352 | int | |
6353 | httpGet(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 | |
6381 | server. | |
6382 | ||
6383 | <H3>Example</H3> | |
6384 | ||
6385 | <PRE> | |
6386 | #include <cups/http.h> | |
6387 | ||
6388 | <A HREF="#http_t">http_t</A> *http; | |
6389 | ||
6390 | httpGet(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> | |
6405 | char * | |
6406 | httpGets(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 | |
6439 | the HTTP connection. It is not normally used by a client program. | |
6440 | ||
6441 | <H3>Example</H3> | |
6442 | ||
6443 | <PRE> | |
6444 | #include <cups/http.h> | |
6445 | ||
6446 | <A HREF="#http_t">http_t</A> *http; | |
6447 | char line[1024]; | |
6448 | ||
6449 | if (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> | |
6466 | const char * | |
6467 | httpGetDateString(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 | |
6486 | the specified UNIX time value. | |
6487 | ||
6488 | <H3>Description</H3> | |
6489 | ||
6490 | <P>The <CODE>httpGetDateString()</CODE> function generates a date/time string | |
6491 | suitable for HTTP requests from a UNIX time value. | |
6492 | ||
6493 | <H3>Example</H3> | |
6494 | ||
6495 | <PRE> | |
6496 | #include <cups/http.h> | |
6497 | ||
6498 | puts(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> | |
6511 | time_t | |
6512 | httpGetDateTime(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 | |
6535 | date/time string to a UNIX time value. | |
6536 | ||
6537 | <H3>Example</H3> | |
6538 | ||
6539 | <PRE> | |
6540 | #include <cups/http.h> | |
6541 | ||
6542 | printf("%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> | |
6555 | const char * | |
6556 | httpGetField(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 | |
6584 | the specified HTTP field. | |
6585 | ||
6586 | <H3>Example</H3> | |
6587 | ||
6588 | <PRE> | |
6589 | #include <cups/http.h> | |
6590 | ||
6591 | <A HREF="#http_t">http_t</A> *http; | |
6592 | ||
6593 | httpGet(http, "/some/uri"); | |
6594 | while (httpUpdate(http) == HTTP_CONTINUE); | |
6595 | ||
6596 | puts(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> | |
6611 | struct hostent * | |
6612 | httpGetHostByName(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 | |
6631 | containing 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 | |
6637 | and IP addresses. | |
6638 | ||
6639 | <H3>Example</H3> | |
6640 | ||
6641 | <PRE> | |
6642 | #include <cups/http.h> | |
6643 | ||
6644 | struct hostent *hostaddr; | |
6645 | ||
6646 | hostaddr = 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> | |
6655 | int | |
6656 | httpGetLength(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 <cups/http.h> | |
6684 | ||
6685 | <A HREF="#http_t">http_t</A> *http; | |
6686 | ||
6687 | ... | |
6688 | ||
6689 | printf("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> | |
6704 | const char * | |
6705 | httpGetSubField(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 | |
6743 | from the specified HTTP field. The destination string buffer must be at | |
6744 | least <CODE>HTTP_MAX_VALUE</CODE> bytes in length. | |
6745 | ||
6746 | <H3>Example</H3> | |
6747 | ||
6748 | <PRE> | |
6749 | #include <cups/http.h> | |
6750 | ||
6751 | <A HREF="#http_t">http_t</A> *http; | |
6752 | char value[HTTP_MAX_VALUE]; | |
6753 | ||
6754 | httpGet(http, "/some/uri"); | |
6755 | while (httpUpdate(http) == HTTP_CONTINUE); | |
6756 | ||
6757 | puts(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> | |
6772 | int | |
6773 | httpHead(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 | |
6801 | server. | |
6802 | ||
6803 | <H3>Example</H3> | |
6804 | ||
6805 | <PRE> | |
6806 | #include <cups/http.h> | |
6807 | ||
6808 | http_t *http; | |
6809 | ||
6810 | httpHead(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> | |
6825 | void httpInitialize(void); | |
6826 | </PRE> | |
6827 | ||
6828 | <H3>Description</H3> | |
6829 | ||
6830 | <P>The <CODE>httpInitialize()</CODE> function initializes the networking | |
6831 | code as needed by the underlying platform. It is called automatically by | |
6832 | the <CODE>httpConnect()</CODE> function. | |
6833 | ||
6834 | <H3>Example</H3> | |
6835 | ||
6836 | <PRE> | |
6837 | #include <cups/http.h> | |
6838 | ||
6839 | httpInitialize(); | |
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> | |
6852 | char * | |
6853 | httpMD5(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, | |
6891 | realm, and password as required by the HTTP Digest specification. | |
6892 | ||
6893 | <H3>Example</H3> | |
6894 | ||
6895 | <PRE> | |
6896 | #include <cups/http.h> | |
6897 | ||
6898 | char md5[33]; | |
6899 | ||
6900 | ... | |
6901 | ||
6902 | httpMD5("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> | |
6917 | char * | |
6918 | httpMD5Final(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 | |
6956 | to the specified MD5 sum. | |
6957 | ||
6958 | <H3>Example</H3> | |
6959 | ||
6960 | <PRE> | |
6961 | #include <cups/http.h> | |
6962 | ||
6963 | char md5[33]; | |
6964 | ||
6965 | ... | |
6966 | ||
6967 | httpMD5Final("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> | |
6982 | char * | |
6983 | httpMD5String(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 <cups/http.h> | |
7016 | ||
7017 | md5_byte_t sum[16]; | |
7018 | char md5[33]; | |
7019 | ||
7020 | ... | |
7021 | ||
7022 | httpMD5String(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> | |
7037 | int | |
7038 | httpOptions(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 | |
7066 | server. | |
7067 | ||
7068 | <H3>Example</H3> | |
7069 | ||
7070 | <PRE> | |
7071 | #include <cups/http.h> | |
7072 | ||
7073 | http_t *http; | |
7074 | ||
7075 | httpOptions(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> | |
7090 | int | |
7091 | httpPost(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 | |
7119 | server. | |
7120 | ||
7121 | <H3>Example</H3> | |
7122 | ||
7123 | <PRE> | |
7124 | #include <cups/http.h> | |
7125 | ||
7126 | http_t *http; | |
7127 | ||
7128 | httpPost(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> | |
7143 | int | |
7144 | httpPrintf(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 | |
7173 | HTTP connection. It is normally only used by the CUPS API and scheduler. | |
7174 | ||
7175 | <H3>Example</H3> | |
7176 | ||
7177 | <PRE> | |
7178 | #include <cups/http.h> | |
7179 | ||
7180 | http_t *http; | |
7181 | ||
7182 | httpPrintf(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> | |
7195 | int | |
7196 | httpPut(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 | |
7224 | server. | |
7225 | ||
7226 | <H3>Example</H3> | |
7227 | ||
7228 | <PRE> | |
7229 | #include <cups/http.h> | |
7230 | ||
7231 | http_t *http; | |
7232 | ||
7233 | httpDelete(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> | |
7248 | int | |
7249 | httpRead(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, | |
7282 | possibly the result of a GET or POST request. | |
7283 | ||
7284 | <H3>Example</H3> | |
7285 | ||
7286 | <PRE> | |
7287 | #include <cups/http.h> | |
7288 | ||
7289 | http_t *http; | |
7290 | char buffer[1024]; | |
7291 | int bytes; | |
7292 | ||
7293 | httpGet(http, "/"); | |
7294 | while (httpUpdate(http) != HTTP_CONTINUE); | |
7295 | while ((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> | |
7313 | int | |
7314 | httpReconnect(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. | |
7337 | This is usually done automatically if the HTTP functions detect that the | |
7338 | server connection has terminated. | |
7339 | ||
7340 | <H3>Example</H3> | |
7341 | ||
7342 | <PRE> | |
7343 | #include <cups/http.h> | |
7344 | ||
7345 | http_t *http; | |
7346 | ||
7347 | httpReconnect(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> | |
7360 | void | |
7361 | httpSeparate(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 | |
7406 | its component parts. The method, username, hostname, and resource strings should | |
7407 | be at least <CODE>HTTP_MAX_URI</CODE> characters long to avoid potential | |
7408 | buffer overflow problems. | |
7409 | ||
7410 | <H3>Example</H3> | |
7411 | ||
7412 | <PRE> | |
7413 | char uri[HTTP_MAX_URI]; | |
7414 | char method[HTTP_MAX_URI]; | |
7415 | char username[HTTP_MAX_URI]; | |
7416 | char host[HTTP_MAX_URI]; | |
7417 | char resource[HTTP_MAX_URI]; | |
7418 | int port; | |
7419 | ||
7420 | ... | |
7421 | ||
7422 | httpSeparate(uri, method, username, host, &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> | |
7435 | void | |
7436 | httpSetField(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 | |
7465 | the specified HTTP field. | |
7466 | ||
7467 | <H3>Example</H3> | |
7468 | ||
7469 | <PRE> | |
7470 | #include <cups/http.h> | |
7471 | ||
7472 | http_t *http; | |
7473 | ||
7474 | httpSetField(http, HTTP_FIELD_AUTHORIZATION, "Basic dfdr34453454325")); | |
7475 | httpGet(http, "/some/uri"); | |
7476 | while (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> | |
7490 | const char * | |
7491 | httpStatus(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 | |
7514 | associated with the status code. | |
7515 | ||
7516 | <H3>Example</H3> | |
7517 | ||
7518 | <PRE> | |
7519 | #include <cups/http.h> | |
7520 | ||
7521 | <A HREF="#http_t">http_t</A> *http; | |
7522 | ||
7523 | ... | |
7524 | ||
7525 | puts(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> | |
7534 | int | |
7535 | httpTrace(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 | |
7563 | server. | |
7564 | ||
7565 | <H3>Example</H3> | |
7566 | ||
7567 | <PRE> | |
7568 | #include <cups/http.h> | |
7569 | ||
7570 | http_t *http; | |
7571 | ||
7572 | httpTrace(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> | |
7587 | http_status_t | |
7588 | httpUpdate(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. | |
7611 | It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or TRACE | |
7612 | request to finalize the HTTP request and retrieve the request status. | |
7613 | ||
7614 | <P>Since proxies and the current blocking mode can cause the request to | |
7615 | take longer, programs should continue calling <CODE>httpUpdate()<CODE> | |
7616 | until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>. | |
7617 | ||
7618 | <H3>Example</H3> | |
7619 | ||
7620 | <PRE> | |
7621 | #include <cups/http.h> | |
7622 | ||
7623 | http_t *http; | |
7624 | http_status_t status; | |
7625 | ||
7626 | httpGet(http, "/some/uri"); | |
7627 | while ((status = httpUpdate(http)) == HTTP_CONTINUE); | |
7628 | printf("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> | |
7648 | int | |
7649 | httpWrite(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, | |
7682 | possibly the result of a GET or POST request. | |
7683 | ||
7684 | <H3>Example</H3> | |
7685 | ||
7686 | <PRE> | |
7687 | #include <cups/http.h> | |
7688 | ||
7689 | http_t *http; | |
7690 | FILE *fp; | |
7691 | char buffer[1024]; | |
7692 | int bytes; | |
7693 | ||
7694 | httpPost(http, "/"); | |
7695 | ||
7696 | while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) | |
7697 | httpWrite(http, buffer, bytes); | |
7698 | ||
7699 | while (httpUpdate(http) != HTTP_CONTINUE); | |
7700 | ||
7701 | while ((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> | |
7719 | ipp_attribute_t * | |
7720 | ippAddBoolean(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 | |
7754 | created. | |
7755 | ||
7756 | <H3>Description</H3> | |
7757 | ||
7758 | <P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean attribute | |
7759 | value to the specified IPP request. | |
7760 | ||
7761 | <H3>Example</H3> | |
7762 | ||
7763 | <PRE> | |
7764 | #include <cups/ipp.h> | |
7765 | ||
7766 | ipp_t *ipp; | |
7767 | ||
7768 | ippAddBoolean(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> | |
7791 | ipp_attribute_t * | |
7792 | ippAddBooleans(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 | |
7831 | created. | |
7832 | ||
7833 | <H3>Description</H3> | |
7834 | ||
7835 | <P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean | |
7836 | attribute values to the specified IPP request. If the | |
7837 | <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of | |
7838 | <CODE>num_values</CODE> false values is created. | |
7839 | ||
7840 | <H3>Example</H3> | |
7841 | ||
7842 | <PRE> | |
7843 | #include <cups/ipp.h> | |
7844 | ||
7845 | ipp_t *ipp; | |
7846 | char values[10]; | |
7847 | ||
7848 | ippAddBooleans(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> | |
7871 | ipp_attribute_t * | |
7872 | ippAddDate(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 | |
7906 | created. | |
7907 | ||
7908 | <H3>Description</H3> | |
7909 | ||
7910 | <P>The <CODE>ippAddDate()</CODE> function adds a single date-time attribute | |
7911 | value to the specified IPP request. | |
7912 | ||
7913 | <H3>Example</H3> | |
7914 | ||
7915 | <PRE> | |
7916 | #include <cups/ipp.h> | |
7917 | ||
7918 | ipp_t *ipp; | |
7919 | ||
7920 | ippAddDate(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> | |
7945 | ipp_attribute_t * | |
7946 | ippAddInteger(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 | |
7985 | created. | |
7986 | ||
7987 | <H3>Description</H3> | |
7988 | ||
7989 | <P>The <CODE>ippAddInteger()</CODE> function adds a single integer attribute | |
7990 | value to the specified IPP request. | |
7991 | ||
7992 | <H3>Example</H3> | |
7993 | ||
7994 | <PRE> | |
7995 | #include <cups/ipp.h> | |
7996 | ||
7997 | ipp_t *ipp; | |
7998 | ||
7999 | ippAddInteger(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> | |
8022 | ipp_attribute_t * | |
8023 | ippAddIntegers(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 | |
8067 | created. | |
8068 | ||
8069 | <H3>Description</H3> | |
8070 | ||
8071 | <P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer | |
8072 | attribute values to the specified IPP request. If the | |
8073 | <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of | |
8074 | <CODE>num_values</CODE> 0 values is created. | |
8075 | ||
8076 | <H3>Example</H3> | |
8077 | ||
8078 | <PRE> | |
8079 | #include <cups/ipp.h> | |
8080 | ||
8081 | ipp_t *ipp; | |
8082 | int values[100]; | |
8083 | ||
8084 | ippAddIntegers(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> | |
8107 | ipp_attribute_t * | |
8108 | ippAddRange(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 | |
8147 | created. | |
8148 | ||
8149 | <H3>Description</H3> | |
8150 | ||
8151 | <P>The <CODE>ippAddRange()</CODE> function adds a single range attribute | |
8152 | value to the specified IPP request. | |
8153 | ||
8154 | <H3>Example</H3> | |
8155 | ||
8156 | <PRE> | |
8157 | #include <cups/ipp.h> | |
8158 | ||
8159 | ipp_t *ipp; | |
8160 | ||
8161 | ippAddRange(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> | |
8184 | ipp_attribute_t * | |
8185 | ippAddRanges(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 | |
8229 | created. | |
8230 | ||
8231 | <H3>Description</H3> | |
8232 | ||
8233 | <P>The <CODE>ippAddRanges()</CODE> function adds one or more range | |
8234 | attribute values to the specified IPP request. If the | |
8235 | <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of | |
8236 | <CODE>num_values</CODE> 0,0 ranges is created. | |
8237 | ||
8238 | <H3>Example</H3> | |
8239 | ||
8240 | <PRE> | |
8241 | #include <cups/ipp.h> | |
8242 | ||
8243 | ipp_t *ipp; | |
8244 | int lows[2]; | |
8245 | int highs[2]; | |
8246 | ||
8247 | ippAddRanges(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> | |
8270 | ipp_attribute_t * | |
8271 | ippAddResolution(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 | |
8315 | created. | |
8316 | ||
8317 | <H3>Description</H3> | |
8318 | ||
8319 | <P>The <CODE>ippAddResolution()</CODE> function adds a single resolution attribute | |
8320 | value to the specified IPP request. | |
8321 | ||
8322 | <H3>Example</H3> | |
8323 | ||
8324 | <PRE> | |
8325 | #include <cups/ipp.h> | |
8326 | ||
8327 | ipp_t *ipp; | |
8328 | ||
8329 | ippAddBoolean(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> | |
8353 | ipp_attribute_t * | |
8354 | ippAddResolutions(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 | |
8403 | created. | |
8404 | ||
8405 | <H3>Description</H3> | |
8406 | ||
8407 | <P>The <CODE>ippAddResolutions()</CODE> function adds one or more | |
8408 | resolution attribute values to the specified IPP request. If the | |
8409 | <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of | |
8410 | <CODE>num_values</CODE> 0,0 resolutions is created. | |
8411 | ||
8412 | <H3>Example</H3> | |
8413 | ||
8414 | <PRE> | |
8415 | #include <cups/ipp.h> | |
8416 | ||
8417 | ipp_t *ipp; | |
8418 | int xres[5]; | |
8419 | int yres[5]; | |
8420 | ipp_res_t units[5]; | |
8421 | ||
8422 | ippAddBoolean(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> | |
8446 | ipp_attribute_t * | |
8447 | ippAddSeparator(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 | |
8466 | created. | |
8467 | ||
8468 | <H3>Description</H3> | |
8469 | ||
8470 | <P>The <CODE>ippAddSeparator()</CODE> function adds a group separator | |
8471 | to the specified IPP request. | |
8472 | ||
8473 | <H3>Example</H3> | |
8474 | ||
8475 | <PRE> | |
8476 | #include <cups/ipp.h> | |
8477 | ||
8478 | ipp_t *ipp; | |
8479 | ||
8480 | ippAddSeparator(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> | |
8503 | ipp_attribute_t * | |
8504 | ippAddString(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 | |
8548 | created. | |
8549 | ||
8550 | <H3>Description</H3> | |
8551 | ||
8552 | <P>The <CODE>ippAddString()</CODE> function adds a single string attribute | |
8553 | value to the specified IPP request. For <CODE>IPP_TAG_NAMELANG</CODE> and | |
8554 | <CODE>IPP_TAG_TEXTLANG</CODE> strings, the charset value is provided with | |
8555 | the string to identify the string encoding used. Otherwise the charset value | |
8556 | is ignored. | |
8557 | ||
8558 | <H3>Example</H3> | |
8559 | ||
8560 | <PRE> | |
8561 | #include <cups/ipp.h> | |
8562 | ||
8563 | ipp_t *ipp; | |
8564 | ||
8565 | ippAddString(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> | |
8589 | ipp_attribute_t * | |
8590 | ippAddStrings(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 | |
8639 | created. | |
8640 | ||
8641 | <H3>Description</H3> | |
8642 | ||
8643 | <P>The <CODE>ippAddStrings()</CODE> function adds one or more string | |
8644 | attribute values to the specified IPP request. For | |
8645 | <CODE>IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> | |
8646 | strings, the charset value is provided with the strings to identify the | |
8647 | string encoding used. Otherwise the charset value is ignored. If the | |
8648 | <CODE>values</CODE> pointer is <CODE>NULL</CODE> then an array of | |
8649 | <CODE>num_values</CODE> NULL strings is created. | |
8650 | ||
8651 | <H3>Example</H3> | |
8652 | ||
8653 | <PRE> | |
8654 | #include <cups/ipp.h> | |
8655 | ||
8656 | ipp_t *ipp; | |
8657 | char *values[2] = { "one", "two" }; | |
8658 | ||
8659 | ippAddStrings(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> | |
8683 | time_t | |
8684 | ippDateToTime(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 | |
8707 | to a UNIX time value. | |
8708 | ||
8709 | <H3>Example</H3> | |
8710 | ||
8711 | <PRE> | |
8712 | #include <cups/ipp.h> | |
8713 | ||
8714 | ipp_uchar_t date[11]; | |
8715 | ||
8716 | printf("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> | |
8729 | void | |
8730 | ippDelete(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 | |
8749 | request or response. | |
8750 | ||
8751 | <H3>Example</H3> | |
8752 | ||
8753 | <PRE> | |
8754 | #include <cups/ipp.h> | |
8755 | ||
8756 | ipp_t *ipp; | |
8757 | ||
8758 | ippDelete(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> | |
8771 | const char * | |
8772 | ippErrorString(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 | |
8795 | of the IPP error code. | |
8796 | ||
8797 | <H3>Example</H3> | |
8798 | ||
8799 | <PRE> | |
8800 | #include <cups/ipp.h> | |
8801 | ||
8802 | puts(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> | |
8816 | ipp_attribute_t * | |
8817 | ippFindAttribute(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 | |
8852 | attribute. The <CODE>tag</CODE> parameter restricts the search to a specific | |
8853 | value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name. | |
8854 | ||
8855 | <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE> | |
8856 | match the name/text values with or without the language code. | |
8857 | ||
8858 | <H3>Example</H3> | |
8859 | ||
8860 | <PRE> | |
8861 | <A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr; | |
8862 | ||
8863 | attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT); | |
8864 | while (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> | |
8886 | ipp_attribute_t * | |
8887 | ippFindNextAttribute(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 | |
8922 | attribute. The <CODE>tag</CODE> parameter restricts the search to a specific | |
8923 | value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value with the name. | |
8924 | ||
8925 | <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE> | |
8926 | match the name/text values with or without the language code. | |
8927 | ||
8928 | <H3>Example</H3> | |
8929 | ||
8930 | <PRE> | |
8931 | <A HREF="#ipp_attribute_t">ipp_attribute_t</A> *attr; | |
8932 | ||
8933 | attr = ippFindAttribute(response, "printer-state-message", IPP_TAG_TEXT); | |
8934 | while (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> | |
8956 | int | |
8957 | ippLength(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 | |
8980 | response in bytes. | |
8981 | ||
8982 | <H3>Example</H3> | |
8983 | ||
8984 | <PRE> | |
8985 | printf("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> | |
8999 | ipp_t * | |
9000 | ippNew(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 <cups/ipp.h> | |
9015 | ||
9016 | ipp_t *ipp; | |
9017 | ||
9018 | ipp = 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> | |
9031 | int | |
9032 | ippPort(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 | |
9042 | for requests. | |
9043 | ||
9044 | <H3>Example</H3> | |
9045 | ||
9046 | <PRE> | |
9047 | #include <cups/http.h> | |
9048 | #include <cups/ipp.h> | |
9049 | ||
9050 | http_t *http; | |
9051 | ||
9052 | http = 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> | |
9066 | ipp_state_t | |
9067 | ippRead(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 | |
9095 | HTTP 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 <cups/http.h> | |
9102 | #include <cups/ipp.h> | |
9103 | ||
9104 | http_t *http; | |
9105 | ipp_t *ipp; | |
9106 | ipp_state_t status; | |
9107 | ||
9108 | ipp = ippNew(); | |
9109 | ||
9110 | while ((status = ippRead(http, ipp)) != IPP_ERROR) | |
9111 | if (status == IPP_DATA) | |
9112 | break; | |
9113 | ||
9114 | if (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> | |
9130 | void | |
9131 | ippSetPort(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 | |
9150 | for requests. | |
9151 | ||
9152 | <H3>Example</H3> | |
9153 | ||
9154 | <PRE> | |
9155 | #include <cups/http.h> | |
9156 | #include <cups/ipp.h> | |
9157 | ||
9158 | ... | |
9159 | ||
9160 | ippSetPort(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> | |
9173 | ipp_uchar_t * | |
9174 | ippTimeToDate(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 | |
9197 | date-time value. | |
9198 | ||
9199 | <H3>Example</H3> | |
9200 | ||
9201 | <PRE> | |
9202 | #include <cups/ipp.h> | |
9203 | ||
9204 | ipp_uchar_t *date; | |
9205 | ||
9206 | date = 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> | |
9219 | ipp_state_t | |
9220 | ippWrite(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 | |
9248 | HTTP 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 <cups/http.h> | |
9255 | #include <cups/ipp.h> | |
9256 | ||
9257 | http_t *http; | |
9258 | ipp_t *ipp; | |
9259 | ipp_state_t status; | |
9260 | ||
9261 | ipp = ippNew(); | |
9262 | ... add attributes ... | |
9263 | ||
9264 | while ((status = ippWrite(http, ipp)) != IPP_ERROR) | |
9265 | if (status == IPP_DATA) | |
9266 | break; | |
9267 | ||
9268 | if (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> | |
9284 | void | |
9285 | ppdClose(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 | |
9304 | PPD file. | |
9305 | ||
9306 | <H3>Example</H3> | |
9307 | ||
9308 | <PRE> | |
9309 | #include <cups/ppd.h> | |
9310 | ||
9311 | ppd_file_t *ppd; | |
9312 | ||
9313 | ppdClose(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> | |
9328 | int | |
9329 | ppdCollect(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 | |
9362 | specified section, sorts them by their order dependency values, and | |
9363 | returns an array that can be used to emit option commands in the proper | |
9364 | order. It is normally used by the <CODE>ppdEmit*()</CODE> functions. | |
9365 | ||
9366 | <H3>Example</H3> | |
9367 | ||
9368 | <PRE> | |
9369 | #include <cups/ppd.h> | |
9370 | ||
9371 | <A HREF="#ppd_file_t">ppd_file_t</A> *ppd; | |
9372 | int num_choices; | |
9373 | <A HREF="#ppd_choice_t">ppd_choice_t</A> **choices; | |
9374 | ||
9375 | ... | |
9376 | ||
9377 | num_choices = ppdCollect(ppd, PPD_ORDER_JCL, &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> | |
9393 | int | |
9394 | ppdConflicts(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 | |
9417 | with the currently selected options. | |
9418 | ||
9419 | <H3>Example</H3> | |
9420 | ||
9421 | <PRE> | |
9422 | #include <cups/ppd.h> | |
9423 | ||
9424 | ppd_file_t *ppd; | |
9425 | ||
9426 | printf("%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> | |
9442 | int | |
9443 | ppdEmit(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 | |
9476 | commands to the specified file. | |
9477 | ||
9478 | <H3>Example</H3> | |
9479 | ||
9480 | <PRE> | |
9481 | #include <cups/ppd.h> | |
9482 | ||
9483 | ppd_file_t *ppd; | |
9484 | ||
9485 | ppdEmit(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> | |
9498 | int | |
9499 | ppdEmitFd(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 | |
9532 | commands to the specified file descriptor. | |
9533 | ||
9534 | <H3>Example</H3> | |
9535 | ||
9536 | <PRE> | |
9537 | #include <cups/ppd.h> | |
9538 | ||
9539 | ppd_file_t *ppd; | |
9540 | ||
9541 | ppdEmitFd(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> | |
9554 | ppd_choice_t * | |
9555 | ppdFindChoice(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 | |
9583 | data for the specified option. | |
9584 | ||
9585 | <H3>Example</H3> | |
9586 | ||
9587 | <PRE> | |
9588 | #include <cups/ppd.h> | |
9589 | ||
9590 | ppd_file_t *ppd; | |
9591 | ppd_option_t *option; | |
9592 | ppd_choice_t *choice; | |
9593 | ||
9594 | option = ppdFindOption(ppd, "PageSize"); | |
9595 | choice = 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> | |
9609 | ppd_choice_t * | |
9610 | ppdFindMarkedChoice(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 | |
9634 | is not marked. | |
9635 | ||
9636 | <H3>Description</H3> | |
9637 | ||
9638 | <P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to | |
9639 | the marked choice data for the specified option. | |
9640 | ||
9641 | <H3>Example</H3> | |
9642 | ||
9643 | <PRE> | |
9644 | #include <cups/ppd.h> | |
9645 | ||
9646 | ppd_file_t *ppd; | |
9647 | ppd_choice_t *choice; | |
9648 | ||
9649 | choice = 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> | |
9663 | ppd_option_t * | |
9664 | ppdFindOption(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 | |
9692 | data for the specified option. | |
9693 | ||
9694 | <H3>Example</H3> | |
9695 | ||
9696 | <PRE> | |
9697 | #include <cups/ppd.h> | |
9698 | ||
9699 | ppd_file_t *ppd; | |
9700 | ppd_option_t *option; | |
9701 | ||
9702 | option = 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> | |
9716 | int | |
9717 | ppdIsMarked(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 | |
9750 | specified option choice is marked. | |
9751 | ||
9752 | <H3>Example</H3> | |
9753 | ||
9754 | <PRE> | |
9755 | #include <cups/ppd.h> | |
9756 | ||
9757 | ppd_file_t *ppd; | |
9758 | ||
9759 | printf("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> | |
9777 | void | |
9778 | ppdMarkDefaults(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 | |
9797 | choices in the PPD file. | |
9798 | ||
9799 | <H3>Example</H3> | |
9800 | ||
9801 | <PRE> | |
9802 | #include <cups/ppd.h> | |
9803 | ||
9804 | ppd_file_t *ppd; | |
9805 | ||
9806 | ppdMarkDefaults(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> | |
9823 | int | |
9824 | ppdMarkOption(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 | |
9857 | choice. | |
9858 | ||
9859 | <H3>Example</H3> | |
9860 | ||
9861 | <PRE> | |
9862 | #include <cups/ppd.h> | |
9863 | ||
9864 | ppd_file_t *ppd; | |
9865 | ||
9866 | ppdMarkOption(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> | |
9883 | ppd_file_t * | |
9884 | ppdOpen(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 | |
9903 | read. | |
9904 | ||
9905 | <H3>Description</H3> | |
9906 | ||
9907 | <P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the specified | |
9908 | file into memory. | |
9909 | ||
9910 | <H3>Example</H3> | |
9911 | ||
9912 | <PRE> | |
9913 | #include <cups/ppd.h> | |
9914 | ||
9915 | ppd_file_t *ppd; | |
9916 | FILE *file; | |
9917 | ||
9918 | file = fopen("filename.ppd", "rb"); | |
9919 | ppd = ppdOpen(file); | |
9920 | fclose(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> | |
9935 | ppd_file_t * | |
9936 | ppdOpenFd(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 | |
9955 | read. | |
9956 | ||
9957 | <H3>Description</H3> | |
9958 | ||
9959 | <P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the specified | |
9960 | file descriptor into memory. | |
9961 | ||
9962 | <H3>Example</H3> | |
9963 | ||
9964 | <PRE> | |
9965 | #include <cups/ppd.h> | |
9966 | ||
9967 | ppd_file_t *ppd; | |
9968 | int fd; | |
9969 | ||
9970 | fd = open("filename.ppd", O_RDONLY); | |
9971 | ppd = ppdOpenFd(fd); | |
9972 | close(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> | |
9987 | ppd_file_t * | |
9988 | ppdOpenFile(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 | |
10007 | read. | |
10008 | ||
10009 | <H3>Description</H3> | |
10010 | ||
10011 | <P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the named | |
10012 | file into memory. | |
10013 | ||
10014 | <H3>Example</H3> | |
10015 | ||
10016 | <PRE> | |
10017 | #include <cups/ppd.h> | |
10018 | ||
10019 | ppd_file_t *ppd; | |
10020 | ||
10021 | ppd = 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> | |
10036 | float | |
10037 | ppdPageLength(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 | |
10061 | does not exist. | |
10062 | ||
10063 | <H3>Description</H3> | |
10064 | ||
10065 | <P>The <CODE>ppdPageLength()</CODE> function returns the page length of the | |
10066 | specified page size. | |
10067 | ||
10068 | <H3>Example</H3> | |
10069 | ||
10070 | <PRE> | |
10071 | #include <cups/ppd.h> | |
10072 | ||
10073 | ppd_file_t *ppd; | |
10074 | ||
10075 | printf("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> | |
10090 | ppd_size_t * | |
10091 | ppdPageSize(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 | |
10115 | points 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 | |
10120 | specified page size. | |
10121 | ||
10122 | <H3>Example</H3> | |
10123 | ||
10124 | <PRE> | |
10125 | #include <cups/ppd.h> | |
10126 | ||
10127 | ppd_file_t *ppd; | |
10128 | ppd_size_t *size; | |
10129 | ||
10130 | size = ppdPageSize(ppd, "Letter"); | |
10131 | if (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> | |
10153 | float | |
10154 | ppdPageWidth(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 | |
10178 | does not exist. | |
10179 | ||
10180 | <H3>Description</H3> | |
10181 | ||
10182 | <P>The <CODE>ppdPageWidth()</CODE> function returns the page width of the | |
10183 | specified page size. | |
10184 | ||
10185 | <H3>Example</H3> | |
10186 | ||
10187 | <PRE> | |
10188 | #include <cups/ppd.h> | |
10189 | ||
10190 | ppd_file_t *ppd; | |
10191 | ||
10192 | printf("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> |