Load cups into easysw/current.
[thirdparty/cups.git] / doc / spm.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
2 <HTML>
3 <HEAD>
4 <TITLE>CUPS Software Programmers Manual</TITLE>
5 <META NAME="author" CONTENT="Easy Software Products">
6 <META NAME="copyright" CONTENT="Copyright 1997-2003, All Rights Reserved">
7 <META NAME="docnumber" CONTENT="CUPS-SPM-1.2.0">
8 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
9 <STYLE TYPE="text/css"><!--
10 BODY { font-family: serif }
11 H1 { font-family: sans-serif }
12 H2 { font-family: sans-serif }
13 H3 { font-family: sans-serif }
14 H4 { font-family: sans-serif }
15 H5 { font-family: sans-serif }
16 H6 { font-family: sans-serif }
17 SUB { font-size: smaller }
18 SUP { font-size: smaller }
19 PRE { font-family: monospace }
20 --></STYLE>
21 </HEAD>
22 <BODY BGCOLOR="#ffffff">
23 <CENTER><A HREF="#CONTENTS"><IMG SRC="images/cups-large.gif" BORDER="0" WIDTH="431" HEIGHT="511"><BR>
24 <H1>CUPS Software Programmers Manual</H1></A><BR>
25 CUPS-SPM-1.2.0<BR>
26 Easy Software Products<BR>
27 Copyright 1997-2003, All Rights Reserved<BR>
28 </CENTER>
29 <HR>
30 <H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1>
31 <BR>
32 <BR><B><A HREF="#1">Preface</A></B>
33 <UL>
34 <LI><A HREF="#1_1">System Overview</A></LI>
35 <LI><A HREF="#1_2">Document Overview</A></LI>
36 <LI><A HREF="#1_3">Notation Conventions</A></LI>
37 <LI><A HREF="#1_4">Abbreviations</A></LI>
38 <LI><A HREF="#1_5">Other References</A></LI>
39 </UL>
40 <B><A HREF="#OVERVIEW">1 - Printing System Overview</A></B>
41 <UL>
42 <LI><A HREF="#2_1">The Printing Problem</A></LI>
43 <LI><A HREF="#2_2">The Technology</A></LI>
44 <LI><A HREF="#2_3">Jobs</A></LI>
45 <LI><A HREF="#2_4">Classes</A></LI>
46 <LI><A HREF="#2_5">Filters</A></LI>
47 <LI><A HREF="#2_6">Backends</A></LI>
48 <LI><A HREF="#2_7">Printer Drivers</A></LI>
49 <LI><A HREF="#2_8">Networking</A></LI>
50 </UL>
51 <B><A HREF="#CUPS_API">2 - The CUPS API</A></B>
52 <UL>
53 <LI><A HREF="#3_1">The CUPS API Library</A></LI>
54 <UL>
55 <LI><A HREF="#3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></LI>
56 </UL>
57 <LI><A HREF="#3_2">Printing Services</A></LI>
58 <UL>
59 <LI><A HREF="#3_2_1">Include Files</A></LI>
60 <LI><A HREF="#3_2_2">Printing a File</A></LI>
61 <LI><A HREF="#3_2_3">Printing Multiple Files</A></LI>
62 <LI><A HREF="#3_2_4">Cancelling Jobs</A></LI>
63 <LI><A HREF="#3_2_5">Getting the Available Printers and Classes</A></LI>
64 <LI><A HREF="#3_2_6">Printing with Options</A></LI>
65 <LI><A HREF="#3_2_7">Setting Printer Options</A></LI>
66 <LI><A HREF="#3_2_8">Getting Errors</A></LI>
67 <LI><A HREF="#3_2_9">Passwords and Authentication</A></LI>
68 </UL>
69 <LI><A HREF="#3_3">PPD Services</A></LI>
70 <UL>
71 <LI><A HREF="#3_3_1">Include Files</A></LI>
72 <LI><A HREF="#3_3_2">Getting a PPD File for a Printer</A></LI>
73 <LI><A HREF="#3_3_3">Loading a PPD File</A></LI>
74 <LI><A HREF="#3_3_4">Freeing PPD File Information</A></LI>
75 <LI><A HREF="#3_3_5">The PPD File Structure</A></LI>
76 <LI><A HREF="#3_3_6">Marking Options</A></LI>
77 <LI><A HREF="#3_3_7">Checking for Conflicts</A></LI>
78 </UL>
79 </UL>
80 <B><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></B>
81 <UL>
82 <LI><A HREF="#4_1">Overview</A></LI>
83 <UL>
84 <LI><A HREF="#4_1_1">Security Considerations</A></LI>
85 <LI><A HREF="#4_1_2">Users and Groups</A></LI>
86 <LI><A HREF="#4_1_3">Temporary Files</A></LI>
87 <LI><A HREF="#4_1_4">Sending Messages to the User</A></LI>
88 <LI><A HREF="#4_1_5">Page Accounting</A></LI>
89 <LI><A HREF="#4_1_6">Command-Line Arguments</A></LI>
90 <LI><A HREF="#4_1_7">Copy Generation</A></LI>
91 <LI><A HREF="#4_1_8">Environment Variables</A></LI>
92 </UL>
93 <LI><A HREF="#4_2">Dissecting the HP-GL/2 Filter</A></LI>
94 <UL>
95 <LI><A HREF="#4_2_1">Initializing the Filter</A></LI>
96 </UL>
97 <LI><A HREF="#4_3">PostScript Output</A></LI>
98 </UL>
99 <B><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></B>
100 <UL>
101 <LI><A HREF="#5_1">Overview</A></LI>
102 <UL>
103 <LI><A HREF="#5_1_1">CUPS Raster Data</A></LI>
104 <LI><A HREF="#5_1_2">Page Accounting</A></LI>
105 <LI><A HREF="#5_1_3">Color Management</A></LI>
106 <LI><A HREF="#5_1_4">Device and Bitmap Variables</A></LI>
107 </UL>
108 <LI><A HREF="#5_2">Dissecting the HP-PCL Driver</A></LI>
109 <UL>
110 <LI><A HREF="#5_2_1">PPD Files</A></LI>
111 <LI><A HREF="#5_2_2">Reading Raster Data</A></LI>
112 </UL>
113 </UL>
114 <B><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></B>
115 <UL>
116 <LI><A HREF="#6_1">Overview</A></LI>
117 <UL>
118 <LI><A HREF="#6_1_1">Security Considerations</A></LI>
119 <LI><A HREF="#6_1_2">Command-Line Arguments</A></LI>
120 <LI><A HREF="#6_1_3">Copy Generation</A></LI>
121 <LI><A HREF="#6_1_4">Page Accounting</A></LI>
122 <LI><A HREF="#6_1_5">Exclusive Access</A></LI>
123 <LI><A HREF="#6_1_6">Retries</A></LI>
124 </UL>
125 <LI><A HREF="#6_2">Dissecting the Serial Port Backend</A></LI>
126 <UL>
127 <LI><A HREF="#6_2_1">Supporting Device Discovery</A></LI>
128 <LI><A HREF="#6_2_2">Opening the Serial Port</A></LI>
129 <LI><A HREF="#6_2_3">Writing Data to the Port</A></LI>
130 <LI><A HREF="#6_2_4">Finishing Up</A></LI>
131 </UL>
132 </UL>
133 <B><A HREF="#LICENSE">A - Software License Agreement</A></B>
134 <UL>
135 <LI><A HREF="#7_1">Common UNIX Printing System License Agreement</A></LI>
136 <UL>
137 <LI><A HREF="#7_1_1">Introduction</A></LI>
138 <LI><A HREF="#7_1_2">License Exceptions</A></LI>
139 <LI><A HREF="#7_1_3">Trademarks</A></LI>
140 <LI><A HREF="#7_1_4">Binary Distribution Rights</A></LI>
141 <LI><A HREF="#7_1_5">Support</A></LI>
142 </UL>
145 </UL>
146 <B><A HREF="#CONSTANTS">B - Constants</A></B>
147 <UL>
148 <LI><A HREF="#8_1">CUPS Constants</A></LI>
149 <UL>
150 <LI><A HREF="#8_1_1">Version Number</A></LI>
151 <LI><A HREF="#8_1_2">Printer Capabilities</A></LI>
152 <LI><A HREF="#8_1_3">Encodings</A></LI>
153 </UL>
154 <LI><A HREF="#8_2">HTTP Constants</A></LI>
155 <UL>
156 <LI><A HREF="#8_2_1">Limits</A></LI>
157 <LI><A HREF="#8_2_2">Status Codes</A></LI>
158 <LI><A HREF="#8_2_3">Fields</A></LI>
159 </UL>
160 <LI><A HREF="#8_3">IPP Constants</A></LI>
161 <UL>
162 <LI><A HREF="#8_3_1">Limits</A></LI>
163 <LI><A HREF="#8_3_2">Tags</A></LI>
164 <LI><A HREF="#8_3_3">Resolution Units</A></LI>
165 <LI><A HREF="#8_3_4">Finishings</A></LI>
166 <LI><A HREF="#8_3_5">Orientations</A></LI>
167 <LI><A HREF="#8_3_6">Qualities</A></LI>
168 <LI><A HREF="#8_3_7">Job States</A></LI>
169 <LI><A HREF="#8_3_8">Printer States</A></LI>
170 <LI><A HREF="#8_3_9">Operations</A></LI>
171 <LI><A HREF="#8_3_10">Status Codes</A></LI>
172 </UL>
173 <LI><A HREF="#8_4">PPD Constants</A></LI>
174 <UL>
175 <LI><A HREF="#8_4_1">PPD Format Version</A></LI>
176 <LI><A HREF="#8_4_2">PPD User-Interface Types</A></LI>
177 <LI><A HREF="#8_4_3">PPD Sections</A></LI>
178 <LI><A HREF="#8_4_4">PPD Colorspaces</A></LI>
179 </UL>
180 <LI><A HREF="#8_5">Raster Constants</A></LI>
181 <UL>
182 <LI><A HREF="#8_5_1">Raster Sync Words</A></LI>
183 <LI><A HREF="#8_5_2">Raster Stream Modes</A></LI>
184 <LI><A HREF="#8_5_3">Raster Boolean Constants</A></LI>
185 <LI><A HREF="#8_5_4">Raster Jog Values</A></LI>
186 <LI><A HREF="#8_5_5">Raster Orientation Values</A></LI>
187 <LI><A HREF="#8_5_6">Raster CutMedia Values</A></LI>
188 <LI><A HREF="#8_5_7">Raster AdvanceMedia Values</A></LI>
189 <LI><A HREF="#8_5_8">Raster LeadingEdge Values</A></LI>
190 <LI><A HREF="#8_5_9">Raster Color Order Values</A></LI>
191 <LI><A HREF="#8_5_10">Raster Colorspace Values</A></LI>
192 </UL>
193 </UL>
194 <B><A HREF="#STRUCTURES">C - Structures</A></B>
195 <UL>
196 <LI><A HREF="#9_1">CUPS Structures</A></LI>
197 <UL>
198 <LI><A HREF="#cups_dest_t">CUPS Destinations</A></LI>
199 <LI><A HREF="#cups_job_t">CUPS Jobs</A></LI>
200 <LI><A HREF="#cups_lang_t">CUPS Messages</A></LI>
201 <LI><A HREF="#cups_option_t">CUPS Options</A></LI>
202 </UL>
203 <LI><A HREF="#9_2">Networking Structures</A></LI>
204 <UL>
205 <LI><A HREF="#http_t">HTTP State</A></LI>
206 <LI><A HREF="#ipp_t">IPP State</A></LI>
207 </UL>
208 <LI><A HREF="#9_3">Raster Structures</A></LI>
209 <UL>
210 <LI><A HREF="#cups_raster_header_t">Raster Page Header</A></LI>
211 </UL>
212 </UL>
213 <B><A HREF="#FUNCTIONS">D - Functions</A></B>
214 <UL>
215 <LI><A HREF="#cupsAddDest">cupsAddDest()</A></LI>
216 <UL>
217 <LI><A HREF="#10_1_1">Usage</A></LI>
218 <LI><A HREF="#10_1_2">Arguments</A></LI>
219 <LI><A HREF="#10_1_3">Returns</A></LI>
220 <LI><A HREF="#10_1_4">Description</A></LI>
221 <LI><A HREF="#10_1_5">Example</A></LI>
222 <LI><A HREF="#10_1_6">See Also</A></LI>
223 </UL>
224 <LI><A HREF="#cupsAddOption">cupsAddOption()</A></LI>
225 <UL>
226 <LI><A HREF="#10_2_1">Usage</A></LI>
227 <LI><A HREF="#10_2_2">Arguments</A></LI>
228 <LI><A HREF="#10_2_3">Returns</A></LI>
229 <LI><A HREF="#10_2_4">Description</A></LI>
230 <LI><A HREF="#10_2_5">Example</A></LI>
231 <LI><A HREF="#10_2_6">See Also</A></LI>
232 </UL>
233 <LI><A HREF="#cupsCancelJob">cupsCancelJob()</A></LI>
234 <UL>
235 <LI><A HREF="#10_3_1">Usage</A></LI>
236 <LI><A HREF="#10_3_2">Arguments</A></LI>
237 <LI><A HREF="#10_3_3">Returns</A></LI>
238 <LI><A HREF="#10_3_4">Description</A></LI>
239 <LI><A HREF="#10_3_5">Example</A></LI>
240 <LI><A HREF="#10_3_6">See Also</A></LI>
241 </UL>
242 <LI><A HREF="#cupsDoFileRequest">cupsDoFileRequest()</A></LI>
243 <UL>
244 <LI><A HREF="#10_4_1">Usage</A></LI>
245 <LI><A HREF="#10_4_2">Arguments</A></LI>
246 <LI><A HREF="#10_4_3">Returns</A></LI>
247 <LI><A HREF="#10_4_4">Description</A></LI>
248 <LI><A HREF="#10_4_5">Example</A></LI>
249 <LI><A HREF="#10_4_6">See Also</A></LI>
250 </UL>
251 <LI><A HREF="#cupsDoRequest">cupsDoRequest()</A></LI>
252 <UL>
253 <LI><A HREF="#10_5_1">Usage</A></LI>
254 <LI><A HREF="#10_5_2">Arguments</A></LI>
255 <LI><A HREF="#10_5_3">Returns</A></LI>
256 <LI><A HREF="#10_5_4">Description</A></LI>
257 <LI><A HREF="#10_5_5">Example</A></LI>
258 <LI><A HREF="#10_5_6">See Also</A></LI>
259 </UL>
260 <LI><A HREF="#cupsEncodeOptions">cupsEncodeOptions()</A></LI>
261 <UL>
262 <LI><A HREF="#10_6_1">Usage</A></LI>
263 <LI><A HREF="#10_6_2">Arguments</A></LI>
264 <LI><A HREF="#10_6_3">Description</A></LI>
265 <LI><A HREF="#10_6_4">Example</A></LI>
266 <LI><A HREF="#10_6_5">See Also</A></LI>
267 </UL>
268 <LI><A HREF="#cupsEncryption">cupsEncryption()</A></LI>
269 <UL>
270 <LI><A HREF="#10_7_1">Usage</A></LI>
271 <LI><A HREF="#10_7_2">Returns</A></LI>
272 <LI><A HREF="#10_7_3">Description</A></LI>
273 <LI><A HREF="#10_7_4">Example</A></LI>
274 <LI><A HREF="#10_7_5">See Also</A></LI>
275 </UL>
276 <LI><A HREF="#cupsFreeDests">cupsFreeDests()</A></LI>
277 <UL>
278 <LI><A HREF="#10_8_1">Usage</A></LI>
279 <LI><A HREF="#10_8_2">Arguments</A></LI>
280 <LI><A HREF="#10_8_3">Description</A></LI>
281 <LI><A HREF="#10_8_4">Example</A></LI>
282 <LI><A HREF="#10_8_5">See Also</A></LI>
283 </UL>
284 <LI><A HREF="#cupsFreeJobs">cupsFreeJobs()</A></LI>
285 <UL>
286 <LI><A HREF="#10_9_1">Usage</A></LI>
287 <LI><A HREF="#10_9_2">Arguments</A></LI>
288 <LI><A HREF="#10_9_3">Description</A></LI>
289 <LI><A HREF="#10_9_4">Example</A></LI>
290 <LI><A HREF="#10_9_5">See Also</A></LI>
291 </UL>
292 <LI><A HREF="#cupsFreeOptions">cupsFreeOptions()</A></LI>
293 <UL>
294 <LI><A HREF="#10_10_1">Usage</A></LI>
295 <LI><A HREF="#10_10_2">Arguments</A></LI>
296 <LI><A HREF="#10_10_3">Description</A></LI>
297 <LI><A HREF="#10_10_4">Example</A></LI>
298 <LI><A HREF="#10_10_5">See Also</A></LI>
299 </UL>
300 <LI><A HREF="#cupsGetClasses">cupsGetClasses()</A></LI>
301 <UL>
302 <LI><A HREF="#10_11_1">Usage</A></LI>
303 <LI><A HREF="#10_11_2">Arguments</A></LI>
304 <LI><A HREF="#10_11_3">Returns</A></LI>
305 <LI><A HREF="#10_11_4">Description</A></LI>
306 <LI><A HREF="#10_11_5">Example</A></LI>
307 <LI><A HREF="#10_11_6">See Also</A></LI>
308 </UL>
309 <LI><A HREF="#cupsGetDefault">cupsGetDefault()</A></LI>
310 <UL>
311 <LI><A HREF="#10_12_1">Usage</A></LI>
312 <LI><A HREF="#10_12_2">Returns</A></LI>
313 <LI><A HREF="#10_12_3">Description</A></LI>
314 <LI><A HREF="#10_12_4">Example</A></LI>
315 <LI><A HREF="#10_12_5">See Also</A></LI>
316 </UL>
317 <LI><A HREF="#cupsGetDest">cupsGetDest()</A></LI>
318 <UL>
319 <LI><A HREF="#10_13_1">Usage</A></LI>
320 <LI><A HREF="#10_13_2">Arguments</A></LI>
321 <LI><A HREF="#10_13_3">Returns</A></LI>
322 <LI><A HREF="#10_13_4">Description</A></LI>
323 <LI><A HREF="#10_13_5">Example</A></LI>
324 <LI><A HREF="#10_13_6">See Also</A></LI>
325 </UL>
326 <LI><A HREF="#cupsGetDests">cupsGetDests()</A></LI>
327 <UL>
328 <LI><A HREF="#10_14_1">Usage</A></LI>
329 <LI><A HREF="#10_14_2">Arguments</A></LI>
330 <LI><A HREF="#10_14_3">Returns</A></LI>
331 <LI><A HREF="#10_14_4">Description</A></LI>
332 <LI><A HREF="#10_14_5">Example</A></LI>
333 <LI><A HREF="#10_14_6">See Also</A></LI>
334 </UL>
335 <LI><A HREF="#cupsGetJobs">cupsGetJobs()</A></LI>
336 <UL>
337 <LI><A HREF="#10_15_1">Usage</A></LI>
338 <LI><A HREF="#10_15_2">Arguments</A></LI>
339 <LI><A HREF="#10_15_3">Returns</A></LI>
340 <LI><A HREF="#10_15_4">Description</A></LI>
341 <LI><A HREF="#10_15_5">Example</A></LI>
342 <LI><A HREF="#10_15_6">See Also</A></LI>
343 </UL>
344 <LI><A HREF="#cupsGetOption">cupsGetOption()</A></LI>
345 <UL>
346 <LI><A HREF="#10_16_1">Usage</A></LI>
347 <LI><A HREF="#10_16_2">Arguments</A></LI>
348 <LI><A HREF="#10_16_3">Returns</A></LI>
349 <LI><A HREF="#10_16_4">Description</A></LI>
350 <LI><A HREF="#10_16_5">See Also</A></LI>
351 </UL>
352 <LI><A HREF="#cupsGetPassword">cupsGetPassword()</A></LI>
353 <UL>
354 <LI><A HREF="#10_17_1">Usage</A></LI>
355 <LI><A HREF="#10_17_2">Arguments</A></LI>
356 <LI><A HREF="#10_17_3">Returns</A></LI>
357 <LI><A HREF="#10_17_4">Description</A></LI>
358 <LI><A HREF="#10_17_5">Example</A></LI>
359 <LI><A HREF="#10_17_6">See Also</A></LI>
360 </UL>
361 <LI><A HREF="#cupsGetPPD">cupsGetPPD()</A></LI>
362 <UL>
363 <LI><A HREF="#10_18_1">Usage</A></LI>
364 <LI><A HREF="#10_18_2">Arguments</A></LI>
365 <LI><A HREF="#10_18_3">Returns</A></LI>
366 <LI><A HREF="#10_18_4">Description</A></LI>
367 <LI><A HREF="#10_18_5">Example</A></LI>
368 </UL>
369 <LI><A HREF="#cupsGetPrinters">cupsGetPrinters()</A></LI>
370 <UL>
371 <LI><A HREF="#10_19_1">Usage</A></LI>
372 <LI><A HREF="#10_19_2">Arguments</A></LI>
373 <LI><A HREF="#10_19_3">Returns</A></LI>
374 <LI><A HREF="#10_19_4">Description</A></LI>
375 <LI><A HREF="#10_19_5">Example</A></LI>
376 <LI><A HREF="#10_19_6">See Also</A></LI>
377 </UL>
378 <LI><A HREF="#cupsLangDefault">cupsLangDefault()</A></LI>
379 <UL>
380 <LI><A HREF="#10_20_1">Usage</A></LI>
381 <LI><A HREF="#10_20_2">Returns</A></LI>
382 <LI><A HREF="#10_20_3">Description</A></LI>
383 <LI><A HREF="#10_20_4">Example</A></LI>
384 <LI><A HREF="#10_20_5">See Also</A></LI>
385 </UL>
386 <LI><A HREF="#cupsLangEncoding">cupsLangEncoding()</A></LI>
387 <UL>
388 <LI><A HREF="#10_21_1">Usage</A></LI>
389 <LI><A HREF="#10_21_2">Arguments</A></LI>
390 <LI><A HREF="#10_21_3">Returns</A></LI>
391 <LI><A HREF="#10_21_4">Description</A></LI>
392 <LI><A HREF="#10_21_5">Example</A></LI>
393 <LI><A HREF="#10_21_6">See Also</A></LI>
394 </UL>
395 <LI><A HREF="#cupsLangFlush">cupsLangFlush()</A></LI>
396 <UL>
397 <LI><A HREF="#10_22_1">Usage</A></LI>
398 <LI><A HREF="#10_22_2">Description</A></LI>
399 <LI><A HREF="#10_22_3">Example</A></LI>
400 <LI><A HREF="#10_22_4">See Also</A></LI>
401 </UL>
402 <LI><A HREF="#cupsLangFree">cupsLangFree()</A></LI>
403 <UL>
404 <LI><A HREF="#10_23_1">Usage</A></LI>
405 <LI><A HREF="#10_23_2">Arguments</A></LI>
406 <LI><A HREF="#10_23_3">Description</A></LI>
407 <LI><A HREF="#10_23_4">Example</A></LI>
408 <LI><A HREF="#10_23_5">See Also</A></LI>
409 </UL>
410 <LI><A HREF="#cupsLangGet">cupsLangGet()</A></LI>
411 <UL>
412 <LI><A HREF="#10_24_1">Usage</A></LI>
413 <LI><A HREF="#10_24_2">Arguments</A></LI>
414 <LI><A HREF="#10_24_3">Returns</A></LI>
415 <LI><A HREF="#10_24_4">Description</A></LI>
416 <LI><A HREF="#10_24_5">Example</A></LI>
417 <LI><A HREF="#10_24_6">See Also</A></LI>
418 </UL>
419 <LI><A HREF="#cupsLangString">cupsLangString()</A></LI>
420 <UL>
421 <LI><A HREF="#10_25_1">Usage</A></LI>
422 <LI><A HREF="#10_25_2">Arguments</A></LI>
423 <LI><A HREF="#10_25_3">Returns</A></LI>
424 <LI><A HREF="#10_25_4">Description</A></LI>
425 <LI><A HREF="#10_25_5">Example</A></LI>
426 <LI><A HREF="#10_25_6">See Also</A></LI>
427 </UL>
428 <LI><A HREF="#cupsLastError">cupsLastError()</A></LI>
429 <UL>
430 <LI><A HREF="#10_26_1">Usage</A></LI>
431 <LI><A HREF="#10_26_2">Returns</A></LI>
432 <LI><A HREF="#10_26_3">Description</A></LI>
433 <LI><A HREF="#10_26_4">Example</A></LI>
434 <LI><A HREF="#10_26_5">See Also</A></LI>
435 </UL>
436 <LI><A HREF="#cupsMarkOptions">cupsMarkOptions()</A></LI>
437 <UL>
438 <LI><A HREF="#10_27_1">Usage</A></LI>
439 <LI><A HREF="#10_27_2">Arguments</A></LI>
440 <LI><A HREF="#10_27_3">Returns</A></LI>
441 <LI><A HREF="#10_27_4">Description</A></LI>
442 <LI><A HREF="#10_27_5">Example</A></LI>
443 <LI><A HREF="#10_27_6">See Also</A></LI>
444 </UL>
445 <LI><A HREF="#cupsParseOptions">cupsParseOptions()</A></LI>
446 <UL>
447 <LI><A HREF="#10_28_1">Usage</A></LI>
448 <LI><A HREF="#10_28_2">Arguments</A></LI>
449 <LI><A HREF="#10_28_3">Returns</A></LI>
450 <LI><A HREF="#10_28_4">Description</A></LI>
451 <LI><A HREF="#10_28_5">Example</A></LI>
452 <LI><A HREF="#10_28_6">See Also</A></LI>
453 </UL>
454 <LI><A HREF="#cupsPrintFile">cupsPrintFile()</A></LI>
455 <UL>
456 <LI><A HREF="#10_29_1">Usage</A></LI>
457 <LI><A HREF="#10_29_2">Arguments</A></LI>
458 <LI><A HREF="#10_29_3">Returns</A></LI>
459 <LI><A HREF="#10_29_4">Description</A></LI>
460 <LI><A HREF="#10_29_5">Example</A></LI>
461 <LI><A HREF="#10_29_6">See Also</A></LI>
462 </UL>
463 <LI><A HREF="#cupsPrintFiles">cupsPrintFiles()</A></LI>
464 <UL>
465 <LI><A HREF="#10_30_1">Usage</A></LI>
466 <LI><A HREF="#10_30_2">Arguments</A></LI>
467 <LI><A HREF="#10_30_3">Returns</A></LI>
468 <LI><A HREF="#10_30_4">Description</A></LI>
469 <LI><A HREF="#10_30_5">Example</A></LI>
470 <LI><A HREF="#10_30_6">See Also</A></LI>
471 </UL>
472 <LI><A HREF="#cupsRasterClose">cupsRasterClose()</A></LI>
473 <UL>
474 <LI><A HREF="#10_31_1">Usage</A></LI>
475 <LI><A HREF="#10_31_2">Arguments</A></LI>
476 <LI><A HREF="#10_31_3">Description</A></LI>
477 <LI><A HREF="#10_31_4">Example</A></LI>
478 <LI><A HREF="#10_31_5">See Also</A></LI>
479 </UL>
480 <LI><A HREF="#cupsRasterOpen">cupsRasterOpen()</A></LI>
481 <UL>
482 <LI><A HREF="#10_32_1">Usage</A></LI>
483 <LI><A HREF="#10_32_2">Arguments</A></LI>
484 <LI><A HREF="#10_32_3">Returns</A></LI>
485 <LI><A HREF="#10_32_4">Description</A></LI>
486 <LI><A HREF="#10_32_5">Example</A></LI>
487 <LI><A HREF="#10_32_6">See Also</A></LI>
488 </UL>
489 <LI><A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A></LI>
490 <UL>
491 <LI><A HREF="#10_33_1">Usage</A></LI>
492 <LI><A HREF="#10_33_2">Arguments</A></LI>
493 <LI><A HREF="#10_33_3">Returns</A></LI>
494 <LI><A HREF="#10_33_4">Description</A></LI>
495 <LI><A HREF="#10_33_5">Example</A></LI>
496 <LI><A HREF="#10_33_6">See Also</A></LI>
497 </UL>
498 <LI><A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A></LI>
499 <UL>
500 <LI><A HREF="#10_34_1">Usage</A></LI>
501 <LI><A HREF="#10_34_2">Arguments</A></LI>
502 <LI><A HREF="#10_34_3">Returns</A></LI>
503 <LI><A HREF="#10_34_4">Description</A></LI>
504 <LI><A HREF="#10_34_5">Example</A></LI>
505 <LI><A HREF="#10_34_6">See Also</A></LI>
506 </UL>
507 <LI><A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A></LI>
508 <UL>
509 <LI><A HREF="#10_35_1">Usage</A></LI>
510 <LI><A HREF="#10_35_2">Arguments</A></LI>
511 <LI><A HREF="#10_35_3">Returns</A></LI>
512 <LI><A HREF="#10_35_4">Description</A></LI>
513 <LI><A HREF="#10_35_5">Example</A></LI>
514 <LI><A HREF="#10_35_6">See Also</A></LI>
515 </UL>
516 <LI><A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A></LI>
517 <UL>
518 <LI><A HREF="#10_36_1">Usage</A></LI>
519 <LI><A HREF="#10_36_2">Arguments</A></LI>
520 <LI><A HREF="#10_36_3">Returns</A></LI>
521 <LI><A HREF="#10_36_4">Description</A></LI>
522 <LI><A HREF="#10_36_5">Example</A></LI>
523 <LI><A HREF="#10_36_6">See Also</A></LI>
524 </UL>
525 <LI><A HREF="#cupsServer">cupsServer()</A></LI>
526 <UL>
527 <LI><A HREF="#10_37_1">Usage</A></LI>
528 <LI><A HREF="#10_37_2">Returns</A></LI>
529 <LI><A HREF="#10_37_3">Description</A></LI>
530 <LI><A HREF="#10_37_4">Example</A></LI>
531 <LI><A HREF="#10_37_5">See Also</A></LI>
532 </UL>
533 <LI><A HREF="#cupsSetDests">cupsSetDests()</A></LI>
534 <UL>
535 <LI><A HREF="#10_38_1">Usage</A></LI>
536 <LI><A HREF="#10_38_2">Arguments</A></LI>
537 <LI><A HREF="#10_38_3">Description</A></LI>
538 <LI><A HREF="#10_38_4">Example</A></LI>
539 <LI><A HREF="#10_38_5">See Also</A></LI>
540 </UL>
541 <LI><A HREF="#cupsSetEncryption">cupsSetEncryption()</A></LI>
542 <UL>
543 <LI><A HREF="#10_39_1">Usage</A></LI>
544 <LI><A HREF="#10_39_2">Arguments</A></LI>
545 <LI><A HREF="#10_39_3">Description</A></LI>
546 <LI><A HREF="#10_39_4">Example</A></LI>
547 <LI><A HREF="#10_39_5">See Also</A></LI>
548 </UL>
549 <LI><A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A></LI>
550 <UL>
551 <LI><A HREF="#10_40_1">Usage</A></LI>
552 <LI><A HREF="#10_40_2">Arguments</A></LI>
553 <LI><A HREF="#10_40_3">Description</A></LI>
554 <LI><A HREF="#10_40_4">Example</A></LI>
555 <LI><A HREF="#10_40_5">See Also</A></LI>
556 </UL>
557 <LI><A HREF="#cupsSetServer">cupsSetServer()</A></LI>
558 <UL>
559 <LI><A HREF="#10_41_1">Usage</A></LI>
560 <LI><A HREF="#10_41_2">Arguments</A></LI>
561 <LI><A HREF="#10_41_3">Description</A></LI>
562 <LI><A HREF="#10_41_4">Example</A></LI>
563 <LI><A HREF="#10_41_5">See Also</A></LI>
564 </UL>
565 <LI><A HREF="#cupsSetUser">cupsSetUser()</A></LI>
566 <UL>
567 <LI><A HREF="#10_42_1">Usage</A></LI>
568 <LI><A HREF="#10_42_2">Arguments</A></LI>
569 <LI><A HREF="#10_42_3">Description</A></LI>
570 <LI><A HREF="#10_42_4">Example</A></LI>
571 <LI><A HREF="#10_42_5">See Also</A></LI>
572 </UL>
573 <LI><A HREF="#cupsTempFd">cupsTempFd()</A></LI>
574 <UL>
575 <LI><A HREF="#10_43_1">Usage</A></LI>
576 <LI><A HREF="#10_43_2">Arguments</A></LI>
577 <LI><A HREF="#10_43_3">Returns</A></LI>
578 <LI><A HREF="#10_43_4">Description</A></LI>
579 <LI><A HREF="#10_43_5">Example</A></LI>
580 <LI><A HREF="#10_43_6">See Also</A></LI>
581 </UL>
582 <LI><A HREF="#cupsTempFile">cupsTempFile()</A></LI>
583 <UL>
584 <LI><A HREF="#10_44_1">Usage</A></LI>
585 <LI><A HREF="#10_44_2">Arguments</A></LI>
586 <LI><A HREF="#10_44_3">Returns</A></LI>
587 <LI><A HREF="#10_44_4">Description</A></LI>
588 <LI><A HREF="#10_44_5">Example</A></LI>
589 <LI><A HREF="#10_44_6">See Also</A></LI>
590 </UL>
591 <LI><A HREF="#cupsUser">cupsUser()</A></LI>
592 <UL>
593 <LI><A HREF="#10_45_1">Usage</A></LI>
594 <LI><A HREF="#10_45_2">Returns</A></LI>
595 <LI><A HREF="#10_45_3">Description</A></LI>
596 <LI><A HREF="#10_45_4">Example</A></LI>
597 <LI><A HREF="#10_45_5">See Also</A></LI>
598 </UL>
599 <LI><A HREF="#httpBlocking">httpBlocking()</A></LI>
600 <UL>
601 <LI><A HREF="#10_46_1">Usage</A></LI>
602 <LI><A HREF="#10_46_2">Arguments</A></LI>
603 <LI><A HREF="#10_46_3">Description</A></LI>
604 <LI><A HREF="#10_46_4">Example</A></LI>
605 <LI><A HREF="#10_46_5">See Also</A></LI>
606 </UL>
607 <LI><A HREF="#httpCheck">httpCheck()</A></LI>
608 <UL>
609 <LI><A HREF="#10_47_1">Usage</A></LI>
610 <LI><A HREF="#10_47_2">Arguments</A></LI>
611 <LI><A HREF="#10_47_3">Returns</A></LI>
612 <LI><A HREF="#10_47_4">Description</A></LI>
613 <LI><A HREF="#10_47_5">Example</A></LI>
614 <LI><A HREF="#10_47_6">See Also</A></LI>
615 </UL>
616 <LI><A HREF="#httpClearFields">httpClearFields()</A></LI>
617 <UL>
618 <LI><A HREF="#10_48_1">Usage</A></LI>
619 <LI><A HREF="#10_48_2">Arguments</A></LI>
620 <LI><A HREF="#10_48_3">Description</A></LI>
621 <LI><A HREF="#10_48_4">Example</A></LI>
622 <LI><A HREF="#10_48_5">See Also</A></LI>
623 </UL>
624 <LI><A HREF="#httpClose">httpClose()</A></LI>
625 <UL>
626 <LI><A HREF="#10_49_1">Usage</A></LI>
627 <LI><A HREF="#10_49_2">Arguments</A></LI>
628 <LI><A HREF="#10_49_3">Description</A></LI>
629 <LI><A HREF="#10_49_4">Example</A></LI>
630 <LI><A HREF="#10_49_5">See Also</A></LI>
631 </UL>
632 <LI><A HREF="#httpConnect">httpConnect()</A></LI>
633 <UL>
634 <LI><A HREF="#10_50_1">Usage</A></LI>
635 <LI><A HREF="#10_50_2">Arguments</A></LI>
636 <LI><A HREF="#10_50_3">Returns</A></LI>
637 <LI><A HREF="#10_50_4">Description</A></LI>
638 <LI><A HREF="#10_50_5">Example</A></LI>
639 <LI><A HREF="#10_50_6">See Also</A></LI>
640 </UL>
641 <LI><A HREF="#httpConnectEncrypt">httpConnectEncrypt()</A></LI>
642 <UL>
643 <LI><A HREF="#10_51_1">Usage</A></LI>
644 <LI><A HREF="#10_51_2">Arguments</A></LI>
645 <LI><A HREF="#10_51_3">Returns</A></LI>
646 <LI><A HREF="#10_51_4">Description</A></LI>
647 <LI><A HREF="#10_51_5">Example</A></LI>
648 <LI><A HREF="#10_51_6">See Also</A></LI>
649 </UL>
650 <LI><A HREF="#httpDecode64">httpDecode64()</A></LI>
651 <UL>
652 <LI><A HREF="#10_52_1">Usage</A></LI>
653 <LI><A HREF="#10_52_2">Arguments</A></LI>
654 <LI><A HREF="#10_52_3">Returns</A></LI>
655 <LI><A HREF="#10_52_4">Description</A></LI>
656 <LI><A HREF="#10_52_5">Example</A></LI>
657 <LI><A HREF="#10_52_6">See Also</A></LI>
658 </UL>
659 <LI><A HREF="#httpDelete">httpDelete()</A></LI>
660 <UL>
661 <LI><A HREF="#10_53_1">Usage</A></LI>
662 <LI><A HREF="#10_53_2">Arguments</A></LI>
663 <LI><A HREF="#10_53_3">Returns</A></LI>
664 <LI><A HREF="#10_53_4">Description</A></LI>
665 <LI><A HREF="#10_53_5">Example</A></LI>
666 <LI><A HREF="#10_53_6">See Also</A></LI>
667 </UL>
668 <LI><A HREF="#httpEncode64">httpEncode64()</A></LI>
669 <UL>
670 <LI><A HREF="#10_54_1">Usage</A></LI>
671 <LI><A HREF="#10_54_2">Arguments</A></LI>
672 <LI><A HREF="#10_54_3">Returns</A></LI>
673 <LI><A HREF="#10_54_4">Description</A></LI>
674 <LI><A HREF="#10_54_5">Example</A></LI>
675 <LI><A HREF="#10_54_6">See Also</A></LI>
676 </UL>
677 <LI><A HREF="#httpEncryption">httpEncryption()</A></LI>
678 <UL>
679 <LI><A HREF="#10_55_1">Usage</A></LI>
680 <LI><A HREF="#10_55_2">Arguments</A></LI>
681 <LI><A HREF="#10_55_3">Returns</A></LI>
682 <LI><A HREF="#10_55_4">Description</A></LI>
683 <LI><A HREF="#10_55_5">Example</A></LI>
684 <LI><A HREF="#10_55_6">See Also</A></LI>
685 </UL>
686 <LI><A HREF="#httpError">httpError()</A></LI>
687 <UL>
688 <LI><A HREF="#10_56_1">Usage</A></LI>
689 <LI><A HREF="#10_56_2">Arguments</A></LI>
690 <LI><A HREF="#10_56_3">Returns</A></LI>
691 <LI><A HREF="#10_56_4">Description</A></LI>
692 <LI><A HREF="#10_56_5">Example</A></LI>
693 <LI><A HREF="#10_56_6">See Also</A></LI>
694 </UL>
695 <LI><A HREF="#httpFlush">httpFlush()</A></LI>
696 <UL>
697 <LI><A HREF="#10_57_1">Usage</A></LI>
698 <LI><A HREF="#10_57_2">Arguments</A></LI>
699 <LI><A HREF="#10_57_3">Description</A></LI>
700 <LI><A HREF="#10_57_4">Example</A></LI>
701 <LI><A HREF="#10_57_5">See Also</A></LI>
702 </UL>
703 <LI><A HREF="#httpGet">httpGet()</A></LI>
704 <UL>
705 <LI><A HREF="#10_58_1">Usage</A></LI>
706 <LI><A HREF="#10_58_2">Arguments</A></LI>
707 <LI><A HREF="#10_58_3">Returns</A></LI>
708 <LI><A HREF="#10_58_4">Description</A></LI>
709 <LI><A HREF="#10_58_5">Example</A></LI>
710 <LI><A HREF="#10_58_6">See Also</A></LI>
711 </UL>
712 <LI><A HREF="#httpGets">httpGets()</A></LI>
713 <UL>
714 <LI><A HREF="#10_59_1">Usage</A></LI>
715 <LI><A HREF="#10_59_2">Arguments</A></LI>
716 <LI><A HREF="#10_59_3">Returns</A></LI>
717 <LI><A HREF="#10_59_4">Description</A></LI>
718 <LI><A HREF="#10_59_5">Example</A></LI>
719 <LI><A HREF="#10_59_6">See Also</A></LI>
720 </UL>
721 <LI><A HREF="#httpGetDateString">httpGetDateString()</A></LI>
722 <UL>
723 <LI><A HREF="#10_60_1">Usage</A></LI>
724 <LI><A HREF="#10_60_2">Arguments</A></LI>
725 <LI><A HREF="#10_60_3">Returns</A></LI>
726 <LI><A HREF="#10_60_4">Description</A></LI>
727 <LI><A HREF="#10_60_5">Example</A></LI>
728 <LI><A HREF="#10_60_6">See Also</A></LI>
729 </UL>
730 <LI><A HREF="#httpGetDateTime">httpGetDateTime()</A></LI>
731 <UL>
732 <LI><A HREF="#10_61_1">Usage</A></LI>
733 <LI><A HREF="#10_61_2">Arguments</A></LI>
734 <LI><A HREF="#10_61_3">Returns</A></LI>
735 <LI><A HREF="#10_61_4">Description</A></LI>
736 <LI><A HREF="#10_61_5">Example</A></LI>
737 <LI><A HREF="#10_61_6">See Also</A></LI>
738 </UL>
739 <LI><A HREF="#httpGetField">httpGetField()</A></LI>
740 <UL>
741 <LI><A HREF="#10_62_1">Usage</A></LI>
742 <LI><A HREF="#10_62_2">Arguments</A></LI>
743 <LI><A HREF="#10_62_3">Returns</A></LI>
744 <LI><A HREF="#10_62_4">Description</A></LI>
745 <LI><A HREF="#10_62_5">Example</A></LI>
746 <LI><A HREF="#10_62_6">See Also</A></LI>
747 </UL>
748 <LI><A HREF="#httpGetHostByName">httpGetHostByName()</A></LI>
749 <UL>
750 <LI><A HREF="#10_63_1">Usage</A></LI>
751 <LI><A HREF="#10_63_2">Arguments</A></LI>
752 <LI><A HREF="#10_63_3">Returns</A></LI>
753 <LI><A HREF="#10_63_4">Description</A></LI>
754 <LI><A HREF="#10_63_5">Example</A></LI>
755 </UL>
756 <LI><A HREF="#httpGetLength">httpGetLength()</A></LI>
757 <UL>
758 <LI><A HREF="#10_64_1">Usage</A></LI>
759 <LI><A HREF="#10_64_2">Arguments</A></LI>
760 <LI><A HREF="#10_64_3">Returns</A></LI>
761 <LI><A HREF="#10_64_4">Description</A></LI>
762 <LI><A HREF="#10_64_5">Example</A></LI>
763 <LI><A HREF="#10_64_6">See Also</A></LI>
764 </UL>
765 <LI><A HREF="#httpGetSubField">httpGetSubField()</A></LI>
766 <UL>
767 <LI><A HREF="#10_65_1">Usage</A></LI>
768 <LI><A HREF="#10_65_2">Arguments</A></LI>
769 <LI><A HREF="#10_65_3">Returns</A></LI>
770 <LI><A HREF="#10_65_4">Description</A></LI>
771 <LI><A HREF="#10_65_5">Example</A></LI>
772 <LI><A HREF="#10_65_6">See Also</A></LI>
773 </UL>
774 <LI><A HREF="#httpHead">httpHead()</A></LI>
775 <UL>
776 <LI><A HREF="#10_66_1">Usage</A></LI>
777 <LI><A HREF="#10_66_2">Arguments</A></LI>
778 <LI><A HREF="#10_66_3">Returns</A></LI>
779 <LI><A HREF="#10_66_4">Description</A></LI>
780 <LI><A HREF="#10_66_5">Example</A></LI>
781 <LI><A HREF="#10_66_6">See Also</A></LI>
782 </UL>
783 <LI><A HREF="#httpInitialize">httpInitialize()</A></LI>
784 <UL>
785 <LI><A HREF="#10_67_1">Usage</A></LI>
786 <LI><A HREF="#10_67_2">Description</A></LI>
787 <LI><A HREF="#10_67_3">Example</A></LI>
788 <LI><A HREF="#10_67_4">See Also</A></LI>
789 </UL>
790 <LI><A HREF="#httpMD5">httpMD5()</A></LI>
791 <UL>
792 <LI><A HREF="#10_68_1">Usage</A></LI>
793 <LI><A HREF="#10_68_2">Arguments</A></LI>
794 <LI><A HREF="#10_68_3">Returns</A></LI>
795 <LI><A HREF="#10_68_4">Description</A></LI>
796 <LI><A HREF="#10_68_5">Example</A></LI>
797 <LI><A HREF="#10_68_6">See Also</A></LI>
798 </UL>
799 <LI><A HREF="#httpMD5Final">httpMD5Final()</A></LI>
800 <UL>
801 <LI><A HREF="#10_69_1">Usage</A></LI>
802 <LI><A HREF="#10_69_2">Arguments</A></LI>
803 <LI><A HREF="#10_69_3">Returns</A></LI>
804 <LI><A HREF="#10_69_4">Description</A></LI>
805 <LI><A HREF="#10_69_5">Example</A></LI>
806 <LI><A HREF="#10_69_6">See Also</A></LI>
807 </UL>
808 <LI><A HREF="#httpMD5String">httpMD5String()</A></LI>
809 <UL>
810 <LI><A HREF="#10_70_1">Usage</A></LI>
811 <LI><A HREF="#10_70_2">Arguments</A></LI>
812 <LI><A HREF="#10_70_3">Returns</A></LI>
813 <LI><A HREF="#10_70_4">Description</A></LI>
814 <LI><A HREF="#10_70_5">Example</A></LI>
815 <LI><A HREF="#10_70_6">See Also</A></LI>
816 </UL>
817 <LI><A HREF="#httpOptions">httpOptions()</A></LI>
818 <UL>
819 <LI><A HREF="#10_71_1">Usage</A></LI>
820 <LI><A HREF="#10_71_2">Arguments</A></LI>
821 <LI><A HREF="#10_71_3">Returns</A></LI>
822 <LI><A HREF="#10_71_4">Description</A></LI>
823 <LI><A HREF="#10_71_5">Example</A></LI>
824 <LI><A HREF="#10_71_6">See Also</A></LI>
825 </UL>
826 <LI><A HREF="#httpPost">httpPost()</A></LI>
827 <UL>
828 <LI><A HREF="#10_72_1">Usage</A></LI>
829 <LI><A HREF="#10_72_2">Arguments</A></LI>
830 <LI><A HREF="#10_72_3">Returns</A></LI>
831 <LI><A HREF="#10_72_4">Description</A></LI>
832 <LI><A HREF="#10_72_5">Example</A></LI>
833 <LI><A HREF="#10_72_6">See Also</A></LI>
834 </UL>
835 <LI><A HREF="#httpPrintf">httpPrintf()</A></LI>
836 <UL>
837 <LI><A HREF="#10_73_1">Usage</A></LI>
838 <LI><A HREF="#10_73_2">Arguments</A></LI>
839 <LI><A HREF="#10_73_3">Returns</A></LI>
840 <LI><A HREF="#10_73_4">Description</A></LI>
841 <LI><A HREF="#10_73_5">Example</A></LI>
842 <LI><A HREF="#10_73_6">See Also</A></LI>
843 </UL>
844 <LI><A HREF="#httpPut">httpPut()</A></LI>
845 <UL>
846 <LI><A HREF="#10_74_1">Usage</A></LI>
847 <LI><A HREF="#10_74_2">Arguments</A></LI>
848 <LI><A HREF="#10_74_3">Returns</A></LI>
849 <LI><A HREF="#10_74_4">Description</A></LI>
850 <LI><A HREF="#10_74_5">Example</A></LI>
851 <LI><A HREF="#10_74_6">See Also</A></LI>
852 </UL>
853 <LI><A HREF="#httpRead">httpRead()</A></LI>
854 <UL>
855 <LI><A HREF="#10_75_1">Usage</A></LI>
856 <LI><A HREF="#10_75_2">Arguments</A></LI>
857 <LI><A HREF="#10_75_3">Returns</A></LI>
858 <LI><A HREF="#10_75_4">Description</A></LI>
859 <LI><A HREF="#10_75_5">Example</A></LI>
860 <LI><A HREF="#10_75_6">See Also</A></LI>
861 </UL>
862 <LI><A HREF="#httpReconnect">httpReconnect()</A></LI>
863 <UL>
864 <LI><A HREF="#10_76_1">Usage</A></LI>
865 <LI><A HREF="#10_76_2">Arguments</A></LI>
866 <LI><A HREF="#10_76_3">Returns</A></LI>
867 <LI><A HREF="#10_76_4">Description</A></LI>
868 <LI><A HREF="#10_76_5">Example</A></LI>
869 <LI><A HREF="#10_76_6">See Also</A></LI>
870 </UL>
871 <LI><A HREF="#httpSeparate">httpSeparate()</A></LI>
872 <UL>
873 <LI><A HREF="#10_77_1">Usage</A></LI>
874 <LI><A HREF="#10_77_2">Arguments</A></LI>
875 <LI><A HREF="#10_77_3">Description</A></LI>
876 <LI><A HREF="#10_77_4">Example</A></LI>
877 <LI><A HREF="#10_77_5">See Also</A></LI>
878 </UL>
879 <LI><A HREF="#httpSetField">httpSetField()</A></LI>
880 <UL>
881 <LI><A HREF="#10_78_1">Usage</A></LI>
882 <LI><A HREF="#10_78_2">Arguments</A></LI>
883 <LI><A HREF="#10_78_3">Description</A></LI>
884 <LI><A HREF="#10_78_4">Example</A></LI>
885 <LI><A HREF="#10_78_5">See Also</A></LI>
886 </UL>
887 <LI><A HREF="#httpStatus">httpStatus()</A></LI>
888 <UL>
889 <LI><A HREF="#10_79_1">Usage</A></LI>
890 <LI><A HREF="#10_79_2">Arguments</A></LI>
891 <LI><A HREF="#10_79_3">Returns</A></LI>
892 <LI><A HREF="#10_79_4">Description</A></LI>
893 <LI><A HREF="#10_79_5">Example</A></LI>
894 </UL>
895 <LI><A HREF="#httpTrace">httpTrace()</A></LI>
896 <UL>
897 <LI><A HREF="#10_80_1">Usage</A></LI>
898 <LI><A HREF="#10_80_2">Arguments</A></LI>
899 <LI><A HREF="#10_80_3">Returns</A></LI>
900 <LI><A HREF="#10_80_4">Description</A></LI>
901 <LI><A HREF="#10_80_5">Example</A></LI>
902 <LI><A HREF="#10_80_6">See Also</A></LI>
903 </UL>
904 <LI><A HREF="#httpUpdate">httpUpdate()</A></LI>
905 <UL>
906 <LI><A HREF="#10_81_1">Usage</A></LI>
907 <LI><A HREF="#10_81_2">Arguments</A></LI>
908 <LI><A HREF="#10_81_3">Returns</A></LI>
909 <LI><A HREF="#10_81_4">Description</A></LI>
910 <LI><A HREF="#10_81_5">Example</A></LI>
911 <LI><A HREF="#10_81_6">See Also</A></LI>
912 </UL>
913 <LI><A HREF="#httpWrite">httpWrite()</A></LI>
914 <UL>
915 <LI><A HREF="#10_82_1">Usage</A></LI>
916 <LI><A HREF="#10_82_2">Arguments</A></LI>
917 <LI><A HREF="#10_82_3">Returns</A></LI>
918 <LI><A HREF="#10_82_4">Description</A></LI>
919 <LI><A HREF="#10_82_5">Example</A></LI>
920 <LI><A HREF="#10_82_6">See Also</A></LI>
921 </UL>
922 <LI><A HREF="#ippAddBoolean">ippAddBoolean()</A></LI>
923 <UL>
924 <LI><A HREF="#10_83_1">Usage</A></LI>
925 <LI><A HREF="#10_83_2">Arguments</A></LI>
926 <LI><A HREF="#10_83_3">Returns</A></LI>
927 <LI><A HREF="#10_83_4">Description</A></LI>
928 <LI><A HREF="#10_83_5">Example</A></LI>
929 <LI><A HREF="#10_83_6">See Also</A></LI>
930 </UL>
931 <LI><A HREF="#ippAddBooleans">ippAddBooleans()</A></LI>
932 <UL>
933 <LI><A HREF="#10_84_1">Usage</A></LI>
934 <LI><A HREF="#10_84_2">Arguments</A></LI>
935 <LI><A HREF="#10_84_3">Returns</A></LI>
936 <LI><A HREF="#10_84_4">Description</A></LI>
937 <LI><A HREF="#10_84_5">Example</A></LI>
938 <LI><A HREF="#10_84_6">See Also</A></LI>
939 </UL>
940 <LI><A HREF="#ippAddDate">ippAddDate()</A></LI>
941 <UL>
942 <LI><A HREF="#10_85_1">Usage</A></LI>
943 <LI><A HREF="#10_85_2">Arguments</A></LI>
944 <LI><A HREF="#10_85_3">Returns</A></LI>
945 <LI><A HREF="#10_85_4">Description</A></LI>
946 <LI><A HREF="#10_85_5">Example</A></LI>
947 <LI><A HREF="#10_85_6">See Also</A></LI>
948 </UL>
949 <LI><A HREF="#ippAddInteger">ippAddInteger()</A></LI>
950 <UL>
951 <LI><A HREF="#10_86_1">Usage</A></LI>
952 <LI><A HREF="#10_86_2">Arguments</A></LI>
953 <LI><A HREF="#10_86_3">Returns</A></LI>
954 <LI><A HREF="#10_86_4">Description</A></LI>
955 <LI><A HREF="#10_86_5">Example</A></LI>
956 <LI><A HREF="#10_86_6">See Also</A></LI>
957 </UL>
958 <LI><A HREF="#ippAddIntegers">ippAddIntegers()</A></LI>
959 <UL>
960 <LI><A HREF="#10_87_1">Usage</A></LI>
961 <LI><A HREF="#10_87_2">Arguments</A></LI>
962 <LI><A HREF="#10_87_3">Returns</A></LI>
963 <LI><A HREF="#10_87_4">Description</A></LI>
964 <LI><A HREF="#10_87_5">Example</A></LI>
965 <LI><A HREF="#10_87_6">See Also</A></LI>
966 </UL>
967 <LI><A HREF="#ippAddRange">ippAddRange()</A></LI>
968 <UL>
969 <LI><A HREF="#10_88_1">Usage</A></LI>
970 <LI><A HREF="#10_88_2">Arguments</A></LI>
971 <LI><A HREF="#10_88_3">Returns</A></LI>
972 <LI><A HREF="#10_88_4">Description</A></LI>
973 <LI><A HREF="#10_88_5">Example</A></LI>
974 <LI><A HREF="#10_88_6">See Also</A></LI>
975 </UL>
976 <LI><A HREF="#ippAddRanges">ippAddRanges()</A></LI>
977 <UL>
978 <LI><A HREF="#10_89_1">Usage</A></LI>
979 <LI><A HREF="#10_89_2">Arguments</A></LI>
980 <LI><A HREF="#10_89_3">Returns</A></LI>
981 <LI><A HREF="#10_89_4">Description</A></LI>
982 <LI><A HREF="#10_89_5">Example</A></LI>
983 <LI><A HREF="#10_89_6">See Also</A></LI>
984 </UL>
985 <LI><A HREF="#ippAddResolution">ippAddResolution()</A></LI>
986 <UL>
987 <LI><A HREF="#10_90_1">Usage</A></LI>
988 <LI><A HREF="#10_90_2">Arguments</A></LI>
989 <LI><A HREF="#10_90_3">Returns</A></LI>
990 <LI><A HREF="#10_90_4">Description</A></LI>
991 <LI><A HREF="#10_90_5">Example</A></LI>
992 <LI><A HREF="#10_90_6">See Also</A></LI>
993 </UL>
994 <LI><A HREF="#ippAddResolutions">ippAddResolutions()</A></LI>
995 <UL>
996 <LI><A HREF="#10_91_1">Usage</A></LI>
997 <LI><A HREF="#10_91_2">Arguments</A></LI>
998 <LI><A HREF="#10_91_3">Returns</A></LI>
999 <LI><A HREF="#10_91_4">Description</A></LI>
1000 <LI><A HREF="#10_91_5">Example</A></LI>
1001 <LI><A HREF="#10_91_6">See Also</A></LI>
1002 </UL>
1003 <LI><A HREF="#ippAddSeparator">ippAddSeparator()</A></LI>
1004 <UL>
1005 <LI><A HREF="#10_92_1">Usage</A></LI>
1006 <LI><A HREF="#10_92_2">Arguments</A></LI>
1007 <LI><A HREF="#10_92_3">Returns</A></LI>
1008 <LI><A HREF="#10_92_4">Description</A></LI>
1009 <LI><A HREF="#10_92_5">Example</A></LI>
1010 <LI><A HREF="#10_92_6">See Also</A></LI>
1011 </UL>
1012 <LI><A HREF="#ippAddString">ippAddString()</A></LI>
1013 <UL>
1014 <LI><A HREF="#10_93_1">Usage</A></LI>
1015 <LI><A HREF="#10_93_2">Arguments</A></LI>
1016 <LI><A HREF="#10_93_3">Returns</A></LI>
1017 <LI><A HREF="#10_93_4">Description</A></LI>
1018 <LI><A HREF="#10_93_5">Example</A></LI>
1019 <LI><A HREF="#10_93_6">See Also</A></LI>
1020 </UL>
1021 <LI><A HREF="#ippAddStrings">ippAddStrings()</A></LI>
1022 <UL>
1023 <LI><A HREF="#10_94_1">Usage</A></LI>
1024 <LI><A HREF="#10_94_2">Arguments</A></LI>
1025 <LI><A HREF="#10_94_3">Returns</A></LI>
1026 <LI><A HREF="#10_94_4">Description</A></LI>
1027 <LI><A HREF="#10_94_5">Example</A></LI>
1028 <LI><A HREF="#10_94_6">See Also</A></LI>
1029 </UL>
1030 <LI><A HREF="#ippDateToTime">ippDateToTime()</A></LI>
1031 <UL>
1032 <LI><A HREF="#10_95_1">Usage</A></LI>
1033 <LI><A HREF="#10_95_2">Arguments</A></LI>
1034 <LI><A HREF="#10_95_3">Returns</A></LI>
1035 <LI><A HREF="#10_95_4">Description</A></LI>
1036 <LI><A HREF="#10_95_5">Example</A></LI>
1037 <LI><A HREF="#10_95_6">See Also</A></LI>
1038 </UL>
1039 <LI><A HREF="#ippDelete">ippDelete()</A></LI>
1040 <UL>
1041 <LI><A HREF="#10_96_1">Usage</A></LI>
1042 <LI><A HREF="#10_96_2">Arguments</A></LI>
1043 <LI><A HREF="#10_96_3">Description</A></LI>
1044 <LI><A HREF="#10_96_4">Example</A></LI>
1045 <LI><A HREF="#10_96_5">See Also</A></LI>
1046 </UL>
1047 <LI><A HREF="#ippErrorString">ippErrorString()</A></LI>
1048 <UL>
1049 <LI><A HREF="#10_97_1">Usage</A></LI>
1050 <LI><A HREF="#10_97_2">Arguments</A></LI>
1051 <LI><A HREF="#10_97_3">Returns</A></LI>
1052 <LI><A HREF="#10_97_4">Description</A></LI>
1053 <LI><A HREF="#10_97_5">Example</A></LI>
1054 <LI><A HREF="#10_97_6">See Also</A></LI>
1055 </UL>
1056 <LI><A HREF="#ippFindAttribute">ippFindAttribute()</A></LI>
1057 <UL>
1058 <LI><A HREF="#10_98_1">Usage</A></LI>
1059 <LI><A HREF="#10_98_2">Arguments</A></LI>
1060 <LI><A HREF="#10_98_3">Returns</A></LI>
1061 <LI><A HREF="#10_98_4">Description</A></LI>
1062 <LI><A HREF="#10_98_5">Example</A></LI>
1063 <LI><A HREF="#10_98_6">See Also</A></LI>
1064 </UL>
1065 <LI><A HREF="#ippFindNextAttribute">ippFindNextAttribute()</A></LI>
1066 <UL>
1067 <LI><A HREF="#10_99_1">Usage</A></LI>
1068 <LI><A HREF="#10_99_2">Arguments</A></LI>
1069 <LI><A HREF="#10_99_3">Returns</A></LI>
1070 <LI><A HREF="#10_99_4">Description</A></LI>
1071 <LI><A HREF="#10_99_5">Example</A></LI>
1072 <LI><A HREF="#10_99_6">See Also</A></LI>
1073 </UL>
1074 <LI><A HREF="#ippLength">ippLength()</A></LI>
1075 <UL>
1076 <LI><A HREF="#10_100_1">Usage</A></LI>
1077 <LI><A HREF="#10_100_2">Arguments</A></LI>
1078 <LI><A HREF="#10_100_3">Returns</A></LI>
1079 <LI><A HREF="#10_100_4">Description</A></LI>
1080 <LI><A HREF="#10_100_5">Example</A></LI>
1081 <LI><A HREF="#10_100_6">See Also</A></LI>
1082 </UL>
1083 <LI><A HREF="#ippNew">ippNew()</A></LI>
1084 <UL>
1085 <LI><A HREF="#10_101_1">Usage</A></LI>
1086 <LI><A HREF="#10_101_2">Returns</A></LI>
1087 <LI><A HREF="#10_101_3">Description</A></LI>
1088 <LI><A HREF="#10_101_4">Example</A></LI>
1089 <LI><A HREF="#10_101_5">See Also</A></LI>
1090 </UL>
1091 <LI><A HREF="#ippPort">ippPort()</A></LI>
1092 <UL>
1093 <LI><A HREF="#10_102_1">Usage</A></LI>
1094 <LI><A HREF="#10_102_2">Returns</A></LI>
1095 <LI><A HREF="#10_102_3">Description</A></LI>
1096 <LI><A HREF="#10_102_4">Example</A></LI>
1097 <LI><A HREF="#10_102_5">See Also</A></LI>
1098 </UL>
1099 <LI><A HREF="#ippRead">ippRead()</A></LI>
1100 <UL>
1101 <LI><A HREF="#10_103_1">Usage</A></LI>
1102 <LI><A HREF="#10_103_2">Arguments</A></LI>
1103 <LI><A HREF="#10_103_3">Returns</A></LI>
1104 <LI><A HREF="#10_103_4">Description</A></LI>
1105 <LI><A HREF="#10_103_5">Example</A></LI>
1106 <LI><A HREF="#10_103_6">See Also</A></LI>
1107 </UL>
1108 <LI><A HREF="#ippSetPort">ippSetPort()</A></LI>
1109 <UL>
1110 <LI><A HREF="#10_104_1">Usage</A></LI>
1111 <LI><A HREF="#10_104_2">Arguments</A></LI>
1112 <LI><A HREF="#10_104_3">Description</A></LI>
1113 <LI><A HREF="#10_104_4">Example</A></LI>
1114 <LI><A HREF="#10_104_5">See Also</A></LI>
1115 </UL>
1116 <LI><A HREF="#ippTimeToDate">ippTimeToDate()</A></LI>
1117 <UL>
1118 <LI><A HREF="#10_105_1">Usage</A></LI>
1119 <LI><A HREF="#10_105_2">Arguments</A></LI>
1120 <LI><A HREF="#10_105_3">Returns</A></LI>
1121 <LI><A HREF="#10_105_4">Description</A></LI>
1122 <LI><A HREF="#10_105_5">Example</A></LI>
1123 <LI><A HREF="#10_105_6">See Also</A></LI>
1124 </UL>
1125 <LI><A HREF="#ippWrite">ippWrite()</A></LI>
1126 <UL>
1127 <LI><A HREF="#10_106_1">Usage</A></LI>
1128 <LI><A HREF="#10_106_2">Arguments</A></LI>
1129 <LI><A HREF="#10_106_3">Returns</A></LI>
1130 <LI><A HREF="#10_106_4">Description</A></LI>
1131 <LI><A HREF="#10_106_5">Example</A></LI>
1132 <LI><A HREF="#10_106_6">See Also</A></LI>
1133 </UL>
1134 <LI><A HREF="#ppdClose">ppdClose()</A></LI>
1135 <UL>
1136 <LI><A HREF="#10_107_1">Usage</A></LI>
1137 <LI><A HREF="#10_107_2">Arguments</A></LI>
1138 <LI><A HREF="#10_107_3">Description</A></LI>
1139 <LI><A HREF="#10_107_4">Example</A></LI>
1140 <LI><A HREF="#10_107_5">See Also</A></LI>
1141 </UL>
1142 <LI><A HREF="#ppdCollect">ppdCollect()</A></LI>
1143 <UL>
1144 <LI><A HREF="#10_108_1">Usage</A></LI>
1145 <LI><A HREF="#10_108_2">Arguments</A></LI>
1146 <LI><A HREF="#10_108_3">Returns</A></LI>
1147 <LI><A HREF="#10_108_4">Description</A></LI>
1148 <LI><A HREF="#10_108_5">Example</A></LI>
1149 <LI><A HREF="#10_108_6">See Also</A></LI>
1150 </UL>
1151 <LI><A HREF="#ppdConflicts">ppdConflicts()</A></LI>
1152 <UL>
1153 <LI><A HREF="#10_109_1">Usage</A></LI>
1154 <LI><A HREF="#10_109_2">Arguments</A></LI>
1155 <LI><A HREF="#10_109_3">Returns</A></LI>
1156 <LI><A HREF="#10_109_4">Description</A></LI>
1157 <LI><A HREF="#10_109_5">Example</A></LI>
1158 <LI><A HREF="#10_109_6">See Also</A></LI>
1159 </UL>
1160 <LI><A HREF="#ppdEmit">ppdEmit()</A></LI>
1161 <UL>
1162 <LI><A HREF="#10_110_1">Usage</A></LI>
1163 <LI><A HREF="#10_110_2">Arguments</A></LI>
1164 <LI><A HREF="#10_110_3">Returns</A></LI>
1165 <LI><A HREF="#10_110_4">Description</A></LI>
1166 <LI><A HREF="#10_110_5">Example</A></LI>
1167 <LI><A HREF="#10_110_6">See Also</A></LI>
1168 </UL>
1169 <LI><A HREF="#ppdEmitFd">ppdEmitFd()</A></LI>
1170 <UL>
1171 <LI><A HREF="#10_111_1">Usage</A></LI>
1172 <LI><A HREF="#10_111_2">Arguments</A></LI>
1173 <LI><A HREF="#10_111_3">Returns</A></LI>
1174 <LI><A HREF="#10_111_4">Description</A></LI>
1175 <LI><A HREF="#10_111_5">Example</A></LI>
1176 <LI><A HREF="#10_111_6">See Also</A></LI>
1177 </UL>
1178 <LI><A HREF="#ppdFindChoice">ppdFindChoice()</A></LI>
1179 <UL>
1180 <LI><A HREF="#10_112_1">Usage</A></LI>
1181 <LI><A HREF="#10_112_2">Arguments</A></LI>
1182 <LI><A HREF="#10_112_3">Returns</A></LI>
1183 <LI><A HREF="#10_112_4">Description</A></LI>
1184 <LI><A HREF="#10_112_5">Example</A></LI>
1185 <LI><A HREF="#10_112_6">See Also</A></LI>
1186 </UL>
1187 <LI><A HREF="#ppdFindMarkedChoice">ppdFindMarkedChoice()</A></LI>
1188 <UL>
1189 <LI><A HREF="#10_113_1">Usage</A></LI>
1190 <LI><A HREF="#10_113_2">Arguments</A></LI>
1191 <LI><A HREF="#10_113_3">Returns</A></LI>
1192 <LI><A HREF="#10_113_4">Description</A></LI>
1193 <LI><A HREF="#10_113_5">Example</A></LI>
1194 <LI><A HREF="#10_113_6">See Also</A></LI>
1195 </UL>
1196 <LI><A HREF="#ppdFindOption">ppdFindOption()</A></LI>
1197 <UL>
1198 <LI><A HREF="#10_114_1">Usage</A></LI>
1199 <LI><A HREF="#10_114_2">Arguments</A></LI>
1200 <LI><A HREF="#10_114_3">Returns</A></LI>
1201 <LI><A HREF="#10_114_4">Description</A></LI>
1202 <LI><A HREF="#10_114_5">Example</A></LI>
1203 <LI><A HREF="#10_114_6">See Also</A></LI>
1204 </UL>
1205 <LI><A HREF="#ppdIsMarked">ppdIsMarked()</A></LI>
1206 <UL>
1207 <LI><A HREF="#10_115_1">Usage</A></LI>
1208 <LI><A HREF="#10_115_2">Arguments</A></LI>
1209 <LI><A HREF="#10_115_3">Returns</A></LI>
1210 <LI><A HREF="#10_115_4">Description</A></LI>
1211 <LI><A HREF="#10_115_5">Example</A></LI>
1212 <LI><A HREF="#10_115_6">See Also</A></LI>
1213 </UL>
1214 <LI><A HREF="#ppdMarkDefaults">ppdMarkDefaults()</A></LI>
1215 <UL>
1216 <LI><A HREF="#10_116_1">Usage</A></LI>
1217 <LI><A HREF="#10_116_2">Arguments</A></LI>
1218 <LI><A HREF="#10_116_3">Description</A></LI>
1219 <LI><A HREF="#10_116_4">Example</A></LI>
1220 <LI><A HREF="#10_116_5">See Also</A></LI>
1221 </UL>
1222 <LI><A HREF="#ppdMarkOption">ppdMarkOption()</A></LI>
1223 <UL>
1224 <LI><A HREF="#10_117_1">Usage</A></LI>
1225 <LI><A HREF="#10_117_2">Arguments</A></LI>
1226 <LI><A HREF="#10_117_3">Returns</A></LI>
1227 <LI><A HREF="#10_117_4">Description</A></LI>
1228 <LI><A HREF="#10_117_5">Example</A></LI>
1229 <LI><A HREF="#10_117_6">See Also</A></LI>
1230 </UL>
1231 <LI><A HREF="#ppdOpen">ppdOpen()</A></LI>
1232 <UL>
1233 <LI><A HREF="#10_118_1">Usage</A></LI>
1234 <LI><A HREF="#10_118_2">Arguments</A></LI>
1235 <LI><A HREF="#10_118_3">Returns</A></LI>
1236 <LI><A HREF="#10_118_4">Description</A></LI>
1237 <LI><A HREF="#10_118_5">Example</A></LI>
1238 <LI><A HREF="#10_118_6">See Also</A></LI>
1239 </UL>
1240 <LI><A HREF="#ppdOpenFd">ppdOpenFd()</A></LI>
1241 <UL>
1242 <LI><A HREF="#10_119_1">Usage</A></LI>
1243 <LI><A HREF="#10_119_2">Arguments</A></LI>
1244 <LI><A HREF="#10_119_3">Returns</A></LI>
1245 <LI><A HREF="#10_119_4">Description</A></LI>
1246 <LI><A HREF="#10_119_5">Example</A></LI>
1247 <LI><A HREF="#10_119_6">See Also</A></LI>
1248 </UL>
1249 <LI><A HREF="#ppdOpenFile">ppdOpenFile()</A></LI>
1250 <UL>
1251 <LI><A HREF="#10_120_1">Usage</A></LI>
1252 <LI><A HREF="#10_120_2">Arguments</A></LI>
1253 <LI><A HREF="#10_120_3">Returns</A></LI>
1254 <LI><A HREF="#10_120_4">Description</A></LI>
1255 <LI><A HREF="#10_120_5">Example</A></LI>
1256 <LI><A HREF="#10_120_6">See Also</A></LI>
1257 </UL>
1258 <LI><A HREF="#ppdPageLength">ppdPageLength()</A></LI>
1259 <UL>
1260 <LI><A HREF="#10_121_1">Usage</A></LI>
1261 <LI><A HREF="#10_121_2">Arguments</A></LI>
1262 <LI><A HREF="#10_121_3">Returns</A></LI>
1263 <LI><A HREF="#10_121_4">Description</A></LI>
1264 <LI><A HREF="#10_121_5">Example</A></LI>
1265 <LI><A HREF="#10_121_6">See Also</A></LI>
1266 </UL>
1267 <LI><A HREF="#ppdPageSize">ppdPageSize()</A></LI>
1268 <UL>
1269 <LI><A HREF="#10_122_1">Usage</A></LI>
1270 <LI><A HREF="#10_122_2">Arguments</A></LI>
1271 <LI><A HREF="#10_122_3">Returns</A></LI>
1272 <LI><A HREF="#10_122_4">Description</A></LI>
1273 <LI><A HREF="#10_122_5">Example</A></LI>
1274 <LI><A HREF="#10_122_6">See Also</A></LI>
1275 </UL>
1276 <LI><A HREF="#ppdPageWidth">ppdPageWidth()</A></LI>
1277 <UL>
1278 <LI><A HREF="#10_123_1">Usage</A></LI>
1279 <LI><A HREF="#10_123_2">Arguments</A></LI>
1280 <LI><A HREF="#10_123_3">Returns</A></LI>
1281 <LI><A HREF="#10_123_4">Description</A></LI>
1282 <LI><A HREF="#10_123_5">Example</A></LI>
1283 <LI><A HREF="#10_123_6">See Also</A></LI>
1284 </UL>
1285 </UL>
1286 <HR>
1287 <H1 ALIGN="RIGHT"><A NAME="1">Preface</A></H1>
1288 <P>This software programmers manual provides software programming
1289  information for the Common UNIX Printing System (&quot;CUPS&quot;) Version 1.2.0.</P>
1290 <H2><A NAME="1_1">System Overview</A></H2>
1291 <P>CUPS provides a portable printing layer for UNIX&reg;-based operating
1292  systems. It has been developed by<A HREF="http://www.easysw.com"> Easy
1293  Software Products</A> to promote a standard printing solution for all
1294  UNIX vendors and users. CUPS provides the System V and Berkeley
1295  command-line interfaces.</P>
1296 <P>CUPS uses the Internet Printing Protocol (&quot;IPP&quot;) as the basis for
1297  managing print jobs and queues. The Line Printer Daemon (&quot;LPD&quot;) Server
1298  Message Block (&quot;SMB&quot;), and AppSocket (a.k.a. JetDirect) protocols are
1299  also supported with reduced functionality. CUPS adds network printer
1300  browsing and PostScript Printer Description (&quot;PPD&quot;) based printing
1301  options to support real-world printing under UNIX.</P>
1302 <P>CUPS also includes a customized version of GNU Ghostscript (currently
1303  based off GNU Ghostscript 5.50) and an image file RIP that are used to
1304  support non-PostScript printers. Sample drivers for HP and EPSON
1305  printers are included that use these filters.</P>
1307 <!-- NEED 2in -->
1308 <H2><A NAME="1_2">Document Overview</A></H2>
1309 <P>This software programmers manual is organized into the following
1310  sections:</P>
1311 <UL>
1312 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A></LI>
1313 <LI><A HREF="#CUPS_API">2 - The CUPS API</A></LI>
1314 <LI><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></LI>
1315 <LI><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></LI>
1316 <LI><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></LI>
1317 <LI><A HREF="#LICENSE">A - Software License Agreement</A></LI>
1318 <LI><A HREF="#CONSTANTS">B - Constants</A></LI>
1319 <LI><A HREF="#STRUCTURES">C - Structures</A></LI>
1320 <LI><A HREF="#FUNCTIONS">D - Functions</A></LI>
1321 </UL>
1322 <H2><A NAME="1_3">Notation Conventions</A></H2>
1323 <P>Various font and syntax conventions are used in this guide. Examples
1324  and their meanings and uses are explained below:
1325 <CENTER>
1326 <TABLE WIDTH="80%">
1327 <TR><TH>Example</TH><TD>&nbsp;&nbsp;&nbsp;</TD><TH>Description</TH></TR>
1328 <TR><TD>&nbsp;</TD></TR>
1329 <TR VALIGN="TOP"><TD><CODE>lpstat</CODE>
1330 <BR> <CODE>lpstat(1)</CODE></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>The names of commands;
1331  the first mention of a command or function in a chapter is followed by
1332  a manual page section number.</TD></TR>
1333 <TR><TD>&nbsp;</TD></TR>
1334 <TR VALIGN="TOP"><TD><VAR>/var</VAR>
1335 <BR><VAR> /usr/share/cups/data/testprint.ps</VAR></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>
1336 File and directory names.</TD></TR>
1337 <TR><TD>&nbsp;</TD></TR>
1338 <TR VALIGN="TOP"><TD NOWRAP><TT>Request ID is Printer-123</TT></TD><TD>
1339 &nbsp;&nbsp;&nbsp;</TD><TD>Screen output.</TD></TR>
1340 <TR><TD>&nbsp;</TD></TR>
1341 <TR VALIGN="TOP"><TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD><TD>
1342 &nbsp;&nbsp;&nbsp;</TD><TD>Literal user input; special keys like <KBD>ENTER</KBD> are
1343  in ALL CAPS.</TD></TR>
1344 <TR><TD>&nbsp;</TD></TR>
1345 <TR VALIGN="TOP"><TD>12.3</TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>Numbers in the text are
1346  written using the period (.) to indicate the decimal point.</TD></TR>
1347 </TABLE>
1348 </CENTER>
1350 <!-- NEED 3in -->
1351 </P>
1352 <H2><A NAME="1_4">Abbreviations</A></H2>
1353  The following abbreviations are used throughout this manual:
1354 <UL>
1355 <DL>
1356 <DT>kb</DT>
1357 <DD>Kilobytes, or 1024 bytes
1358 <BR>&nbsp;</DD>
1359 <DT>Mb</DT>
1360 <DD>Megabytes, or 1048576 bytes
1361 <BR>&nbsp;</DD>
1362 <DT>Gb</DT>
1363 <DD>Gigabytes, or 1073741824 bytes
1364 <BR>&nbsp;</DD>
1365 </DL>
1366 </UL>
1367 <H2><A NAME="1_5">Other References</A></H2>
1368 <UL>
1369 <DL>
1370 <DT>CUPS Software Administrators Manual</DT>
1371 <DD>An administration guide for the CUPS software.
1372 <BR>&nbsp;</DD>
1373 <DT>CUPS Software Users Manual</DT>
1374 <DD>An end-user guide for using the CUPS software.
1375 <BR>&nbsp;</DD>
1376 </DL>
1377 </UL>
1378 <H1 ALIGN="RIGHT"><A NAME="OVERVIEW">1 - Printing System Overview</A></H1>
1379 <P>This chapter provides an overview of how the Common UNIX Printing
1380  System works.</P>
1381 <H2><A NAME="2_1">The Printing Problem</A></H2>
1382 <P>For years<I> the printing problem</I> has plagued UNIX. Unlike
1383  Microsoft&reg; Windows&reg; or Mac OS, UNIX has no standard interface or system
1384  in place for supporting printers. Among the solutions currently
1385  available, the Berkeley and System V printing systems are the most
1386  prevalent.</P>
1387 <P>These printing systems support line printers (text only) or
1388  PostScript printers (text and graphics), and with some coaxing they can
1389  be made to support a full range of printers and file formats. However,
1390  because each varient of the UNIX operating system uses a different
1391  printing system than the next developing printer drivers for a wide
1392  range of printers and operating systems is extremely difficult. That
1393  combined with the limited volume of customers for each UNIX varient has
1394  forced most printer vendors to give up supporting UNIX entirely.</P>
1395 <P>CUPS is designed to eliminate<I> the printing problem</I>. One common
1396  printing system can be used by all UNIX varients to support the
1397  printing needs of users. Printer vendors can use its modular filter
1398  interface to develop a single driver program that supports a wide range
1399  of file formats with little or no effort. Since CUPS provides both the
1400  System V and Berkeley printing commands, users (and applications) can
1401  reap the benefits of this new technology with no changes.</P>
1402 <H2><A NAME="2_2">The Technology</A></H2>
1403 <P>CUPS is based upon an emerging Internet standard called the Internet
1404  Printing Protocol. IPP has been embraced by dozens of printer and
1405  printer server manufacturers and is supported by Microsoft Windows
1406  2000.</P>
1407 <P>IPP defines a standard protocol for printing as well as managing
1408  print jobs and printer options like media size, resolution, and so
1409  forth. Like all IP-based protocols, IPP can be used locally or over the
1410  Internet to printers hundreds or thousands of miles away. Unlike other
1411  protocols, however, IPP also supports access control, authentication,
1412  and encryption, making it a much more capable and secure printing
1413  solution than older ones.</P>
1414 <P>IPP is layered on top of the Hyper-Text Transport Protocol (&quot;HTTP&quot;)
1415  which is the basis of web servers on the Internet. This allows users to
1416  view documentation, check status information on a printer or server,
1417  and manage their printers, classes, and jobs using their web browser.</P>
1418 <P>CUPS provides a complete IPP/1.1 based printing system that provides
1419  Basic, Digest, and local certificate authentication and user, domain,
1420  or IP-based access control. TLS encryption will be available in future
1421  versions of CUPS.</P>
1422 <H2><A NAME="2_3">Jobs</A></H2>
1423 <P>Each file or set of files that is submitted for printing is called a<I>
1424  job</I>. Jobs are identified by a unique number starting at 1 and are
1425  assigned to a particular destination, usually a printer. Jobs can also
1426  have options associated with them such as media size, number of copies,
1427  and priority.</P>
1428 <H2><A NAME="2_4">Classes</A></H2>
1429 <P>CUPS supports collections of printers known as<I> classes</I>. Jobs
1430  sent to a class are forwarded to the first available printer in the
1431  class.</P>
1432 <H2><A NAME="2_5">Filters</A></H2>
1433 <P>Filters allow a user or application to print many types of files
1434  without extra effort. Print jobs sent to a CUPS server are filtered
1435  before sending them to a printer. Some filters convert job files to
1436  different formats that the printer can understand. Others perform page
1437  selection and ordering tasks.</P>
1438 <P>CUPS provides filters for printing many types of image files, HP-GL/2
1439  files, PDF files, and text files. CUPS also supplies PostScript and
1440  image file Raster Image Processor (&quot;RIP&quot;) filters that convert
1441  PostScript or image files into bitmaps that can be sent to a raster
1442  printer.</P>
1443 <H2><A NAME="2_6">Backends</A></H2>
1444 <P>Backends perform the most important task of all - they send the
1445  filtered print data to the printer.</P>
1446 <P>CUPS provides backends for printing over parallel, serial, and USB
1447  ports, and over the network via the IPP, JetDirect (AppSocket), and
1448  Line Printer Daemon (&quot;LPD&quot;) protocols. Additional backends are
1449  available in network service packages such as the SMB backend included
1450  with the popular SAMBA software.</P>
1451 <P>Backends are also used to determine the available devices. On startup
1452  each backend is asked for a list of devices it supports, and any
1453  information that is available. This allows the parallel backend to tell
1454  CUPS that an EPSON Stylus Color 600 printer is attached to parallel
1455  port 1, for example.</P>
1456 <H2><A NAME="2_7">Printer Drivers</A></H2>
1457 <P>Printer drivers in CUPS consist of one of more filters specific to a
1458  printer. CUPS includes sample printer drivers for Hewlett-Packard
1459  LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color,
1460  and Stylus Photo printers. While these drivers do not generate optimal
1461  output for the different printer models, they do provide basic printing
1462  and demonstrate how you can write your own printer drivers and
1463  incorporate them into CUPS.</P>
1464 <H2><A NAME="2_8">Networking</A></H2>
1465 <P>Printers and classes on the local system are automatically shared
1466  with other systems on the network. This allows you to setup one system
1467  to print to a printer and use this system as a printer server or spool
1468  host for all of the others. Users may then select a local printer by
1469  name or a remote printer using &quot;name@server&quot;.</P>
1470 <P>CUPS also provides<I> implicit classes</I>, which are collections of
1471  printers and/or classes with the same name. This allows you to setup
1472  multiple servers pointing to the same physical network printer, for
1473  example, so that you aren't relying on a single system for printing.
1474  Because this also works with printer classes, you can setup multiple
1475  servers and printers and never worry about a single point of failure
1476  unless all of the printers and servers go down!</P>
1477 <H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1>
1478 <P>This chapter describes the CUPS Application Programmers Interface
1479  (&quot;API&quot;).</P>
1480 <H2><A NAME="3_1">The CUPS API Library</A></H2>
1481 <P>The CUPS library provides a whole collection of interfaces needed to
1482  support the internal needs of the CUPS software as well as the needs of
1483  applications, filters, printer drivers, and backends.</P>
1484 <P>Unlike the rest of CUPS, the CUPS API library is provided under the
1485  GNU Library General Public License. This means that you can use the
1486  CUPS API library in both proprietary and open-source programs.</P>
1487 <P>Programs that use the CUPS API library typically will include the <CODE>
1488 &lt;cups/cups.h&gt;</CODE> header file:</P>
1489 <UL>
1490 <PRE>
1491 #include &lt;cups/cups.h&gt;
1493 ...
1495 jobid = cupsPrintFile(&quot;myprinter&quot;, &quot;filename.ps&quot;, &quot;title&quot;,
1496                       num_options, options);
1497 </PRE>
1498 </UL>
1499 <P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS
1500  API library:</P>
1501 <UL>
1502 <PRE>
1503 <B>cc -o program program.c -lcups ENTER</B>
1504 </PRE>
1505 </UL>
1506 <P>Additional options and libraries may be required depending on the
1507  operating system and the location of the CUPS API library.</P>
1508 <H3><A NAME="3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></H3>
1509 <P>GNU autoconf is a popular configuration tool used by many programs.
1510  Add the following lines to your<VAR> configure.in</VAR> file to check
1511  for the CUPS API library in your configuration script:</P>
1512 <UL>
1513 <PRE>
1514 AC_CHECK_LIB(socket,socket,
1515 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1516         LIBS=&quot;-lsocket $LIBS&quot;
1517 else
1518         echo &quot;Not using -lsocket since you are running IRIX.&quot;
1519 fi)
1520 AC_CHECK_LIB(nsl,gethostbyaddr,
1521 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1522         LIBS=&quot;-lnsl $LIBS&quot;
1523 else
1524         echo &quot;Not using -lnsl since you are running IRIX.&quot;
1525 fi)
1527 AC_CHECK_LIB(cups,httpConnect)
1528 </PRE>
1529 </UL>
1530 <H2><A NAME="3_2">Printing Services</A></H2>
1531 <P>The CUPS API library provides some basic printing services for
1532  applications that need to print files.</P>
1533 <H3><A NAME="3_2_1">Include Files</A></H3>
1534 <P>The include file used by all of these functions is <CODE>
1535 &lt;cups/cups.h&gt;</CODE>:</P>
1536 <UL>
1537 <PRE>
1538 #include &lt;cups/cups.h&gt;
1539 </PRE>
1540 </UL>
1541 <H3><A NAME="3_2_2">Printing a File</A></H3>
1542 <P>The CUPS API provides two functions for printing files. The first is <CODE>
1543 cupsPrintFile</CODE> which prints a single named file:</P>
1544 <UL>
1545 <PRE>
1546 #include &lt;cups/cups.h&gt;
1548 ...
1550 int jobid;
1552 ...
1554 jobid = cupsPrintFile(&quot;<I>name</I>&quot;, &quot;<I>filename</I>&quot;, &quot;<I>title</I>&quot;, 0, NULL);
1555 </PRE>
1556 </UL>
1557 <P>The <CODE>name</CODE> string is the name of the printer or class to
1558  print to. The <CODE>filename</CODE> string is the name of the file to
1559  print. The <CODE>title</CODE> string is the name of the print job, e.g.
1560  &quot;Acme Word Document&quot;.</P>
1561 <P>The return value is a unique ID number for the print job or 0 if
1562  there was an error.</P>
1563 <H3><A NAME="3_2_3">Printing Multiple Files</A></H3>
1564 <P>The second printing function is <CODE>cupsPrintFiles</CODE>:</P>
1565 <UL>
1566 <PRE>
1567 #include &lt;cups/cups.h&gt;
1569 ...
1571 int        jobid;
1572 int        num_files;
1573 const char *files[100];
1574 ...
1576 jobid = cupsPrintFiles(&quot;name&quot;, <I>num_files</I>, <I>files</I>, &quot;title&quot;, 0, NULL);
1577 </PRE>
1578 </UL>
1579 <P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE>
1580  you pass a file count (<CODE>num_files</CODE>) and filename pointer
1581  array (<CODE>files</CODE>) for each file that you want to print.</P>
1582 <P>As with <CODE>cupsPrintFile()</CODE> the return value is a unique ID
1583  for the print job.</P>
1584 <H3><A NAME="3_2_4">Cancelling Jobs</A></H3>
1585 <P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:</P>
1586 <UL>
1587 <PRE>
1588 #include &lt;cups/cups.h&gt;
1590 ...
1592 int jobid;
1593 int status;
1594 ...
1596 status = cupsCancelJob(&quot;<I>name</I>&quot;, <I>jobid</I>);
1597 </PRE>
1598 </UL>
1599 <P>The <CODE>name</CODE> string specifies the destination and is used to
1600  determine the server to send the request to. The <CODE>jobid</CODE>
1601  value is the integer returned from a previous <CODE>cupsPrintFile()</CODE>
1602  or <CODE>cupsPrintFiles()</CODE> call.</P>
1603 <P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
1604  successfully cancelled and <CODE>0</CODE> if there was an error.</P>
1605 <H3><A NAME="3_2_5">Getting the Available Printers and Classes</A></H3>
1606 <P>The <CODE>cupsGetDests()</CODE> function can be used to get a list of
1607  the available printers, classes, and instances that a user has defined:</P>
1608 <UL>
1609 <PRE>
1610 #include &lt;cups/cups.h&gt;
1612 ...
1614 int         num_dests;
1615 cups_dest_t *dests;
1617 ...
1619 num_dests = cupsGetDests(&amp;dests);
1620 </PRE>
1621 </UL>
1622 <P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure
1623  which defines the printer or class name, the instance name (if any), if
1624  it is the default destination, and the default options the user has
1625  defined for the destination:</P>
1626 <UL>
1627 <PRE>
1628 typedef struct               /**** Destination ****/
1629 {
1630   char          *name,       /* Printer or class name */
1631                 *instance;   /* Local instance name or NULL */
1632   int           is_default;  /* Is this printer the default? */
1633   int           num_options; /* Number of options */
1634   cups_option_t *options;    /* Options */
1635 } cups_dest_t;
1636 </PRE>
1637 </UL>
1638 <P>The destinations are sorted by name and instance for your
1639  convenience. Once you have the list of available destinations, you can
1640  lookup a specific destination using the <CODE>cupsGetDest()</CODE>
1641  function:</P>
1642 <UL>
1643 <PRE>
1644 #include &lt;cups/cups.h&gt;
1646 ...
1648 int         num_dests;
1649 cups_dest_t *dests;
1650 cups_dest_t *mydest;
1652 ...
1654 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1655 </PRE>
1656 </UL>
1657 <P>The <CODE>name</CODE> string is the printer or class name. You can
1658  pass a value of <CODE>NULL</CODE> to get the default destination.</P>
1659 <P>The <CODE>instance</CODE> string is the user-defined instance name.
1660  Pass <CODE>NULL</CODE> to select the default instance, e.g. &quot;name&quot;
1661  instead of &quot;name/instance&quot;.</P>
1662 <H3><A NAME="3_2_6">Printing with Options</A></H3>
1663 <P>All of the previous printing examples have passed <CODE>0</CODE> and <CODE>
1664 NULL</CODE> for the last two arguments to the <CODE>cupsPrintFile()</CODE>
1665  and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments
1666  are the number of options and a pointer to the option array:</P>
1667 <UL>
1668 <PRE>
1669 int cupsPrintFile(const char *name, const char *filename, const char *title,
1670                   int num_options, cups_option_t *options);
1671 int cupsPrintFiles(const char *name, int num_files, const char **files,
1672                    const char *title, int num_options,
1673                    cups_option_t *options);
1674 </PRE>
1675 </UL>
1676 <P>The <CODE>cups_option_t</CODE> structure holds each option and its
1677  value. These are converted as needed and passed to the CUPS server when
1678  printing a file.</P>
1679 <P>The simplest way of handling options is to use the <CODE>num_options</CODE>
1680  and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE>
1681  structure described earlier:</P>
1682 <UL>
1683 <PRE>
1684 #include &lt;cups/cups.h&gt;
1686 ...
1688 int         jobid;
1689 int         num_dests;
1690 cups_dest_t *dests;
1691 cups_dest_t *mydest;
1693 ...
1695 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1697 jobid  = cupsPrintFile(mydest-&gt;name, &quot;filename&quot;, &quot;title&quot;,
1698                        mydest-&gt;num_options, mydest-&gt;options);
1699 </PRE>
1700 </UL>
1701 <P>This effectively uses the options a user has previous selected
1702  without a lot of code.</P>
1703 <H3><A NAME="3_2_7">Setting Printer Options</A></H3>
1704 <P>Options can also be set by your program using the <CODE>
1705 cupsAddOption()</CODE> function:</P>
1706 <UL>
1707 <PRE>
1708 #include &lt;cups/cups.h&gt;
1710 ...
1712 int           num_options;
1713 cups_option_t *options;
1715 ...
1717 num_options = 0;
1718 options     = NULL;
1720 ...
1722 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1723 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1724 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1725 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1726 </PRE>
1727 </UL>
1728 <P>The <CODE>name</CODE> string is the name of the option, and the <CODE>
1729 value</CODE> string is the value for that option.</P>
1730 <P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of
1731  options. Since adding two options with the same name overwrites the
1732  first value with the second, do not assume that calling <CODE>
1733 cupsAddOptions()</CODE> 20 times will result in 20 options.</P>
1734 <P>Call <CODE>cupsFreeOptions</CODE> once you are done using the
1735  options:</P>
1736 <UL>
1737 <PRE>
1738 #include &lt;cups/cups.h&gt;
1740 ...
1742 int           num_options;
1743 cups_option_t *options;
1745 ...
1747 cupsFreeOptions(num_options, options);
1748 </PRE>
1749 </UL>
1750 <H3><A NAME="3_2_8">Getting Errors</A></H3>
1751 <P>If any of the CUPS API printing functions returns an error, the
1752  reason for that error can be found by calling <CODE>cupsLastError()</CODE>
1753  and <CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE>
1754  returns the last IPP error code that was encountered. <CODE>
1755 cupsErrorString()</CODE> converts the error code to a localized message
1756  string suitable for presentation to the user:</P>
1757 <UL>
1758 <PRE>
1759 #include &lt;cups/cups.h&gt;
1761 ...
1763 int jobid;
1765 ...
1767 if (jobid == 0)
1768   puts(cupsErrorString(cupsLastError()));
1769 </PRE>
1770 </UL>
1771 <H3><A NAME="3_2_9">Passwords and Authentication</A></H3>
1772 <P>CUPS supports authentication of any request, including submission of
1773  print jobs. The default mechanism for getting the username and password
1774  is to use the login user and a password from the console.</P>
1775 <P>To support other types of applications, in particular Graphical User
1776  Interfaces (&quot;GUIs&quot;), the CUPS API provides functions to set the default
1777  username and to register a callback function that returns a password
1778  string.</P>
1779 <P>The<A HREF="#cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>
1780  function is used to set a password callback in your program. Only one
1781  function can be used at any time.</P>
1782 <P>The<A HREF="#cupsSetUser"> <CODE>cupsSetUser()</CODE></A> function
1783  sets the current username for authentication. This function can be
1784  called by your password callback function to change the current
1785  username as needed.</P>
1786 <P>The following example shows a simple password callback that gets a
1787  username and password from the user:</P>
1788 <UL>
1789 <PRE>
1790 #include &lt;cups/cups.h&gt;
1792 const char *
1793 my_password_cb(const char *prompt)
1794 {
1795   char  user[65];
1798   puts(prompt);
1800  /* Get a username from the user */
1801   printf(&quot;Username: &quot;);
1802   if (fgets(user, sizeof(user), stdin) == NULL)
1803     return (NULL);
1805  /* Strip the newline from the string and set the user */
1806   user[strlen(user) - 1] = '\0';
1808   cupsSetUser(user);
1810  /* Use getpass() to ask for the password... */
1811   return (getpass(&quot;Password: &quot;));
1812 }
1814 ...
1816 cupsSetPasswordCB(my_password_cb);
1817 </PRE>
1818 </UL>
1819 <P>Similarly, a GUI interface could display the prompt string in a
1820  window with input fields for the username and password. The username
1821  should probably default to the value of<A HREF="#cupsUser"> <CODE>
1822 cupsUser()</CODE></A> to make things easier on the user.</P>
1823 <H2><A NAME="3_3">PPD Services</A></H2>
1824 <P>CUPS includes functions to access and manipulate PostScript Printer
1825  Description (&quot;PPD&quot;) files that are used with the printer drivers in
1826  CUPS.</P>
1827 <P>Each PPD file enumerates the available features provided by a
1828  printer, including conflict information for specific options (e.g.
1829  can't duplex output on envelopes.)</P>
1830 <H3><A NAME="3_3_1">Include Files</A></H3>
1831 <P>Include the <CODE>&lt;cups/ppd.h&gt;</CODE> header file to use the PPD
1832  functions:</P>
1833 <UL>
1834 <PRE>
1835 #include &lt;cups/ppd.h&gt;
1836 </PRE>
1837 </UL>
1838 <P>This header file is also included by the <CODE>&lt;cups/cups.h&gt;</CODE>
1839  header file.</P>
1840 <H3><A NAME="3_3_2">Getting a PPD File for a Printer</A></H3>
1841 <P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the
1842  named printer or class:</P>
1843 <UL>
1844 <PRE>
1845 #include &lt;cups/cups.h&gt;
1847 ...
1849 const char *filename;
1851 filename = cupsGetPPD(&quot;<I>name</I>&quot;);
1852 </PRE>
1853 </UL>
1854 <P>The <CODE>name</CODE> string is the name of the printer or class,
1855  including the remote server name as appropriate (e.g.
1856  &quot;printer@server&quot;.)</P>
1857 <P>The return value is a pointer to a filename in static storage; this
1858  value is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If
1859  the printer or class does not exist, a <CODE>NULL</CODE> pointer will
1860  be returned.</P>
1861 <H3><A NAME="3_3_3">Loading a PPD File</A></H3>
1862 <P>The <CODE>ppdOpenFile()</CODE> function &quot;opens&quot; a PPD file and loads
1863  it into memory:</P>
1864 <UL>
1865 <PRE>
1866 #include &lt;cups/ppd.h&gt;
1868 ...
1870 ppd_file_t *ppd;
1872 ppd = ppdOpenFile(&quot;<I>filename</I>&quot;);
1873 </PRE>
1874 </UL>
1875 <P>The <CODE>filename</CODE> string is the name of the file to load,
1876  such as the value returned by the <CODE>cupsGetPPD()</CODE> function.</P>
1877 <P>The return value is a pointer to a structure describing the contents
1878  of the PPD file or NULL if the PPD file could not be read.</P>
1879 <H3><A NAME="3_3_4">Freeing PPD File Information</A></H3>
1880 <P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE>
1881  function to free all memory that has been used:</P>
1882 <UL>
1883 <PRE>
1884 #include &lt;cups/ppd.h&gt;
1886 ...
1888 ppd_file_t *ppd;
1890 ...
1892 ppdClose(ppd);
1893 </PRE>
1894 </UL>
1895 <H3><A NAME="3_3_5">The PPD File Structure</A></H3>
1896 <P>Each PPD file contains a number of capability attributes, printer
1897  options, and conflict definitions. The page size options also include
1898  the physical margins for the printer and the minimum and maximum sizes
1899  for the printer. All of this information is stored in the <CODE>
1900 ppd_file_t</CODE> structure.</P>
1901 <H4>Capabilities</H4>
1902 <P>Each PPD file contains a number of informational attributes that
1903  describe the capabilities of the printer. These are provided in the <CODE>
1904 ppd_file_t</CODE> structure in the following members:
1905 <CENTER>
1906 <TABLE BORDER="1" WIDTH="80%">
1907 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
1908 <TR><TD><CODE>accurate_screens</CODE></TD><TD><CODE>int</CODE></TD><TD>1
1909  = supports accurate screens</TD></TR>
1910 <TR><TD><CODE>color_device</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1911  color device</TD></TR>
1912 <TR><TD><CODE>colorspace</CODE></TD><TD><CODE>ppd_cs_t</CODE></TD><TD>
1913 Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB,
1915 <TR><TD><CODE>contone_only</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1916  printer is continuous tone only</TD></TR>
1917 <TR><TD><CODE>num_emulations
1918 <BR> emulations</CODE></TD><TD><CODE>int
1919 <BR> ppd_emul_t *</CODE></TD><TD>Emulations supported by the printer</TD>
1920 </TR>
1921 <TR><TD><CODE>flip_duplex</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1922  need to flip odd pages when duplexing</TD></TR>
1923 <TR><TD><CODE>num_fonts
1924 <BR> fonts</CODE></TD><TD><CODE>int
1925 <BR> char **</CODE></TD><TD>The fonts available on the printer.</TD></TR>
1926 <TR><TD><CODE>jcl_begin
1927 <BR> jcl_ps
1928 <BR> jcl_end</CODE></TD><TD><CODE>char *</CODE></TD><TD>Job Control
1929  Language commands for PostScript output</TD></TR>
1930 <TR><TD><CODE>landscape</CODE></TD><TD><CODE>int</CODE></TD><TD>
1931 Landscape orientation, -90 or 90 degrees</TD></TR>
1932 <TR><TD><CODE>lang_encoding</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1933 The character used for the option strings</TD></TR>
1934 <TR><TD><CODE>lang_version</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1935 The language used for the options strings (English, French, etc.)</TD></TR>
1936 <TR><TD><CODE>language_level</CODE></TD><TD><CODE>int</CODE></TD><TD>
1937 PostScript language level, 1 to 3</TD></TR>
1938 <TR><TD><CODE>manual_copies</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1939  Copies are done manually</TD></TR>
1940 <TR><TD><CODE>model_number</CODE></TD><TD><CODE>int</CODE></TD><TD>
1941 Driver-specific model number.</TD></TR>
1942 <TR><TD><CODE>patches</CODE></TD><TD><CODE>char *</CODE></TD><TD>Patch
1943  commands to send to the printer</TD></TR>
1944 <TR><TD><CODE>manufacturer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1945 The Manufacturer attribute from the PPD file, if any</TD></TR>
1946 <TR><TD><CODE>modelname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1947  ModelName attribute from the PPD file</TD></TR>
1948 <TR><TD><CODE>nickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1949  NickName attribute from the PPD file, if any</TD></TR>
1950 <TR><TD><CODE>product</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1951  Product attribute from the PPD file, if any</TD></TR>
1952 <TR><TD><CODE>shortnickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1953 The ShortNickName attribute from the PPD file, if any</TD></TR>
1954 <TR><TD><CODE>throughput</CODE></TD><TD><CODE>int</CODE></TD><TD>Number
1955  of pages per minute</TD></TR>
1956 <TR><TD><CODE>ttrasterizer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1957 The TruType font rasterizer (Type42)</TD></TR>
1958 <TR><TD><CODE>variable_sizes</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1959  supports variable sizes</TD></TR>
1960 </TABLE>
1961 </CENTER>
1962 </P>
1963 <H4>Options and Groups</H4>
1964 <P>PPD files support multiple options, which are stored in <CODE>
1965 ppd_option_t</CODE> and <CODE>ppd_choice_t</CODE> structures by the PPD
1966  functions.</P>
1967 <P>Each option in turn is associated with a group stored in the <CODE>
1968 ppd_group_t</CODE> structure. Groups can be specified in the PPD file;
1969  if an option is not associated with a group then it is put in a
1970  &quot;General&quot; or &quot;Extra&quot; group depending on the option.</P>
1971 <P>Groups can also have sub-groups; CUPS currently limits the depth of
1972  sub-groups to 1 level to reduce programming complexity.</P>
1973 <H4>Conflicts</H4>
1974 <P>PPD files support specification of conflict conditions between
1975  different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE>
1976  structures which specify the options that conflict with each other.</P>
1977 <H4>Page Sizes</H4>
1978 <P>PPD files specify all of the available pages sizes and the physical
1979  margins associated with them. These sizes are stored in <CODE>
1980 ppd_size_t</CODE> structures and are available in the <CODE>num_sizes</CODE>
1981  and <CODE>sizes</CODE> members of the <CODE>ppd_file_t</CODE>
1982  structure. You can lookup a particular page size with the <CODE>
1983 ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and <CODE>
1984 ppdPageSize()</CODE> functions:</P>
1985 <UL>
1986 <PRE>
1987 #include &lt;cups/ppd.h&gt;
1989 ...
1991 ppd_file_t *ppd;
1992 ppd_size_t *size;
1993 float      width;
1994 float      length;
1996 ...
1998 size   = ppdPageSize(ppd, &quot;<I>size</I>&quot;);
1999 width  = ppdPageWidth(ppd, &quot;<I>size</I>&quot;);
2000 length = ppdPageLength(ppd, &quot;<I>size</I>&quot;);
2001 </PRE>
2002 </UL>
2003 <P>The <CODE>size</CODE> string is the named page size option. The width
2004  and length are in points; there are 72 points per inch. The <CODE>
2005 ppd_size_t</CODE> structure contains the width, length, and margin
2006  information:</P>
2007 <UL>
2008 <PRE>
2009 typedef struct    /**** Page Sizes ****/
2010 {
2011   int   marked;   /* Page size selected? */
2012   char  name[41]; /* Media size option */
2013   float width,    /* Width of media in points */
2014         length,   /* Length of media in points */
2015         left,     /* Left printable margin in points */
2016         bottom,   /* Bottom printable margin in points */
2017         right,    /* Right printable margin in points */
2018         top;      /* Top printable margin in points */
2019 } ppd_size_t;
2020 </PRE>
2021 </UL>
2022 <H4>Custom Page Sizes</H4>
2023 <P>Besides the standard page sizes listed in a PPD file, some printers
2024  support variable or custom page sizes. If <CODE>variables_sizes</CODE>
2025  is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and <CODE>
2026 custom_margins</CODE> members of the <CODE>ppd_file_t</CODE> structure
2027  define the limits of the variable sizes.</P>
2028 <P>To get the resulting media size, use a page size string of <CODE>
2029 Custom.<I>width</I>x<I>length</I></CODE>, where <CODE>width</CODE> and <CODE>
2030 length</CODE> are integer values in points:</P>
2031 <UL>
2032 <PRE>
2033 Custom.612x792   [8.5 inches wide, 11 inches long]
2034 Custom.1224x792  [17 inches wide, 11 inches long]
2035 </PRE>
2036 </UL>
2037 <H3><A NAME="3_3_6">Marking Options</A></H3>
2038 <P>Before marking any user-defined options, call the <CODE>
2039 ppdMarkDefaults()</CODE> function to mark the default options from the
2040  PPD file:</P>
2041 <UL>
2042 <PRE>
2043 #include &lt;cups/ppd.h&gt;
2045 ...
2047 ppd_file_t *ppd;
2049 ...
2051 ppdMarkDefaults(ppd);
2052 </PRE>
2053 </UL>
2054 <P>Then call the <CODE>ppdMarkOption()</CODE> function to mark
2055  individual options:</P>
2056 <UL>
2057 <PRE>
2058 #include &lt;cups/ppd.h&gt;
2060 ...
2062 ppd_file_t *ppd;
2063 int        conflicts;
2065 ...
2067 conflicts = ppdMarkOption(ppd, &quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;);
2068 </PRE>
2069 </UL>
2070 <P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a
2071  particular option and choice, respectively. The return value is 0 if
2072  there are not conflicts created by the selection.</P>
2073 <P>CUPS also provides a convenience function for marking all options in
2074  the <CODE>cups_option_t</CODE> structure:</P>
2075 <UL>
2076 <PRE>
2077 #include &lt;cups/cups.h&gt;
2079 ...
2081 ppd_file_t    *ppd;
2082 int           num_options;
2083 cups_option_t *options;
2084 int           conflicts;
2086 ...
2088 conflicts = cupsMarkOptions(ppd, num_options, options);
2089 </PRE>
2090 </UL>
2091 <P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the
2092  IPP job template attributes to PPD options. The return value is the
2093  number of conflicts present.</P>
2094 <H3><A NAME="3_3_7">Checking for Conflicts</A></H3>
2095 <P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE>
2096  functions return the number of conflicts with the currently marked
2097  options.</P>
2098 <P>Call the <CODE>ppdConflicts()</CODE> function to get the number of
2099  conflicts after you have marked all of the options:</P>
2100 <UL>
2101 <PRE>
2102 #include &lt;cups/cups.h&gt;
2104 ...
2106 ppd_file_t *ppd;
2107 int        conflicts;
2109 ...
2111 conflicts = ppdConflicts(ppd);
2112 </PRE>
2113 </UL>
2114 <P>The return value is the number of conflicting options, or 0 if there
2115  are no conflicts.</P>
2116 <H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
2117 <P>This chapter describes how to write a file filter for CUPS.</P>
2118 <H2><A NAME="4_1">Overview</A></H2>
2119 <P>File filters are programs that convert from one or more MIME types to
2120  another type. Filters use a common command-line and environment
2121  interface that allows them to be joined as needed to print files to any
2122  type of printer.</P>
2123 <H3><A NAME="4_1_1">Security Considerations</A></H3>
2124 <P>Filters are normally run as a non-priviledged user, so the major
2125  security consideration is resource utilization - filters should not
2126  depend on unlimited amounts of memory and disk space.</P>
2127 <H3><A NAME="4_1_2">Users and Groups</A></H3>
2128 <P>The default CUPS configuration runs filters as user &quot;lp&quot; and group
2129  &quot;other&quot;.</P>
2130 <H3><A NAME="4_1_3">Temporary Files</A></H3>
2131 <P>Temporary files should be created in the directory specified by the
2132  &quot;TMPDIR&quot; environment variable. The<A HREF="#cupsTempFile"> <CODE>
2133 cupsTempFile()</CODE></A> function can be used to safely choose
2134  temporary files in this directory.</P>
2135 <H3><A NAME="4_1_4">Sending Messages to the User</A></H3>
2136 <P>The CUPS scheduler collects messages sent to the standard error file
2137  by the filter. These messages are relayed to the user based upon the
2138  scheduler <CODE>LogLevel</CODE> directive.</P>
2139 <P>The type of message is determined by an initial prefix sent on each
2140  line:</P>
2141 <UL>
2142 <LI><CODE>DEBUG:</CODE> - a debug message</LI>
2143 <LI><CODE>INFO:</CODE> - an informational message</LI>
2144 <LI><CODE>WARNING:</CODE> - a warning message</LI>
2145 <LI><CODE>ERROR:</CODE> - an error message</LI>
2146 <LI><CODE>PAGE:</CODE> - a page accounting message</LI>
2147 </UL>
2148 <P>If the line of text does not begin with any of the above prefixes, it
2149  is treated as a debug message. Text following the prefix is copied to
2150  the <CODE>printer-state-message</CODE> attribute for the printer, and
2151  also added to the<VAR> error_log</VAR> unless it is an informational or
2152  page accounting message.</P>
2153 <H3><A NAME="4_1_5">Page Accounting</A></H3>
2154 <P>Page accounting messages are used to inform the server when one or
2155  more pages are printed. Each line has the form:</P>
2156 <UL>
2157 <PRE>
2158 PAGE: page-number copy-count
2159 </PRE>
2160 </UL>
2161 <P>The<I> page-number</I> field is the current page number, starting at
2162  1. The<I> copy-count</I> field specifies the number of copies of that
2163  page that was produced.</P>
2164 <P>Page account messages are added to the<VAR> page_log</VAR> file and
2165  cause the <CODE>job-sheets-completed</CODE> attribute to be updated for
2166  the job.</P>
2167 <H3><A NAME="4_1_6">Command-Line Arguments</A></H3>
2168 <P>Every filter accepts exactly 6 or 7 command-line arguments:</P>
2169 <UL>
2170 <PRE>
2171 printer job user title copies options [filename]
2172 </PRE>
2173 <LI><CODE>printer</CODE> - The name of the printer queue (normally this
2174  is the name of the program being run)</LI>
2175 <LI><CODE>job</CODE> - The numeric job ID for the job being printed</LI>
2176 <LI><CODE>user</CODE> - The string from the <CODE>originating-user-name</CODE>
2177  attribute</LI>
2178 <LI><CODE>title</CODE> - The string from the <CODE>job-name</CODE>
2179  attribute</LI>
2180 <LI><CODE>copies</CODE> - The numeric value from the <CODE>number-copies</CODE>
2181  attribute</LI>
2182 <LI><CODE>options</CODE> - String representations of the job template
2183  attributes, separated by spaces. Boolean attributes are provided as
2184  &quot;name&quot; for true values and &quot;noname&quot; for false values. All other
2185  attributes are provided as &quot;name=value&quot; for single-valued attributes
2186  and &quot;name=value1,value2,...,valueN&quot; for set attributes</LI>
2187 <LI><CODE>filename</CODE> - The request file</LI>
2188 </UL>
2189 <P>The<I> filename</I> argument is only provided to the first filter in
2190  the chain; all filters<B> must</B> be prepared to read the print file
2191  from the standard input if the<I> filename</I> argument is omitted.</P>
2192 <H3><A NAME="4_1_7">Copy Generation</A></H3>
2193 <P>The<I> copies</I> argument specifies the number of copies to produce
2194  of the input file. In general, you should only generate copies if the<I>
2195  filename</I> argument is supplied. The only exception to this are
2196  filters that produce device-independent PostScript output (without any
2197  printer commands from the printer's PPD file), since the PostScript
2198  filter <CODE>pstops</CODE> is responsible for copy generation.</P>
2199 <H3><A NAME="4_1_8">Environment Variables</A></H3>
2200 <P>Every filter receives a fixed set of environment variables that can
2201  be used by the filter:</P>
2202 <UL>
2203 <LI><CODE>CHARSET</CODE> - The character set used by the client for this
2204  print file</LI>
2205 <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as
2206  &quot;application/postscript&quot;</LI>
2207 <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files</LI>
2208 <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration
2209  files</LI>
2210 <LI><CODE>DEVICE_URI</CODE> - The output device URI</LI>
2211 <LI><CODE>LANG</CODE> - The language used by the client for this print
2212  file</LI>
2213 <LI><CODE>PATH</CODE> - The execution path exported to the filter</LI>
2214 <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file</LI>
2215 <LI><CODE>PRINTER</CODE> - The name of the printer queue</LI>
2216 <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter
2217  should use</LI>
2218 <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically
2219  &quot;CUPS/1.1&quot;</LI>
2220 <LI><CODE>TZ</CODE> - The local timezone</LI>
2221 <LI><CODE>USER</CODE> - The name of the current user</LI>
2222 </UL>
2223 <H2><A NAME="4_2">Dissecting the HP-GL/2 Filter</A></H2>
2224 <P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a
2225  complex program that converts HP-GL/2 files into device-independent
2226  PostScript output. Since it produces device-independent PostScript
2227  output, it does not need to handle copy generation or writing printer
2228  options from the printer's PPD file.</P>
2229 <H3><A NAME="4_2_1">Initializing the Filter</A></H3>
2230 <P>The first task of any filter is to ensure that the correct number of
2231  command-line arguments are present:</P>
2232 <UL>
2233 <PRE>
2234 if (argc &lt; 6 || argc &gt; 7)
2235 {
2236   fputs(&quot;ERROR: hpgltops job-id user title copies options [file]\n&quot;, stderr);
2237   return (1);
2238 }
2239 </PRE>
2240 </UL>
2241 <P>After this you open the print file or read from the standard input as
2242  needed:</P>
2243 <UL>
2244 <PRE>
2245 FILE *fp;
2247 /*
2248  * If we have 7 arguments, print the file named on the command-line.
2249  * Otherwise, send stdin instead...
2250  */
2252 if (argc == 6)
2253   fp = stdin;
2254 else
2255 {
2256  /*
2257   * Try to open the print file...
2258   */
2260   if ((fp = fopen(argv[6], &quot;rb&quot;)) == NULL)
2261   {
2262     perror(&quot;ERROR: unable to open print file - &quot;);
2263     return (1);
2264   }
2265 }
2266 </PRE>
2267 </UL>
2268 <P>Once the print file has been opened, options can be processed using
2269  the<A HREF="#cupsParseOptions"> <CODE>cupsParseOptions()</CODE></A> and<A
2270 HREF="#cupsGetOption"> <CODE>cupsGetOption()</CODE></A> functions:</P>
2271 <UL>
2272 <PRE>
2273 int           num_options;
2274 cups_option_t *options;
2275 const char    *val;
2277 /*
2278  * Process command-line options and write the prolog...
2279  */
2281 options     = NULL;
2282 num_options = cupsParseOptions(argv[5], 0, 
2284 if ((val = cupsGetOption(&quot;blackplot&quot;, num_options, options)) != NULL)
2285   shading = 0;
2287 if ((val = cupsGetOption(&quot;fitplot&quot;, num_options, options)) != NULL)
2288   FitPlot = 1;
2290 if ((val = cupsGetOption(&quot;penwidth&quot;, num_options, options)) != NULL)
2291   PenWidth = (float)atoi(val) * 0.001f;
2292 </PRE>
2293 </UL>
2294 <P>After the options have been processed, the filter writes PostScript
2295  code to the standard output based on the print file, closes the print
2296  file (as needed), and returns 0 to the scheduler.</P>
2297 <H2><A NAME="4_3">PostScript Output</A></H2>
2298 <P>Filters that produce PostScript output must generate output
2299  conforming to the Adobe Document Structuring Conventions, 3.0. In
2300  general this means the beginning of each file must begin with:</P>
2301 <UL>
2302 <PRE>
2303 %!PS-Adobe-3.0
2304 %%BoundingBox: left bottom right top
2305 %%Pages: (atend)
2306 %%EndComments
2307 </PRE>
2308 </UL>
2309 <P>The<I> left</I>,<I> bottom</I>,<I> right</I>, and<I> top</I> values
2310  are integers in points from the lower-lefthand corner of the page.</P>
2311 <P>Pages must be surrounded by:</P>
2312 <UL>
2313 <PRE>
2314 %%Page: number number
2315 gsave
2316 ...
2317 grestore
2318 showpage
2319 </PRE>
2320 </UL>
2321 <P>And the end of each file must contain:</P>
2322 <UL>
2323 <PRE>
2324 %%Trailer
2325 %%Pages: number-pages
2326 %%EOF
2327 </PRE>
2328 </UL>
2329 <P>These comments allow the PostScript filter to correctly perform page
2330  accounting, copy generation, N-up printing, and so forth.</P>
2331 <H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A>
2332 </H1>
2333 <P>This chapter discusses how to write a printer driver, which is a
2334  special filter program that converts CUPS raster data into the
2335  appropriate commands and data required for a printer.</P>
2336 <H2><A NAME="5_1">Overview</A></H2>
2337 <P>Raster printers utilitize PPD files that specify one or more
2338  device-specific filters that handle converting print files for the
2339  printer. The simplest raster printer drivers provide a single filter
2340  that converts CUPS raster data to the printer's native format.</P>
2341 <H3><A NAME="5_1_1">CUPS Raster Data</A></H3>
2342 <P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists
2343  of a stream of raster page descriptions produced by one of the RIP
2344  filters, such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.</P>
2345 <P>Each page of data begins with a page dictionary structure called<A HREF="#cups_raster_header_t">
2346  <CODE>cups_raster_header_t</CODE></A>. This structure contains the
2347  colorspace, bits per color, media size, media type, hardware
2348  resolution, and so forth.</P>
2349 <P>After the page dictionary comes the page data which is a
2350  full-resolution, uncompressed bitmap representing the page in the
2351  printer's output colorspace.</P>
2352 <H3><A NAME="5_1_2">Page Accounting</A></H3>
2353 <P>Printer drivers must handle all page accounting. This means they must
2354  send &quot;PAGE:&quot; messages to the standard error file for each page (and in
2355  many cases, copy) sent to the printer.</P>
2356 <H3><A NAME="5_1_3">Color Management</A></H3>
2357 <P>Printer drivers can implement their color management via the <CODE>
2358 cupsColorProfile</CODE> attributes in the PPD file or internally in the
2359  driver from a device-independent colorspace. In general, color
2360  management performed by the RIP filters is more efficient than that
2361  performed inside printer drivers.</P>
2362 <P>For example, the <CODE>pstoraster</CODE> filter often only has to
2363  perform a color conversion once each time the color is used for
2364  multiple output pixels, while the raster filter must convert every
2365  pixel on the page.</P>
2366 <H3><A NAME="5_1_4">Device and Bitmap Variables</A></H3>
2367 <P>Besides the standard PostScript page device dictionary variables
2368  defined in the Adobe PostScript Level 3 reference manual, the CUPS
2369  filters support additional variables that are passed in the page device
2370  dictionary header for the page and in some cases control the type of
2371  raster data that is generated:
2372 <CENTER>
2373 <TABLE BORDER="1" WIDTH="90%">
2374 <TR><TH>Variable</TH><TH>Type</TH><TH>Description</TH></TR>
2375 <TR><TD>cupsWidth</TD><TD>read-only integer</TD><TD>Width of bitmap in
2376  pixels</TD></TR>
2377 <TR><TD>cupsHeight</TD><TD>read-only integer</TD><TD>Height of bitmap in
2378  pixels</TD></TR>
2379 <TR><TD>cupsMediaType</TD><TD>read-write integer</TD><TD>Device-specific
2380  media type code</TD></TR>
2381 <TR><TD>cupsBitsPerColor</TD><TD>read-write integer</TD><TD>Number of
2382  bits per color; 1, 2, 4, and 8 are currently supported</TD></TR>
2383 <TR><TD>cupsBitsPerPixel</TD><TD>read-only integer</TD><TD>Number of
2384  bits per pixel; 1 to 32</TD></TR>
2385 <TR><TD>cupsBytesPerLine</TD><TD>read-only integer</TD><TD>Number of
2386  bytes per line of raster graphics</TD></TR>
2387 <TR><TD>cupsColorOrder</TD><TD>read-write enum</TD><TD>The order of
2388  color values in the bitmap:
2389 <UL>
2392 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...</LI>
2393 </UL>
2394 </TD></TR>
2395 <TR><TD>cupsColorSpace</TD><TD>read-write enum</TD><TD>The colorspace of
2396  the bitmap:
2397 <UL>
2398 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI>
2399 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI>
2400 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI>
2401 <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI>
2402 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI>
2403 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI>
2404 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI>
2405 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI>
2406 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI>
2407 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
2408  light cyan, light magenta</LI>
2409 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic
2410  magenta, metallic cyan, black</LI>
2411 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic
2412  magenta, metallic cyan, metallic grey (silver)</LI>
2413 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white
2414  pigment)</LI>
2415 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI>
2416 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI>
2417 </UL>
2418 </TD></TR>
2419 <TR><TD>cupsCompression</TD><TD>read-write integer</TD><TD>
2420 Device-specific compression type code</TD></TR>
2421 <TR><TD>cupsRowCount</TD><TD>read-write integer</TD><TD>Device-specific
2422  row count value</TD></TR>
2423 <TR><TD>cupsRowFeed</TD><TD>read-write integer</TD><TD>Device-specific
2424  row feed value</TD></TR>
2425 <TR><TD>cupsRowStep</TD><TD>read-write integer</TD><TD>Device-specific
2426  row step value</TD></TR>
2427 </TABLE>
2428 </CENTER>
2429 </P>
2430 <P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit
2431  per color are transmitted to the raster driver in KCMY colorspace; the
2432  driver is responsible for producing the correct separation of normal
2433  and light cyan and magenta inks.</P>
2434 <H2><A NAME="5_2">Dissecting the HP-PCL Driver</A></H2>
2435 <P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>)
2436  converts bitmap data from the raster filters into HP-PCL commands for
2437  most PCL-compatible printers. The actual format of the raster data is
2438  controlled by the PPD file being used -<VAR> deskjet.ppd</VAR> or<VAR>
2439  laserjet.ppd</VAR>.</P>
2440 <H3><A NAME="5_2_1">PPD Files</A></H3>
2441 <P>PPD files play an important part of all raster printer drivers.
2442  Options defined in the PPD file contain PostScript commands that
2443  control the raster data that is sent to the printer driver.</P>
2444 <P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>, <CODE>
2445 InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>, and <CODE>
2446 Resolution</CODE> options. Each option is shown using the standard PPD
2447  format:</P>
2448 <UL>
2449 <PRE>
2450 *OpenUI *PageSize/Media Size: PickOne
2451 *OrderDependency: 10 AnySetup *PageSize
2452 *DefaultPageSize: Letter
2453 *PageSize Letter/US Letter: &quot;&lt;&lt;
2454 /PageSize [612 792]
2455 /ImagingBBox null
2456 &gt;&gt; setpagedevice&quot;
2457 *End
2458 *PageSize Legal/US Legal: &quot;&lt;&lt;
2459 /PageSize [612 1008]
2460 /ImagingBBox null
2461 &gt;&gt; setpagedevice&quot;
2462 *End
2463 *PageSize A4/A4: &quot;&lt;&lt;
2464 /PageSize [595 842]
2465 /ImagingBBox null
2466 &gt;&gt; setpagedevice&quot;
2467 *End
2468 *CloseUI: *PageSize
2469 </PRE>
2470 </UL>
2471 <P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first
2472  name is the option with an asterisk (*) in front of it. The first name
2473  is usually followed by a slash (/) and a human-readable version of the
2474  option name.</P>
2475 <P>Every option<B> must</B> have a default value, specified using the <CODE>
2476 Default<I>Option</I></CODE> keyword.</P>
2477 <P>Each option begins with the option name followed by the computer and
2478  human-readable values. The PostScript commands follow these inside
2479  double quotes. PostScript commands can be provided on a single line:</P>
2480 <UL>
2481 <PRE>
2482 *PageSize A4/A4: &quot;&lt;&lt;/PageSize[595 842]/ImagingBBox null&gt;&gt; setpagedevice&quot;
2483 </PRE>
2484 </UL>
2485 <P>or broken down on separate lines using the <CODE>End</CODE> keyword
2486  to terminate them:</P>
2487 <UL>
2488 <PRE>
2489 *PageSize A4/A4: &quot;&lt;&lt;
2490 /PageSize [595 842]
2491 /ImagingBBox null
2492 &gt;&gt; setpagedevice&quot;
2493 *End
2494 </PRE>
2495 </UL>
2496 <P>The choice of the two formats is usually esthetic. However, each line
2497  in a PPD file must not exceed 255 characters, so if your PostScript
2498  commands are long you may need to break them up on separate lines.</P>
2499 <H3><A NAME="5_2_2">Reading Raster Data</A></H3>
2500 <P>As with any filter, your printer driver should handle raster data
2501  from a filename specified on the command-line or from the standard
2502  input. The<A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>
2503  function opens a raster stream for printing:</P>
2504 <UL>
2505 <PRE>
2506 int           fd;   /* File descriptor */
2507 cups_raster_t *ras; /* Raster stream for printing */
2510 /*
2511  * Check for valid arguments...
2512  */
2514 if (argc &lt; 6 || argc &gt; 7)
2515 {
2516  /*
2517   * We don't have the correct number of arguments; write an error message
2518   * and return.
2519   */
2521   fputs(&quot;ERROR: rastertopcl job-id user title copies options [file]\n&quot;, stderr);
2522   return (1);
2523 }
2525 /*
2526  * Open the page stream...
2527  */
2529 if (argc == 7)
2530 {
2531   if ((fd = open(argv[6], O_RDONLY)) == -1)
2532   {
2533     perror(&quot;ERROR: Unable to open raster file - &quot;);
2534     sleep(1);
2535     return (1);
2536   }
2537 }
2538 else
2539   fd = 0;
2541 ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
2542 </PRE>
2543 </UL>
2544 <P>Once you have opened the raster stream you just need to read each
2545  page and print it:</P>
2546 <UL>
2547 <PRE>
2548 cups_raster_header_t header;
2549 int                  y;
2550 unsigned char        data[8192];
2552 while (cupsRasterReadHeader(ras, &amp;header))
2553 {
2554   ... initialize the printer ...
2555   for (y = header.cupsHeight; y &gt; 0; y ++)
2556   {
2557     cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
2558     ... send raster line to printer ...
2559   }
2560 }
2561 </PRE>
2562 </UL>
2563 <P>After you have processed all pages, close the raster stream and
2564  return:</P>
2565 <UL>
2566 <PRE>
2567 cupsRasterClose(ras);
2569 return (0);
2570 </PRE>
2571 </UL>
2572 <H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
2573 <P>This chapter describes how to write a backend for CUPS. Backends
2574  communicate directly with printers and allow printer drivers and
2575  filters to send data using any type of connection transparently.</P>
2576 <H2><A NAME="6_1">Overview</A></H2>
2577 <P>Backends are special filters that communicate with printers directly.
2578  They are treated slightly differently than filters, however, and have
2579  some unique requirements.</P>
2580 <H3><A NAME="6_1_1">Security Considerations</A></H3>
2581 <P>Backends are run as the root user, so special care must be taken to
2582  avoid potential security violations. In particular, remember that a
2583  backend will be able to manipulate disk files, devices, and other
2584  resources that potentially could damage a system or printer.</P>
2585 <H3><A NAME="6_1_2">Command-Line Arguments</A></H3>
2586 <P>Besides the standard filter arguments, backends are also run with no
2587  arguments to get a list of available devices. This discovery process is
2588  described later in this chapter.</P>
2589 <H3><A NAME="6_1_3">Copy Generation</A></H3>
2590 <P>Like filters, backends should send multiple copies of the print file
2591  only if a filename is supplied on the command-line. Otherwise the
2592  backend should assume that the upstream filter has already added the
2593  necessary commands or data to produce the multiple copies.</P>
2594 <H3><A NAME="6_1_4">Page Accounting</A></H3>
2595 <P>Backend filters generally do not do page accounting, however they
2596  should at a minimum produce a single page message for each copy that is
2597  produced when a filename is present on the command-line. This is
2598  because the user selected &quot;raw&quot; printing and no other accounting
2599  information is possible.</P>
2600 <H3><A NAME="6_1_5">Exclusive Access</A></H3>
2601 <P>Backends that talk to local character or block devices should open
2602  the device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate
2603  with other printers defined for the same device.</P>
2604 <H3><A NAME="6_1_6">Retries</A></H3>
2605 <P>All backends<B> must</B> retry connections to the device. This
2606  includes backends that talk to local character or block devices, as the
2607  user may define more than one printer queue pointing at the same
2608  physical device.</P>
2609 <P>To prevent excess CPU utilitization, the backend should go to sleep
2610  for an amount of time between retries; the CUPS-supplied backends retry
2611  once every 30 seconds.</P>
2612 <H2><A NAME="6_2">Dissecting the Serial Port Backend</A></H2>
2613 <P>The serial port backend provides support for serial printers. Since
2614  it does everything a good backend needs to do, it provides an excellent
2615  example of what to do.</P>
2616 <H3><A NAME="6_2_1">Supporting Device Discovery</A></H3>
2617 <P>As previously noted, backends are special filter programs that talk
2618  to printer devices. Another task a backend must perform is to list the
2619  available devices it supports. The backend lists the available devices
2620  when no additioanl arguments are supplied on the command-line (i.e.
2621  just the command name...)</P>
2622 <P>The serial backend lists devices by looking at serial port files in
2623  the<VAR> /dev</VAR> directory, by consulting a hardware inventory
2624  (IRIX), and in some cases by trying to open the ports to see if they
2625  actually exist.</P>
2626 <P>Once it finds a serial port it writes a single line for each port to
2627  the standard error file. Each line looks like this:</P>
2628 <UL>
2629 <PRE>
2630 serial serial:/dev/ttyS0?baud=115200 &quot;Unknown&quot; &quot;Serial Port 1&quot;
2631 </PRE>
2632 </UL>
2633 <P>The first word &quot;serial&quot; is the<I> device class</I>; this identifies
2634  the class of device which can be used to categorize it in user
2635  interfaces. CUPS currently recognizes the following classes:</P>
2636 <UL>
2637 <LI>&quot;file&quot; - a disk file.</LI>
2638 <LI>&quot;direct&quot; - a parallel or fixed-rate serial data port, currently used
2639  for Centronics, IEEE-1284, and USB printer ports.</LI>
2640 <LI>&quot;serial&quot; - a variable-rate serial port.</LI>
2641 <LI>&quot;network&quot; - a network connection, typically via AppSocket, HTTP,
2642  IPP, LPD, or SMB/CIFS protocols.</LI>
2643 </UL>
2644 <P>After the device class is the<I> device URI</I>, in this case
2645  &quot;serial:/dev/ttyS0?baud=115200&quot;. This is the URI that should be used by
2646  the user to select this port. For serial ports, the &quot;baud=115200&quot;
2647  specifies the maximum baud rate supported by the port - the actual
2648  value will vary based on the speed the user selects for the printer.</P>
2649 <P>The last two strings are the model and description for the port. The
2650  &quot;Unknown&quot; string means that the printer model is unknown - some devices
2651  are able to provide a make and model such as &quot;HP DeskJet&quot; that allows
2652  users and software to choose an appropriate printer driver more easily.
2653  Both the model and description must be enclosed inside double quotes.</P>
2654 <H3><A NAME="6_2_2">Opening the Serial Port</A></H3>
2655 <P>As noted previously, all backends should open device files in
2656  exclusive mode, and retry as needed until the port is available. The
2657  serial port does this using a <CODE>do-while</CODE> loop:</P>
2658 <UL>
2659 <PRE>
2660 do
2661 {
2662   if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
2663   {
2664     if (errno == EBUSY)
2665     {
2666       fputs(&quot;INFO: Serial port busy; will retry in 30 seconds...\n&quot;, stderr);
2667       sleep(30);
2668     }
2669     else
2670     {
2671       perror(&quot;ERROR: Unable to open serial port device file&quot;);
2672       return (1);
2673     }
2674   }
2675 }
2676 while (fd &lt; 0);
2677 </PRE>
2678 </UL>
2679 <P>If the port is busy or in use by another process, the backend will go
2680  to sleep for 30 seconds and try again. If another error is detected a
2681  message is sent to the user and the backend aborts the print job until
2682  the problem can be corrected.</P>
2683 <H3><A NAME="6_2_3">Writing Data to the Port</A></H3>
2684 <P>Network and character devices pose an interesting problem when
2685  writing data to the port - they may not be able to write all of the
2686  bytes in your buffer before returning. To work around this problem you
2687  must loop until all bytes have been written:</P>
2688 <UL>
2689 <PRE>
2690 while (nbytes &gt; 0)
2691 {
2692   if ((wbytes = write(fd, bufptr, nbytes)) &lt; 0)
2693     if (errno == ENOTTY)
2694       wbytes = write(fd, bufptr, nbytes);
2696   if (wbytes &lt; 0)
2697   {
2698     perror(&quot;ERROR: Unable to send print file to printer&quot;);
2699     break;
2700   }
2702   nbytes -= wbytes;
2703   bufptr += wbytes;
2704 }
2705 </PRE>
2706 </UL>
2707 <P>The check for the <CODE>ENOTTY</CODE> error is needed on some
2708  platforms to clear an error from a previous <CODE>ioctl()</CODE> call.</P>
2709 <H3><A NAME="6_2_4">Finishing Up</A></H3>
2710 <P>Once you have sent the print file, return 0 if the file printed
2711  successfully or 1 if it did not. This will allow the scheduler to stop
2712  the print job if there is a device error, preserving the print job for
2713  later printing once the problem has been corrected.</P>
2714 <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
2715 <H2 ALIGN="CENTER"><A NAME="7_1">Common UNIX Printing System License
2716  Agreement</A></H2>
2717 <P ALIGN="CENTER">Copyright 1997-2003 by Easy Software Products
2718 <BR> 44141 AIRPORT VIEW DR STE 204
2719 <BR> HOLLYWOOD, MARYLAND 20636-3111 USA
2720 <BR>
2721 <BR> Voice: +1.301.373.9600
2722 <BR> Email:<A HREF="mailto:cups-info@cups.org"> cups-info@cups.org</A>
2723 <BR> WWW:<A HREF="http://www.cups.org"> http://www.cups.org</A></P>
2724 <H3><A NAME="7_1_1">Introduction</A></H3>
2725 <P>The Common UNIX Printing System<SUP>TM</SUP>, (&quot;CUPS<SUP>TM</SUP>&quot;),
2726  is provided under the GNU General Public License (&quot;GPL&quot;) and GNU
2727  Library General Public License (&quot;LGPL&quot;), Version 2, with exceptions for
2728  Apple operating systems and the OpenSSL toolkit. A copy of the
2729  exceptions and licenses follow this introduction.</P>
2730 <P>The GNU LGPL applies to the CUPS API library, located in the &quot;cups&quot;
2731  subdirectory of the CUPS source distribution and in the &quot;cups&quot; include
2732  directory and library files in the binary distributions. The GNU GPL
2733  applies to the remainder of the CUPS distribution, including the
2734  &quot;pdftops&quot; filter which is based upon Xpdf and the CUPS imaging library.</P>
2735 <P>For those not familiar with the GNU GPL, the license basically allows
2736  you to:</P>
2737 <UL>
2738 <LI>Use the CUPS software at no charge.</LI>
2739 <LI>Distribute verbatim copies of the software in source or binary form.</LI>
2740 <LI>Sell verbatim copies of the software for a media fee, or sell
2741  support for the software.</LI>
2742 <LI>Distribute or sell printer drivers and filters that use CUPS so long
2743  as source code is made available under the GPL.</LI>
2744 </UL>
2745 <P>What this license<B> does not</B> allow you to do is make changes or
2746  add features to CUPS and then sell a binary distribution without source
2747  code. You must provide source for any new drivers, changes, or
2748  additions to the software, and all code must be provided under the GPL
2749  or LGPL as appropriate. The only exceptions to this are the portions of
2750  the CUPS software covered by the Apple operating system license
2751  exceptions outlined later in this license agreement.</P>
2752 <P>The GNU LGPL relaxes the &quot;link-to&quot; restriction, allowing you to
2753  develop applications that use the CUPS API library under other licenses
2754  and/or conditions as appropriate for your application.</P>
2755 <H3><A NAME="7_1_2">License Exceptions</A></H3>
2756 <P>In addition, as the copyright holder of CUPS, Easy Software Products
2757  grants the following special exceptions:</P>
2758 <OL>
2759 <LI><B>Apple Operating System Development License Exception</B>;
2760 <OL TYPE="a">
2761 <LI>Software that is developed by any person or entity for an Apple
2762  Operating System (&quot;Apple OS-Developed Software&quot;), including but not
2763  limited to Apple and third party printer drivers, filters, and backends
2764  for an Apple Operating System, that is linked to the CUPS imaging
2765  library or based on any sample filters or backends provided with CUPS
2766  shall not be considered to be a derivative work or collective work
2767  based on the CUPS program and is exempt from the mandatory source code
2768  release clauses of the GNU GPL. You may therefore distribute linked
2769  combinations of the CUPS imaging library with Apple OS-Developed
2770  Software without releasing the source code of the Apple OS-Developed
2771  Software. You may also use sample filters and backends provided with
2772  CUPS to develop Apple OS-Developed Software without releasing the
2773  source code of the Apple OS-Developed Software.</LI>
2774 <LI>An Apple Operating System means any operating system software
2775  developed and/or marketed by Apple Computer, Inc., including but not
2776  limited to all existing releases and versions of Apple's Darwin, Mac OS
2777  X, and Mac OS X Server products and all follow-on releases and future
2778  versions thereof.</LI>
2779 <LI>This exception is only available for Apple OS-Developed Software and
2780  does not apply to software that is distributed for use on other
2781  operating systems.</LI>
2782 <LI>All CUPS software that falls under this license exception have the
2783  following text at the top of each source file:<BLOCKQUOTE>This file is
2784  subject to the Apple OS-Developed Software exception.</BLOCKQUOTE></LI>
2785 </OL>
2786 </LI>
2787 <LI><B>OpenSSL Toolkit License Exception</B>;
2788 <OL TYPE="a">
2789 <LI>Easy Software Products explicitly allows the compilation and
2790  distribution of the CUPS software with the OpenSSL Toolkit.</LI>
2791 </OL>
2792 </LI>
2793 </OL>
2794 <P>No developer is required to provide these exceptions in a derived
2795  work.</P>
2796 <H3><A NAME="7_1_3">Trademarks</A></H3>
2797 <P>Easy Software Products has trademarked the Common UNIX Printing
2798  System, CUPS, and CUPS logo. These names and logos may be used freely
2799  in any direct port or binary distribution of CUPS. Please contract Easy
2800  Software Products for written permission to use them in derivative
2801  products. Our intention is to protect the value of these trademarks and
2802  ensure that any derivative product meets the same high-quality
2803  standards as the original.</P>
2804 <H3><A NAME="7_1_4">Binary Distribution Rights</A></H3>
2805 <P>Easy Software Products also sells rights to the CUPS source code
2806  under a binary distribution license for vendors that are unable to
2807  release source code for their drivers, additions, and modifications to
2808  CUPS under the GNU GPL and LGPL. For information please contact us at
2809  the address shown above.</P>
2810 <P>The Common UNIX Printing System provides a &quot;pdftops&quot; filter that is
2811  based on the Xpdf software. For binary distribution licensing of this
2812  software, please contact:<BLOCKQUOTE> Derek B. Noonburg
2813 <BR> Email:<A HREF="mailto:derekn@foolabs.com"> derekn@foolabs.com</A>
2814 <BR> WWW:<A HREF="http://www.foolabs.com/xpdf/">
2815  http://www.foolabs.com/xpdf/</A></BLOCKQUOTE></P>
2816 <H3><A NAME="7_1_5">Support</A></H3>
2817 <P>Easy Software Products sells software support for CUPS as well as a
2818  commercial printing product based on CUPS called ESP Print Pro. You can
2819  find out more at our web site:</P>
2820 <UL>
2821 <PRE>
2822 <A HREF="http://www.easysw.com/">http://www.easysw.com/</A>
2823 </PRE>
2824 </UL>
2826 <!-- NEW PAGE -->
2828 <P>Version 2, June 1991</P>
2829 <PRE>
2830 Copyright 1989, 1991 Free Software Foundation, Inc.
2831 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
2833 Everyone is permitted to copy and distribute verbatim
2834 copies of this license document, but changing it is not allowed.
2835 </PRE>
2836 <H4>Preamble</H4>
2837 <P>The licenses for most software are designed to take away your freedom
2838  to share and change it. By contrast, the GNU General Public License is
2839  intended to guarantee your freedom to share and change free
2840  software--to make sure the software is free for all its users. This
2841  General Public License applies to most of the Free Software
2842  Foundation's software and to any other program whose authors commit to
2843  using it. (Some other Free Software Foundation software is covered by
2844  the GNU Library General Public License instead.) You can apply it to
2845  your programs, too.</P>
2846 <P>When we speak of free software, we are referring to freedom, not
2847  price. Our General Public Licenses are designed to make sure that you
2848  have the freedom to distribute copies of free software (and charge for
2849  this service if you wish), that you receive source code or can get it
2850  if you want it, that you can change the software or use pieces of it in
2851  new free programs; and that you know you can do these things.</P>
2852 <P>To protect your rights, we need to make restrictions that forbid
2853  anyone to deny you these rights or to ask you to surrender the rights.
2854  These restrictions translate to certain responsibilities for you if you
2855  distribute copies of the software, or if you modify it.</P>
2856 <P>For example, if you distribute copies of such a program, whether
2857  gratis or for a fee, you must give the recipients all the rights that
2858  you have. You must make sure that they, too, receive or can get the
2859  source code. And you must show them these terms so they know their
2860  rights.</P>
2861 <P>We protect your rights with two steps: (1) copyright the software,
2862  and (2) offer you this license which gives you legal permission to
2863  copy, distribute and/or modify the software.</P>
2864 <P>Also, for each author's protection and ours, we want to make certain
2865  that everyone understands that there is no warranty for this free
2866  software. If the software is modified by someone else and passed on, we
2867  want its recipients to know that what they have is not the original, so
2868  that any problems introduced by others will not reflect on the original
2869  authors' reputations.</P>
2870 <P>Finally, any free program is threatened constantly by software
2871  patents. We wish to avoid the danger that redistributors of a free
2872  program will individually obtain patent licenses, in effect making the
2873  program proprietary. To prevent this, we have made it clear that any
2874  patent must be licensed for everyone's free use or not licensed at all.</P>
2875 <P>The precise terms and conditions for copying, distribution and
2876  modification follow.</P>
2879 <OL START="0">
2880 <LI>This License applies to any program or other work which contains a
2881  notice placed by the copyright holder saying it may be distributed
2882  under the terms of this General Public License. The &quot;Program&quot;, below,
2883  refers to any such program or work, and a &quot;work based on the Program&quot;
2884  means either the Program or any derivative work under copyright law:
2885  that is to say, a work containing the Program or a portion of it,
2886  either verbatim or with modifications and/or translated into another
2887  language. (Hereinafter, translation is included without limitation in
2888  the term &quot;modification&quot;.) Each licensee is addressed as &quot;you&quot;.
2889 <P>Activities other than copying, distribution and modification are not
2890  covered by this License; they are outside its scope. The act of running
2891  the Program is not restricted, and the output from the Program is
2892  covered only if its contents constitute a work based on the Program
2893  (independent of having been made by running the Program). Whether that
2894  is true depends on what the Program does.</P>
2895 <LI>You may copy and distribute verbatim copies of the Program's source
2896  code as you receive it, in any medium, provided that you conspicuously
2897  and appropriately publish on each copy an appropriate copyright notice
2898  and disclaimer of warranty; keep intact all the notices that refer to
2899  this License and to the absence of any warranty; and give any other
2900  recipients of the Program a copy of this License along with the
2901  Program.
2902 <P>You may charge a fee for the physical act of transferring a copy, and
2903  you may at your option offer warranty protection in exchange for a fee.</P>
2904 <LI>You may modify your copy or copies of the Program or any portion of
2905  it, thus forming a work based on the Program, and copy and distribute
2906  such modifications or work under the terms of Section 1 above, provided
2907  that you also meet all of these conditions:
2908 <OL TYPE="a">
2909 <LI>You must cause the modified files to carry prominent notices stating
2910  that you changed the files and the date of any change.</LI>
2911 <LI>You must cause any work that you distribute or publish, that in
2912  whole or in part contains or is derived from the Program or any part
2913  thereof, to be licensed as a whole at no charge to all third parties
2914  under the terms of this License.</LI>
2915 <LI>if the modified program normally reads commands interactively when
2916  run, you must cause it, when started running for such interactive use
2917  in the most ordinary way, to print or display an announcement including
2918  an appropriate copyright notice and a notice that there is no warranty
2919  (or else, saying that you provide a warranty) and that users may
2920  redistribute the program under these conditions, and telling the user
2921  how to view a copy of this License. (Exception: if the Program itself
2922  is interactive but does not normally print such an announcement, your
2923  work based on the Program is not required to print an announcement.)</LI>
2924 </OL>
2925 <P>These requirements apply to the modified work as a whole. If
2926  identifiable sections of that work are not derived from the Program,
2927  and can be reasonably considered independent and separate works in
2928  themselves, then this License, and its terms, do not apply to those
2929  sections when you distribute them as separate works. But when you
2930  distribute the same sections as part of a whole which is a work based
2931  on the Program, the distribution of the whole must be on the terms of
2932  this License, whose permissions for other licensees extend to the
2933  entire whole, and thus to each and every part regardless of who wrote
2934  it.</P>
2935 <P>Thus, it is not the intent of this section to claim rights or contest
2936  your rights to work written entirely by you; rather, the intent is to
2937  exercise the right to control the distribution of derivative or
2938  collective works based on the Program.</P>
2939 <P>In addition, mere aggregation of another work not based on the
2940  Program with the Program (or with a work based on the Program) on a
2941  volume of a storage or distribution medium does not bring the other
2942  work under the scope of this License.</P>
2943 <LI>You may copy and distribute the Program (or a work based on it,
2944  under Section 2) in object code or executable form under the terms of
2945  Sections 1 and 2 above provided that you also do one of the following:
2946 <OL TYPE="a">
2947 <LI>Accompany it with the complete corresponding machine-readable source
2948  code, which must be distributed under the terms of Sections 1 and 2
2949  above on a medium customarily used for software interchange; or,</LI>
2950 <LI>Accompany it with a written offer, valid for at least three years,
2951  to give any third party, for a charge no more than your cost of
2952  physically performing source distribution, a complete machine-readable
2953  copy of the corresponding source code, to be distributed under the
2954  terms of Sections 1 and 2 above on a medium customarily used for
2955  software interchange; or,</LI>
2956 <LI>Accompany it with the information you received as to the offer to
2957  distribute corresponding source code. (This alternative is allowed only
2958  for noncommercial distribution and only if you received the program in
2959  object code or executable form with such an offer, in accord with
2960  Subsection b above.)</LI>
2961 </OL>
2962 <P>The source code for a work means the preferred form of the work for
2963  making modifications to it. For an executable work, complete source
2964  code means all the source code for all modules it contains, plus any
2965  associated interface definition files, plus the scripts used to control
2966  compilation and installation of the executable. However, as a special
2967  exception, the source code distributed need not include anything that
2968  is normally distributed (in either source or binary form) with the
2969  major components (compiler, kernel, and so on) of the operating system
2970  on which the executable runs, unless that component itself accompanies
2971  the executable.</P>
2972 <P>If distribution of executable or object code is made by offering
2973  access to copy from a designated place, then offering equivalent access
2974  to copy the source code from the same place counts as distribution of
2975  the source code, even though third parties are not compelled to copy
2976  the source along with the object code.</P>
2977 <LI>You may not copy, modify, sublicense, or distribute the Program
2978  except as expressly provided under this License. Any attempt otherwise
2979  to copy, modify, sublicense or distribute the Program is void, and will
2980  automatically terminate your rights under this License. However,
2981  parties who have received copies, or rights, from you under this
2982  License will not have their licenses terminated so long as such parties
2983  remain in full compliance.</LI>
2984 <LI>You are not required to accept this License, since you have not
2985  signed it. However, nothing else grants you permission to modify or
2986  distribute the Program or its derivative works. These actions are
2987  prohibited by law if you do not accept this License. Therefore, by
2988  modifying or distributing the Program (or any work based on the
2989  Program), you indicate your acceptance of this License to do so, and
2990  all its terms and conditions for copying, distributing or modifying the
2991  Program or works based on it.</LI>
2992 <LI>Each time you redistribute the Program (or any work based on the
2993  Program), the recipient automatically receives a license from the
2994  original licensor to copy, distribute or modify the Program subject to
2995  these terms and conditions. You may not impose any further restrictions
2996  on the recipients' exercise of the rights granted herein. You are not
2997  responsible for enforcing compliance by third parties to this License.</LI>
2998 <LI>If, as a consequence of a court judgment or allegation of patent
2999  infringement or for any other reason (not limited to patent issues),
3000  conditions are imposed on you (whether by court order, agreement or
3001  otherwise) that contradict the conditions of this License, they do not
3002  excuse you from the conditions of this License. If you cannot
3003  distribute so as to satisfy simultaneously your obligations under this
3004  License and any other pertinent obligations, then as a consequence you
3005  may not distribute the Program at all. For example, if a patent license
3006  would not permit royalty-free redistribution of the Program by all
3007  those who receive copies directly or indirectly through you, then the
3008  only way you could satisfy both it and this License would be to refrain
3009  entirely from distribution of the Program.
3010 <P>If any portion of this section is held invalid or unenforceable under
3011  any particular circumstance, the balance of the section is intended to
3012  apply and the section as a whole is intended to apply in other
3013  circumstances.</P>
3014 <P>It is not the purpose of this section to induce you to infringe any
3015  patents or other property right claims or to contest validity of any
3016  such claims; this section has the sole purpose of protecting the
3017  integrity of the free software distribution system, which is
3018  implemented by public license practices. Many people have made generous
3019  contributions to the wide range of software distributed through that
3020  system in reliance on consistent application of that system; it is up
3021  to the author/donor to decide if he or she is willing to distribute
3022  software through any other system and a licensee cannot impose that
3023  choice.</P>
3024 <P>This section is intended to make thoroughly clear what is believed to
3025  be a consequence of the rest of this License.</P>
3026 <LI>If the distribution and/or use of the Program is restricted in
3027  certain countries either by patents or by copyrighted interfaces, the
3028  original copyright holder who places the Program under this License may
3029  add an explicit geographical distribution limitation excluding those
3030  countries, so that distribution is permitted only in or among countries
3031  not thus excluded. In such case, this License incorporates the
3032  limitation as if written in the body of this License.</LI>
3033 <LI>The Free Software Foundation may publish revised and/or new versions
3034  of the General Public License from time to time. Such new versions will
3035  be similar in spirit to the present version, but may differ in detail
3036  to address new problems or concerns.
3037 <P>Each version is given a distinguishing version number. If the Program
3038  specifies a version number of this License which applies to it and &quot;any
3039  later version&quot;, you have the option of following the terms and
3040  conditions either of that version or of any later version published by
3041  the Free Software Foundation. If the Program does not specify a version
3042  number of this License, you may choose any version ever published by
3043  the Free Software Foundation.</P>
3044 <LI>If you wish to incorporate parts of the Program into other free
3045  programs whose distribution conditions are different, write to the
3046  author to ask for permission. For software which is copyrighted by the
3047  Free Software Foundation, write to the Free Software Foundation; we
3048  sometimes make exceptions for this. Our decision will be guided by the
3049  two goals of preserving the free status of all derivatives of our free
3050  software and of promoting the sharing and reuse of software generally.</LI>
3051 </LI>
3052 </LI>
3053 </LI>
3054 </LI>
3055 </LI>
3056 </LI>
3057 </OL>
3058 <H4>NO WARRANTY</H4>
3059 <OL START="11">
3078  DAMAGES.</LI>
3079 </OL>
3082 <!-- NEW PAGE -->
3084 <P>Version 2, June 1991</P>
3085 <PRE>
3086 Copyright (C) 1991 Free Software Foundation, Inc.
3087 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
3088 Everyone is permitted to copy and distribute verbatim copies
3089 of this license document, but changing it is not allowed.
3091 [This is the first released version of the library GPL.  It is
3092  numbered 2 because it goes with version 2 of the ordinary GPL.]
3093 </PRE>
3094 <H4>Preamble</H4>
3095 <P>The licenses for most software are designed to take away your freedom
3096  to share and change it. By contrast, the GNU General Public Licenses
3097  are intended to guarantee your freedom to share and change free
3098  software--to make sure the software is free for all its users.</P>
3099 <P>This license, the Library General Public License, applies to some
3100  specially designated Free Software Foundation software, and to any
3101  other libraries whose authors decide to use it. You can use it for your
3102  libraries, too.</P>
3103 <P>When we speak of free software, we are referring to freedom, not
3104  price. Our General Public Licenses are designed to make sure that you
3105  have the freedom to distribute copies of free software (and charge for
3106  this service if you wish), that you receive source code or can get it
3107  if you want it, that you can change the software or use pieces of it in
3108  new free programs; and that you know you can do these things.</P>
3109 <P>To protect your rights, we need to make restrictions that forbid
3110  anyone to deny you these rights or to ask you to surrender the rights.
3111  These restrictions translate to certain responsibilities for you if you
3112  distribute copies of the library, or if you modify it.</P>
3113 <P>For example, if you distribute copies of the library, whether gratis
3114  or for a fee, you must give the recipients all the rights that we gave
3115  you. You must make sure that they, too, receive or can get the source
3116  code. If you link a program with the library, you must provide complete
3117  object files to the recipients so that they can relink them with the
3118  library, after making changes to the library and recompiling it. And
3119  you must show them these terms so they know their rights.</P>
3120 <P>Our method of protecting your rights has two steps: (1) copyright the
3121  library, and (2) offer you this license which gives you legal
3122  permission to copy, distribute and/or modify the library.</P>
3123 <P>Also, for each distributor's protection, we want to make certain that
3124  everyone understands that there is no warranty for this free library.
3125  If the library is modified by someone else and passed on, we want its
3126  recipients to know that what they have is not the original version, so
3127  that any problems introduced by others will not reflect on the original
3128  authors' reputations.</P>
3129 <P>Finally, any free program is threatened constantly by software
3130  patents. We wish to avoid the danger that companies distributing free
3131  software will individually obtain patent licenses, thus in effect
3132  transforming the program into proprietary software. To prevent this, we
3133  have made it clear that any patent must be licensed for everyone's free
3134  use or not licensed at all.</P>
3135 <P>Most GNU software, including some libraries, is covered by the
3136  ordinary GNU General Public License, which was designed for utility
3137  programs. This license, the GNU Library General Public License, applies
3138  to certain designated libraries. This license is quite different from
3139  the ordinary one; be sure to read it in full, and don't assume that
3140  anything in it is the same as in the ordinary license.</P>
3141 <P>The reason we have a separate public license for some libraries is
3142  that they blur the distinction we usually make between modifying or
3143  adding to a program and simply using it. Linking a program with a
3144  library, without changing the library, is in some sense simply using
3145  the library, and is analogous to running a utility program or
3146  application program. However, in a textual and legal sense, the linked
3147  executable is a combined work, a derivative of the original library,
3148  and the ordinary General Public License treats it as such.</P>
3149 <P>Because of this blurred distinction, using the ordinary General
3150  Public License for libraries did not effectively promote software
3151  sharing, because most developers did not use the libraries. We
3152  concluded that weaker conditions might promote sharing better.</P>
3153 <P>However, unrestricted linking of non-free programs would deprive the
3154  users of those programs of all benefit from the free status of the
3155  libraries themselves. This Library General Public License is intended
3156  to permit developers of non-free programs to use free libraries, while
3157  preserving your freedom as a user of such programs to change the free
3158  libraries that are incorporated in them. (We have not seen how to
3159  achieve this as regards changes in header files, but we have achieved
3160  it as regards changes in the actual functions of the Library.) The hope
3161  is that this will lead to faster development of free libraries.</P>
3162 <P>The precise terms and conditions for copying, distribution and
3163  modification follow. Pay close attention to the difference between a
3164  &quot;work based on the library&quot; and a &quot;work that uses the library&quot;. The
3165  former contains code derived from the library, while the latter only
3166  works together with the library.</P>
3167 <P>Note that it is possible for a library to be covered by the ordinary
3168  General Public License rather than by this special one.</P>
3170 <P><STRONG>0.</STRONG> This License Agreement applies to any software
3171  library which contains a notice placed by the copyright holder or other
3172  authorized party saying it may be distributed under the terms of this
3173  Library General Public License (also called &quot;this License&quot;). Each
3174  licensee is addressed as &quot;you&quot;.</P>
3175 <P>A &quot;library&quot; means a collection of software functions and/or data
3176  prepared so as to be conveniently linked with application programs
3177  (which use some of those functions and data) to form executables.</P>
3178 <P>The &quot;Library&quot;, below, refers to any such software library or work
3179  which has been distributed under these terms. A &quot;work based on the
3180  Library&quot; means either the Library or any derivative work under
3181  copyright law: that is to say, a work containing the Library or a
3182  portion of it, either verbatim or with modifications and/or translated
3183  straightforwardly into another language. (Hereinafter, translation is
3184  included without limitation in the term &quot;modification&quot;.)</P>
3185 <P>&quot;Source code&quot; for a work means the preferred form of the work for
3186  making modifications to it. For a library, complete source code means
3187  all the source code for all modules it contains, plus any associated
3188  interface definition files, plus the scripts used to control
3189  compilation and installation of the library.</P>
3190 <P>Activities other than copying, distribution and modification are not
3191  covered by this License; they are outside its scope. The act of running
3192  a program using the Library is not restricted, and output from such a
3193  program is covered only if its contents constitute a work based on the
3194  Library (independent of the use of the Library in a tool for writing
3195  it). Whether that is true depends on what the Library does and what the
3196  program that uses the Library does.</P>
3197 <P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of
3198  the Library's complete source code as you receive it, in any medium,
3199  provided that you conspicuously and appropriately publish on each copy
3200  an appropriate copyright notice and disclaimer of warranty; keep intact
3201  all the notices that refer to this License and to the absence of any
3202  warranty; and distribute a copy of this License along with the Library.</P>
3203 <P>You may charge a fee for the physical act of transferring a copy, and
3204  you may at your option offer warranty protection in exchange for a fee.</P>
3205 <P><STRONG>2.</STRONG> You may modify your copy or copies of the Library
3206  or any portion of it, thus forming a work based on the Library, and
3207  copy and distribute such modifications or work under the terms of
3208  Section 1 above, provided that you also meet all of these conditions:</P>
3209 <OL TYPE="a">
3210 <LI>The modified work must itself be a software library.
3211 <P></P>
3212 <LI>You must cause the files modified to carry prominent notices stating
3213  that you changed the files and the date of any change.
3214 <P></P>
3215 <LI>You must cause the whole of the work to be licensed at no charge to
3216  all third parties under the terms of this License.
3217 <P></P>
3218 <LI>If a facility in the modified Library refers to a function or a
3219  table of data to be supplied by an application program that uses the
3220  facility, other than as an argument passed when the facility is
3221  invoked, then you must make a good faith effort to ensure that, in the
3222  event an application does not supply such function or table, the
3223  facility still operates, and performs whatever part of its purpose
3224  remains meaningful.
3225 <P>(For example, a function in a library to compute square roots has a
3226  purpose that is entirely well-defined independent of the application.
3227  Therefore, Subsection 2d requires that any application-supplied
3228  function or table used by this function must be optional: if the
3229  application does not supply it, the square root function must still
3230  compute square roots.)</P>
3231 </LI>
3232 </LI>
3233 </LI>
3234 </LI>
3235 </OL>
3236 <P>These requirements apply to the modified work as a whole. If
3237  identifiable sections of that work are not derived from the Library,
3238  and can be reasonably considered independent and separate works in
3239  themselves, then this License, and its terms, do not apply to those
3240  sections when you distribute them as separate works. But when you
3241  distribute the same sections as part of a whole which is a work based
3242  on the Library, the distribution of the whole must be on the terms of
3243  this License, whose permissions for other licensees extend to the
3244  entire whole, and thus to each and every part regardless of who wrote
3245  it.</P>
3246 <P>Thus, it is not the intent of this section to claim rights or contest
3247  your rights to work written entirely by you; rather, the intent is to
3248  exercise the right to control the distribution of derivative or
3249  collective works based on the Library.</P>
3250 <P>In addition, mere aggregation of another work not based on the
3251  Library with the Library (or with a work based on the Library) on a
3252  volume of a storage or distribution medium does not bring the other
3253  work under the scope of this License.</P>
3254 <P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary
3255  GNU General Public License instead of this License to a given copy of
3256  the Library. To do this, you must alter all the notices that refer to
3257  this License, so that they refer to the ordinary GNU General Public
3258  License, version 2, instead of to this License. (If a newer version
3259  than version 2 of the ordinary GNU General Public License has appeared,
3260  then you can specify that version instead if you wish.) Do not make any
3261  other change in these notices.</P>
3262 <P>Once this change is made in a given copy, it is irreversible for that
3263  copy, so the ordinary GNU General Public License applies to all
3264  subsequent copies and derivative works made from that copy.</P>
3265 <P>This option is useful when you wish to copy part of the code of the
3266  Library into a program that is not a library.</P>
3267 <P><STRONG>4.</STRONG> You may copy and distribute the Library (or a
3268  portion or derivative of it, under Section 2) in object code or
3269  executable form under the terms of Sections 1 and 2 above provided that
3270  you accompany it with the complete corresponding machine-readable
3271  source code, which must be distributed under the terms of Sections 1
3272  and 2 above on a medium customarily used for software interchange.</P>
3273 <P>If distribution of object code is made by offering access to copy
3274  from a designated place, then offering equivalent access to copy the
3275  source code from the same place satisfies the requirement to distribute
3276  the source code, even though third parties are not compelled to copy
3277  the source along with the object code.</P>
3278 <P><STRONG>5.</STRONG> A program that contains no derivative of any
3279  portion of the Library, but is designed to work with the Library by
3280  being compiled or linked with it, is called a &quot;work that uses the
3281  Library&quot;. Such a work, in isolation, is not a derivative work of the
3282  Library, and therefore falls outside the scope of this License.</P>
3283 <P>However, linking a &quot;work that uses the Library&quot; with the Library
3284  creates an executable that is a derivative of the Library (because it
3285  contains portions of the Library), rather than a &quot;work that uses the
3286  library&quot;. The executable is therefore covered by this License. Section
3287  6 states terms for distribution of such executables.</P>
3288 <P>When a &quot;work that uses the Library&quot; uses material from a header file
3289  that is part of the Library, the object code for the work may be a
3290  derivative work of the Library even though the source code is not.
3291  Whether this is true is especially significant if the work can be
3292  linked without the Library, or if the work is itself a library. The
3293  threshold for this to be true is not precisely defined by law.</P>
3294 <P>If such an object file uses only numerical parameters, data structure
3295  layouts and accessors, and small macros and small inline functions (ten
3296  lines or less in length), then the use of the object file is
3297  unrestricted, regardless of whether it is legally a derivative work.
3298  (Executables containing this object code plus portions of the Library
3299  will still fall under Section 6.)</P>
3300 <P>Otherwise, if the work is a derivative of the Library, you may
3301  distribute the object code for the work under the terms of Section 6.
3302  Any executables containing that work also fall under Section 6, whether
3303  or not they are linked directly with the Library itself.</P>
3304 <P><STRONG>6.</STRONG> As an exception to the Sections above, you may
3305  also compile or link a &quot;work that uses the Library&quot; with the Library to
3306  produce a work containing portions of the Library, and distribute that
3307  work under terms of your choice, provided that the terms permit
3308  modification of the work for the customer's own use and reverse
3309  engineering for debugging such modifications.</P>
3310 <P>You must give prominent notice with each copy of the work that the
3311  Library is used in it and that the Library and its use are covered by
3312  this License. You must supply a copy of this License. If the work
3313  during execution displays copyright notices, you must include the
3314  copyright notice for the Library among them, as well as a reference
3315  directing the user to the copy of this License. Also, you must do one
3316  of these things:</P>
3317 <OL TYPE="a">
3318 <LI>Accompany the work with the complete corresponding machine-readable
3319  source code for the Library including whatever changes were used in the
3320  work (which must be distributed under Sections 1 and 2 above); and, if
3321  the work is an executable linked with the Library, with the complete
3322  machine-readable &quot;work that uses the Library&quot;, as object code and/or
3323  source code, so that the user can modify the Library and then relink to
3324  produce a modified executable containing the modified Library. (It is
3325  understood that the user who changes the contents of definitions files
3326  in the Library will not necessarily be able to recompile the
3327  application to use the modified definitions.)
3328 <P></P>
3329 <LI>Accompany the work with a written offer, valid for at least three
3330  years, to give the same user the materials specified in Subsection 6a,
3331  above, for a charge no more than the cost of performing this
3332  distribution.
3333 <P></P>
3334 <LI>If distribution of the work is made by offering access to copy from
3335  a designated place, offer equivalent access to copy the above specified
3336  materials from the same place.
3337 <P></P>
3338 <LI>Verify that the user has already received a copy of these materials
3339  or that you have already sent this user a copy.</LI>
3340 </LI>
3341 </LI>
3342 </LI>
3343 </OL>
3344 <P>For an executable, the required form of the &quot;work that uses the
3345  Library&quot; must include any data and utility programs needed for
3346  reproducing the executable from it. However, as a special exception,
3347  the source code distributed need not include anything that is normally
3348  distributed (in either source or binary form) with the major components
3349  (compiler, kernel, and so on) of the operating system on which the
3350  executable runs, unless that component itself accompanies the
3351  executable.</P>
3352 <P>It may happen that this requirement contradicts the license
3353  restrictions of other proprietary libraries that do not normally
3354  accompany the operating system. Such a contradiction means you cannot
3355  use both them and the Library together in an executable that you
3356  distribute.</P>
3357 <P><STRONG>7.</STRONG> You may place library facilities that are a work
3358  based on the Library side-by-side in a single library together with
3359  other library facilities not covered by this License, and distribute
3360  such a combined library, provided that the separate distribution of the
3361  work based on the Library and of the other library facilities is
3362  otherwise permitted, and provided that you do these two things:</P>
3363 <OL TYPE="a">
3364 <LI>Accompany the combined library with a copy of the same work based on
3365  the Library, uncombined with any other library facilities. This must be
3366  distributed under the terms of the Sections above.
3367 <P></P>
3368 <LI>Give prominent notice with the combined library of the fact that
3369  part of it is a work based on the Library, and explaining where to find
3370  the accompanying uncombined form of the same work.</LI>
3371 </LI>
3372 </OL>
3373 <P><STRONG>8.</STRONG> You may not copy, modify, sublicense, link with,
3374  or distribute the Library except as expressly provided under this
3375  License. Any attempt otherwise to copy, modify, sublicense, link with,
3376  or distribute the Library is void, and will automatically terminate
3377  your rights under this License. However, parties who have received
3378  copies, or rights, from you under this License will not have their
3379  licenses terminated so long as such parties remain in full compliance.</P>
3380 <P><STRONG>9.</STRONG> You are not required to accept this License,
3381  since you have not signed it. However, nothing else grants you
3382  permission to modify or distribute the Library or its derivative works.
3383  These actions are prohibited by law if you do not accept this License.
3384  Therefore, by modifying or distributing the Library (or any work based
3385  on the Library), you indicate your acceptance of this License to do so,
3386  and all its terms and conditions for copying, distributing or modifying
3387  the Library or works based on it.</P>
3388 <P><STRONG>10.</STRONG> Each time you redistribute the Library (or any
3389  work based on the Library), the recipient automatically receives a
3390  license from the original licensor to copy, distribute, link with or
3391  modify the Library subject to these terms and conditions. You may not
3392  impose any further restrictions on the recipients' exercise of the
3393  rights granted herein. You are not responsible for enforcing compliance
3394  by third parties to this License.</P>
3395 <P><STRONG>11.</STRONG> If, as a consequence of a court judgment or
3396  allegation of patent infringement or for any other reason (not limited
3397  to patent issues), conditions are imposed on you (whether by court
3398  order, agreement or otherwise) that contradict the conditions of this
3399  License, they do not excuse you from the conditions of this License. If
3400  you cannot distribute so as to satisfy simultaneously your obligations
3401  under this License and any other pertinent obligations, then as a
3402  consequence you may not distribute the Library at all. For example, if
3403  a patent license would not permit royalty-free redistribution of the
3404  Library by all those who receive copies directly or indirectly through
3405  you, then the only way you could satisfy both it and this License would
3406  be to refrain entirely from distribution of the Library.</P>
3407 <P>If any portion of this section is held invalid or unenforceable under
3408  any particular circumstance, the balance of the section is intended to
3409  apply, and the section as a whole is intended to apply in other
3410  circumstances.</P>
3411 <P>It is not the purpose of this section to induce you to infringe any
3412  patents or other property right claims or to contest validity of any
3413  such claims; this section has the sole purpose of protecting the
3414  integrity of the free software distribution system which is implemented
3415  by public license practices. Many people have made generous
3416  contributions to the wide range of software distributed through that
3417  system in reliance on consistent application of that system; it is up
3418  to the author/donor to decide if he or she is willing to distribute
3419  software through any other system and a licensee cannot impose that
3420  choice.</P>
3421 <P>This section is intended to make thoroughly clear what is believed to
3422  be a consequence of the rest of this License.</P>
3423 <P><STRONG>12.</STRONG> If the distribution and/or use of the Library is
3424  restricted in certain countries either by patents or by copyrighted
3425  interfaces, the original copyright holder who places the Library under
3426  this License may add an explicit geographical distribution limitation
3427  excluding those countries, so that distribution is permitted only in or
3428  among countries not thus excluded. In such case, this License
3429  incorporates the limitation as if written in the body of this License.</P>
3430 <P><STRONG>13.</STRONG> The Free Software Foundation may publish revised
3431  and/or new versions of the Library General Public License from time to
3432  time. Such new versions will be similar in spirit to the present
3433  version, but may differ in detail to address new problems or concerns.</P>
3434 <P>Each version is given a distinguishing version number. If the Library
3435  specifies a version number of this License which applies to it and &quot;any
3436  later version&quot;, you have the option of following the terms and
3437  conditions either of that version or of any later version published by
3438  the Free Software Foundation. If the Library does not specify a license
3439  version number, you may choose any version ever published by the Free
3440  Software Foundation.</P>
3441 <P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library
3442  into other free programs whose distribution conditions are incompatible
3443  with these, write to the author to ask for permission. For software
3444  which is copyrighted by the Free Software Foundation, write to the Free
3445  Software Foundation; we sometimes make exceptions for this. Our
3446  decision will be guided by the two goals of preserving the free status
3447  of all derivatives of our free software and of promoting the sharing
3448  and reuse of software generally.</P>
3468  DAMAGES.</P>
3470 <H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1>
3471 <P>This appendix lists all of the constants that are defined by the CUPS
3472  API.</P>
3473 <H2><A NAME="8_1">CUPS Constants</A></H2>
3474 <H3><A NAME="8_1_1">Version Number</A></H3>
3475 <P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number
3476  representing the API version number. The current version number is
3477  1.0100 which represents CUPS version 1.1.0.</P>
3478 <H3><A NAME="8_1_2">Printer Capabilities</A></H3>
3479 <P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for
3480  printers and classes:</P>
3481 <UL>
3482 <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.</LI>
3483 <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.</LI>
3484 <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.</LI>
3485 <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.</LI>
3486 <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.</LI>
3487 <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.</LI>
3488 <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.</LI>
3489 <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple
3490  copies on its own.</LI>
3491 <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.</LI>
3492 <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.</LI>
3493 <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.</LI>
3494 <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.</LI>
3495 <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.</LI>
3496 <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up to
3497  9x14 inches.</LI>
3498 <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media from
3499  9x14 to 18x24 inches.</LI>
3500 <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media larger
3501  than 18x24 inches.</LI>
3502 <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on variable
3503  or custom media sizes.</LI>
3504 <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.</LI>
3505 <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability
3506  and option bits.</LI>
3507 </UL>
3508 <H3><A NAME="8_1_3">Encodings</A></H3>
3509 <P>CUPS defines the following character set encoding constants:</P>
3510 <UL>
3511 <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.</LI>
3512 <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.</LI>
3513 <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.</LI>
3514 <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.</LI>
3515 <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.</LI>
3516 <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.</LI>
3517 <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.</LI>
3518 <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.</LI>
3519 <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.</LI>
3520 <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.</LI>
3521 <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.</LI>
3522 <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.</LI>
3523 <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.</LI>
3524 <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.</LI>
3525 <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.</LI>
3526 <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.</LI>
3527 <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.</LI>
3528 <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.</LI>
3529 <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.</LI>
3530 <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.</LI>
3531 <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.</LI>
3532 <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.</LI>
3533 <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.</LI>
3534 <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.</LI>
3535 <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.</LI>
3536 <LI><CODE>CUPS_KOI8_R</CODE> - Russian code page koi8-r.</LI>
3537 <LI><CODE>CUPS_KOI8_U</CODE> - Ukrainian code page koi8-r.</LI>
3538 </UL>
3539 <H2><A NAME="8_2">HTTP Constants</A></H2>
3540 <H3><A NAME="8_2_1">Limits</A></H3>
3541 <P>The following constants define the limits for strings:</P>
3542 <UL>
3543 <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.</LI>
3544 <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.</LI>
3545 <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.</LI>
3546 <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.</LI>
3547 </UL>
3548 <H3><A NAME="8_2_2">Status Codes</A></H3>
3549 <P>The following status codes can be returned by <CODE>httpUpdate()</CODE>
3550 :</P>
3551 <UL>
3552 <LI><CODE>HTTP_ERROR</CODE> - A network error occurred</LI>
3553 <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy</LI>
3555  successful</LI>
3556 <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful</LI>
3557 <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful</LI>
3558 <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't
3559  authoritative</LI>
3560 <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command</LI>
3561 <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated</LI>
3562 <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was
3563  recieved/sent</LI>
3564 <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request</LI>
3565 <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently</LI>
3566 <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily</LI>
3567 <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...</LI>
3568 <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified</LI>
3569 <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI</LI>
3570 <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request</LI>
3571 <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host</LI>
3572 <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required</LI>
3573 <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI</LI>
3574 <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found</LI>
3575 <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed</LI>
3576 <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable</LI>
3577 <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is
3578  Required</LI>
3579 <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out</LI>
3580 <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting</LI>
3581 <LI><CODE>HTTP_GONE</CODE> - Server has gone away</LI>
3582 <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is
3583  required</LI>
3584 <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed</LI>
3585 <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large</LI>
3586 <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long</LI>
3587 <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type
3588  is unsupported</LI>
3589 <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error</LI>
3590 <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented</LI>
3591 <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway</LI>
3592 <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable</LI>
3593 <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out</LI>
3594 <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported</LI>
3595 </UL>
3596 <H3><A NAME="8_2_3">Fields</A></H3>
3597 <P>The following fields are indices for each of the standard HTTP fields
3598  in HTTP 1/1:</P>
3599 <UL>
3627 </UL>
3628 <H2><A NAME="8_3">IPP Constants</A></H2>
3629 <H3><A NAME="8_3_1">Limits</A></H3>
3630 <P>The following constants define array limits for IPP data:</P>
3631 <UL>
3632 <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name</LI>
3633 <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values that
3634  can be read in a request.</LI>
3635 </UL>
3636 <H3><A NAME="8_3_2">Tags</A></H3>
3637 <UL>
3638 <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
3639  used to separate groups of attributes</LI>
3640 <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation</LI>
3641 <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job</LI>
3642 <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end</LI>
3643 <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer</LI>
3644 <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type
3645  unsupported_group</LI>
3646 <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type
3647  unsupported_value</LI>
3648 <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default</LI>
3649 <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown</LI>
3650 <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue</LI>
3651 <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type