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-2002, All Rights Reserved">
   7 <META NAME="docnumber" CONTENT="CUPS-SPM-1.1.13">
   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.1.13<BR>
  26 Easy Software Products<BR>
  27 Copyright 1997-2002, 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">Trademarks</A></LI>
 139 <LI><A HREF="#7_1_3">Binary Distribution Rights</A></LI>
 140 <LI><A HREF="#7_1_4">Support</A></LI>
 141 </UL>
 142 <LI><A HREF="#7_2">GNU GENERAL PUBLIC LICENSE</A></LI>
 143 <LI><A HREF="#7_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></LI>
 144 </UL>
 145 <B><A HREF="#CONSTANTS">B - Constants</A></B>
 146 <UL>
 147 <LI><A HREF="#8_1">CUPS Constants</A></LI>
 148 <UL>
 149 <LI><A HREF="#8_1_1">Version Number</A></LI>
 150 <LI><A HREF="#8_1_2">Printer Capabilities</A></LI>
 151 <LI><A HREF="#8_1_3">Encodings</A></LI>
 152 </UL>
 153 <LI><A HREF="#8_2">HTTP Constants</A></LI>
 154 <UL>
 155 <LI><A HREF="#8_2_1">Limits</A></LI>
 156 <LI><A HREF="#8_2_2">Status Codes</A></LI>
 157 <LI><A HREF="#8_2_3">Fields</A></LI>
 158 </UL>
 159 <LI><A HREF="#8_3">IPP Constants</A></LI>
 160 <UL>
 161 <LI><A HREF="#8_3_1">Limits</A></LI>
 162 <LI><A HREF="#8_3_2">Tags</A></LI>
 163 <LI><A HREF="#8_3_3">Resolution Units</A></LI>
 164 <LI><A HREF="#8_3_4">Finishings</A></LI>
 165 <LI><A HREF="#8_3_5">Orientations</A></LI>
 166 <LI><A HREF="#8_3_6">Qualities</A></LI>
 167 <LI><A HREF="#8_3_7">Job States</A></LI>
 168 <LI><A HREF="#8_3_8">Printer States</A></LI>
 169 <LI><A HREF="#8_3_9">Operations</A></LI>
 170 <LI><A HREF="#8_3_10">Status Codes</A></LI>
 171 </UL>
 172 <LI><A HREF="#8_4">PPD Constants</A></LI>
 173 <UL>
 174 <LI><A HREF="#8_4_1">PPD Format Version</A></LI>
 175 <LI><A HREF="#8_4_2">PPD User-Interface Types</A></LI>
 176 <LI><A HREF="#8_4_3">PPD Sections</A></LI>
 177 <LI><A HREF="#8_4_4">PPD Colorspaces</A></LI>
 178 </UL>
 179 <LI><A HREF="#8_5">Raster Constants</A></LI>
 180 <UL>
 181 <LI><A HREF="#8_5_1">Raster Sync Words</A></LI>
 182 <LI><A HREF="#8_5_2">Raster Stream Modes</A></LI>
 183 <LI><A HREF="#8_5_3">Raster Boolean Constants</A></LI>
 184 <LI><A HREF="#8_5_4">Raster Jog Values</A></LI>
 185 <LI><A HREF="#8_5_5">Raster Orientation Values</A></LI>
 186 <LI><A HREF="#8_5_6">Raster CutMedia Values</A></LI>
 187 <LI><A HREF="#8_5_7">Raster AdvanceMedia Values</A></LI>
 188 <LI><A HREF="#8_5_8">Raster LeadingEdge Values</A></LI>
 189 <LI><A HREF="#8_5_9">Raster Color Order Values</A></LI>
 190 <LI><A HREF="#8_5_10">Raster Colorspace Values</A></LI>
 191 </UL>
 192 </UL>
 193 <B><A HREF="#STRUCTURES">C - Structures</A></B>
 194 <UL>
 195 <LI><A HREF="#9_1">Raster Structures</A></LI>
 196 <UL>
 197 <LI><A HREF="#9_1_1">Raster Page Header</A></LI>
 198 </UL>
 199 </UL>
 200 <B><A HREF="#10">D - Functions</A></B>
 201 <UL>
 202 <LI><A HREF="#cupsAddOption">cupsAddOption()</A></LI>
 203 <UL>
 204 <LI><A HREF="#10_1_1">Usage</A></LI>
 205 <LI><A HREF="#10_1_2">Arguments</A></LI>
 206 <LI><A HREF="#10_1_3">Returns</A></LI>
 207 <LI><A HREF="#10_1_4">Description</A></LI>
 208 <LI><A HREF="#10_1_5">Example</A></LI>
 209 <LI><A HREF="#10_1_6">See Also</A></LI>
 210 </UL>
 211 <LI><A HREF="#cupsCancelJob">cupsCancelJob()</A></LI>
 212 <UL>
 213 <LI><A HREF="#10_2_1">Usage</A></LI>
 214 <LI><A HREF="#10_2_2">Arguments</A></LI>
 215 <LI><A HREF="#10_2_3">Returns</A></LI>
 216 <LI><A HREF="#10_2_4">Description</A></LI>
 217 <LI><A HREF="#10_2_5">Example</A></LI>
 218 <LI><A HREF="#10_2_6">See Also</A></LI>
 219 </UL>
 220 <LI><A HREF="#cupsDoFileRequest">cupsDoFileRequest()</A></LI>
 221 <UL>
 222 <LI><A HREF="#10_3_1">Usage</A></LI>
 223 <LI><A HREF="#10_3_2">Arguments</A></LI>
 224 <LI><A HREF="#10_3_3">Returns</A></LI>
 225 <LI><A HREF="#10_3_4">Description</A></LI>
 226 <LI><A HREF="#10_3_5">Example</A></LI>
 227 <LI><A HREF="#10_3_6">See Also</A></LI>
 228 </UL>
 229 <LI><A HREF="#cupsDoRequest">cupsDoRequest()</A></LI>
 230 <UL>
 231 <LI><A HREF="#10_4_1">Usage</A></LI>
 232 <LI><A HREF="#10_4_2">Arguments</A></LI>
 233 <LI><A HREF="#10_4_3">Returns</A></LI>
 234 <LI><A HREF="#10_4_4">Description</A></LI>
 235 <LI><A HREF="#10_4_5">Example</A></LI>
 236 <LI><A HREF="#10_4_6">See Also</A></LI>
 237 </UL>
 238 <LI><A HREF="#cupsFreeOptions">cupsFreeOptions()</A></LI>
 239 <UL>
 240 <LI><A HREF="#10_5_1">Usage</A></LI>
 241 <LI><A HREF="#10_5_2">Arguments</A></LI>
 242 <LI><A HREF="#10_5_3">Description</A></LI>
 243 <LI><A HREF="#10_5_4">Example</A></LI>
 244 <LI><A HREF="#10_5_5">See Also</A></LI>
 245 </UL>
 246 <LI><A HREF="#cupsGetClasses">cupsGetClasses()</A></LI>
 247 <UL>
 248 <LI><A HREF="#10_6_1">Usage</A></LI>
 249 <LI><A HREF="#10_6_2">Arguments</A></LI>
 250 <LI><A HREF="#10_6_3">Returns</A></LI>
 251 <LI><A HREF="#10_6_4">Description</A></LI>
 252 <LI><A HREF="#10_6_5">Example</A></LI>
 253 <LI><A HREF="#10_6_6">See Also</A></LI>
 254 </UL>
 255 <LI><A HREF="#cupsGetDefault">cupsGetDefault()</A></LI>
 256 <UL>
 257 <LI><A HREF="#10_7_1">Usage</A></LI>
 258 <LI><A HREF="#10_7_2">Returns</A></LI>
 259 <LI><A HREF="#10_7_3">Description</A></LI>
 260 <LI><A HREF="#10_7_4">Example</A></LI>
 261 <LI><A HREF="#10_7_5">See Also</A></LI>
 262 </UL>
 263 <LI><A HREF="#cupsGetOption">cupsGetOption()</A></LI>
 264 <UL>
 265 <LI><A HREF="#10_8_1">Usage</A></LI>
 266 <LI><A HREF="#10_8_2">Arguments</A></LI>
 267 <LI><A HREF="#10_8_3">Returns</A></LI>
 268 <LI><A HREF="#10_8_4">Description</A></LI>
 269 <LI><A HREF="#10_8_5">See Also</A></LI>
 270 </UL>
 271 <LI><A HREF="#cupsGetPassword">cupsGetPassword()</A></LI>
 272 <UL>
 273 <LI><A HREF="#10_9_1">Usage</A></LI>
 274 <LI><A HREF="#10_9_2">Arguments</A></LI>
 275 <LI><A HREF="#10_9_3">Returns</A></LI>
 276 <LI><A HREF="#10_9_4">Description</A></LI>
 277 <LI><A HREF="#10_9_5">Example</A></LI>
 278 <LI><A HREF="#10_9_6">See Also</A></LI>
 279 </UL>
 280 <LI><A HREF="#cupsGetPPD">cupsGetPPD()</A></LI>
 281 <UL>
 282 <LI><A HREF="#10_10_1">Usage</A></LI>
 283 <LI><A HREF="#10_10_2">Arguments</A></LI>
 284 <LI><A HREF="#10_10_3">Returns</A></LI>
 285 <LI><A HREF="#10_10_4">Description</A></LI>
 286 <LI><A HREF="#10_10_5">Example</A></LI>
 287 </UL>
 288 <LI><A HREF="#cupsGetPrinters">cupsGetPrinters()</A></LI>
 289 <UL>
 290 <LI><A HREF="#10_11_1">Usage</A></LI>
 291 <LI><A HREF="#10_11_2">Arguments</A></LI>
 292 <LI><A HREF="#10_11_3">Returns</A></LI>
 293 <LI><A HREF="#10_11_4">Description</A></LI>
 294 <LI><A HREF="#10_11_5">Example</A></LI>
 295 <LI><A HREF="#10_11_6">See Also</A></LI>
 296 </UL>
 297 <LI><A HREF="#cupsLangDefault">cupsLangDefault()</A></LI>
 298 <UL>
 299 <LI><A HREF="#10_12_1">Usage</A></LI>
 300 <LI><A HREF="#10_12_2">Returns</A></LI>
 301 <LI><A HREF="#10_12_3">Description</A></LI>
 302 <LI><A HREF="#10_12_4">Example</A></LI>
 303 <LI><A HREF="#10_12_5">See Also</A></LI>
 304 </UL>
 305 <LI><A HREF="#cupsLangEncoding">cupsLangEncoding()</A></LI>
 306 <UL>
 307 <LI><A HREF="#10_13_1">Usage</A></LI>
 308 <LI><A HREF="#10_13_2">Arguments</A></LI>
 309 <LI><A HREF="#10_13_3">Returns</A></LI>
 310 <LI><A HREF="#10_13_4">Description</A></LI>
 311 <LI><A HREF="#10_13_5">Example</A></LI>
 312 <LI><A HREF="#10_13_6">See Also</A></LI>
 313 </UL>
 314 <LI><A HREF="#cupsLangFlush">cupsLangFlush()</A></LI>
 315 <UL>
 316 <LI><A HREF="#10_14_1">Usage</A></LI>
 317 <LI><A HREF="#10_14_2">Description</A></LI>
 318 <LI><A HREF="#10_14_3">Example</A></LI>
 319 <LI><A HREF="#10_14_4">See Also</A></LI>
 320 </UL>
 321 <LI><A HREF="#cupsLangFree">cupsLangFree()</A></LI>
 322 <UL>
 323 <LI><A HREF="#10_15_1">Usage</A></LI>
 324 <LI><A HREF="#10_15_2">Arguments</A></LI>
 325 <LI><A HREF="#10_15_3">Description</A></LI>
 326 <LI><A HREF="#10_15_4">Example</A></LI>
 327 <LI><A HREF="#10_15_5">See Also</A></LI>
 328 </UL>
 329 <LI><A HREF="#cupsLangGet">cupsLangGet()</A></LI>
 330 <UL>
 331 <LI><A HREF="#10_16_1">Usage</A></LI>
 332 <LI><A HREF="#10_16_2">Arguments</A></LI>
 333 <LI><A HREF="#10_16_3">Returns</A></LI>
 334 <LI><A HREF="#10_16_4">Description</A></LI>
 335 <LI><A HREF="#10_16_5">Example</A></LI>
 336 <LI><A HREF="#10_16_6">See Also</A></LI>
 337 </UL>
 338 <LI><A HREF="#cupsLangString">cupsLangString()</A></LI>
 339 <UL>
 340 <LI><A HREF="#10_17_1">Usage</A></LI>
 341 <LI><A HREF="#10_17_2">Arguments</A></LI>
 342 <LI><A HREF="#10_17_3">Returns</A></LI>
 343 <LI><A HREF="#10_17_4">Description</A></LI>
 344 <LI><A HREF="#10_17_5">Example</A></LI>
 345 <LI><A HREF="#10_17_6">See Also</A></LI>
 346 </UL>
 347 <LI><A HREF="#cupsLastError">cupsLastError()</A></LI>
 348 <UL>
 349 <LI><A HREF="#10_18_1">Usage</A></LI>
 350 <LI><A HREF="#10_18_2">Returns</A></LI>
 351 <LI><A HREF="#10_18_3">Description</A></LI>
 352 <LI><A HREF="#10_18_4">Example</A></LI>
 353 <LI><A HREF="#10_18_5">See Also</A></LI>
 354 </UL>
 355 <LI><A HREF="#cupsMarkOptions">cupsMarkOptions()</A></LI>
 356 <UL>
 357 <LI><A HREF="#10_19_1">Usage</A></LI>
 358 <LI><A HREF="#10_19_2">Arguments</A></LI>
 359 <LI><A HREF="#10_19_3">Returns</A></LI>
 360 <LI><A HREF="#10_19_4">Description</A></LI>
 361 <LI><A HREF="#10_19_5">Example</A></LI>
 362 <LI><A HREF="#10_19_6">See Also</A></LI>
 363 </UL>
 364 <LI><A HREF="#cupsParseOptions">cupsParseOptions()</A></LI>
 365 <UL>
 366 <LI><A HREF="#10_20_1">Usage</A></LI>
 367 <LI><A HREF="#10_20_2">Arguments</A></LI>
 368 <LI><A HREF="#10_20_3">Returns</A></LI>
 369 <LI><A HREF="#10_20_4">Description</A></LI>
 370 <LI><A HREF="#10_20_5">Example</A></LI>
 371 <LI><A HREF="#10_20_6">See Also</A></LI>
 372 </UL>
 373 <LI><A HREF="#cupsPrintFile">cupsPrintFile()</A></LI>
 374 <UL>
 375 <LI><A HREF="#10_21_1">Usage</A></LI>
 376 <LI><A HREF="#10_21_2">Arguments</A></LI>
 377 <LI><A HREF="#10_21_3">Returns</A></LI>
 378 <LI><A HREF="#10_21_4">Description</A></LI>
 379 <LI><A HREF="#10_21_5">Example</A></LI>
 380 <LI><A HREF="#10_21_6">See Also</A></LI>
 381 </UL>
 382 <LI><A HREF="#cupsPrintFiles">cupsPrintFiles()</A></LI>
 383 <UL>
 384 <LI><A HREF="#10_22_1">Usage</A></LI>
 385 <LI><A HREF="#10_22_2">Arguments</A></LI>
 386 <LI><A HREF="#10_22_3">Returns</A></LI>
 387 <LI><A HREF="#10_22_4">Description</A></LI>
 388 <LI><A HREF="#10_22_5">Example</A></LI>
 389 <LI><A HREF="#10_22_6">See Also</A></LI>
 390 </UL>
 391 <LI><A HREF="#cupsRasterClose">cupsRasterClose()</A></LI>
 392 <UL>
 393 <LI><A HREF="#10_23_1">Usage</A></LI>
 394 <LI><A HREF="#10_23_2">Arguments</A></LI>
 395 <LI><A HREF="#10_23_3">Description</A></LI>
 396 <LI><A HREF="#10_23_4">Example</A></LI>
 397 <LI><A HREF="#10_23_5">See Also</A></LI>
 398 </UL>
 399 <LI><A HREF="#cupsRasterOpen">cupsRasterOpen()</A></LI>
 400 <UL>
 401 <LI><A HREF="#10_24_1">Usage</A></LI>
 402 <LI><A HREF="#10_24_2">Arguments</A></LI>
 403 <LI><A HREF="#10_24_3">Returns</A></LI>
 404 <LI><A HREF="#10_24_4">Description</A></LI>
 405 <LI><A HREF="#10_24_5">Example</A></LI>
 406 <LI><A HREF="#10_24_6">See Also</A></LI>
 407 </UL>
 408 <LI><A HREF="#cupsRasterReadHeader">cupsRasterReadHeader()</A></LI>
 409 <UL>
 410 <LI><A HREF="#10_25_1">Usage</A></LI>
 411 <LI><A HREF="#10_25_2">Arguments</A></LI>
 412 <LI><A HREF="#10_25_3">Returns</A></LI>
 413 <LI><A HREF="#10_25_4">Description</A></LI>
 414 <LI><A HREF="#10_25_5">Example</A></LI>
 415 <LI><A HREF="#10_25_6">See Also</A></LI>
 416 </UL>
 417 <LI><A HREF="#cupsRasterReadPixels">cupsRasterReadPixels()</A></LI>
 418 <UL>
 419 <LI><A HREF="#10_26_1">Usage</A></LI>
 420 <LI><A HREF="#10_26_2">Arguments</A></LI>
 421 <LI><A HREF="#10_26_3">Returns</A></LI>
 422 <LI><A HREF="#10_26_4">Description</A></LI>
 423 <LI><A HREF="#10_26_5">Example</A></LI>
 424 <LI><A HREF="#10_26_6">See Also</A></LI>
 425 </UL>
 426 <LI><A HREF="#cupsRasterWriteHeader">cupsRasterWriteHeader()</A></LI>
 427 <UL>
 428 <LI><A HREF="#10_27_1">Usage</A></LI>
 429 <LI><A HREF="#10_27_2">Arguments</A></LI>
 430 <LI><A HREF="#10_27_3">Returns</A></LI>
 431 <LI><A HREF="#10_27_4">Description</A></LI>
 432 <LI><A HREF="#10_27_5">Example</A></LI>
 433 <LI><A HREF="#10_27_6">See Also</A></LI>
 434 </UL>
 435 <LI><A HREF="#cupsRasterWritePixels">cupsRasterWritePixels()</A></LI>
 436 <UL>
 437 <LI><A HREF="#10_28_1">Usage</A></LI>
 438 <LI><A HREF="#10_28_2">Arguments</A></LI>
 439 <LI><A HREF="#10_28_3">Returns</A></LI>
 440 <LI><A HREF="#10_28_4">Description</A></LI>
 441 <LI><A HREF="#10_28_5">Example</A></LI>
 442 <LI><A HREF="#10_28_6">See Also</A></LI>
 443 </UL>
 444 <LI><A HREF="#cupsServer">cupsServer()</A></LI>
 445 <UL>
 446 <LI><A HREF="#10_29_1">Usage</A></LI>
 447 <LI><A HREF="#10_29_2">Returns</A></LI>
 448 <LI><A HREF="#10_29_3">Description</A></LI>
 449 <LI><A HREF="#10_29_4">Example</A></LI>
 450 <LI><A HREF="#10_29_5">See Also</A></LI>
 451 </UL>
 452 <LI><A HREF="#cupsSetPasswordCB">cupsSetPasswordCB()</A></LI>
 453 <UL>
 454 <LI><A HREF="#10_30_1">Usage</A></LI>
 455 <LI><A HREF="#10_30_2">Arguments</A></LI>
 456 <LI><A HREF="#10_30_3">Description</A></LI>
 457 <LI><A HREF="#10_30_4">Example</A></LI>
 458 <LI><A HREF="#10_30_5">See Also</A></LI>
 459 </UL>
 460 <LI><A HREF="#cupsSetServer">cupsSetServer()</A></LI>
 461 <UL>
 462 <LI><A HREF="#10_31_1">Usage</A></LI>
 463 <LI><A HREF="#10_31_2">Arguments</A></LI>
 464 <LI><A HREF="#10_31_3">Description</A></LI>
 465 <LI><A HREF="#10_31_4">Example</A></LI>
 466 <LI><A HREF="#10_31_5">See Also</A></LI>
 467 </UL>
 468 <LI><A HREF="#cupsSetUser">cupsSetUser()</A></LI>
 469 <UL>
 470 <LI><A HREF="#10_32_1">Usage</A></LI>
 471 <LI><A HREF="#10_32_2">Arguments</A></LI>
 472 <LI><A HREF="#10_32_3">Description</A></LI>
 473 <LI><A HREF="#10_32_4">Example</A></LI>
 474 <LI><A HREF="#10_32_5">See Also</A></LI>
 475 </UL>
 476 <LI><A HREF="#cupsTempFile">cupsTempFile()</A></LI>
 477 <UL>
 478 <LI><A HREF="#10_33_1">Usage</A></LI>
 479 <LI><A HREF="#10_33_2">Arguments</A></LI>
 480 <LI><A HREF="#10_33_3">Returns</A></LI>
 481 <LI><A HREF="#10_33_4">Description</A></LI>
 482 <LI><A HREF="#10_33_5">Example</A></LI>
 483 </UL>
 484 <LI><A HREF="#cupsUser">cupsUser()</A></LI>
 485 <UL>
 486 <LI><A HREF="#10_34_1">Usage</A></LI>
 487 <LI><A HREF="#10_34_2">Returns</A></LI>
 488 <LI><A HREF="#10_34_3">Description</A></LI>
 489 <LI><A HREF="#10_34_4">Example</A></LI>
 490 <LI><A HREF="#10_34_5">See Also</A></LI>
 491 </UL>
 492 <LI><A HREF="#httpBlocking">httpBlocking()</A></LI>
 493 <UL>
 494 <LI><A HREF="#10_35_1">Usage</A></LI>
 495 <LI><A HREF="#10_35_2">Arguments</A></LI>
 496 <LI><A HREF="#10_35_3">Description</A></LI>
 497 <LI><A HREF="#10_35_4">Example</A></LI>
 498 <LI><A HREF="#10_35_5">See Also</A></LI>
 499 </UL>
 500 <LI><A HREF="#httpCheck">httpCheck()</A></LI>
 501 <UL>
 502 <LI><A HREF="#10_36_1">Usage</A></LI>
 503 <LI><A HREF="#10_36_2">Arguments</A></LI>
 504 <LI><A HREF="#10_36_3">Returns</A></LI>
 505 <LI><A HREF="#10_36_4">Description</A></LI>
 506 <LI><A HREF="#10_36_5">Example</A></LI>
 507 <LI><A HREF="#10_36_6">See Also</A></LI>
 508 </UL>
 509 <LI><A HREF="#httpClearFields">httpClearFields()</A></LI>
 510 <UL>
 511 <LI><A HREF="#10_37_1">Usage</A></LI>
 512 <LI><A HREF="#10_37_2">Arguments</A></LI>
 513 <LI><A HREF="#10_37_3">Description</A></LI>
 514 <LI><A HREF="#10_37_4">Example</A></LI>
 515 <LI><A HREF="#10_37_5">See Also</A></LI>
 516 </UL>
 517 <LI><A HREF="#httpClose">httpClose()</A></LI>
 518 <UL>
 519 <LI><A HREF="#10_38_1">Usage</A></LI>
 520 <LI><A HREF="#10_38_2">Arguments</A></LI>
 521 <LI><A HREF="#10_38_3">Description</A></LI>
 522 <LI><A HREF="#10_38_4">Example</A></LI>
 523 <LI><A HREF="#10_38_5">See Also</A></LI>
 524 </UL>
 525 <LI><A HREF="#httpConnect">httpConnect()</A></LI>
 526 <UL>
 527 <LI><A HREF="#10_39_1">Usage</A></LI>
 528 <LI><A HREF="#10_39_2">Arguments</A></LI>
 529 <LI><A HREF="#10_39_3">Returns</A></LI>
 530 <LI><A HREF="#10_39_4">Description</A></LI>
 531 <LI><A HREF="#10_39_5">Example</A></LI>
 532 <LI><A HREF="#10_39_6">See Also</A></LI>
 533 </UL>
 534 <LI><A HREF="#httpDecode64">httpDecode64()</A></LI>
 535 <UL>
 536 <LI><A HREF="#10_40_1">Usage</A></LI>
 537 <LI><A HREF="#10_40_2">Arguments</A></LI>
 538 <LI><A HREF="#10_40_3">Returns</A></LI>
 539 <LI><A HREF="#10_40_4">Description</A></LI>
 540 <LI><A HREF="#10_40_5">Example</A></LI>
 541 <LI><A HREF="#10_40_6">See Also</A></LI>
 542 </UL>
 543 <LI><A HREF="#httpDelete">httpDelete()</A></LI>
 544 <UL>
 545 <LI><A HREF="#10_41_1">Usage</A></LI>
 546 <LI><A HREF="#10_41_2">Arguments</A></LI>
 547 <LI><A HREF="#10_41_3">Returns</A></LI>
 548 <LI><A HREF="#10_41_4">Description</A></LI>
 549 <LI><A HREF="#10_41_5">Example</A></LI>
 550 <LI><A HREF="#10_41_6">See Also</A></LI>
 551 </UL>
 552 <LI><A HREF="#httpEncode64">httpEncode64()</A></LI>
 553 <UL>
 554 <LI><A HREF="#10_42_1">Usage</A></LI>
 555 <LI><A HREF="#10_42_2">Arguments</A></LI>
 556 <LI><A HREF="#10_42_3">Returns</A></LI>
 557 <LI><A HREF="#10_42_4">Description</A></LI>
 558 <LI><A HREF="#10_42_5">Example</A></LI>
 559 <LI><A HREF="#10_42_6">See Also</A></LI>
 560 </UL>
 561 <LI><A HREF="#httpError">httpError()</A></LI>
 562 <UL>
 563 <LI><A HREF="#10_43_1">Usage</A></LI>
 564 <LI><A HREF="#10_43_2">Arguments</A></LI>
 565 <LI><A HREF="#10_43_3">Returns</A></LI>
 566 <LI><A HREF="#10_43_4">Description</A></LI>
 567 <LI><A HREF="#10_43_5">Example</A></LI>
 568 <LI><A HREF="#10_43_6">See Also</A></LI>
 569 </UL>
 570 <LI><A HREF="#httpFlush">httpFlush()</A></LI>
 571 <UL>
 572 <LI><A HREF="#10_44_1">Usage</A></LI>
 573 <LI><A HREF="#10_44_2">Arguments</A></LI>
 574 <LI><A HREF="#10_44_3">Description</A></LI>
 575 <LI><A HREF="#10_44_4">Example</A></LI>
 576 <LI><A HREF="#10_44_5">See Also</A></LI>
 577 </UL>
 578 <LI><A HREF="#httpGet">httpGet()</A></LI>
 579 <UL>
 580 <LI><A HREF="#10_45_1">Usage</A></LI>
 581 <LI><A HREF="#10_45_2">Arguments</A></LI>
 582 <LI><A HREF="#10_45_3">Returns</A></LI>
 583 <LI><A HREF="#10_45_4">Description</A></LI>
 584 <LI><A HREF="#10_45_5">Example</A></LI>
 585 <LI><A HREF="#10_45_6">See Also</A></LI>
 586 </UL>
 587 <LI><A HREF="#httpGets">httpGets()</A></LI>
 588 <UL>
 589 <LI><A HREF="#10_46_1">Usage</A></LI>
 590 <LI><A HREF="#10_46_2">Arguments</A></LI>
 591 <LI><A HREF="#10_46_3">Returns</A></LI>
 592 <LI><A HREF="#10_46_4">Description</A></LI>
 593 <LI><A HREF="#10_46_5">Example</A></LI>
 594 <LI><A HREF="#10_46_6">See Also</A></LI>
 595 </UL>
 596 <LI><A HREF="#httpGetDateString">httpGetDateString()</A></LI>
 597 <UL>
 598 <LI><A HREF="#10_47_1">Usage</A></LI>
 599 <LI><A HREF="#10_47_2">Arguments</A></LI>
 600 <LI><A HREF="#10_47_3">Returns</A></LI>
 601 <LI><A HREF="#10_47_4">Description</A></LI>
 602 <LI><A HREF="#10_47_5">Example</A></LI>
 603 <LI><A HREF="#10_47_6">See Also</A></LI>
 604 </UL>
 605 <LI><A HREF="#httpGetDateTime">httpGetDateTime()</A></LI>
 606 <UL>
 607 <LI><A HREF="#10_48_1">Usage</A></LI>
 608 <LI><A HREF="#10_48_2">Arguments</A></LI>
 609 <LI><A HREF="#10_48_3">Returns</A></LI>
 610 <LI><A HREF="#10_48_4">Description</A></LI>
 611 <LI><A HREF="#10_48_5">Example</A></LI>
 612 <LI><A HREF="#10_48_6">See Also</A></LI>
 613 </UL>
 614 <LI><A HREF="#httpGetField">httpGetField()</A></LI>
 615 <UL>
 616 <LI><A HREF="#10_49_1">Usage</A></LI>
 617 <LI><A HREF="#10_49_2">Arguments</A></LI>
 618 <LI><A HREF="#10_49_3">Returns</A></LI>
 619 <LI><A HREF="#10_49_4">Description</A></LI>
 620 <LI><A HREF="#10_49_5">Example</A></LI>
 621 <LI><A HREF="#10_49_6">See Also</A></LI>
 622 </UL>
 623 <LI><A HREF="#httpHead">httpHead()</A></LI>
 624 <UL>
 625 <LI><A HREF="#10_50_1">Usage</A></LI>
 626 <LI><A HREF="#10_50_2">Arguments</A></LI>
 627 <LI><A HREF="#10_50_3">Returns</A></LI>
 628 <LI><A HREF="#10_50_4">Description</A></LI>
 629 <LI><A HREF="#10_50_5">Example</A></LI>
 630 <LI><A HREF="#10_50_6">See Also</A></LI>
 631 </UL>
 632 <LI><A HREF="#httpInitialize">httpInitialize()</A></LI>
 633 <UL>
 634 <LI><A HREF="#10_51_1">Usage</A></LI>
 635 <LI><A HREF="#10_51_2">Description</A></LI>
 636 <LI><A HREF="#10_51_3">Example</A></LI>
 637 <LI><A HREF="#10_51_4">See Also</A></LI>
 638 </UL>
 639 <LI><A HREF="#httpOptions">httpOptions()</A></LI>
 640 <UL>
 641 <LI><A HREF="#10_52_1">Usage</A></LI>
 642 <LI><A HREF="#10_52_2">Arguments</A></LI>
 643 <LI><A HREF="#10_52_3">Returns</A></LI>
 644 <LI><A HREF="#10_52_4">Description</A></LI>
 645 <LI><A HREF="#10_52_5">Example</A></LI>
 646 <LI><A HREF="#10_52_6">See Also</A></LI>
 647 </UL>
 648 <LI><A HREF="#httpPost">httpPost()</A></LI>
 649 <UL>
 650 <LI><A HREF="#10_53_1">Usage</A></LI>
 651 <LI><A HREF="#10_53_2">Arguments</A></LI>
 652 <LI><A HREF="#10_53_3">Returns</A></LI>
 653 <LI><A HREF="#10_53_4">Description</A></LI>
 654 <LI><A HREF="#10_53_5">Example</A></LI>
 655 <LI><A HREF="#10_53_6">See Also</A></LI>
 656 </UL>
 657 <LI><A HREF="#httpPrintf">httpPrintf()</A></LI>
 658 <UL>
 659 <LI><A HREF="#10_54_1">Usage</A></LI>
 660 <LI><A HREF="#10_54_2">Arguments</A></LI>
 661 <LI><A HREF="#10_54_3">Returns</A></LI>
 662 <LI><A HREF="#10_54_4">Description</A></LI>
 663 <LI><A HREF="#10_54_5">Example</A></LI>
 664 <LI><A HREF="#10_54_6">See Also</A></LI>
 665 </UL>
 666 <LI><A HREF="#httpPut">httpPut()</A></LI>
 667 <UL>
 668 <LI><A HREF="#10_55_1">Usage</A></LI>
 669 <LI><A HREF="#10_55_2">Arguments</A></LI>
 670 <LI><A HREF="#10_55_3">Returns</A></LI>
 671 <LI><A HREF="#10_55_4">Description</A></LI>
 672 <LI><A HREF="#10_55_5">Example</A></LI>
 673 <LI><A HREF="#10_55_6">See Also</A></LI>
 674 </UL>
 675 <LI><A HREF="#httpRead">httpRead()</A></LI>
 676 <UL>
 677 <LI><A HREF="#10_56_1">Usage</A></LI>
 678 <LI><A HREF="#10_56_2">Arguments</A></LI>
 679 <LI><A HREF="#10_56_3">Returns</A></LI>
 680 <LI><A HREF="#10_56_4">Description</A></LI>
 681 <LI><A HREF="#10_56_5">Example</A></LI>
 682 <LI><A HREF="#10_56_6">See Also</A></LI>
 683 </UL>
 684 <LI><A HREF="#httpReconnect">httpReconnect()</A></LI>
 685 <UL>
 686 <LI><A HREF="#10_57_1">Usage</A></LI>
 687 <LI><A HREF="#10_57_2">Arguments</A></LI>
 688 <LI><A HREF="#10_57_3">Returns</A></LI>
 689 <LI><A HREF="#10_57_4">Description</A></LI>
 690 <LI><A HREF="#10_57_5">Example</A></LI>
 691 <LI><A HREF="#10_57_6">See Also</A></LI>
 692 </UL>
 693 <LI><A HREF="#httpSeparate">httpSeparate()</A></LI>
 694 <UL>
 695 <LI><A HREF="#10_58_1">Usage</A></LI>
 696 <LI><A HREF="#10_58_2">Arguments</A></LI>
 697 <LI><A HREF="#10_58_3">Description</A></LI>
 698 <LI><A HREF="#10_58_4">Example</A></LI>
 699 <LI><A HREF="#10_58_5">See Also</A></LI>
 700 </UL>
 701 <LI><A HREF="#httpSetField">httpSetField()</A></LI>
 702 <UL>
 703 <LI><A HREF="#10_59_1">Usage</A></LI>
 704 <LI><A HREF="#10_59_2">Arguments</A></LI>
 705 <LI><A HREF="#10_59_3">Description</A></LI>
 706 <LI><A HREF="#10_59_4">Example</A></LI>
 707 <LI><A HREF="#10_59_5">See Also</A></LI>
 708 </UL>
 709 <LI><A HREF="#httpTrace">httpTrace()</A></LI>
 710 <UL>
 711 <LI><A HREF="#10_60_1">Usage</A></LI>
 712 <LI><A HREF="#10_60_2">Arguments</A></LI>
 713 <LI><A HREF="#10_60_3">Returns</A></LI>
 714 <LI><A HREF="#10_60_4">Description</A></LI>
 715 <LI><A HREF="#10_60_5">Example</A></LI>
 716 <LI><A HREF="#10_60_6">See Also</A></LI>
 717 </UL>
 718 <LI><A HREF="#httpUpdate">httpUpdate()</A></LI>
 719 <UL>
 720 <LI><A HREF="#10_61_1">Usage</A></LI>
 721 <LI><A HREF="#10_61_2">Arguments</A></LI>
 722 <LI><A HREF="#10_61_3">Returns</A></LI>
 723 <LI><A HREF="#10_61_4">Description</A></LI>
 724 <LI><A HREF="#10_61_5">Example</A></LI>
 725 <LI><A HREF="#10_61_6">See Also</A></LI>
 726 </UL>
 727 <LI><A HREF="#httpWrite">httpWrite()</A></LI>
 728 <UL>
 729 <LI><A HREF="#10_62_1">Usage</A></LI>
 730 <LI><A HREF="#10_62_2">Arguments</A></LI>
 731 <LI><A HREF="#10_62_3">Returns</A></LI>
 732 <LI><A HREF="#10_62_4">Description</A></LI>
 733 <LI><A HREF="#10_62_5">Example</A></LI>
 734 <LI><A HREF="#10_62_6">See Also</A></LI>
 735 </UL>
 736 <LI><A HREF="#ippAddBoolean">ippAddBoolean()</A></LI>
 737 <UL>
 738 <LI><A HREF="#10_63_1">Usage</A></LI>
 739 <LI><A HREF="#10_63_2">Arguments</A></LI>
 740 <LI><A HREF="#10_63_3">Returns</A></LI>
 741 <LI><A HREF="#10_63_4">Description</A></LI>
 742 <LI><A HREF="#10_63_5">Example</A></LI>
 743 <LI><A HREF="#10_63_6">See Also</A></LI>
 744 </UL>
 745 <LI><A HREF="#ippAddBooleans">ippAddBooleans()</A></LI>
 746 <UL>
 747 <LI><A HREF="#10_64_1">Usage</A></LI>
 748 <LI><A HREF="#10_64_2">Arguments</A></LI>
 749 <LI><A HREF="#10_64_3">Returns</A></LI>
 750 <LI><A HREF="#10_64_4">Description</A></LI>
 751 <LI><A HREF="#10_64_5">Example</A></LI>
 752 <LI><A HREF="#10_64_6">See Also</A></LI>
 753 </UL>
 754 <LI><A HREF="#ippAddDate">ippAddDate()</A></LI>
 755 <UL>
 756 <LI><A HREF="#10_65_1">Usage</A></LI>
 757 <LI><A HREF="#10_65_2">Arguments</A></LI>
 758 <LI><A HREF="#10_65_3">Returns</A></LI>
 759 <LI><A HREF="#10_65_4">Description</A></LI>
 760 <LI><A HREF="#10_65_5">Example</A></LI>
 761 <LI><A HREF="#10_65_6">See Also</A></LI>
 762 </UL>
 763 <LI><A HREF="#ippAddInteger">ippAddInteger()</A></LI>
 764 <UL>
 765 <LI><A HREF="#10_66_1">Usage</A></LI>
 766 <LI><A HREF="#10_66_2">Arguments</A></LI>
 767 <LI><A HREF="#10_66_3">Returns</A></LI>
 768 <LI><A HREF="#10_66_4">Description</A></LI>
 769 <LI><A HREF="#10_66_5">Example</A></LI>
 770 <LI><A HREF="#10_66_6">See Also</A></LI>
 771 </UL>
 772 <LI><A HREF="#ippAddIntegers">ippAddIntegers()</A></LI>
 773 <UL>
 774 <LI><A HREF="#10_67_1">Usage</A></LI>
 775 <LI><A HREF="#10_67_2">Arguments</A></LI>
 776 <LI><A HREF="#10_67_3">Returns</A></LI>
 777 <LI><A HREF="#10_67_4">Description</A></LI>
 778 <LI><A HREF="#10_67_5">Example</A></LI>
 779 <LI><A HREF="#10_67_6">See Also</A></LI>
 780 </UL>
 781 <LI><A HREF="#ippAddRange">ippAddRange()</A></LI>
 782 <UL>
 783 <LI><A HREF="#10_68_1">Usage</A></LI>
 784 <LI><A HREF="#10_68_2">Arguments</A></LI>
 785 <LI><A HREF="#10_68_3">Returns</A></LI>
 786 <LI><A HREF="#10_68_4">Description</A></LI>
 787 <LI><A HREF="#10_68_5">Example</A></LI>
 788 <LI><A HREF="#10_68_6">See Also</A></LI>
 789 </UL>
 790 <LI><A HREF="#ippAddRanges">ippAddRanges()</A></LI>
 791 <UL>
 792 <LI><A HREF="#10_69_1">Usage</A></LI>
 793 <LI><A HREF="#10_69_2">Arguments</A></LI>
 794 <LI><A HREF="#10_69_3">Returns</A></LI>
 795 <LI><A HREF="#10_69_4">Description</A></LI>
 796 <LI><A HREF="#10_69_5">Example</A></LI>
 797 <LI><A HREF="#10_69_6">See Also</A></LI>
 798 </UL>
 799 <LI><A HREF="#ippAddResolution">ippAddResolution()</A></LI>
 800 <UL>
 801 <LI><A HREF="#10_70_1">Usage</A></LI>
 802 <LI><A HREF="#10_70_2">Arguments</A></LI>
 803 <LI><A HREF="#10_70_3">Returns</A></LI>
 804 <LI><A HREF="#10_70_4">Description</A></LI>
 805 <LI><A HREF="#10_70_5">Example</A></LI>
 806 <LI><A HREF="#10_70_6">See Also</A></LI>
 807 </UL>
 808 <LI><A HREF="#ippAddResolutions">ippAddResolutions()</A></LI>
 809 <UL>
 810 <LI><A HREF="#10_71_1">Usage</A></LI>
 811 <LI><A HREF="#10_71_2">Arguments</A></LI>
 812 <LI><A HREF="#10_71_3">Returns</A></LI>
 813 <LI><A HREF="#10_71_4">Description</A></LI>
 814 <LI><A HREF="#10_71_5">Example</A></LI>
 815 <LI><A HREF="#10_71_6">See Also</A></LI>
 816 </UL>
 817 <LI><A HREF="#ippAddSeparator">ippAddSeparator()</A></LI>
 818 <UL>
 819 <LI><A HREF="#10_72_1">Usage</A></LI>
 820 <LI><A HREF="#10_72_2">Arguments</A></LI>
 821 <LI><A HREF="#10_72_3">Returns</A></LI>
 822 <LI><A HREF="#10_72_4">Description</A></LI>
 823 <LI><A HREF="#10_72_5">Example</A></LI>
 824 <LI><A HREF="#10_72_6">See Also</A></LI>
 825 </UL>
 826 <LI><A HREF="#ippAddString">ippAddString()</A></LI>
 827 <UL>
 828 <LI><A HREF="#10_73_1">Usage</A></LI>
 829 <LI><A HREF="#10_73_2">Arguments</A></LI>
 830 <LI><A HREF="#10_73_3">Returns</A></LI>
 831 <LI><A HREF="#10_73_4">Description</A></LI>
 832 <LI><A HREF="#10_73_5">Example</A></LI>
 833 <LI><A HREF="#10_73_6">See Also</A></LI>
 834 </UL>
 835 <LI><A HREF="#ippAddStrings">ippAddStrings()</A></LI>
 836 <UL>
 837 <LI><A HREF="#10_74_1">Usage</A></LI>
 838 <LI><A HREF="#10_74_2">Arguments</A></LI>
 839 <LI><A HREF="#10_74_3">Returns</A></LI>
 840 <LI><A HREF="#10_74_4">Description</A></LI>
 841 <LI><A HREF="#10_74_5">Example</A></LI>
 842 <LI><A HREF="#10_74_6">See Also</A></LI>
 843 </UL>
 844 <LI><A HREF="#ippDateToTime">ippDateToTime()</A></LI>
 845 <UL>
 846 <LI><A HREF="#10_75_1">Usage</A></LI>
 847 <LI><A HREF="#10_75_2">Arguments</A></LI>
 848 <LI><A HREF="#10_75_3">Returns</A></LI>
 849 <LI><A HREF="#10_75_4">Description</A></LI>
 850 <LI><A HREF="#10_75_5">Example</A></LI>
 851 <LI><A HREF="#10_75_6">See Also</A></LI>
 852 </UL>
 853 <LI><A HREF="#ippDelete">ippDelete()</A></LI>
 854 <UL>
 855 <LI><A HREF="#10_76_1">Usage</A></LI>
 856 <LI><A HREF="#10_76_2">Arguments</A></LI>
 857 <LI><A HREF="#10_76_3">Description</A></LI>
 858 <LI><A HREF="#10_76_4">Example</A></LI>
 859 <LI><A HREF="#10_76_5">See Also</A></LI>
 860 </UL>
 861 <LI><A HREF="#ippFindAttribute">ippFindAttribute()</A></LI>
 862 <UL>
 863 <LI><A HREF="#10_77_1">Usage</A></LI>
 864 <LI><A HREF="#10_77_2">Arguments</A></LI>
 865 <LI><A HREF="#10_77_3">Returns</A></LI>
 866 <LI><A HREF="#10_77_4">Description</A></LI>
 867 <LI><A HREF="#10_77_5">Example</A></LI>
 868 <LI><A HREF="#10_77_6">See Also</A></LI>
 869 </UL>
 870 <LI><A HREF="#ippLength">ippLength()</A></LI>
 871 <UL>
 872 <LI><A HREF="#10_78_1">Usage</A></LI>
 873 <LI><A HREF="#10_78_2">Arguments</A></LI>
 874 <LI><A HREF="#10_78_3">Returns</A></LI>
 875 <LI><A HREF="#10_78_4">Description</A></LI>
 876 <LI><A HREF="#10_78_5">Example</A></LI>
 877 <LI><A HREF="#10_78_6">See Also</A></LI>
 878 </UL>
 879 <LI><A HREF="#ippNew">ippNew()</A></LI>
 880 <UL>
 881 <LI><A HREF="#10_79_1">Usage</A></LI>
 882 <LI><A HREF="#10_79_2">Returns</A></LI>
 883 <LI><A HREF="#10_79_3">Description</A></LI>
 884 <LI><A HREF="#10_79_4">Example</A></LI>
 885 <LI><A HREF="#10_79_5">See Also</A></LI>
 886 </UL>
 887 <LI><A HREF="#ippPort">ippPort()</A></LI>
 888 <UL>
 889 <LI><A HREF="#10_80_1">Usage</A></LI>
 890 <LI><A HREF="#10_80_2">Returns</A></LI>
 891 <LI><A HREF="#10_80_3">Description</A></LI>
 892 <LI><A HREF="#10_80_4">Example</A></LI>
 893 <LI><A HREF="#10_80_5">See Also</A></LI>
 894 </UL>
 895 <LI><A HREF="#ippRead">ippRead()</A></LI>
 896 <UL>
 897 <LI><A HREF="#10_81_1">Usage</A></LI>
 898 <LI><A HREF="#10_81_2">Arguments</A></LI>
 899 <LI><A HREF="#10_81_3">Returns</A></LI>
 900 <LI><A HREF="#10_81_4">Description</A></LI>
 901 <LI><A HREF="#10_81_5">Example</A></LI>
 902 <LI><A HREF="#10_81_6">See Also</A></LI>
 903 </UL>
 904 <LI><A HREF="#ippSetPort">ippSetPort()</A></LI>
 905 <UL>
 906 <LI><A HREF="#10_82_1">Usage</A></LI>
 907 <LI><A HREF="#10_82_2">Arguments</A></LI>
 908 <LI><A HREF="#10_82_3">Description</A></LI>
 909 <LI><A HREF="#10_82_4">Example</A></LI>
 910 <LI><A HREF="#10_82_5">See Also</A></LI>
 911 </UL>
 912 <LI><A HREF="#ippTimeToDate">ippTimeToDate()</A></LI>
 913 <UL>
 914 <LI><A HREF="#10_83_1">Usage</A></LI>
 915 <LI><A HREF="#10_83_2">Arguments</A></LI>
 916 <LI><A HREF="#10_83_3">Returns</A></LI>
 917 <LI><A HREF="#10_83_4">Description</A></LI>
 918 <LI><A HREF="#10_83_5">Example</A></LI>
 919 <LI><A HREF="#10_83_6">See Also</A></LI>
 920 </UL>
 921 <LI><A HREF="#ippWrite">ippWrite()</A></LI>
 922 <UL>
 923 <LI><A HREF="#10_84_1">Usage</A></LI>
 924 <LI><A HREF="#10_84_2">Arguments</A></LI>
 925 <LI><A HREF="#10_84_3">Returns</A></LI>
 926 <LI><A HREF="#10_84_4">Description</A></LI>
 927 <LI><A HREF="#10_84_5">Example</A></LI>
 928 <LI><A HREF="#10_84_6">See Also</A></LI>
 929 </UL>
 930 <LI><A HREF="#ppdClose">ppdClose()</A></LI>
 931 <UL>
 932 <LI><A HREF="#10_85_1">Usage</A></LI>
 933 <LI><A HREF="#10_85_2">Arguments</A></LI>
 934 <LI><A HREF="#10_85_3">Description</A></LI>
 935 <LI><A HREF="#10_85_4">Example</A></LI>
 936 <LI><A HREF="#10_85_5">See Also</A></LI>
 937 </UL>
 938 <LI><A HREF="#ppdConflicts">ppdConflicts()</A></LI>
 939 <UL>
 940 <LI><A HREF="#10_86_1">Usage</A></LI>
 941 <LI><A HREF="#10_86_2">Arguments</A></LI>
 942 <LI><A HREF="#10_86_3">Returns</A></LI>
 943 <LI><A HREF="#10_86_4">Description</A></LI>
 944 <LI><A HREF="#10_86_5">Example</A></LI>
 945 <LI><A HREF="#10_86_6">See Also</A></LI>
 946 </UL>
 947 <LI><A HREF="#ppdEmit">ppdEmit()</A></LI>
 948 <UL>
 949 <LI><A HREF="#10_87_1">Usage</A></LI>
 950 <LI><A HREF="#10_87_2">Arguments</A></LI>
 951 <LI><A HREF="#10_87_3">Returns</A></LI>
 952 <LI><A HREF="#10_87_4">Description</A></LI>
 953 <LI><A HREF="#10_87_5">Example</A></LI>
 954 <LI><A HREF="#10_87_6">See Also</A></LI>
 955 </UL>
 956 <LI><A HREF="#ppdEmitFd">ppdEmitFd()</A></LI>
 957 <UL>
 958 <LI><A HREF="#10_88_1">Usage</A></LI>
 959 <LI><A HREF="#10_88_2">Arguments</A></LI>
 960 <LI><A HREF="#10_88_3">Returns</A></LI>
 961 <LI><A HREF="#10_88_4">Description</A></LI>
 962 <LI><A HREF="#10_88_5">Example</A></LI>
 963 <LI><A HREF="#10_88_6">See Also</A></LI>
 964 </UL>
 965 <LI><A HREF="#ppdFindChoice">ppdFindChoice()</A></LI>
 966 <UL>
 967 <LI><A HREF="#10_89_1">Usage</A></LI>
 968 <LI><A HREF="#10_89_2">Arguments</A></LI>
 969 <LI><A HREF="#10_89_3">Returns</A></LI>
 970 <LI><A HREF="#10_89_4">Description</A></LI>
 971 <LI><A HREF="#10_89_5">Example</A></LI>
 972 <LI><A HREF="#10_89_6">See Also</A></LI>
 973 </UL>
 974 <LI><A HREF="#ppdFindMarkedChoice">ppdFindMarkedChoice()</A></LI>
 975 <UL>
 976 <LI><A HREF="#10_90_1">Usage</A></LI>
 977 <LI><A HREF="#10_90_2">Arguments</A></LI>
 978 <LI><A HREF="#10_90_3">Returns</A></LI>
 979 <LI><A HREF="#10_90_4">Description</A></LI>
 980 <LI><A HREF="#10_90_5">Example</A></LI>
 981 <LI><A HREF="#10_90_6">See Also</A></LI>
 982 </UL>
 983 <LI><A HREF="#ppdFindOption">ppdFindOption()</A></LI>
 984 <UL>
 985 <LI><A HREF="#10_91_1">Usage</A></LI>
 986 <LI><A HREF="#10_91_2">Arguments</A></LI>
 987 <LI><A HREF="#10_91_3">Returns</A></LI>
 988 <LI><A HREF="#10_91_4">Description</A></LI>
 989 <LI><A HREF="#10_91_5">Example</A></LI>
 990 <LI><A HREF="#10_91_6">See Also</A></LI>
 991 </UL>
 992 <LI><A HREF="#ppdIsMarked">ppdIsMarked()</A></LI>
 993 <UL>
 994 <LI><A HREF="#10_92_1">Usage</A></LI>
 995 <LI><A HREF="#10_92_2">Arguments</A></LI>
 996 <LI><A HREF="#10_92_3">Returns</A></LI>
 997 <LI><A HREF="#10_92_4">Description</A></LI>
 998 <LI><A HREF="#10_92_5">Example</A></LI>
 999 <LI><A HREF="#10_92_6">See Also</A></LI>
1000 </UL>
1001 <LI><A HREF="#ppdMarkDefaults">ppdMarkDefaults()</A></LI>
1002 <UL>
1003 <LI><A HREF="#10_93_1">Usage</A></LI>
1004 <LI><A HREF="#10_93_2">Arguments</A></LI>
1005 <LI><A HREF="#10_93_3">Description</A></LI>
1006 <LI><A HREF="#10_93_4">Example</A></LI>
1007 <LI><A HREF="#10_93_5">See Also</A></LI>
1008 </UL>
1009 <LI><A HREF="#ppdMarkOption">ppdMarkOption()</A></LI>
1010 <UL>
1011 <LI><A HREF="#10_94_1">Usage</A></LI>
1012 <LI><A HREF="#10_94_2">Arguments</A></LI>
1013 <LI><A HREF="#10_94_3">Returns</A></LI>
1014 <LI><A HREF="#10_94_4">Description</A></LI>
1015 <LI><A HREF="#10_94_5">Example</A></LI>
1016 <LI><A HREF="#10_94_6">See Also</A></LI>
1017 </UL>
1018 <LI><A HREF="#ppdOpen">ppdOpen()</A></LI>
1019 <UL>
1020 <LI><A HREF="#10_95_1">Usage</A></LI>
1021 <LI><A HREF="#10_95_2">Arguments</A></LI>
1022 <LI><A HREF="#10_95_3">Returns</A></LI>
1023 <LI><A HREF="#10_95_4">Description</A></LI>
1024 <LI><A HREF="#10_95_5">Example</A></LI>
1025 <LI><A HREF="#10_95_6">See Also</A></LI>
1026 </UL>
1027 <LI><A HREF="#ppdOpenFd">ppdOpenFd()</A></LI>
1028 <UL>
1029 <LI><A HREF="#10_96_1">Usage</A></LI>
1030 <LI><A HREF="#10_96_2">Arguments</A></LI>
1031 <LI><A HREF="#10_96_3">Returns</A></LI>
1032 <LI><A HREF="#10_96_4">Description</A></LI>
1033 <LI><A HREF="#10_96_5">Example</A></LI>
1034 <LI><A HREF="#10_96_6">See Also</A></LI>
1035 </UL>
1036 <LI><A HREF="#ppdOpenFile">ppdOpenFile()</A></LI>
1037 <UL>
1038 <LI><A HREF="#10_97_1">Usage</A></LI>
1039 <LI><A HREF="#10_97_2">Arguments</A></LI>
1040 <LI><A HREF="#10_97_3">Returns</A></LI>
1041 <LI><A HREF="#10_97_4">Description</A></LI>
1042 <LI><A HREF="#10_97_5">Example</A></LI>
1043 <LI><A HREF="#10_97_6">See Also</A></LI>
1044 </UL>
1045 <LI><A HREF="#ppdPageLength">ppdPageLength()</A></LI>
1046 <UL>
1047 <LI><A HREF="#10_98_1">Usage</A></LI>
1048 <LI><A HREF="#10_98_2">Arguments</A></LI>
1049 <LI><A HREF="#10_98_3">Returns</A></LI>
1050 <LI><A HREF="#10_98_4">Description</A></LI>
1051 <LI><A HREF="#10_98_5">Example</A></LI>
1052 <LI><A HREF="#10_98_6">See Also</A></LI>
1053 </UL>
1054 <LI><A HREF="#ppdPageSize">ppdPageSize()</A></LI>
1055 <UL>
1056 <LI><A HREF="#10_99_1">Usage</A></LI>
1057 <LI><A HREF="#10_99_2">Arguments</A></LI>
1058 <LI><A HREF="#10_99_3">Returns</A></LI>
1059 <LI><A HREF="#10_99_4">Description</A></LI>
1060 <LI><A HREF="#10_99_5">Example</A></LI>
1061 <LI><A HREF="#10_99_6">See Also</A></LI>
1062 </UL>
1063 <LI><A HREF="#ppdPageWidth">ppdPageWidth()</A></LI>
1064 <UL>
1065 <LI><A HREF="#10_100_1">Usage</A></LI>
1066 <LI><A HREF="#10_100_2">Arguments</A></LI>
1067 <LI><A HREF="#10_100_3">Returns</A></LI>
1068 <LI><A HREF="#10_100_4">Description</A></LI>
1069 <LI><A HREF="#10_100_5">Example</A></LI>
1070 <LI><A HREF="#10_100_6">See Also</A></LI>
1071 </UL>
1072 </UL>
1073 <HR>
1074 <H1 ALIGN="RIGHT"><A NAME="1">Preface</A></H1>
1075 <P>This software programmers manual provides software programming
1076  information for the Common UNIX Printing System (&quot;CUPS&quot;) Version
1077  1.1.13.</P>
1078 <H2><A NAME="1_1">System Overview</A></H2>
1079 <P>CUPS provides a portable printing layer for UNIX&reg;-based operating
1080  systems. It has been developed by<A HREF="http://www.easysw.com"> Easy
1081  Software Products</A> to promote a standard printing solution for all
1082  UNIX vendors and users. CUPS provides the System V and Berkeley
1083  command-line interfaces.</P>
1084 <P>CUPS uses the Internet Printing Protocol (&quot;IPP&quot;) as the basis for
1085  managing print jobs and queues. The Line Printer Daemon (&quot;LPD&quot;) Server
1086  Message Block (&quot;SMB&quot;), and AppSocket (a.k.a. JetDirect) protocols are
1087  also supported with reduced functionality. CUPS adds network printer
1088  browsing and PostScript Printer Description (&quot;PPD&quot;) based printing
1089  options to support real-world printing under UNIX.</P>
1090 <P>CUPS also includes a customized version of GNU Ghostscript (currently
1091  based off GNU Ghostscript 5.50) and an image file RIP that are used to
1092  support non-PostScript printers. Sample drivers for HP and EPSON
1093  printers are included that use these filters.</P>
1094
1095 <!-- NEED 2in -->
1096 <H2><A NAME="1_2">Document Overview</A></H2>
1097 <P>This software programmers manual is organized into the following
1098  sections:</P>
1099 <UL>
1100 <LI><A HREF="#OVERVIEW">1 - Printing System Overview</A></LI>
1101 <LI><A HREF="#CUPS_API">2 - The CUPS API</A></LI>
1102 <LI><A HREF="#WRITING_FILTERS">3 - Writing Filters</A></LI>
1103 <LI><A HREF="#WRITING_DRIVERS">4 - Writing Printer Drivers</A></LI>
1104 <LI><A HREF="#WRITING_BACKENDS">5 - Writing Backends</A></LI>
1105 <LI><A HREF="#LICENSE">A - Software License Agreement</A></LI>
1106 <LI><A HREF="#CONSTANTS">B - Constants</A></LI>
1107 <LI><A HREF="#STRUCTURES">C - Structures</A></LI>
1108 <LI><A HREF="#FUNCTIONS">D - Functions</A></LI>
1109 </UL>
1110 <H2><A NAME="1_3">Notation Conventions</A></H2>
1111 <P>Various font and syntax conventions are used in this guide. Examples
1112  and their meanings and uses are explained below:
1113 <CENTER>
1114 <TABLE WIDTH="80%">
1115 <TR><TH>Example</TH><TD>&nbsp;&nbsp;&nbsp;</TD><TH>Description</TH></TR>
1116 <TR><TD>&nbsp;</TD></TR>
1117 <TR VALIGN="TOP"><TD><CODE>lpstat</CODE>
1118 <BR> <CODE>lpstat(1)</CODE></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>The names of commands;
1119  the first mention of a command or function in a chapter is followed by
1120  a manual page section number.</TD></TR>
1121 <TR><TD>&nbsp;</TD></TR>
1122 <TR VALIGN="TOP"><TD><VAR>/var</VAR>
1123 <BR><VAR> /usr/share/cups/data/testprint.ps</VAR></TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>
1124 File and directory names.</TD></TR>
1125 <TR><TD>&nbsp;</TD></TR>
1126 <TR VALIGN="TOP"><TD NOWRAP><TT>Request ID is Printer-123</TT></TD><TD>
1127 &nbsp;&nbsp;&nbsp;</TD><TD>Screen output.</TD></TR>
1128 <TR><TD>&nbsp;</TD></TR>
1129 <TR VALIGN="TOP"><TD NOWRAP><KBD>lp -d printer filename ENTER</KBD></TD><TD>
1130 &nbsp;&nbsp;&nbsp;</TD><TD>Literal user input; special keys like <KBD>ENTER</KBD> are
1131  in ALL CAPS.</TD></TR>
1132 <TR><TD>&nbsp;</TD></TR>
1133 <TR VALIGN="TOP"><TD>12.3</TD><TD>&nbsp;&nbsp;&nbsp;</TD><TD>Numbers in the text are
1134  written using the period (.) to indicate the decimal point.</TD></TR>
1135 </TABLE>
1136 </CENTER>
1137
1138 <!-- NEED 3in -->
1139 </P>
1140 <H2><A NAME="1_4">Abbreviations</A></H2>
1141  The following abbreviations are used throughout this manual:
1142 <UL>
1143 <DL>
1144 <DT>kb</DT>
1145 <DD>Kilobytes, or 1024 bytes
1146 <BR>&nbsp;</DD>
1147 <DT>Mb</DT>
1148 <DD>Megabytes, or 1048576 bytes
1149 <BR>&nbsp;</DD>
1150 <DT>Gb</DT>
1151 <DD>Gigabytes, or 1073741824 bytes
1152 <BR>&nbsp;</DD>
1153 </DL>
1154 </UL>
1155 <H2><A NAME="1_5">Other References</A></H2>
1156 <UL>
1157 <DL>
1158 <DT>CUPS Software Administrators Manual</DT>
1159 <DD>An administration guide for the CUPS software.
1160 <BR>&nbsp;</DD>
1161 <DT>CUPS Software Users Manual</DT>
1162 <DD>An end-user guide for using the CUPS software.
1163 <BR>&nbsp;</DD>
1164 </DL>
1165 </UL>
1166 <H1 ALIGN="RIGHT"><A NAME="OVERVIEW">1 - Printing System Overview</A></H1>
1167 <P>This chapter provides an overview of how the Common UNIX Printing
1168  System works.</P>
1169 <H2><A NAME="2_1">The Printing Problem</A></H2>
1170 <P>For years<I> the printing problem</I> has plagued UNIX. Unlike
1171  Microsoft&reg; Windows&reg; or Mac OS, UNIX has no standard interface or system
1172  in place for supporting printers. Among the solutions currently
1173  available, the Berkeley and System V printing systems are the most
1174  prevalent.</P>
1175 <P>These printing systems support line printers (text only) or
1176  PostScript printers (text and graphics), and with some coaxing they can
1177  be made to support a full range of printers and file formats. However,
1178  because each varient of the UNIX operating system uses a different
1179  printing system than the next developing printer drivers for a wide
1180  range of printers and operating systems is extremely difficult. That
1181  combined with the limited volume of customers for each UNIX varient has
1182  forced most printer vendors to give up supporting UNIX entirely.</P>
1183 <P>CUPS is designed to eliminate<I> the printing problem</I>. One common
1184  printing system can be used by all UNIX varients to support the
1185  printing needs of users. Printer vendors can use its modular filter
1186  interface to develop a single driver program that supports a wide range
1187  of file formats with little or no effort. Since CUPS provides both the
1188  System V and Berkeley printing commands, users (and applications) can
1189  reap the benefits of this new technology with no changes.</P>
1190 <H2><A NAME="2_2">The Technology</A></H2>
1191 <P>CUPS is based upon an emerging Internet standard called the Internet
1192  Printing Protocol. IPP has been embraced by dozens of printer and
1193  printer server manufacturers and is supported by Microsoft Windows
1194  2000.</P>
1195 <P>IPP defines a standard protocol for printing as well as managing
1196  print jobs and printer options like media size, resolution, and so
1197  forth. Like all IP-based protocols, IPP can be used locally or over the
1198  Internet to printers hundreds or thousands of miles away. Unlike other
1199  protocols, however, IPP also supports access control, authentication,
1200  and encryption, making it a much more capable and secure printing
1201  solution than older ones.</P>
1202 <P>IPP is layered on top of the Hyper-Text Transport Protocol (&quot;HTTP&quot;)
1203  which is the basis of web servers on the Internet. This allows users to
1204  view documentation, check status information on a printer or server,
1205  and manage their printers, classes, and jobs using their web browser.</P>
1206 <P>CUPS provides a complete IPP/1.1 based printing system that provides
1207  Basic, Digest, and local certificate authentication and user, domain,
1208  or IP-based access control. TLS encryption will be available in future
1209  versions of CUPS.</P>
1210 <H2><A NAME="2_3">Jobs</A></H2>
1211 <P>Each file or set of files that is submitted for printing is called a<I>
1212  job</I>. Jobs are identified by a unique number starting at 1 and are
1213  assigned to a particular destination, usually a printer. Jobs can also
1214  have options associated with them such as media size, number of copies,
1215  and priority.</P>
1216 <H2><A NAME="2_4">Classes</A></H2>
1217 <P>CUPS supports collections of printers known as<I> classes</I>. Jobs
1218  sent to a class are forwarded to the first available printer in the
1219  class.</P>
1220 <H2><A NAME="2_5">Filters</A></H2>
1221 <P>Filters allow a user or application to print many types of files
1222  without extra effort. Print jobs sent to a CUPS server are filtered
1223  before sending them to a printer. Some filters convert job files to
1224  different formats that the printer can understand. Others perform page
1225  selection and ordering tasks.</P>
1226 <P>CUPS provides filters for printing many types of image files, HP-GL/2
1227  files, PDF files, and text files. CUPS also supplies PostScript and
1228  image file Raster Image Processor (&quot;RIP&quot;) filters that convert
1229  PostScript or image files into bitmaps that can be sent to a raster
1230  printer.</P>
1231 <H2><A NAME="2_6">Backends</A></H2>
1232 <P>Backends perform the most important task of all - they send the
1233  filtered print data to the printer.</P>
1234 <P>CUPS provides backends for printing over parallel, serial, and USB
1235  ports, and over the network via the IPP, JetDirect (AppSocket), and
1236  Line Printer Daemon (&quot;LPD&quot;) protocols. Additional backends are
1237  available in network service packages such as the SMB backend included
1238  with the popular SAMBA software.</P>
1239 <P>Backends are also used to determine the available devices. On startup
1240  each backend is asked for a list of devices it supports, and any
1241  information that is available. This allows the parallel backend to tell
1242  CUPS that an EPSON Stylus Color 600 printer is attached to parallel
1243  port 1, for example.</P>
1244 <H2><A NAME="2_7">Printer Drivers</A></H2>
1245 <P>Printer drivers in CUPS consist of one of more filters specific to a
1246  printer. CUPS includes sample printer drivers for Hewlett-Packard
1247  LaserJet and DeskJet printers and EPSON 9-pin, 24-pin, Stylus Color,
1248  and Stylus Photo printers. While these drivers do not generate optimal
1249  output for the different printer models, they do provide basic printing
1250  and demonstrate how you can write your own printer drivers and
1251  incorporate them into CUPS.</P>
1252 <H2><A NAME="2_8">Networking</A></H2>
1253 <P>Printers and classes on the local system are automatically shared
1254  with other systems on the network. This allows you to setup one system
1255  to print to a printer and use this system as a printer server or spool
1256  host for all of the others. Users may then select a local printer by
1257  name or a remote printer using &quot;name@server&quot;.</P>
1258 <P>CUPS also provides<I> implicit classes</I>, which are collections of
1259  printers and/or classes with the same name. This allows you to setup
1260  multiple servers pointing to the same physical network printer, for
1261  example, so that you aren't relying on a single system for printing.
1262  Because this also works with printer classes, you can setup multiple
1263  servers and printers and never worry about a single point of failure
1264  unless all of the printers and servers go down!</P>
1265 <H1 ALIGN="RIGHT"><A NAME="CUPS_API">2 - The CUPS API</A></H1>
1266 <P>This chapter describes the CUPS Application Programmers Interface
1267  (&quot;API&quot;).</P>
1268 <H2><A NAME="3_1">The CUPS API Library</A></H2>
1269 <P>The CUPS library provides a whole collection of interfaces needed to
1270  support the internal needs of the CUPS software as well as the needs of
1271  applications, filters, printer drivers, and backends.</P>
1272 <P>Unlike the rest of CUPS, the CUPS API library is provided under the
1273  GNU Library General Public License. This means that you can use the
1274  CUPS API library in both proprietary and open-source programs.</P>
1275 <P>Programs that use the CUPS API library typically will include the <CODE>
1276 &lt;cups/cups.h&gt;</CODE> header file:</P>
1277 <UL>
1278 <PRE>
1279 #include &lt;cups/cups.h&gt;
1280
1281 ...
1282
1283 jobid = cupsPrintFile(&quot;myprinter&quot;, &quot;filename.ps&quot;, &quot;title&quot;,
1284                       num_options, options);
1285 </PRE>
1286 </UL>
1287 <P>Use the <CODE>-lcups</CODE> compiler option when linking to the CUPS
1288  API library:</P>
1289 <UL>
1290 <PRE>
1291 <B>cc -o program program.c -lcups ENTER</B>
1292 </PRE>
1293 </UL>
1294 <P>Additional options and libraries may be required depending on the
1295  operating system and the location of the CUPS API library.</P>
1296 <H3><A NAME="3_1_1">Detecting the CUPS API Library in GNU Autoconf</A></H3>
1297 <P>GNU autoconf is a popular configuration tool used by many programs.
1298  Add the following lines to your<VAR> configure.in file to check for the
1299  CUPS API library in your configuration script:</VAR></P>
1300 <UL>
1301 <PRE>
1302 AC_CHECK_LIB(socket,socket,
1303 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1304         LIBS=&quot;-lsocket $LIBS&quot;
1305 else
1306         echo &quot;Not using -lsocket since you are running IRIX.&quot;
1307 fi)
1308 AC_CHECK_LIB(nsl,gethostbyaddr,
1309 if test &quot;$uname&quot; != &quot;IRIX&quot;; then
1310         LIBS=&quot;-lnsl $LIBS&quot;
1311 else
1312         echo &quot;Not using -lnsl since you are running IRIX.&quot;
1313 fi)
1314
1315 AC_CHECK_LIB(cups,httpConnect)
1316 </PRE>
1317 </UL>
1318 <H2><A NAME="3_2">Printing Services</A></H2>
1319 <P>The CUPS API library provides some basic printing services for
1320  applications that need to print files.</P>
1321 <H3><A NAME="3_2_1">Include Files</A></H3>
1322 <P>The include file used by all of these functions is <CODE>
1323 &lt;cups/cups.h&gt;</CODE>:</P>
1324 <UL>
1325 <PRE>
1326 #include &lt;cups/cups.h&gt;
1327 </PRE>
1328 </UL>
1329 <H3><A NAME="3_2_2">Printing a File</A></H3>
1330 <P>The CUPS API provides two functions for printing files. The first is <CODE>
1331 cupsPrintFile</CODE> which prints a single named file:</P>
1332 <UL>
1333 <PRE>
1334 #include &lt;cups/cups.h&gt;
1335
1336 ...
1337
1338 int jobid;
1339
1340 ...
1341
1342 jobid = cupsPrintFile(&quot;<I>name</I>&quot;, &quot;<I>filename</I>&quot;, &quot;<I>title</I>&quot;, 0, NULL);
1343 </PRE>
1344 </UL>
1345 <P>The <CODE>name</CODE> string is the name of the printer or class to
1346  print to. The <CODE>filename</CODE> string is the name of the file to
1347  print. The <CODE>title</CODE> string is the name of the print job, e.g.
1348  &quot;Acme Word Document&quot;.</P>
1349 <P>The return value is a unique ID number for the print job or 0 if
1350  there was an error.</P>
1351 <H3><A NAME="3_2_3">Printing Multiple Files</A></H3>
1352 <P>The second printing function is <CODE>cupsPrintFiles</CODE>:</P>
1353 <UL>
1354 <PRE>
1355 #include &lt;cups/cups.h&gt;
1356
1357 ...
1358
1359 int        jobid;
1360 int        num_files;
1361 const char *files[100];
1362 ...
1363
1364 jobid = cupsPrintFiles(&quot;name&quot;, <I>num_files</I>, <I>files</I>, &quot;title&quot;, 0, NULL);
1365 </PRE>
1366 </UL>
1367 <P>Instead of passing a filename string as with <CODE>cupsPrintFile()</CODE>
1368 , you pass a file count (<CODE>num_files</CODE>) and filename pointer
1369  array (<CODE>files</CODE>) for each file that you want to print.</P>
1370 <P>As with <CODE>cupsPrintFile()</CODE>, the return value is a unique ID
1371  for the print job.</P>
1372 <H3><A NAME="3_2_4">Cancelling Jobs</A></H3>
1373 <P>The <CODE>cupsCancelJob()</CODE> function cancels a queued print job:</P>
1374 <UL>
1375 <PRE>
1376 #include &lt;cups/cups.h&gt;
1377
1378 ...
1379
1380 int jobid;
1381 int status;
1382 ...
1383
1384 status = cupsCancelJob(&quot;<I>name</I>&quot;, <I>jobid</I>);
1385 </PRE>
1386 </UL>
1387 <P>The <CODE>name</CODE> string specifies the destination and is used to
1388  determine the server to send the request to. The <CODE>jobid</CODE>
1389  value is the integer returned from a previous <CODE>cupsPrintFile()</CODE>
1390  or <CODE>cupsPrintFiles()</CODE> call.</P>
1391 <P><CODE>cupsCancelJob()</CODE> returns <CODE>1</CODE> if the job was
1392  successfully cancelled and <CODE>0</CODE> if there was an error.</P>
1393 <H3><A NAME="3_2_5">Getting the Available Printers and Classes</A></H3>
1394 <P>The <CODE>cupsGetDests()</CODE> function can be used to get a list of
1395  the available printers, classes, and instances that a user has defined:</P>
1396 <UL>
1397 <PRE>
1398 #include &lt;cups/cups.h&gt;
1399
1400 ...
1401
1402 int         num_dests;
1403 cups_dest_t *dests;
1404
1405 ...
1406
1407 num_dests = cupsGetDests(&amp;dests);
1408 </PRE>
1409 </UL>
1410 <P>Each destination is stored in a <CODE>cups_dest_t</CODE> structure
1411  which defines the printer or class name, the instance name (if any), if
1412  it is the default destination, and the default options the user has
1413  defined for the destination:</P>
1414 <UL>
1415 <PRE>
1416 typedef struct               /**** Destination ****/
1417 {
1418   char          *name,       /* Printer or class name */
1419                 *instance;   /* Local instance name or NULL */
1420   int           is_default;  /* Is this printer the default? */
1421   int           num_options; /* Number of options */
1422   cups_option_t *options;    /* Options */
1423 } cups_dest_t;
1424 </PRE>
1425 </UL>
1426 <P>The destinations are sorted by name and instance for your
1427  convenience. Once you have the list of available destinations, you can
1428  lookup a specific destination using the <CODE>cupsGetDest()</CODE>
1429  function:</P>
1430 <UL>
1431 <PRE>
1432 #include &lt;cups/cups.h&gt;
1433
1434 ...
1435
1436 int         num_dests;
1437 cups_dest_t *dests;
1438 cups_dest_t *mydest;
1439
1440 ...
1441
1442 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1443 </PRE>
1444 </UL>
1445 <P>The <CODE>name</CODE> string is the printer or class name. You can
1446  pass a value of <CODE>NULL</CODE> to get the default destination.</P>
1447 <P>The <CODE>instance</CODE> string is the user-defined instance name.
1448  Pass <CODE>NULL</CODE> to select the default instance, e.g. &quot;name&quot;
1449  instead of &quot;name/instance&quot;.</P>
1450 <H3><A NAME="3_2_6">Printing with Options</A></H3>
1451 <P>All of the previous printing examples have passed <CODE>0</CODE> and <CODE>
1452 NULL</CODE> for the last two arguments to the <CODE>cupsPrintFile()</CODE>
1453  and <CODE>cupsPrintFiles()</CODE> functions. These last two arguments
1454  are the number of options and a pointer to the option array:</P>
1455 <UL>
1456 <PRE>
1457 int cupsPrintFile(const char *name, const char *filename, const char *title,
1458                   int num_options, cups_option_t *options);
1459 int cupsPrintFiles(const char *name, int num_files, const char **files,
1460                    const char *title, int num_options,
1461                    cups_option_t *options);
1462 </PRE>
1463 </UL>
1464 <P>The <CODE>cups_option_t</CODE> structure holds each option and its
1465  value. These are converted as needed and passed to the CUPS server when
1466  printing a file.</P>
1467 <P>The simplest way of handling options is to use the <CODE>num_options</CODE>
1468  and <CODE>options</CODE> members of the <CODE>cups_dest_t</CODE>
1469  structure described earlier:</P>
1470 <UL>
1471 <PRE>
1472 #include &lt;cups/cups.h&gt;
1473
1474 ...
1475
1476 int         jobid;
1477 int         num_dests;
1478 cups_dest_t *dests;
1479 cups_dest_t *mydest;
1480
1481 ...
1482
1483 mydest = cupsGetDest(&quot;<I>name</I>&quot;, &quot;<I>instance</I>&quot;, num_dests, dests);
1484
1485 jobid  = cupsPrintFile(mydest-&gt;name, &quot;filename&quot;, &quot;title&quot;,
1486                        mydest-&gt;num_options, mydest-&gt;options);
1487 </PRE>
1488 </UL>
1489 <P>This effectively uses the options a user has previous selected
1490  without a lot of code.</P>
1491 <H3><A NAME="3_2_7">Setting Printer Options</A></H3>
1492 <P>Options can also be set by your program using the <CODE>
1493 cupsAddOption()</CODE> function:</P>
1494 <UL>
1495 <PRE>
1496 #include &lt;cups/cups.h&gt;
1497
1498 ...
1499
1500 int           num_options;
1501 cups_option_t *options;
1502
1503 ...
1504
1505 num_options = 0;
1506 options     = NULL;
1507
1508 ...
1509
1510 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1511 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1512 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1513 num_options = cupsAddOption(&quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;, num_options, &amp;options);
1514 </PRE>
1515 </UL>
1516 <P>The <CODE>name</CODE> string is the name of the option, and the <CODE>
1517 value</CODE> string is the value for that option.</P>
1518 <P>Each call to <CODE>cupsAddOption()</CODE> returns the new number of
1519  options. Since adding two options with the same name overwrites the
1520  first value with the second, do not assume that calling <CODE>
1521 cupsAddOptions()</CODE> 20 times will result in 20 options.</P>
1522 <P>Call <CODE>cupsFreeOptions</CODE> once you are done using the
1523  options:</P>
1524 <UL>
1525 <PRE>
1526 #include &lt;cups/cups.h&gt;
1527
1528 ...
1529
1530 int           num_options;
1531 cups_option_t *options;
1532
1533 ...
1534
1535 cupsFreeOptions(num_options, options);
1536 </PRE>
1537 </UL>
1538 <H3><A NAME="3_2_8">Getting Errors</A></H3>
1539 <P>If any of the CUPS API printing functions returns an error, the
1540  reason for that error can be found by calling <CODE>cupsLastError()</CODE>
1541  and <CODE>cupsErrorString()</CODE>. <CODE>cupsLastError()</CODE>
1542  returns the last IPP error code that was encountered. <CODE>
1543 cupsErrorString()</CODE> converts the error code to a localized message
1544  string suitable for presentation to the user:</P>
1545 <UL>
1546 <PRE>
1547 #include &lt;cups/cups.h&gt;
1548
1549 ...
1550
1551 int jobid;
1552
1553 ...
1554
1555 if (jobid == 0)
1556   puts(cupsErrorString(cupsLastError()));
1557 </PRE>
1558 </UL>
1559 <H3><A NAME="3_2_9">Passwords and Authentication</A></H3>
1560 <P>CUPS supports authentication of any request, including submission of
1561  print jobs. The default mechanism for getting the username and password
1562  is to use the login user and a password from the console.</P>
1563 <P>To support other types of applications, in particular Graphical User
1564  Interfaces (&quot;GUIs&quot;), the CUPS API provides functions to set the default
1565  username and to register a callback function that returns a password
1566  string.</P>
1567 <P>The<A HREF="cupsSetPasswordCB"> <CODE>cupsSetPasswordCB()</CODE></A>
1568  function is used to set a password callback in your program. Only one
1569  function can be used at any time.</P>
1570 <P>The<A HREF="cupsSetUser"> <CODE>cupsSetUser()</CODE></A> function
1571  sets the current username for authentication. This function can be
1572  called by your password callback function to change the current
1573  username as needed.</P>
1574 <P>The following example shows a simple password callback that gets a
1575  username and password from the user:</P>
1576 <UL>
1577 <PRE>
1578 #include &lt;cups/cups.h&gt;
1579
1580 const char *
1581 my_password_cb(const char *prompt)
1582 {
1583   char  user[65];
1584
1585
1586   puts(prompt);
1587
1588  /* Get a username from the user */
1589   printf(&quot;Username: &quot;);
1590   if (fgets(user, sizeof(user), stdin) == NULL)
1591     return (NULL);
1592
1593  /* Strip the newline from the string and set the user */
1594   user[strlen(user) - 1] = '\0';
1595
1596   cupsSetUser(user);
1597
1598  /* Use getpass() to ask for the password... */
1599   return (getpass(&quot;Password: &quot;));
1600 }
1601
1602 ...
1603
1604 cupsSetPasswordCB(my_password_cb);
1605 </PRE>
1606 </UL>
1607 <P>Similarly, a GUI interface could display the prompt string in a
1608  window with input fields for the username and password. The username
1609  should probably default to the value of<A HREF="#cupsUser"> <CODE>
1610 cupsUser()</CODE></A> to make things easier on the user.</P>
1611 <H2><A NAME="3_3">PPD Services</A></H2>
1612 <P>CUPS includes functions to access and manipulate PostScript Printer
1613  Description (&quot;PPD&quot;) files that are used with the printer drivers in
1614  CUPS.</P>
1615 <P>Each PPD file enumerates the available features provided by a
1616  printer, including conflict information for specific options (e.g.
1617  can't duplex output on envelopes.)</P>
1618 <H3><A NAME="3_3_1">Include Files</A></H3>
1619 <P>Include the <CODE>&lt;cups/ppd.h&gt;</CODE> header file to use the PPD
1620  functions:</P>
1621 <UL>
1622 <PRE>
1623 #include &lt;cups/ppd.h&gt;
1624 </PRE>
1625 </UL>
1626 <P>This header file is also included by the <CODE>&lt;cups/cups.h&gt;</CODE>
1627  header file.</P>
1628 <H3><A NAME="3_3_2">Getting a PPD File for a Printer</A></H3>
1629 <P>The <CODE>cupsGetPPD()</CODE> function retrieves the PPD file for the
1630  named printer or class:</P>
1631 <UL>
1632 <PRE>
1633 #include &lt;cups/cups.h&gt;
1634
1635 ...
1636
1637 const char *filename;
1638
1639 filename = cupsGetPPD(&quot;<I>name</I>&quot;);
1640 </PRE>
1641 </UL>
1642 <P>The <CODE>name</CODE> string is the name of the printer or class,
1643  including the remote server name as appropriate (e.g.
1644  &quot;printer@server&quot;.)</P>
1645 <P>The return value is a pointer to a filename in static storage; this
1646  value is overwritten with each call to <CODE>cupsGetPPD()</CODE>. If
1647  the printer or class does not exist, a <CODE>NULL</CODE> pointer will
1648  be returned.</P>
1649 <H3><A NAME="3_3_3">Loading a PPD File</A></H3>
1650 <P>The <CODE>ppdOpenFile()</CODE> function &quot;opens&quot; a PPD file and loads
1651  it into memory:</P>
1652 <UL>
1653 <PRE>
1654 #include &lt;cups/ppd.h&gt;
1655
1656 ...
1657
1658 ppd_file_t *ppd;
1659
1660 ppd = ppdOpenFile(&quot;<I>filename</I>&quot;);
1661 </PRE>
1662 </UL>
1663 <P>The <CODE>filename</CODE> string is the name of the file to load,
1664  such as the value returned by the <CODE>cupsGetPPD()</CODE> function.</P>
1665 <P>The return value is a pointer to a structure describing the contents
1666  of the PPD file or NULL if the PPD file could not be read.</P>
1667 <H3><A NAME="3_3_4">Freeing PPD File Information</A></H3>
1668 <P>Once you are done using a PPD file, call the <CODE>ppdClose()</CODE>
1669  function to free all memory that has been used:</P>
1670 <UL>
1671 <PRE>
1672 #include &lt;cups/ppd.h&gt;
1673
1674 ...
1675
1676 ppd_file_t *ppd;
1677
1678 ...
1679
1680 ppdClose(ppd);
1681 </PRE>
1682 </UL>
1683 <H3><A NAME="3_3_5">The PPD File Structure</A></H3>
1684 <P>Each PPD file contains a number of capability attributes, printer
1685  options, and conflict definitions. The page size options also include
1686  the physical margins for the printer and the minimum and maximum sizes
1687  for the printer. All of this information is stored in the <CODE>
1688 ppd_file_t</CODE> structure.</P>
1689 <H4>Capabilities</H4>
1690 <P>Each PPD file contains a number of informational attributes that
1691  describe the capabilities of the printer. These are provided in the <CODE>
1692 ppd_file_t</CODE> structure in the following members:
1693 <CENTER>
1694 <TABLE BORDER="1" WIDTH="80%">
1695 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
1696 <TR><TD><CODE>accurate_screens</CODE></TD><TD><CODE>int</CODE></TD><TD>1
1697  = supports accurate screens</TD></TR>
1698 <TR><TD><CODE>color_device</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1699  color device</TD></TR>
1700 <TR><TD><CODE>colorspace</CODE></TD><TD><CODE>ppd_cs_t</CODE></TD><TD>
1701 Default colorspace: PPD_CS_CMYK, PPD_CS_CMY, PPD_CS_GRAY, PPD_CS_RGB,
1702  PPD_CS_RGBK, PPD_CS_N</TD></TR>
1703 <TR><TD><CODE>contone_only</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1704  printer is continuous tone only</TD></TR>
1705 <TR><TD><CODE>num_emulations
1706 <BR> emulations</CODE></TD><TD><CODE>int
1707 <BR> ppd_emul_t *</CODE></TD><TD>Emulations supported by the printer</TD>
1708 </TR>
1709 <TR><TD><CODE>flip_duplex</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1710  need to flip odd pages when duplexing</TD></TR>
1711 <TR><TD><CODE>num_fonts
1712 <BR> fonts</CODE></TD><TD><CODE>int
1713 <BR> char **</CODE></TD><TD>The fonts available on the printer.</TD></TR>
1714 <TR><TD><CODE>jcl_begin
1715 <BR> jcl_ps
1716 <BR> jcl_end</CODE></TD><TD><CODE>char *</CODE></TD><TD>Job Control
1717  Language commands for PostScript output</TD></TR>
1718 <TR><TD><CODE>landscape</CODE></TD><TD><CODE>int</CODE></TD><TD>
1719 Landscape orientation, -90 or 90 degrees</TD></TR>
1720 <TR><TD><CODE>lang_encoding</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1721 The character used for the option strings</TD></TR>
1722 <TR><TD><CODE>lang_version</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1723 The language used for the options strings (English, French, etc.)</TD></TR>
1724 <TR><TD><CODE>language_level</CODE></TD><TD><CODE>int</CODE></TD><TD>
1725 PostScript language level, 1 to 3</TD></TR>
1726 <TR><TD><CODE>manual_copies</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1727  Copies are done manually</TD></TR>
1728 <TR><TD><CODE>model_number</CODE></TD><TD><CODE>int</CODE></TD><TD>
1729 Driver-specific model number.</TD></TR>
1730 <TR><TD><CODE>patches</CODE></TD><TD><CODE>char *</CODE></TD><TD>Patch
1731  commands to send to the printer</TD></TR>
1732 <TR><TD><CODE>manufacturer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1733 The Manufacturer attribute from the PPD file, if any</TD></TR>
1734 <TR><TD><CODE>modelname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1735  ModelName attribute from the PPD file</TD></TR>
1736 <TR><TD><CODE>nickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1737  NickName attribute from the PPD file, if any</TD></TR>
1738 <TR><TD><CODE>product</CODE></TD><TD><CODE>char *</CODE></TD><TD>The
1739  Product attribute from the PPD file, if any</TD></TR>
1740 <TR><TD><CODE>shortnickname</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1741 The ShortNickName attribute from the PPD file, if any</TD></TR>
1742 <TR><TD><CODE>throughput</CODE></TD><TD><CODE>int</CODE></TD><TD>Number
1743  of pages per minute</TD></TR>
1744 <TR><TD><CODE>ttrasterizer</CODE></TD><TD><CODE>char *</CODE></TD><TD>
1745 The TruType font rasterizer (Type42)</TD></TR>
1746 <TR><TD><CODE>variable_sizes</CODE></TD><TD><CODE>int</CODE></TD><TD>1 =
1747  supports variable sizes</TD></TR>
1748 </TABLE>
1749 </CENTER>
1750 </P>
1751 <H4>Options and Groups</H4>
1752 <P>PPD files support multiple options, which are stored in <CODE>
1753 ppd_option_t</CODE> and <CODE>ppd_choice_t</CODE> structures by the PPD
1754  functions.</P>
1755 <P>Each option in turn is associated with a group stored in the <CODE>
1756 ppd_group_t</CODE> structure. Groups can be specified in the PPD file;
1757  if an option is not associated with a group then it is put in a
1758  &quot;General&quot; or &quot;Extra&quot; group depending on the option.</P>
1759 <P>Groups can also have sub-groups; CUPS currently limits the depth of
1760  sub-groups to 1 level to reduce programming complexity.</P>
1761 <H4>Conflicts</H4>
1762 <P>PPD files support specification of conflict conditions between
1763  different options. Conflicts are stored in <CODE>ppd_conflict_t</CODE>
1764  structures which specify the options that conflict with each other.</P>
1765 <H4>Page Sizes</H4>
1766 <P>PPD files specify all of the available pages sizes and the physical
1767  margins associated with them. These sizes are stored in <CODE>
1768 ppd_size_t</CODE> structures and are available in the <CODE>num_sizes</CODE>
1769  and <CODE>sizes</CODE> members of the <CODE>ppd_file_t</CODE>
1770  structure. You can lookup a particular page size with the <CODE>
1771 ppdPageWidth()</CODE>, <CODE>ppdPageLength()</CODE>, and <CODE>
1772 ppdPageSize()</CODE> functions:</P>
1773 <UL>
1774 <PRE>
1775 #include &lt;cups/ppd.h&gt;
1776
1777 ...
1778
1779 ppd_file_t *ppd;
1780 ppd_size_t *size;
1781 float      width;
1782 float      length;
1783
1784 ...
1785
1786 size   = ppdPageSize(ppd, &quot;<I>size</I>&quot;);
1787 width  = ppdPageWidth(ppd, &quot;<I>size</I>&quot;);
1788 length = ppdPageLength(ppd, &quot;<I>size</I>&quot;);
1789 </PRE>
1790 </UL>
1791 <P>The <CODE>size</CODE> string is the named page size option. The width
1792  and length are in points; there are 72 points per inch. The <CODE>
1793 ppd_size_t</CODE> structure contains the width, length, and margin
1794  information:</P>
1795 <UL>
1796 <PRE>
1797 typedef struct    /**** Page Sizes ****/
1798 {
1799   int   marked;   /* Page size selected? */
1800   char  name[41]; /* Media size option */
1801   float width,    /* Width of media in points */
1802         length,   /* Length of media in points */
1803         left,     /* Left printable margin in points */
1804         bottom,   /* Bottom printable margin in points */
1805         right,    /* Right printable margin in points */
1806         top;      /* Top printable margin in points */
1807 } ppd_size_t;
1808 </PRE>
1809 </UL>
1810 <H4>Custom Page Sizes</H4>
1811 <P>Besides the standard page sizes listed in a PPD file, some printers
1812  support variable or custom page sizes. If <CODE>variables_sizes</CODE>
1813  is non-zero, the <CODE>custom_min</CODE>, <CODE>custom_max</CODE>, and <CODE>
1814 custom_margins</CODE> members of the <CODE>ppd_file_t</CODE> structure
1815  define the limits of the variable sizes.</P>
1816 <P>To get the resulting media size, use a page size string of <CODE>
1817 Custom.<I>width</I>x<I>length</I></CODE>, where <CODE>width</CODE> and <CODE>
1818 length</CODE> are integer values in points:</P>
1819 <UL>
1820 <PRE>
1821 Custom.612x792   [8.5 inches wide, 11 inches long]
1822 Custom.1224x792  [17 inches wide, 11 inches long]
1823 </PRE>
1824 </UL>
1825 <H3><A NAME="3_3_6">Marking Options</A></H3>
1826 <P>Before marking any user-defined options, call the <CODE>
1827 ppdMarkDefaults()</CODE> function to mark the default options from the
1828  PPD file:</P>
1829 <UL>
1830 <PRE>
1831 #include &lt;cups/ppd.h&gt;
1832
1833 ...
1834
1835 ppd_file_t *ppd;
1836
1837 ...
1838
1839 ppdMarkDefaults(ppd);
1840 </PRE>
1841 </UL>
1842 <P>Then call the <CODE>ppdMarkOption()</CODE> function to mark
1843  individual options:</P>
1844 <UL>
1845 <PRE>
1846 #include &lt;cups/ppd.h&gt;
1847
1848 ...
1849
1850 ppd_file_t *ppd;
1851 int        conflicts;
1852
1853 ...
1854
1855 conflicts = ppdMarkOption(ppd, &quot;<I>name</I>&quot;, &quot;<I>value</I>&quot;);
1856 </PRE>
1857 </UL>
1858 <P>The <CODE>name</CODE> and <CODE>value</CODE> strings choose a
1859  particular option and choice, respectively. The return value is 0 if
1860  there are not conflicts created by the selection.</P>
1861 <P>CUPS also provides a convenience function for marking all options in
1862  the <CODE>cups_option_t</CODE> structure:</P>
1863 <UL>
1864 <PRE>
1865 #include &lt;cups/cups.h&gt;
1866
1867 ...
1868
1869 ppd_file_t    *ppd;
1870 int           num_options;
1871 cups_option_t *options;
1872 int           conflicts;
1873
1874 ...
1875
1876 conflicts = cupsMarkOptions(ppd, num_options, options);
1877 </PRE>
1878 </UL>
1879 <P>The <CODE>cupsMarkOptions()</CODE> function also handles mapping the
1880  IPP job template attributes to PPD options. The return value is the
1881  number of conflicts present.</P>
1882 <H3><A NAME="3_3_7">Checking for Conflicts</A></H3>
1883 <P>The <CODE>ppdMarkOption()</CODE> and <CODE>cupsMarkOptions()</CODE>
1884  functions return the number of conflicts with the currently marked
1885  options.</P>
1886 <P>Call the <CODE>ppdConflicts()</CODE> function to get the number of
1887  conflicts after you have marked all of the options:</P>
1888 <UL>
1889 <PRE>
1890 #include &lt;cups/cups.h&gt;
1891
1892 ...
1893
1894 ppd_file_t *ppd;
1895 int        conflicts;
1896
1897 ...
1898
1899 conflicts = ppdConflicts(ppd);
1900 </PRE>
1901 </UL>
1902 <P>The return value is the number of conflicting options, or 0 if there
1903  are no conflicts.</P>
1904 <H1 ALIGN="RIGHT"><A NAME="WRITING_FILTERS">3 - Writing Filters</A></H1>
1905 <P>This chapter describes how to write a file filter for CUPS.</P>
1906 <H2><A NAME="4_1">Overview</A></H2>
1907 <P>File filters are programs that convert from one or more MIME types to
1908  another type. Filters use a common command-line and environment
1909  interface that allows them to be joined as needed to print files to any
1910  type of printer.</P>
1911 <H3><A NAME="4_1_1">Security Considerations</A></H3>
1912 <P>Filters are normally run as a non-priviledged user, so the major
1913  security consideration is resource utilization - filters should not
1914  depend on unlimited amounts of memory and disk space.</P>
1915 <H3><A NAME="4_1_2">Users and Groups</A></H3>
1916 <P>The default CUPS configuration runs filters as user &quot;lp&quot; and group
1917  &quot;other&quot;.</P>
1918 <H3><A NAME="4_1_3">Temporary Files</A></H3>
1919 <P>Temporary files should be created in the directory specified by the
1920  &quot;TMPDIR&quot; environment variable. The<A HREF="#cupsTempFile"> <CODE>
1921 cupsTempFile()</CODE></A> function can be used to safely choose
1922  temporary files in this directory.</P>
1923 <H3><A NAME="4_1_4">Sending Messages to the User</A></H3>
1924 <P>The CUPS scheduler collects messages sent to the standard error file
1925  by the filter. These messages are relayed to the user based upon the
1926  scheduler <CODE>LogLevel</CODE> directive.</P>
1927 <P>The type of message is determined by an initial prefix sent on each
1928  line:</P>
1929 <UL>
1930 <LI><CODE>DEBUG:</CODE> - a debug message</LI>
1931 <LI><CODE>INFO:</CODE> - an informational message</LI>
1932 <LI><CODE>WARNING:</CODE> - a warning message</LI>
1933 <LI><CODE>ERROR:</CODE> - an error message</LI>
1934 <LI><CODE>PAGE:</CODE> - a page accounting message</LI>
1935 </UL>
1936 <P>If the line of text does not begin with any of the above prefixes, it
1937  is treated as a debug message. Text following the prefix is copied to
1938  the <CODE>printer-state-message</CODE> attribute for the printer, and
1939  also added to the<VAR> error_log</VAR> unless it is an informational or
1940  page accounting message.</P>
1941 <H3><A NAME="4_1_5">Page Accounting</A></H3>
1942 <P>Page accounting messages are used to inform the server when one or
1943  more pages are printed. Each line has the form:</P>
1944 <UL>
1945 <PRE>
1946 PAGE: page-number copy-count
1947 </PRE>
1948 </UL>
1949 <P>The<I> page-number</I> field is the current page number, starting at
1950  1. The<I> copy-count</I> field specifies the number of copies of that
1951  page that was produced.</P>
1952 <P>Page account messages are added to the<VAR> page_log</VAR> file and
1953  cause the <CODE>job-sheets-completed</CODE> attribute to be updated for
1954  the job.</P>
1955 <H3><A NAME="4_1_6">Command-Line Arguments</A></H3>
1956 <P>Every filter accepts exactly 6 or 7 command-line arguments:</P>
1957 <UL>
1958 <PRE>
1959 printer job user title copies options [filename]
1960 </PRE>
1961 <LI><CODE>printer</CODE> - The name of the printer queue (normally this
1962  is the name of the program being run)</LI>
1963 <LI><CODE>job</CODE> - The numeric job ID for the job being printed</LI>
1964 <LI><CODE>user</CODE> - The string from the <CODE>originating-user-name</CODE>
1965  attribute</LI>
1966 <LI><CODE>title</CODE> - The string from the <CODE>job-name</CODE>
1967  attribute</LI>
1968 <LI><CODE>copies</CODE> - The numeric value from the <CODE>number-copies</CODE>
1969  attribute</LI>
1970 <LI><CODE>options</CODE> - String representations of the job template
1971  attributes, separated by spaces. Boolean attributes are provided as
1972  &quot;name&quot; for true values and &quot;noname&quot; for false values. All other
1973  attributes are provided as &quot;name=value&quot; for single-valued attributes
1974  and &quot;name=value1,value2,...,valueN&quot; for set attributes</LI>
1975 <LI><CODE>filename</CODE> - The request file</LI>
1976 </UL>
1977 <P>The<I> filename</I> argument is only provided to the first filter in
1978  the chain; all filters<B> must</B> be prepared to read the print file
1979  from the standard input if the<I> filename</I> argument is omitted.</P>
1980 <H3><A NAME="4_1_7">Copy Generation</A></H3>
1981 <P>The<I> copies</I> argument specifies the number of copies to produce
1982  of the input file. In general, you should only generate copies if the<I>
1983  filename</I> argument is supplied. The only exception to this are
1984  filters that produce device-independent PostScript output (without any
1985  printer commands from the printer's PPD file), since the PostScript
1986  filter <CODE>pstops</CODE> is responsible for copy generation.</P>
1987 <H3><A NAME="4_1_8">Environment Variables</A></H3>
1988 <P>Every filter receives a fixed set of environment variables that can
1989  be used by the filter:</P>
1990 <UL>
1991 <LI><CODE>CHARSET</CODE> - The character set used by the client for this
1992  print file</LI>
1993 <LI><CODE>CONTENT_TYPE</CODE> - The original document type, such as
1994  &quot;application/postscript&quot;</LI>
1995 <LI><CODE>CUPS_DATADIR</CODE> - The location of CUPS data files</LI>
1996 <LI><CODE>CUPS_SERVERROOT</CODE> - The location of CUPS configuration
1997  files</LI>
1998 <LI><CODE>DEVICE_URI</CODE> - The output device URI</LI>
1999 <LI><CODE>LANG</CODE> - The language used by the client for this print
2000  file</LI>
2001 <LI><CODE>PATH</CODE> - The execution path exported to the filter</LI>
2002 <LI><CODE>PPD</CODE> - The full filename of the printer's PPD file</LI>
2003 <LI><CODE>PRINTER</CODE> - The name of the printer queue</LI>
2004 <LI><CODE>RIP_CACHE</CODE> - The maximum amount of memory each filter
2005  should use</LI>
2006 <LI><CODE>SOFTWARE</CODE> - The name of the CUPS software, typically
2007  &quot;CUPS/1.1&quot;</LI>
2008 <LI><CODE>TZ</CODE> - The local timezone</LI>
2009 <LI><CODE>USER</CODE> - The name of the current user</LI>
2010 </UL>
2011 <H2><A NAME="4_2">Dissecting the HP-GL/2 Filter</A></H2>
2012 <P>The HP-GL/2 filter (<CODE>hpgltops</CODE>) provided with CUPS is a
2013  complex program that converts HP-GL/2 files into device-independent
2014  PostScript output. Since it produces device-independent PostScript
2015  output, it does not need to handle copy generation or writing printer
2016  options from the printer's PPD file.</P>
2017 <H3><A NAME="4_2_1">Initializing the Filter</A></H3>
2018 <P>The first task of any filter is to ensure that the correct number of
2019  command-line arguments are present:</P>
2020 <UL>
2021 <PRE>
2022 if (argc &lt; 6 || argc &gt; 7)
2023 {
2024   fputs(&quot;ERROR: hpgltops job-id user title copies options [file]\n&quot;, stderr);
2025   return (1);
2026 }
2027 </PRE>
2028 </UL>
2029 <P>After this you open the print file or read from the standard input as
2030  needed:</P>
2031 <UL>
2032 <PRE>
2033 FILE *fp;
2034
2035 /*
2036  * If we have 7 arguments, print the file named on the command-line.
2037  * Otherwise, send stdin instead...
2038  */
2039
2040 if (argc == 6)
2041   fp = stdin;
2042 else
2043 {
2044  /*
2045   * Try to open the print file...
2046   */
2047
2048   if ((fp = fopen(argv[6], &quot;rb&quot;)) == NULL)
2049   {
2050     perror(&quot;ERROR: unable to open print file - &quot;);
2051     return (1);
2052   }
2053 }
2054 </PRE>
2055 </UL>
2056 <P>Once the print file has been opened, options can be processed using
2057  the<A HREF="#cupsParseOptions"> <CODE>cupsParseOptions()</CODE></A> and<A
2058 HREF="#cupsGetOption"> <CODE>cupsGetOption()</CODE></A> functions:</P>
2059 <UL>
2060 <PRE>
2061 int           num_options;
2062 cups_option_t *options;
2063 const char    *val;
2064
2065 /*
2066  * Process command-line options and write the prolog...
2067  */
2068
2069 options     = NULL;
2070 num_options = cupsParseOptions(argv[5], 0,
2071
2072 if ((val = cupsGetOption(&quot;blackplot&quot;, num_options, options)) != NULL)
2073   shading = 0;
2074
2075 if ((val = cupsGetOption(&quot;fitplot&quot;, num_options, options)) != NULL)
2076   FitPlot = 1;
2077
2078 if ((val = cupsGetOption(&quot;penwidth&quot;, num_options, options)) != NULL)
2079   PenWidth = (float)atoi(val) * 0.001f;
2080 </PRE>
2081 </UL>
2082 <P>After the options have been processed, the filter writes PostScript
2083  code to the standard output based on the print file, closes the print
2084  file (as needed), and returns 0 to the scheduler.</P>
2085 <H2><A NAME="4_3">PostScript Output</A></H2>
2086 <P>Filters that produce PostScript output must generate output
2087  conforming to the Adobe Document Structuring Conventions, 3.0. In
2088  general this means the beginning of each file must begin with:</P>
2089 <UL>
2090 <PRE>
2091 %!PS-Adobe-3.0
2092 %%BoundingBox: left bottom right top
2093 %%Pages: (atend)
2094 %%EndComments
2095 </PRE>
2096 </UL>
2097 <P>The<I> left</I>,<I> bottom</I>,<I> right</I>, and<I> top</I> values
2098  are integers in points from the lower-lefthand corner of the page.</P>
2099 <P>Pages must be surrounded by:</P>
2100 <UL>
2101 <PRE>
2102 %%Page: number number
2103 gsave
2104 ...
2105 grestore
2106 showpage
2107 </PRE>
2108 </UL>
2109 <P>And the end of each file must contain:</P>
2110 <UL>
2111 <PRE>
2112 %%Trailer
2113 %%Pages: number-pages
2114 %%EOF
2115 </PRE>
2116 </UL>
2117 <P>These comments allow the PostScript filter to correctly perform page
2118  accounting, copy generation, N-up printing, and so forth.</P>
2119 <H1 ALIGN="RIGHT"><A NAME="WRITING_DRIVERS">4 - Writing Printer Drivers</A>
2120 </H1>
2121 <P>This chapter discusses how to write a printer driver, which is a
2122  special filter program that converts CUPS raster data into the
2123  appropriate commands and data required for a printer.</P>
2124 <H2><A NAME="5_1">Overview</A></H2>
2125 <P>Raster printers utilitize PPD files that specify one or more
2126  device-specific filters that handle converting print files for the
2127  printer. The simplest raster printer drivers provide a single filter
2128  that converts CUPS raster data to the printer's native format.</P>
2129 <H3><A NAME="5_1_1">CUPS Raster Data</A></H3>
2130 <P>CUPS raster data (<CODE>application/vnd.cups-raster</CODE>) consists
2131  of a stream of raster page descriptions produced by one of the RIP
2132  filters, such as <CODE>pstoraster</CODE> or <CODE>imagetoraster</CODE>.</P>
2133 <P>Each page of data begins with a page dictionary structure called<A HREF="#cups_raster_header_t">
2134  <CODE>cups_raster_header_t</CODE></A>. This structure contains the
2135  colorspace, bits per color, media size, media type, hardware
2136  resolution, and so forth.</P>
2137 <P>After the page dictionary comes the page data which is a
2138  full-resolution, uncompressed bitmap representing the page in the
2139  printer's output colorspace.</P>
2140 <H3><A NAME="5_1_2">Page Accounting</A></H3>
2141 <P>Printer drivers must handle all page accounting. This means they must
2142  send &quot;PAGE:&quot; messages to the standard error file for each page (and in
2143  many cases, copy) sent to the printer.</P>
2144 <H3><A NAME="5_1_3">Color Management</A></H3>
2145 <P>Printer drivers can implement their color management via the <CODE>
2146 cupsColorProfile</CODE> attributes in the PPD file or internally in the
2147  driver from a device-independent colorspace. In general, color
2148  management performed by the RIP filters is more efficient than that
2149  performed inside printer drivers.</P>
2150 <P>For example, the <CODE>pstoraster</CODE> filter often only has to
2151  perform a color conversion once each time the color is used for
2152  multiple output pixels, while the raster filter must convert every
2153  pixel on the page.</P>
2154 <H3><A NAME="5_1_4">Device and Bitmap Variables</A></H3>
2155 <P>Besides the standard PostScript page device dictionary variables
2156  defined in the Adobe PostScript Level 3 reference manual, the CUPS
2157  filters support additional variables that are passed in the page device
2158  dictionary header for the page and in some cases control the type of
2159  raster data that is generated:
2160 <CENTER>
2161 <TABLE BORDER="1" WIDTH="90%">
2162 <TR><TH>Variable</TH><TH>Type</TH><TH>Description</TH></TR>
2163 <TR><TD>cupsWidth</TD><TD>read-only integer</TD><TD>Width of bitmap in
2164  pixels</TD></TR>
2165 <TR><TD>cupsHeight</TD><TD>read-only integer</TD><TD>Height of bitmap in
2166  pixels</TD></TR>
2167 <TR><TD>cupsMediaType</TD><TD>read-write integer</TD><TD>Device-specific
2168  media type code</TD></TR>
2169 <TR><TD>cupsBitsPerColor</TD><TD>read-write integer</TD><TD>Number of
2170  bits per color; 1, 2, 4, and 8 are currently supported</TD></TR>
2171 <TR><TD>cupsBitsPerPixel</TD><TD>read-only integer</TD><TD>Number of
2172  bits per pixel; 1 to 32</TD></TR>
2173 <TR><TD>cupsBytesPerLine</TD><TD>read-only integer</TD><TD>Number of
2174  bytes per line of raster graphics</TD></TR>
2175 <TR><TD>cupsColorOrder</TD><TD>read-write enum</TD><TD>The order of
2176  color values in the bitmap:
2177 <UL>
2178 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK</LI>
2179 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK</LI>
2180 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...</LI>
2181 </UL>
2182 </TD></TR>
2183 <TR><TD>cupsColorSpace</TD><TD>read-write enum</TD><TD>The colorspace of
2184  the bitmap:
2185 <UL>
2186 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI>
2187 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI>
2188 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI>
2189 <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI>
2190 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI>
2191 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI>
2192 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI>
2193 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI>
2194 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI>
2195 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
2196  light cyan, light magenta</LI>
2197 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic
2198  magenta, metallic cyan, black</LI>
2199 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic
2200  magenta, metallic cyan, metallic grey (silver)</LI>
2201 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white
2202  pigment)</LI>
2203 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI>
2204 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI>
2205 </UL>
2206 </TD></TR>
2207 <TR><TD>cupsCompression</TD><TD>read-write integer</TD><TD>
2208 Device-specific compression type code</TD></TR>
2209 <TR><TD>cupsRowCount</TD><TD>read-write integer</TD><TD>Device-specific
2210  row count value</TD></TR>
2211 <TR><TD>cupsRowFeed</TD><TD>read-write integer</TD><TD>Device-specific
2212  row feed value</TD></TR>
2213 <TR><TD>cupsRowStep</TD><TD>read-write integer</TD><TD>Device-specific
2214  row step value</TD></TR>
2215 </TABLE>
2216 </CENTER>
2217 </P>
2218 <P>Bitmaps with a colorspace of CUPS_CSPACE_KCMYcm and more than 1 bit
2219  per color are transmitted to the raster driver in KCMY colorspace; the
2220  driver is responsible for producing the correct separation of normal
2221  and light cyan and magenta inks.</P>
2222 <H2><A NAME="5_2">Dissecting the HP-PCL Driver</A></H2>
2223 <P>The HP-PCL driver provided with CUPS (<CODE>rastertohp</CODE>)
2224  converts bitmap data from the raster filters into HP-PCL commands for
2225  most PCL-compatible printers. The actual format of the raster data is
2226  controlled by the PPD file being used -<VAR> deskjet.ppd</VAR> or<VAR>
2227  laserjet.ppd</VAR>.</P>
2228 <H3><A NAME="5_2_1">PPD Files</A></H3>
2229 <P>PPD files play an important part of all raster printer drivers.
2230  Options defined in the PPD file contain PostScript commands that
2231  control the raster data that is sent to the printer driver.</P>
2232 <P>A typical CUPS printer driver will include <CODE>ColorModel</CODE>, <CODE>
2233 InputSlot</CODE>, <CODE>PageSize</CODE>, <CODE>PageRegion</CODE>, and <CODE>
2234 Resolution</CODE> options. Each option is shown using the standard PPD
2235  format:</P>
2236 <UL>
2237 <PRE>
2238 *OpenUI *PageSize/Media Size: PickOne
2239 *OrderDependency: 10 AnySetup *PageSize
2240 *DefaultPageSize: Letter
2241 *PageSize Letter/US Letter: &quot;&lt;&lt;
2242 /PageSize [612 792]
2243 /ImagingBBox null
2244 &gt;&gt; setpagedevice&quot;
2245 *End
2246 *PageSize Legal/US Legal: &quot;&lt;&lt;
2247 /PageSize [612 1008]
2248 /ImagingBBox null
2249 &gt;&gt; setpagedevice&quot;
2250 *End
2251 *PageSize A4/A4: &quot;&lt;&lt;
2252 /PageSize [595 842]
2253 /ImagingBBox null
2254 &gt;&gt; setpagedevice&quot;
2255 *End
2256 *CloseUI: *PageSize
2257 </PRE>
2258 </UL>
2259 <P>The <CODE>OpenUI</CODE> keyword specifies the new option. The first
2260  name is the option with an asterisk (*) in front of it. The first name
2261  is usually followed by a slash (/) and a human-readable version of the
2262  option name.</P>
2263 <P>Every option<B> must</B> have a default value, specified using the <CODE>
2264 Default<I>Option</I></CODE> keyword.</P>
2265 <P>Each option begins with the option name followed by the computer and
2266  human-readable values. The PostScript commands follow these inside
2267  double quotes. PostScript commands can be provided on a single line:</P>
2268 <UL>
2269 <PRE>
2270 *PageSize A4/A4: &quot;&lt;&lt;/PageSize[595 842]/ImagingBBox null&gt;&gt; setpagedevice&quot;
2271 </PRE>
2272 </UL>
2273 <P>or broken down on separate lines using the <CODE>End</CODE> keyword
2274  to terminate them:</P>
2275 <UL>
2276 <PRE>
2277 *PageSize A4/A4: &quot;&lt;&lt;
2278 /PageSize [595 842]
2279 /ImagingBBox null
2280 &gt;&gt; setpagedevice&quot;
2281 *End
2282 </PRE>
2283 </UL>
2284 <P>The choice of the two formats is usually esthetic. However, each line
2285  in a PPD file must not exceed 255 characters, so if your PostScript
2286  commands are long you may need to break them up on separate lines.</P>
2287 <H3><A NAME="5_2_2">Reading Raster Data</A></H3>
2288 <P>As with any filter, your printer driver should handle raster data
2289  from a filename specified on the command-line or from the standard
2290  input. The<A HREF="#cupsRasterOpen"> <CODE>cupsRasterOpen()</CODE></A>
2291  function opens a raster stream for printing:</P>
2292 <UL>
2293 <PRE>
2294 int           fd;   /* File descriptor */
2295 cups_raster_t *ras; /* Raster stream for printing */
2296
2297
2298 /*
2299  * Check for valid arguments...
2300  */
2301
2302 if (argc &lt; 6 || argc &gt; 7)
2303 {
2304  /*
2305   * We don't have the correct number of arguments; write an error message
2306   * and return.
2307   */
2308
2309   fputs(&quot;ERROR: rastertopcl job-id user title copies options [file]\n&quot;, stderr);
2310   return (1);
2311 }
2312
2313 /*
2314  * Open the page stream...
2315  */
2316
2317 if (argc == 7)
2318 {
2319   if ((fd = open(argv[6], O_RDONLY)) == -1)
2320   {
2321     perror(&quot;ERROR: Unable to open raster file - &quot;);
2322     sleep(1);
2323     return (1);
2324   }
2325 }
2326 else
2327   fd = 0;
2328
2329 ras = cupsRasterOpen(fd, CUPS_RASTER_READ);
2330 </PRE>
2331 </UL>
2332 <P>Once you have opened the raster stream you just need to read each
2333  page and print it:</P>
2334 <UL>
2335 <PRE>
2336 cups_raster_header_t header;
2337 int                  y;
2338 unsigned char        data[8192];
2339
2340 while (cupsRasterReadHeader(ras, &amp;header))
2341 {
2342   ... initialize the printer ...
2343   for (y = header.cupsHeight; y &gt; 0; y ++)
2344   {
2345     cupsRasterReadPixels(ras, data, header.cupsBytesPerLine);
2346     ... send raster line to printer ...
2347   }
2348 }
2349 </PRE>
2350 </UL>
2351 <P>After you have processed all pages, close the raster stream and
2352  return:</P>
2353 <UL>
2354 <PRE>
2355 cupsRasterClose(ras);
2356
2357 return (0);
2358 </PRE>
2359 </UL>
2360 <H1 ALIGN="RIGHT"><A NAME="WRITING_BACKENDS">5 - Writing Backends</A></H1>
2361 <P>This chapter describes how to write a backend for CUPS. Backends
2362  communicate directly with printers and allow printer drivers and
2363  filters to send data using any type of connection transparently.</P>
2364 <H2><A NAME="6_1">Overview</A></H2>
2365 <P>Backends are special filters that communicate with printers directly.
2366  They are treated slightly differently than filters, however, and have
2367  some unique requirements.</P>
2368 <H3><A NAME="6_1_1">Security Considerations</A></H3>
2369 <P>Backends are run as the root user, so special care must be taken to
2370  avoid potential security violations. In particular, remember that a
2371  backend will be able to manipulate disk files, devices, and other
2372  resources that potentially could damage a system or printer.</P>
2373 <H3><A NAME="6_1_2">Command-Line Arguments</A></H3>
2374 <P>Besides the standard filter arguments, backends are also run with no
2375  arguments to get a list of available devices. This discovery process is
2376  described later in this chapter.</P>
2377 <H3><A NAME="6_1_3">Copy Generation</A></H3>
2378 <P>Like filters, backends should send multiple copies of the print file
2379  only if a filename is supplied on the command-line. Otherwise the
2380  backend should assume that the upstream filter has already added the
2381  necessary commands or data to produce the multiple copies.</P>
2382 <H3><A NAME="6_1_4">Page Accounting</A></H3>
2383 <P>Backend filters generally do not do page accounting, however they
2384  should at a minimum produce a single page message for each copy that is
2385  produced when a filename is present on the command-line. This is
2386  because the user selected &quot;raw&quot; printing and no other accounting
2387  information is possible.</P>
2388 <H3><A NAME="6_1_5">Exclusive Access</A></H3>
2389 <P>Backends that talk to local character or block devices should open
2390  the device file in exclusive mode (<CODE>O_EXCL</CODE>) to cooperate
2391  with other printers defined for the same device.</P>
2392 <H3><A NAME="6_1_6">Retries</A></H3>
2393 <P>All backends<B> must</B> retry connections to the device. This
2394  includes backends that talk to local character or block devices, as the
2395  user may define more than one printer queue pointing at the same
2396  physical device.</P>
2397 <P>To prevent excess CPU utilitization, the backend should go to sleep
2398  for an amount of time between retries; the CUPS-supplied backends retry
2399  once every 30 seconds.</P>
2400 <H2><A NAME="6_2">Dissecting the Serial Port Backend</A></H2>
2401 <P>The serial port backend provides support for serial printers. Since
2402  it does everything a good backend needs to do, it provides an excellent
2403  example of what to do.</P>
2404 <H3><A NAME="6_2_1">Supporting Device Discovery</A></H3>
2405 <P>As previously noted, backends are special filter programs that talk
2406  to printer devices. Another task a backend must perform is to list the
2407  available devices it supports. The backend lists the available devices
2408  when no additioanl arguments are supplied on the command-line (i.e.
2409  just the command name...)</P>
2410 <P>The serial backend lists devices by looking at serial port files in
2411  the<VAR> /dev</VAR> directory, by consulting a hardware inventory
2412  (IRIX), and in some cases by trying to open the ports to see if they
2413  actually exist.</P>
2414 <P>Once it finds a serial port it writes a single line for each port to
2415  the standard error file. Each line looks like this:</P>
2416 <UL>
2417 <PRE>
2418 serial serial:/dev/ttyS0?baud=115200 &quot;Unknown&quot; &quot;Serial Port 1&quot;
2419 </PRE>
2420 </UL>
2421 <P>The first word &quot;serial&quot; is the<I> device class</I>; this identifies
2422  the class of device which can be used to categorize it in user
2423  interfaces. CUPS currently recognizes the following classes:</P>
2424 <UL>
2425 <LI>&quot;file&quot; - a disk file.</LI>
2426 <LI>&quot;direct&quot; - a parallel or fixed-rate serial data port, currently used
2427  for Centronics, IEEE-1284, and USB printer ports.</LI>
2428 <LI>&quot;serial&quot; - a variable-rate serial port.</LI>
2429 <LI>&quot;network&quot; - a network connection, typically via AppSocket, HTTP,
2430  IPP, LPD, or SMB/CIFS protocols.</LI>
2431 </UL>
2432 <P>After the device class is the<I> device URI</I>, in this case
2433  &quot;serial:/dev/ttyS0?baud=115200&quot;. This is the URI that should be used by
2434  the user to select this port. For serial ports, the &quot;baud=115200&quot;
2435  specifies the maximum baud rate supported by the port - the actual
2436  value will vary based on the speed the user selects for the printer.</P>
2437 <P>The last two strings are the model and description for the port. The
2438  &quot;Unknown&quot; string means that the printer model is unknown - some devices
2439  are able to provide a make and model such as &quot;HP DeskJet&quot; that allows
2440  users and software to choose an appropriate printer driver more easily.
2441  Both the model and description must be enclosed inside double quotes.</P>
2442 <H3><A NAME="6_2_2">Opening the Serial Port</A></H3>
2443 <P>As noted previously, all backends should open device files in
2444  exclusive mode, and retry as needed until the port is available. The
2445  serial port does this using a <CODE>do-while</CODE> loop:</P>
2446 <UL>
2447 <PRE>
2448 do
2449 {
2450   if ((fd = open(resource, O_WRONLY | O_NOCTTY | O_EXCL)) == -1)
2451   {
2452     if (errno == EBUSY)
2453     {
2454       fputs(&quot;INFO: Serial port busy; will retry in 30 seconds...\n&quot;, stderr);
2455       sleep(30);
2456     }
2457     else
2458     {
2459       perror(&quot;ERROR: Unable to open serial port device file&quot;);
2460       return (1);
2461     }
2462   }
2463 }
2464 while (fd &lt; 0);
2465 </PRE>
2466 </UL>
2467 <P>If the port is busy or in use by another process, the backend will go
2468  to sleep for 30 seconds and try again. If another error is detected a
2469  message is sent to the user and the backend aborts the print job until
2470  the problem can be corrected.</P>
2471 <H3><A NAME="6_2_3">Writing Data to the Port</A></H3>
2472 <P>Network and character devices pose an interesting problem when
2473  writing data to the port - they may not be able to write all of the
2474  bytes in your buffer before returning. To work around this problem you
2475  must loop until all bytes have been written:</P>
2476 <UL>
2477 <PRE>
2478 while (nbytes &gt; 0)
2479 {
2480   if ((wbytes = write(fd, bufptr, nbytes)) &lt; 0)
2481     if (errno == ENOTTY)
2482       wbytes = write(fd, bufptr, nbytes);
2483
2484   if (wbytes &lt; 0)
2485   {
2486     perror(&quot;ERROR: Unable to send print file to printer&quot;);
2487     break;
2488   }
2489
2490   nbytes -= wbytes;
2491   bufptr += wbytes;
2492 }
2493 </PRE>
2494 </UL>
2495 <P>The check for the <CODE>ENOTTY</CODE> error is needed on some
2496  platforms to clear an error from a previous <CODE>ioctl()</CODE> call.</P>
2497 <H3><A NAME="6_2_4">Finishing Up</A></H3>
2498 <P>Once you have sent the print file, return 0 if the file printed
2499  successfully or 1 if it did not. This will allow the scheduler to stop
2500  the print job if there is a device error, preserving the print job for
2501  later printing once the problem has been corrected.</P>
2502 <H1 ALIGN="RIGHT"><A NAME="LICENSE">A - Software License Agreement</A></H1>
2503 <H2 ALIGN="CENTER"><A NAME="7_1">Common UNIX Printing System License
2504  Agreement</A></H2>
2505 <P ALIGN="CENTER">Copyright 1997-2002 by Easy Software Products
2506 <BR> 44141 AIRPORT VIEW DR STE 204
2507 <BR> HOLLYWOOD, MARYLAND 20636-3111 USA
2508 <BR>
2509 <BR> Voice: +1.301.373.9600
2510 <BR> Email:<A HREF="mailto:cups-info@cups.org"> cups-info@cups.org</A>
2511 <BR> WWW:<A HREF="http://www.cups.org"> http://www.cups.org</A></P>
2512 <H3><A NAME="7_1_1">Introduction</A></H3>
2513 <P>The Common UNIX Printing System<SUP>TM</SUP>, (&quot;CUPS<SUP>TM</SUP>&quot;),
2514  is provided under the GNU General Public License (&quot;GPL&quot;) and GNU
2515  Library General Public License (&quot;LGPL&quot;), Version 2. A copy of these
2516  licenses follow this introduction.</P>
2517 <P>The GNU LGPL applies to the CUPS API library, located in the &quot;cups&quot;
2518  subdirectory of the CUPS source distribution and in the
2519  &quot;/usr/include/cups&quot; directory and &quot;libcups.a&quot;, &quot;libcups_s.a&quot;,
2520  &quot;libcups.sl&quot;, or &quot;libcups.so&quot; files in the binary distributions.</P>
2521 <P>The GNU GPL applies to the remainder of the CUPS distribution,
2522  including the &quot;pstoraster&quot; filter which is based upon GNU Ghostscript
2523  5.50 and the &quot;pdftops&quot; filter which is based upon Xpdf 0.93a.</P>
2524 <P>For those not familiar with the GNU GPL, the license basically allows
2525  you to:</P>
2526 <UL>
2527 <LI>Use the CUPS software at no charge.</LI>
2528 <LI>Distribute verbatim copies of the software in source or binary form.</LI>
2529 <LI>Sell verbatim copies of the software for a media fee, or sell
2530  support for the software.</LI>
2531 <LI>Distribute or sell printer drivers and filters that use CUPS so long
2532  as source code is made available under the GPL.</LI>
2533 </UL>
2534 <P>What this license<B> does not</B> allow you to do is make changes or
2535  add features to CUPS and then sell a binary distribution without source
2536  code. You must provide source for any new drivers, changes, or
2537  additions to the software, and all code must be provided under the GPL
2538  or LGPL as appropriate.</P>
2539 <P>The GNU LGPL relaxes the &quot;link-to&quot; restriction, allowing you to
2540  develop applications that use the CUPS API library under other licenses
2541  and/or conditions as appropriate for your application.</P>
2542 <H3><A NAME="7_1_2">Trademarks</A></H3>
2543 <P>Easy Software Products has trademarked the Common UNIX Printing
2544  System, CUPS, and CUPS logo. These names and logos may be used freely
2545  in any direct port or binary distribution of CUPS. To use them in
2546  derivative products, please contract Easy Software Products for written
2547  permission. Our intention is to protect the value of these trademarks
2548  and ensure that any derivative product meets the same high-quality
2549  standards as the original.</P>
2550 <H3><A NAME="7_1_3">Binary Distribution Rights</A></H3>
2551 <P>Easy Software Products also sells rights to the CUPS source code
2552  under a binary distribution license for vendors that are unable to
2553  release source code for their drivers, additions, and modifications to
2554  CUPS under the GNU GPL and LGPL. For information please contact us at
2555  the address shown above.</P>
2556 <P>The Common UNIX Printing System provides a &quot;pstoraster&quot; filter that
2557  utilizes the GNU GhostScript 5.50 core to convert PostScript files into
2558  a stream of raster images. For binary distribution licensing of this
2559  software, please contact:<BLOCKQUOTE> Miles Jones
2560 <BR> Director of Marketing
2561 <BR> Artifex Software Inc.
2562 <BR> 454 Las Gallinas Ave., Suite 108
2563 <BR> San Rafael, CA 94903 USA
2564 <BR> Voice: +1.415.492.9861
2565 <BR> Fax: +1.415.492.9862
2566 <BR> EMail:<A HREF="mailto:info@arsoft.com"> info@arsoft.com</A></BLOCKQUOTE>
2567 </P>
2568 <P>The &quot;pdftops&quot; filter is based on the Xpdf 0.93a software. For binary
2569  distribution licensing of this software, please contact:<BLOCKQUOTE>
2570  Derek B. Noonburg
2571 <BR> Email:<A HREF="mailto:derekn@foolabs.com"> derekn@foolabs.com</A>
2572 <BR> WWW:<A HREF="http://www.foolabs.com/xpdf/">
2573  http://www.foolabs.com/xpdf/</A></BLOCKQUOTE></P>
2574 <H3><A NAME="7_1_4">Support</A></H3>
2575 <P>Easy Software Products sells software support for CUPS as well as a
2576  commercial printing product based on CUPS called ESP Print Pro. You can
2577  find out more at our web site:</P>
2578 <UL>
2579 <PRE>
2580 <A HREF="http://www.easysw.com">http://www.easysw.com</A>
2581 </PRE>
2582 </UL>
2583
2584 <!-- NEW PAGE -->
2585 <H2><A NAME="7_2">GNU GENERAL PUBLIC LICENSE</A></H2>
2586 <P>Version 2, June 1991</P>
2587 <PRE>
2588 Copyright 1989, 1991 Free Software Foundation, Inc.
2589 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
2590
2591 Everyone is permitted to copy and distribute verbatim
2592 copies of this license document, but changing it is not allowed.
2593 </PRE>
2594 <PRE>
2595
2596 </PRE>
2597 <H4>Preamble</H4>
2598 <P>The licenses for most software are designed to take away your freedom
2599  to share and change it. By contrast, the GNU General Public License is
2600  intended to guarantee your freedom to share and change free
2601  software--to make sure the software is free for all its users. This
2602  General Public License applies to most of the Free Software
2603  Foundation's software and to any other program whose authors commit to
2604  using it. (Some other Free Software Foundation software is covered by
2605  the GNU Library General Public License instead.) You can apply it to
2606  your programs, too.</P>
2607 <P>When we speak of free software, we are referring to freedom, not
2608  price. Our General Public Licenses are designed to make sure that you
2609  have the freedom to distribute copies of free software (and charge for
2610  this service if you wish), that you receive source code or can get it
2611  if you want it, that you can change the software or use pieces of it in
2612  new free programs; and that you know you can do these things.</P>
2613 <P>To protect your rights, we need to make restrictions that forbid
2614  anyone to deny you these rights or to ask you to surrender the rights.
2615  These restrictions translate to certain responsibilities for you if you
2616  distribute copies of the software, or if you modify it.</P>
2617 <P>For example, if you distribute copies of such a program, whether
2618  gratis or for a fee, you must give the recipients all the rights that
2619  you have. You must make sure that they, too, receive or can get the
2620  source code. And you must show them these terms so they know their
2621  rights.</P>
2622 <P>We protect your rights with two steps: (1) copyright the software,
2623  and (2) offer you this license which gives you legal permission to
2624  copy, distribute and/or modify the software.</P>
2625 <P>Also, for each author's protection and ours, we want to make certain
2626  that everyone understands that there is no warranty for this free
2627  software. If the software is modified by someone else and passed on, we
2628  want its recipients to know that what they have is not the original, so
2629  that any problems introduced by others will not reflect on the original
2630  authors' reputations.</P>
2631 <P>Finally, any free program is threatened constantly by software
2632  patents. We wish to avoid the danger that redistributors of a free
2633  program will individually obtain patent licenses, in effect making the
2634  program proprietary. To prevent this, we have made it clear that any
2635  patent must be licensed for everyone's free use or not licensed at all.</P>
2636 <P>The precise terms and conditions for copying, distribution and
2637  modification follow.</P>
2638 <H4>GNU GENERAL PUBLIC LICENSE
2639 <BR> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
2640 <OL START="0">
2641 <LI>This License applies to any program or other work which contains a
2642  notice placed by the copyright holder saying it may be distributed
2643  under the terms of this General Public License. The &quot;Program&quot;, below,
2644  refers to any such program or work, and a &quot;work based on the Program&quot;
2645  means either the Program or any derivative work under copyright law:
2646  that is to say, a work containing the Program or a portion of it,
2647  either verbatim or with modifications and/or translated into another
2648  language. (Hereinafter, translation is included without limitation in
2649  the term &quot;modification&quot;.) Each licensee is addressed as &quot;you&quot;.</LI>
2650 <P>Activities other than copying, distribution and modification are not
2651  covered by this License; they are outside its scope. The act of running
2652  the Program is not restricted, and the output from the Program is
2653  covered only if its contents constitute a work based on the Program
2654  (independent of having been made by running the Program). Whether that
2655  is true depends on what the Program does.</P>
2656 <LI>You may copy and distribute verbatim copies of the Program's source
2657  code as you receive it, in any medium, provided that you conspicuously
2658  and appropriately publish on each copy an appropriate copyright notice
2659  and disclaimer of warranty; keep intact all the notices that refer to
2660  this License and to the absence of any warranty; and give any other
2661  recipients of the Program a copy of this License along with the
2662  Program.</LI>
2663 <P>You may charge a fee for the physical act of transferring a copy, and
2664  you may at your option offer warranty protection in exchange for a fee.</P>
2665 <LI>You may modify your copy or copies of the Program or any portion of
2666  it, thus forming a work based on the Program, and copy and distribute
2667  such modifications or work under the terms of Section 1 above, provided
2668  that you also meet all of these conditions:
2669 <OL TYPE="a">
2670 <LI>You must cause the modified files to carry prominent notices stating
2671  that you changed the files and the date of any change.</LI>
2672 <LI>You must cause any work that you distribute or publish, that in
2673  whole or in part contains or is derived from the Program or any part
2674  thereof, to be licensed as a whole at no charge to all third parties
2675  under the terms of this License.</LI>
2676 <LI>if the modified program normally reads commands interactively when
2677  run, you must cause it, when started running for such interactive use
2678  in the most ordinary way, to print or display an announcement including
2679  an appropriate copyright notice and a notice that there is no warranty
2680  (or else, saying that you provide a warranty) and that users may
2681  redistribute the program under these conditions, and telling the user
2682  how to view a copy of this License. (Exception: if the Program itself
2683  is interactive but does not normally print such an announcement, your
2684  work based on the Program is not required to print an announcement.)</LI>
2685 </OL>
2686 </LI>
2687 <P>These requirements apply to the modified work as a whole. If
2688  identifiable sections of that work are not derived from the Program,
2689  and can be reasonably considered independent and separate works in
2690  themselves, then this License, and its terms, do not apply to those
2691  sections when you distribute them as separate works. But when you
2692  distribute the same sections as part of a whole which is a work based
2693  on the Program, the distribution of the whole must be on the terms of
2694  this License, whose permissions for other licensees extend to the
2695  entire whole, and thus to each and every part regardless of who wrote
2696  it.</P>
2697 <P>Thus, it is not the intent of this section to claim rights or contest
2698  your rights to work written entirely by you; rather, the intent is to
2699  exercise the right to control the distribution of derivative or
2700  collective works based on the Program.</P>
2701 <P>In addition, mere aggregation of another work not based on the
2702  Program with the Program (or with a work based on the Program) on a
2703  volume of a storage or distribution medium does not bring the other
2704  work under the scope of this License.</P>
2705 <LI>You may copy and distribute the Program (or a work based on it,
2706  under Section 2) in object code or executable form under the terms of
2707  Sections 1 and 2 above provided that you also do one of the following:
2708 <OL TYPE="a">
2709 <LI>Accompany it with the complete corresponding machine-readable source
2710  code, which must be distributed under the terms of Sections 1 and 2
2711  above on a medium customarily used for software interchange; or,</LI>
2712 <LI>Accompany it with a written offer, valid for at least three years,
2713  to give any third party, for a charge no more than your cost of
2714  physically performing source distribution, a complete machine-readable
2715  copy of the corresponding source code, to be distributed under the
2716  terms of Sections 1 and 2 above on a medium customarily used for
2717  software interchange; or,</LI>
2718 <LI>Accompany it with the information you received as to the offer to
2719  distribute corresponding source code. (This alternative is allowed only
2720  for noncommercial distribution and only if you received the program in
2721  object code or executable form with such an offer, in accord with
2722  Subsection b above.)</LI>
2723 </OL>
2724 </LI>
2725 <P>The source code for a work means the preferred form of the work for
2726  making modifications to it. For an executable work, complete source
2727  code means all the source code for all modules it contains, plus any
2728  associated interface definition files, plus the scripts used to control
2729  compilation and installation of the executable. However, as a special
2730  exception, the source code distributed need not include anything that
2731  is normally distributed (in either source or binary form) with the
2732  major components (compiler, kernel, and so on) of the operating system
2733  on which the executable runs, unless that component itself accompanies
2734  the executable.</P>
2735 <P>If distribution of executable or object code is made by offering
2736  access to copy from a designated place, then offering equivalent access
2737  to copy the source code from the same place counts as distribution of
2738  the source code, even though third parties are not compelled to copy
2739  the source along with the object code.</P>
2740 <LI>You may not copy, modify, sublicense, or distribute the Program
2741  except as expressly provided under this License. Any attempt otherwise
2742  to copy, modify, sublicense or distribute the Program is void, and will
2743  automatically terminate your rights under this License. However,
2744  parties who have received copies, or rights, from you under this
2745  License will not have their licenses terminated so long as such parties
2746  remain in full compliance.</LI>
2747 <LI>You are not required to accept this License, since you have not
2748  signed it. However, nothing else grants you permission to modify or
2749  distribute the Program or its derivative works. These actions are
2750  prohibited by law if you do not accept this License. Therefore, by
2751  modifying or distributing the Program (or any work based on the
2752  Program), you indicate your acceptance of this License to do so, and
2753  all its terms and conditions for copying, distributing or modifying the
2754  Program or works based on it.</LI>
2755 <LI>Each time you redistribute the Program (or any work based on the
2756  Program), the recipient automatically receives a license from the
2757  original licensor to copy, distribute or modify the Program subject to
2758  these terms and conditions. You may not impose any further restrictions
2759  on the recipients' exercise of the rights granted herein. You are not
2760  responsible for enforcing compliance by third parties to this License.</LI>
2761 <LI>If, as a consequence of a court judgment or allegation of patent
2762  infringement or for any other reason (not limited to patent issues),
2763  conditions are imposed on you (whether by court order, agreement or
2764  otherwise) that contradict the conditions of this License, they do not
2765  excuse you from the conditions of this License. If you cannot
2766  distribute so as to satisfy simultaneously your obligations under this
2767  License and any other pertinent obligations, then as a consequence you
2768  may not distribute the Program at all. For example, if a patent license
2769  would not permit royalty-free redistribution of the Program by all
2770  those who receive copies directly or indirectly through you, then the
2771  only way you could satisfy both it and this License would be to refrain
2772  entirely from distribution of the Program.</LI>
2773 <P>If any portion of this section is held invalid or unenforceable under
2774  any particular circumstance, the balance of the section is intended to
2775  apply and the section as a whole is intended to apply in other
2776  circumstances.</P>
2777 <P>It is not the purpose of this section to induce you to infringe any
2778  patents or other property right claims or to contest validity of any
2779  such claims; this section has the sole purpose of protecting the
2780  integrity of the free software distribution system, which is
2781  implemented by public license practices. Many people have made generous
2782  contributions to the wide range of software distributed through that
2783  system in reliance on consistent application of that system; it is up
2784  to the author/donor to decide if he or she is willing to distribute
2785  software through any other system and a licensee cannot impose that
2786  choice.</P>
2787 <P>This section is intended to make thoroughly clear what is believed to
2788  be a consequence of the rest of this License.</P>
2789 <LI>If the distribution and/or use of the Program is restricted in
2790  certain countries either by patents or by copyrighted interfaces, the
2791  original copyright holder who places the Program under this License may
2792  add an explicit geographical distribution limitation excluding those
2793  countries, so that distribution is permitted only in or among countries
2794  not thus excluded. In such case, this License incorporates the
2795  limitation as if written in the body of this License.</LI>
2796 <LI>The Free Software Foundation may publish revised and/or new versions
2797  of the General Public License from time to time. Such new versions will
2798  be similar in spirit to the present version, but may differ in detail
2799  to address new problems or concerns.</LI>
2800 <P>Each version is given a distinguishing version number. If the Program
2801  specifies a version number of this License which applies to it and &quot;any
2802  later version&quot;, you have the option of following the terms and
2803  conditions either of that version or of any later version published by
2804  the Free Software Foundation. If the Program does not specify a version
2805  number of this License, you may choose any version ever published by
2806  the Free Software Foundation.</P>
2807 <LI>If you wish to incorporate parts of the Program into other free
2808  programs whose distribution conditions are different, write to the
2809  author to ask for permission. For software which is copyrighted by the
2810  Free Software Foundation, write to the Free Software Foundation; we
2811  sometimes make exceptions for this. Our decision will be guided by the
2812  two goals of preserving the free status of all derivatives of our free
2813  software and of promoting the sharing and reuse of software generally.</LI>
2814 </OL>
2815 <H4>NO WARRANTY</H4>
2816 <OL START="11">
2817 <LI>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2818  FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2819  OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2820  PROVIDE THE PROGRAM &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER
2821  EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
2822  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
2823  ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
2824  YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
2825  NECESSARY SERVICING, REPAIR OR CORRECTION.</LI>
2826 <LI>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
2827  WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
2828  AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
2829  FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
2830  CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
2831  PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
2832  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
2833  FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
2834  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
2835  DAMAGES.</LI>
2836 </OL>
2837 <H4>END OF TERMS AND CONDITIONS</H4>
2838
2839 <!-- NEW PAGE -->
2840 <H2><A NAME="7_3">GNU LIBRARY GENERAL PUBLIC LICENSE</A></H2>
2841 <P>Version 2, June 1991</P>
2842 <PRE>
2843 Copyright (C) 1991 Free Software Foundation, Inc.
2844 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
2845 Everyone is permitted to copy and distribute verbatim copies
2846 of this license document, but changing it is not allowed.
2847
2848 [This is the first released version of the library GPL.  It is
2849  numbered 2 because it goes with version 2 of the ordinary GPL.]
2850 </PRE>
2851 <H4>Preamble</H4>
2852 <P>The licenses for most software are designed to take away your freedom
2853  to share and change it. By contrast, the GNU General Public Licenses
2854  are intended to guarantee your freedom to share and change free
2855  software--to make sure the software is free for all its users.</P>
2856 <P>This license, the Library General Public License, applies to some
2857  specially designated Free Software Foundation software, and to any
2858  other libraries whose authors decide to use it. You can use it for your
2859  libraries, too.</P>
2860 <P>When we speak of free software, we are referring to freedom, not
2861  price. Our General Public Licenses are designed to make sure that you
2862  have the freedom to distribute copies of free software (and charge for
2863  this service if you wish), that you receive source code or can get it
2864  if you want it, that you can change the software or use pieces of it in
2865  new free programs; and that you know you can do these things.</P>
2866 <P>To protect your rights, we need to make restrictions that forbid
2867  anyone to deny you these rights or to ask you to surrender the rights.
2868  These restrictions translate to certain responsibilities for you if you
2869  distribute copies of the library, or if you modify it.</P>
2870 <P>For example, if you distribute copies of the library, whether gratis
2871  or for a fee, you must give the recipients all the rights that we gave
2872  you. You must make sure that they, too, receive or can get the source
2873  code. If you link a program with the library, you must provide complete
2874  object files to the recipients so that they can relink them with the
2875  library, after making changes to the library and recompiling it. And
2876  you must show them these terms so they know their rights.</P>
2877 <P>Our method of protecting your rights has two steps: (1) copyright the
2878  library, and (2) offer you this license which gives you legal
2879  permission to copy, distribute and/or modify the library.</P>
2880 <P>Also, for each distributor's protection, we want to make certain that
2881  everyone understands that there is no warranty for this free library.
2882  If the library is modified by someone else and passed on, we want its
2883  recipients to know that what they have is not the original version, so
2884  that any problems introduced by others will not reflect on the original
2885  authors' reputations.</P>
2886 <P>Finally, any free program is threatened constantly by software
2887  patents. We wish to avoid the danger that companies distributing free
2888  software will individually obtain patent licenses, thus in effect
2889  transforming the program into proprietary software. To prevent this, we
2890  have made it clear that any patent must be licensed for everyone's free
2891  use or not licensed at all.</P>
2892 <P>Most GNU software, including some libraries, is covered by the
2893  ordinary GNU General Public License, which was designed for utility
2894  programs. This license, the GNU Library General Public License, applies
2895  to certain designated libraries. This license is quite different from
2896  the ordinary one; be sure to read it in full, and don't assume that
2897  anything in it is the same as in the ordinary license.</P>
2898 <P>The reason we have a separate public license for some libraries is
2899  that they blur the distinction we usually make between modifying or
2900  adding to a program and simply using it. Linking a program with a
2901  library, without changing the library, is in some sense simply using
2902  the library, and is analogous to running a utility program or
2903  application program. However, in a textual and legal sense, the linked
2904  executable is a combined work, a derivative of the original library,
2905  and the ordinary General Public License treats it as such.</P>
2906 <P>Because of this blurred distinction, using the ordinary General
2907  Public License for libraries did not effectively promote software
2908  sharing, because most developers did not use the libraries. We
2909  concluded that weaker conditions might promote sharing better.</P>
2910 <P>However, unrestricted linking of non-free programs would deprive the
2911  users of those programs of all benefit from the free status of the
2912  libraries themselves. This Library General Public License is intended
2913  to permit developers of non-free programs to use free libraries, while
2914  preserving your freedom as a user of such programs to change the free
2915  libraries that are incorporated in them. (We have not seen how to
2916  achieve this as regards changes in header files, but we have achieved
2917  it as regards changes in the actual functions of the Library.) The hope
2918  is that this will lead to faster development of free libraries.</P>
2919 <P>The precise terms and conditions for copying, distribution and
2920  modification follow. Pay close attention to the difference between a
2921  &quot;work based on the library&quot; and a &quot;work that uses the library&quot;. The
2922  former contains code derived from the library, while the latter only
2923  works together with the library.</P>
2924 <P>Note that it is possible for a library to be covered by the ordinary
2925  General Public License rather than by this special one.</P>
2926 <H4>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H4>
2927 <P><STRONG>0.</STRONG> This License Agreement applies to any software
2928  library which contains a notice placed by the copyright holder or other
2929  authorized party saying it may be distributed under the terms of this
2930  Library General Public License (also called &quot;this License&quot;). Each
2931  licensee is addressed as &quot;you&quot;.</P>
2932 <P>A &quot;library&quot; means a collection of software functions and/or data
2933  prepared so as to be conveniently linked with application programs
2934  (which use some of those functions and data) to form executables.</P>
2935 <P>The &quot;Library&quot;, below, refers to any such software library or work
2936  which has been distributed under these terms. A &quot;work based on the
2937  Library&quot; means either the Library or any derivative work under
2938  copyright law: that is to say, a work containing the Library or a
2939  portion of it, either verbatim or with modifications and/or translated
2940  straightforwardly into another language. (Hereinafter, translation is
2941  included without limitation in the term &quot;modification&quot;.)</P>
2942 <P>&quot;Source code&quot; for a work means the preferred form of the work for
2943  making modifications to it. For a library, complete source code means
2944  all the source code for all modules it contains, plus any associated
2945  interface definition files, plus the scripts used to control
2946  compilation and installation of the library.</P>
2947 <P>Activities other than copying, distribution and modification are not
2948  covered by this License; they are outside its scope. The act of running
2949  a program using the Library is not restricted, and output from such a
2950  program is covered only if its contents constitute a work based on the
2951  Library (independent of the use of the Library in a tool for writing
2952  it). Whether that is true depends on what the Library does and what the
2953  program that uses the Library does.</P>
2954 <P><STRONG>1.</STRONG> You may copy and distribute verbatim copies of
2955  the Library's complete source code as you receive it, in any medium,
2956  provided that you conspicuously and appropriately publish on each copy
2957  an appropriate copyright notice and disclaimer of warranty; keep intact
2958  all the notices that refer to this License and to the absence of any
2959  warranty; and distribute a copy of this License along with the Library.</P>
2960 <P>You may charge a fee for the physical act of transferring a copy, and
2961  you may at your option offer warranty protection in exchange for a fee.</P>
2962 <P><STRONG>2.</STRONG> You may modify your copy or copies of the Library
2963  or any portion of it, thus forming a work based on the Library, and
2964  copy and distribute such modifications or work under the terms of
2965  Section 1 above, provided that you also meet all of these conditions:</P>
2966 <OL TYPE="a">
2967 <LI>The modified work must itself be a software library.</LI>
2968 <P></P>
2969 <LI>You must cause the files modified to carry prominent notices stating
2970  that you changed the files and the date of any change.</LI>
2971 <P></P>
2972 <LI>You must cause the whole of the work to be licensed at no charge to
2973  all third parties under the terms of this License.</LI>
2974 <P></P>
2975 <LI>If a facility in the modified Library refers to a function or a
2976  table of data to be supplied by an application program that uses the
2977  facility, other than as an argument passed when the facility is
2978  invoked, then you must make a good faith effort to ensure that, in the
2979  event an application does not supply such function or table, the
2980  facility still operates, and performs whatever part of its purpose
2981  remains meaningful.</LI>
2982 <P>(For example, a function in a library to compute square roots has a
2983  purpose that is entirely well-defined independent of the application.
2984  Therefore, Subsection 2d requires that any application-supplied
2985  function or table used by this function must be optional: if the
2986  application does not supply it, the square root function must still
2987  compute square roots.)</P>
2988 </OL>
2989 <P>These requirements apply to the modified work as a whole. If
2990  identifiable sections of that work are not derived from the Library,
2991  and can be reasonably considered independent and separate works in
2992  themselves, then this License, and its terms, do not apply to those
2993  sections when you distribute them as separate works. But when you
2994  distribute the same sections as part of a whole which is a work based
2995  on the Library, the distribution of the whole must be on the terms of
2996  this License, whose permissions for other licensees extend to the
2997  entire whole, and thus to each and every part regardless of who wrote
2998  it.</P>
2999 <P>Thus, it is not the intent of this section to claim rights or contest
3000  your rights to work written entirely by you; rather, the intent is to
3001  exercise the right to control the distribution of derivative or
3002  collective works based on the Library.</P>
3003 <P>In addition, mere aggregation of another work not based on the
3004  Library with the Library (or with a work based on the Library) on a
3005  volume of a storage or distribution medium does not bring the other
3006  work under the scope of this License.</P>
3007 <P><STRONG>3.</STRONG> You may opt to apply the terms of the ordinary
3008  GNU General Public License instead of this License to a given copy of
3009  the Library. To do this, you must alter all the notices that refer to
3010  this License, so that they refer to the ordinary GNU General Public
3011  License, version 2, instead of to this License. (If a newer version
3012  than version 2 of the ordinary GNU General Public License has appeared,
3013  then you can specify that version instead if you wish.) Do not make any
3014  other change in these notices.</P>
3015 <P>Once this change is made in a given copy, it is irreversible for that
3016  copy, so the ordinary GNU General Public License applies to all
3017  subsequent copies and derivative works made from that copy.</P>
3018 <P>This option is useful when you wish to copy part of the code of the
3019  Library into a program that is not a library.</P>
3020 <P><STRONG>4.</STRONG> You may copy and distribute the Library (or a
3021  portion or derivative of it, under Section 2) in object code or
3022  executable form under the terms of Sections 1 and 2 above provided that
3023  you accompany it with the complete corresponding machine-readable
3024  source code, which must be distributed under the terms of Sections 1
3025  and 2 above on a medium customarily used for software interchange.</P>
3026 <P>If distribution of object code is made by offering access to copy
3027  from a designated place, then offering equivalent access to copy the
3028  source code from the same place satisfies the requirement to distribute
3029  the source code, even though third parties are not compelled to copy
3030  the source along with the object code.</P>
3031 <P><STRONG>5.</STRONG> A program that contains no derivative of any
3032  portion of the Library, but is designed to work with the Library by
3033  being compiled or linked with it, is called a &quot;work that uses the
3034  Library&quot;. Such a work, in isolation, is not a derivative work of the
3035  Library, and therefore falls outside the scope of this License.</P>
3036 <P>However, linking a &quot;work that uses the Library&quot; with the Library
3037  creates an executable that is a derivative of the Library (because it
3038  contains portions of the Library), rather than a &quot;work that uses the
3039  library&quot;. The executable is therefore covered by this License. Section
3040  6 states terms for distribution of such executables.</P>
3041 <P>When a &quot;work that uses the Library&quot; uses material from a header file
3042  that is part of the Library, the object code for the work may be a
3043  derivative work of the Library even though the source code is not.
3044  Whether this is true is especially significant if the work can be
3045  linked without the Library, or if the work is itself a library. The
3046  threshold for this to be true is not precisely defined by law.</P>
3047 <P>If such an object file uses only numerical parameters, data structure
3048  layouts and accessors, and small macros and small inline functions (ten
3049  lines or less in length), then the use of the object file is
3050  unrestricted, regardless of whether it is legally a derivative work.
3051  (Executables containing this object code plus portions of the Library
3052  will still fall under Section 6.)</P>
3053 <P>Otherwise, if the work is a derivative of the Library, you may
3054  distribute the object code for the work under the terms of Section 6.
3055  Any executables containing that work also fall under Section 6, whether
3056  or not they are linked directly with the Library itself.</P>
3057 <P><STRONG>6.</STRONG> As an exception to the Sections above, you may
3058  also compile or link a &quot;work that uses the Library&quot; with the Library to
3059  produce a work containing portions of the Library, and distribute that
3060  work under terms of your choice, provided that the terms permit
3061  modification of the work for the customer's own use and reverse
3062  engineering for debugging such modifications.</P>
3063 <P>You must give prominent notice with each copy of the work that the
3064  Library is used in it and that the Library and its use are covered by
3065  this License. You must supply a copy of this License. If the work
3066  during execution displays copyright notices, you must include the
3067  copyright notice for the Library among them, as well as a reference
3068  directing the user to the copy of this License. Also, you must do one
3069  of these things:</P>
3070 <OL TYPE="a">
3071 <LI>Accompany the work with the complete corresponding machine-readable
3072  source code for the Library including whatever changes were used in the
3073  work (which must be distributed under Sections 1 and 2 above); and, if
3074  the work is an executable linked with the Library, with the complete
3075  machine-readable &quot;work that uses the Library&quot;, as object code and/or
3076  source code, so that the user can modify the Library and then relink to
3077  produce a modified executable containing the modified Library. (It is
3078  understood that the user who changes the contents of definitions files
3079  in the Library will not necessarily be able to recompile the
3080  application to use the modified definitions.)</LI>
3081 <P></P>
3082 <LI>Accompany the work with a written offer, valid for at least three
3083  years, to give the same user the materials specified in Subsection 6a,
3084  above, for a charge no more than the cost of performing this
3085  distribution.</LI>
3086 <P></P>
3087 <LI>If distribution of the work is made by offering access to copy from
3088  a designated place, offer equivalent access to copy the above specified
3089  materials from the same place.</LI>
3090 <P></P>
3091 <LI>Verify that the user has already received a copy of these materials
3092  or that you have already sent this user a copy.</LI>
3093 </OL>
3094 <P>For an executable, the required form of the &quot;work that uses the
3095  Library&quot; must include any data and utility programs needed for
3096  reproducing the executable from it. However, as a special exception,
3097  the source code distributed need not include anything that is normally
3098  distributed (in either source or binary form) with the major components
3099  (compiler, kernel, and so on) of the operating system on which the
3100  executable runs, unless that component itself accompanies the
3101  executable.</P>
3102 <P>It may happen that this requirement contradicts the license
3103  restrictions of other proprietary libraries that do not normally
3104  accompany the operating system. Such a contradiction means you cannot
3105  use both them and the Library together in an executable that you
3106  distribute.</P>
3107 <P><STRONG>7.</STRONG> You may place library facilities that are a work
3108  based on the Library side-by-side in a single library together with
3109  other library facilities not covered by this License, and distribute
3110  such a combined library, provided that the separate distribution of the
3111  work based on the Library and of the other library facilities is
3112  otherwise permitted, and provided that you do these two things:</P>
3113 <OL TYPE="a">
3114 <LI>Accompany the combined library with a copy of the same work based on
3115  the Library, uncombined with any other library facilities. This must be
3116  distributed under the terms of the Sections above.</LI>
3117 <P></P>
3118 <LI>Give prominent notice with the combined library of the fact that
3119  part of it is a work based on the Library, and explaining where to find
3120  the accompanying uncombined form of the same work.</LI>
3121 </OL>
3122 <P><STRONG>8.</STRONG> You may not copy, modify, sublicense, link with,
3123  or distribute the Library except as expressly provided under this
3124  License. Any attempt otherwise to copy, modify, sublicense, link with,
3125  or distribute the Library is void, and will automatically terminate
3126  your rights under this License. However, parties who have received
3127  copies, or rights, from you under this License will not have their
3128  licenses terminated so long as such parties remain in full compliance.</P>
3129 <P><STRONG>9.</STRONG> You are not required to accept this License,
3130  since you have not signed it. However, nothing else grants you
3131  permission to modify or distribute the Library or its derivative works.
3132  These actions are prohibited by law if you do not accept this License.
3133  Therefore, by modifying or distributing the Library (or any work based
3134  on the Library), you indicate your acceptance of this License to do so,
3135  and all its terms and conditions for copying, distributing or modifying
3136  the Library or works based on it.</P>
3137 <P><STRONG>10.</STRONG> Each time you redistribute the Library (or any
3138  work based on the Library), the recipient automatically receives a
3139  license from the original licensor to copy, distribute, link with or
3140  modify the Library subject to these terms and conditions. You may not
3141  impose any further restrictions on the recipients' exercise of the
3142  rights granted herein. You are not responsible for enforcing compliance
3143  by third parties to this License.</P>
3144 <P><STRONG>11.</STRONG> If, as a consequence of a court judgment or
3145  allegation of patent infringement or for any other reason (not limited
3146  to patent issues), conditions are imposed on you (whether by court
3147  order, agreement or otherwise) that contradict the conditions of this
3148  License, they do not excuse you from the conditions of this License. If
3149  you cannot distribute so as to satisfy simultaneously your obligations
3150  under this License and any other pertinent obligations, then as a
3151  consequence you may not distribute the Library at all. For example, if
3152  a patent license would not permit royalty-free redistribution of the
3153  Library by all those who receive copies directly or indirectly through
3154  you, then the only way you could satisfy both it and this License would
3155  be to refrain entirely from distribution of the Library.</P>
3156 <P>If any portion of this section is held invalid or unenforceable under
3157  any particular circumstance, the balance of the section is intended to
3158  apply, and the section as a whole is intended to apply in other
3159  circumstances.</P>
3160 <P>It is not the purpose of this section to induce you to infringe any
3161  patents or other property right claims or to contest validity of any
3162  such claims; this section has the sole purpose of protecting the
3163  integrity of the free software distribution system which is implemented
3164  by public license practices. Many people have made generous
3165  contributions to the wide range of software distributed through that
3166  system in reliance on consistent application of that system; it is up
3167  to the author/donor to decide if he or she is willing to distribute
3168  software through any other system and a licensee cannot impose that
3169  choice.</P>
3170 <P>This section is intended to make thoroughly clear what is believed to
3171  be a consequence of the rest of this License.</P>
3172 <P><STRONG>12.</STRONG> If the distribution and/or use of the Library is
3173  restricted in certain countries either by patents or by copyrighted
3174  interfaces, the original copyright holder who places the Library under
3175  this License may add an explicit geographical distribution limitation
3176  excluding those countries, so that distribution is permitted only in or
3177  among countries not thus excluded. In such case, this License
3178  incorporates the limitation as if written in the body of this License.</P>
3179 <P><STRONG>13.</STRONG> The Free Software Foundation may publish revised
3180  and/or new versions of the Library General Public License from time to
3181  time. Such new versions will be similar in spirit to the present
3182  version, but may differ in detail to address new problems or concerns.</P>
3183 <P>Each version is given a distinguishing version number. If the Library
3184  specifies a version number of this License which applies to it and &quot;any
3185  later version&quot;, you have the option of following the terms and
3186  conditions either of that version or of any later version published by
3187  the Free Software Foundation. If the Library does not specify a license
3188  version number, you may choose any version ever published by the Free
3189  Software Foundation.</P>
3190 <P><STRONG>14.</STRONG> If you wish to incorporate parts of the Library
3191  into other free programs whose distribution conditions are incompatible
3192  with these, write to the author to ask for permission. For software
3193  which is copyrighted by the Free Software Foundation, write to the Free
3194  Software Foundation; we sometimes make exceptions for this. Our
3195  decision will be guided by the two goals of preserving the free status
3196  of all derivatives of our free software and of promoting the sharing
3197  and reuse of software generally.</P>
3198 <P><STRONG>NO WARRANTY</STRONG></P>
3199 <P><STRONG>15.</STRONG> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,
3200  THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY
3201  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
3202  HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY &quot;AS IS&quot; WITHOUT
3203  WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
3204  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
3205  PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
3206  OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
3207  ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</P>
3208 <P><STRONG>16.</STRONG> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
3209  AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO
3210  MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
3211  LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
3212  OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
3213  LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
3214  RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
3215  FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
3216  SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
3217  DAMAGES.</P>
3218 <H4>END OF TERMS AND CONDITIONS</H4>
3219 <H1 ALIGN="RIGHT"><A NAME="CONSTANTS">B - Constants</A></H1>
3220 <P>This appendix lists all of the constants that are defined by the CUPS
3221  API.</P>
3222 <H2><A NAME="8_1">CUPS Constants</A></H2>
3223 <H3><A NAME="8_1_1">Version Number</A></H3>
3224 <P>The <CODE>CUPS_VERSION</CODE> constant is a floating-point number
3225  representing the API version number. The current version number is
3226  1.0100 which represents CUPS version 1.1.0.</P>
3227 <H3><A NAME="8_1_2">Printer Capabilities</A></H3>
3228 <P>The <CODE>CUPS_PRINTER</CODE> constants represent capability bits for
3229  printers and classes:</P>
3230 <UL>
3231 <LI><CODE>CUPS_PRINTER_LOCAL</CODE> - Is a local printer or class.</LI>
3232 <LI><CODE>CUPS_PRINTER_REMOTE</CODE> - Is a remote printer or class.</LI>
3233 <LI><CODE>CUPS_PRINTER_CLASS</CODE> - Is a class.</LI>
3234 <LI><CODE>CUPS_PRINTER_BW</CODE> - Printer prints in black and white.</LI>
3235 <LI><CODE>CUPS_PRINTER_COLOR</CODE> - Printer prints in color.</LI>
3236 <LI><CODE>CUPS_PRINTER_DUPLEX</CODE> - Printer can print double-sided.</LI>
3237 <LI><CODE>CUPS_PRINTER_STAPLE</CODE> - Printer can staple output.</LI>
3238 <LI><CODE>CUPS_PRINTER_COPIES</CODE> - Printer can produce multiple
3239  copies on its own.</LI>
3240 <LI><CODE>CUPS_PRINTER_COLLATE</CODE> - Printer can collate copies.</LI>
3241 <LI><CODE>CUPS_PRINTER_PUNCH</CODE> - Printer can punch holes in output.</LI>
3242 <LI><CODE>CUPS_PRINTER_COVER</CODE> - Printer can put covers on output.</LI>
3243 <LI><CODE>CUPS_PRINTER_BIND</CODE> - Printer can bind output.</LI>
3244 <LI><CODE>CUPS_PRINTER_SORT</CODE> - Printer can sort output.</LI>
3245 <LI><CODE>CUPS_PRINTER_SMALL</CODE> - Printer can print on media up to
3246  9x14 inches.</LI>
3247 <LI><CODE>CUPS_PRINTER_MEDIUM</CODE> - Printer can print on media from
3248  9x14 to 18x24 inches.</LI>
3249 <LI><CODE>CUPS_PRINTER_LARGE</CODE> - Printer can print on media larger
3250  than 18x24 inches.</LI>
3251 <LI><CODE>CUPS_PRINTER_VARIABLE</CODE> - Printer can print on variable
3252  or custom media sizes.</LI>
3253 <LI><CODE>CUPS_PRINTER_IMPLICIT</CODE> - Is an implicit class.</LI>
3254 <LI><CODE>CUPS_PRINTER_OPTIONS</CODE> - All of the printer capability
3255  and option bits.</LI>
3256 </UL>
3257 <H3><A NAME="8_1_3">Encodings</A></H3>
3258 <P>CUPS defines the following character set encoding constants:</P>
3259 <UL>
3260 <LI><CODE>CUPS_US_ASCII</CODE> - US ASCII character set.</LI>
3261 <LI><CODE>CUPS_UTF_8</CODE> - UTF-8 encoding of Unicode.</LI>
3262 <LI><CODE>CUPS_ISO8859_1</CODE> - ISO-8859-1 character set.</LI>
3263 <LI><CODE>CUPS_ISO8859_2</CODE> - ISO-8859-2 character set.</LI>
3264 <LI><CODE>CUPS_ISO8859_3</CODE> - ISO-8859-3 character set.</LI>
3265 <LI><CODE>CUPS_ISO8859_4</CODE> - ISO-8859-4 character set.</LI>
3266 <LI><CODE>CUPS_ISO8859_5</CODE> - ISO-8859-5 character set.</LI>
3267 <LI><CODE>CUPS_ISO8859_6</CODE> - ISO-8859-6 character set.</LI>
3268 <LI><CODE>CUPS_ISO8859_7</CODE> - ISO-8859-7 character set.</LI>
3269 <LI><CODE>CUPS_ISO8859_8</CODE> - ISO-8859-8 character set.</LI>
3270 <LI><CODE>CUPS_ISO8859_9</CODE> - ISO-8859-9 character set.</LI>
3271 <LI><CODE>CUPS_ISO8859_10</CODE> - ISO-8859-10 character set.</LI>
3272 <LI><CODE>CUPS_ISO8859_13</CODE> - ISO-8859-13 character set.</LI>
3273 <LI><CODE>CUPS_ISO8859_14</CODE> - ISO-8859-14 character set.</LI>
3274 <LI><CODE>CUPS_ISO8859_15</CODE> - ISO-8859-15 character set.</LI>
3275 <LI><CODE>CUPS_WINDOWS_874</CODE> - Windows code page 874.</LI>
3276 <LI><CODE>CUPS_WINDOWS_1250</CODE> - Windows code page 1250.</LI>
3277 <LI><CODE>CUPS_WINDOWS_1251</CODE> - Windows code page 1251.</LI>
3278 <LI><CODE>CUPS_WINDOWS_1252</CODE> - Windows code page 1252.</LI>
3279 <LI><CODE>CUPS_WINDOWS_1253</CODE> - Windows code page 1253.</LI>
3280 <LI><CODE>CUPS_WINDOWS_1254</CODE> - Windows code page 1254.</LI>
3281 <LI><CODE>CUPS_WINDOWS_1255</CODE> - Windows code page 1255.</LI>
3282 <LI><CODE>CUPS_WINDOWS_1256</CODE> - Windows code page 1256.</LI>
3283 <LI><CODE>CUPS_WINDOWS_1257</CODE> - Windows code page 1257.</LI>
3284 <LI><CODE>CUPS_WINDOWS_1258</CODE> - Windows code page 1258.</LI>
3285 </UL>
3286 <H2><A NAME="8_2">HTTP Constants</A></H2>
3287 <H3><A NAME="8_2_1">Limits</A></H3>
3288 <P>The following constants define the limits for strings:</P>
3289 <UL>
3290 <LI><CODE>HTTP_MAX_BUFFER</CODE> - Size of socket buffer.</LI>
3291 <LI><CODE>HTTP_MAX_HOST</CODE> - Maximum length of hostname.</LI>
3292 <LI><CODE>HTTP_MAX_URI</CODE> - Maximum length of URI.</LI>
3293 <LI><CODE>HTTP_MAX_VALUE</CODE> - Maximum length of field values.</LI>
3294 </UL>
3295 <H3><A NAME="8_2_2">Status Codes</A></H3>
3296 <P>The following status codes can be returned by <CODE>httpUpdate()</CODE>
3297 :</P>
3298 <UL>
3299 <LI><CODE>HTTP_ERROR</CODE> - A network error occurred</LI>
3300 <LI><CODE>HTTP_CONTINUE</CODE> - Continue response from HTTP proxy</LI>
3301 <LI><CODE>HTTP_OK</CODE> - OPTIONS/GET/HEAD/POST/TRACE command was
3302  successful</LI>
3303 <LI><CODE>HTTP_CREATED</CODE> - PUT command was successful</LI>
3304 <LI><CODE>HTTP_ACCEPTED</CODE> - DELETE command was successful</LI>
3305 <LI><CODE>HTTP_NOT_AUTHORITATIVE</CODE> - Information isn't
3306  authoritative</LI>
3307 <LI><CODE>HTTP_NO_CONTENT</CODE> - Successful command</LI>
3308 <LI><CODE>HTTP_RESET_CONTENT</CODE> - Content was reset/recreated</LI>
3309 <LI><CODE>HTTP_PARTIAL_CONTENT</CODE> - Only a partial file was
3310  recieved/sent</LI>
3311 <LI><CODE>HTTP_MULTIPLE_CHOICES</CODE> - Multiple files match request</LI>
3312 <LI><CODE>HTTP_MOVED_PERMANENTLY</CODE> - Document has moved permanently</LI>
3313 <LI><CODE>HTTP_MOVED_TEMPORARILY</CODE> - Document has moved temporarily</LI>
3314 <LI><CODE>HTTP_SEE_OTHER</CODE> - See this other link...</LI>
3315 <LI><CODE>HTTP_NOT_MODIFIED</CODE> - File not modified</LI>
3316 <LI><CODE>HTTP_USE_PROXY</CODE> - Must use a proxy to access this URI</LI>
3317 <LI><CODE>HTTP_BAD_REQUEST</CODE> - Bad request</LI>
3318 <LI><CODE>HTTP_UNAUTHORIZED</CODE> - Unauthorized to access host</LI>
3319 <LI><CODE>HTTP_PAYMENT_REQUIRED</CODE> - Payment required</LI>
3320 <LI><CODE>HTTP_FORBIDDEN</CODE> - Forbidden to access this URI</LI>
3321 <LI><CODE>HTTP_NOT_FOUND</CODE> - URI was not found</LI>
3322 <LI><CODE>HTTP_METHOD_NOT_ALLOWED</CODE> - Method is not allowed</LI>
3323 <LI><CODE>HTTP_NOT_ACCEPTABLE</CODE> - Not Acceptable</LI>
3324 <LI><CODE>HTTP_PROXY_AUTHENTICATION</CODE> - Proxy Authentication is
3325  Required</LI>
3326 <LI><CODE>HTTP_REQUEST_TIMEOUT</CODE> - Request timed out</LI>
3327 <LI><CODE>HTTP_CONFLICT</CODE> - Request is self-conflicting</LI>
3328 <LI><CODE>HTTP_GONE</CODE> - Server has gone away</LI>
3329 <LI><CODE>HTTP_LENGTH_REQUIRED</CODE> - A content length or encoding is
3330  required</LI>
3331 <LI><CODE>HTTP_PRECONDITION</CODE> - Precondition failed</LI>
3332 <LI><CODE>HTTP_REQUEST_TOO_LARGE</CODE> - Request entity too large</LI>
3333 <LI><CODE>HTTP_URI_TOO_LONG</CODE> - URI too long</LI>
3334 <LI><CODE>HTTP_UNSUPPORTED_MEDIATYPE</CODE> - The requested media type
3335  is unsupported</LI>
3336 <LI><CODE>HTTP_SERVER_ERROR</CODE> - Internal server error</LI>
3337 <LI><CODE>HTTP_NOT_IMPLEMENTED</CODE> - Feature not implemented</LI>
3338 <LI><CODE>HTTP_BAD_GATEWAY</CODE> - Bad gateway</LI>
3339 <LI><CODE>HTTP_SERVICE_UNAVAILABLE</CODE> - Service is unavailable</LI>
3340 <LI><CODE>HTTP_GATEWAY_TIMEOUT</CODE> - Gateway connection timed out</LI>
3341 <LI><CODE>HTTP_NOT_SUPPORTED</CODE> - HTTP version not supported</LI>
3342 </UL>
3343 <H3><A NAME="8_2_3">Fields</A></H3>
3344 <P>The following fields are indices for each of the standard HTTP fields
3345  in HTTP 1/1:</P>
3346 <UL>
3347 <LI><CODE>HTTP_FIELD_ACCEPT_LANGUAGE</CODE> - Accept-Language</LI>
3348 <LI><CODE>HTTP_FIELD_ACCEPT_RANGES</CODE> - Accept-Ranges</LI>
3349 <LI><CODE>HTTP_FIELD_AUTHORIZATION</CODE> - Authorization</LI>
3350 <LI><CODE>HTTP_FIELD_CONNECTION</CODE> - Connection</LI>
3351 <LI><CODE>HTTP_FIELD_CONTENT_ENCODING</CODE> - Content-Encoding</LI>
3352 <LI><CODE>HTTP_FIELD_CONTENT_LANGUAGE</CODE> - Content-Language</LI>
3353 <LI><CODE>HTTP_FIELD_CONTENT_LENGTH</CODE> - Content-Length</LI>
3354 <LI><CODE>HTTP_FIELD_CONTENT_LOCATION</CODE> - Content-Location</LI>
3355 <LI><CODE>HTTP_FIELD_CONTENT_MD5</CODE> - Content-MD5</LI>
3356 <LI><CODE>HTTP_FIELD_CONTENT_RANGE</CODE> - Content-Range</LI>
3357 <LI><CODE>HTTP_FIELD_CONTENT_TYPE</CODE> - Content-Type</LI>
3358 <LI><CODE>HTTP_FIELD_CONTENT_VERSION</CODE> - Content-Version</LI>
3359 <LI><CODE>HTTP_FIELD_DATE</CODE> - Date</LI>
3360 <LI><CODE>HTTP_FIELD_HOST</CODE> - Host</LI>
3361 <LI><CODE>HTTP_FIELD_IF_MODIFIED_SINCE</CODE> - If-Modified-Since</LI>
3362 <LI><CODE>HTTP_FIELD_IF_UNMODIFIED_SINCE</CODE> - If-Unmodified-Since</LI>
3363 <LI><CODE>HTTP_FIELD_KEEP_ALIVE</CODE> - Keep-Alive</LI>
3364 <LI><CODE>HTTP_FIELD_LAST_MODIFIED</CODE> - Last-Modified</LI>
3365 <LI><CODE>HTTP_FIELD_LINK</CODE> - Link</LI>
3366 <LI><CODE>HTTP_FIELD_LOCATION</CODE> - Location</LI>
3367 <LI><CODE>HTTP_FIELD_RANGE</CODE> - Range</LI>
3368 <LI><CODE>HTTP_FIELD_REFERER</CODE> - Referer</LI>
3369 <LI><CODE>HTTP_FIELD_RETRY_AFTER</CODE> - Retry-After</LI>
3370 <LI><CODE>HTTP_FIELD_TRANSFER_ENCODING</CODE> - Transfer-Encoding</LI>
3371 <LI><CODE>HTTP_FIELD_UPGRADE</CODE> - Upgrade</LI>
3372 <LI><CODE>HTTP_FIELD_USER_AGENT</CODE> - User-Agent</LI>
3373 <LI><CODE>HTTP_FIELD_WWW_AUTHENTICATE</CODE> - WWW-Authenticate</LI>
3374 </UL>
3375 <H2><A NAME="8_3">IPP Constants</A></H2>
3376 <H3><A NAME="8_3_1">Limits</A></H3>
3377 <P>The following constants define array limits for IPP data:</P>
3378 <UL>
3379 <LI><CODE>IPP_MAX_NAME</CODE> - Maximum length of an attribute name</LI>
3380 <LI><CODE>IPP_MAX_VALUES</CODE> - Maximum number of set-of values that
3381  can be read in a request.</LI>
3382 </UL>
3383 <H3><A NAME="8_3_2">Tags</A></H3>
3384 <UL>
3385 <LI><CODE>IPP_TAG_ZERO</CODE> - Wildcard tag value for searches; also
3386  used to separate groups of attributes</LI>
3387 <LI><CODE>IPP_TAG_OPERATION</CODE> - Tag for values of type operation</LI>
3388 <LI><CODE>IPP_TAG_JOB</CODE> - Tag for values of type job</LI>
3389 <LI><CODE>IPP_TAG_END</CODE> - Tag for values of type end</LI>
3390 <LI><CODE>IPP_TAG_PRINTER</CODE> - Tag for values of type printer</LI>
3391 <LI><CODE>IPP_TAG_UNSUPPORTED_GROUP</CODE> - Tag for values of type
3392  unsupported_group</LI>
3393 <LI><CODE>IPP_TAG_UNSUPPORTED_VALUE</CODE> - Tag for values of type
3394  unsupported_value</LI>
3395 <LI><CODE>IPP_TAG_DEFAULT</CODE> - Tag for values of type default</LI>
3396 <LI><CODE>IPP_TAG_UNKNOWN</CODE> - Tag for values of type unknown</LI>
3397 <LI><CODE>IPP_TAG_NOVALUE</CODE> - Tag for values of type novalue</LI>
3398 <LI><CODE>IPP_TAG_NOTSETTABLE</CODE> - Tag for values of type
3399  notsettable</LI>
3400 <LI><CODE>IPP_TAG_DELETEATTR</CODE> - Tag for values of type deleteattr</LI>
3401 <LI><CODE>IPP_TAG_ANYVALUE</CODE> - Tag for values of type anyvalue</LI>
3402 <LI><CODE>IPP_TAG_INTEGER</CODE> - Tag for values of type integer</LI>
3403 <LI><CODE>IPP_TAG_BOOLEAN</CODE> - Tag for values of type boolean</LI>
3404 <LI><CODE>IPP_TAG_ENUM</CODE> - Tag for values of type enum</LI>
3405 <LI><CODE>IPP_TAG_STRING</CODE> - Tag for values of type string</LI>
3406 <LI><CODE>IPP_TAG_DATE</CODE> - Tag for values of type date</LI>
3407 <LI><CODE>IPP_TAG_RESOLUTION</CODE> - Tag for values of type resolution</LI>
3408 <LI><CODE>IPP_TAG_RANGE</CODE> - Tag for values of type range</LI>
3409 <LI><CODE>IPP_TAG_COLLECTION</CODE> - Tag for values of type collection</LI>
3410 <LI><CODE>IPP_TAG_TEXTLANG</CODE> - Tag for values of type textlang</LI>
3411 <LI><CODE>IPP_TAG_NAMELANG</CODE> - Tag for values of type namelang</LI>
3412 <LI><CODE>IPP_TAG_TEXT</CODE> - Tag for values of type text</LI>
3413 <LI><CODE>IPP_TAG_NAME</CODE> - Tag for values of type name</LI>
3414 <LI><CODE>IPP_TAG_KEYWORD</CODE> - Tag for values of type keyword</LI>
3415 <LI><CODE>IPP_TAG_URI</CODE> - Tag for values of type uri</LI>
3416 <LI><CODE>IPP_TAG_URISCHEME</CODE> - Tag for values of type urischeme</LI>
3417 <LI><CODE>IPP_TAG_CHARSET</CODE> - Tag for values of type charset</LI>
3418 <LI><CODE>IPP_TAG_LANGUAGE</CODE> - Tag for values of type language</LI>
3419 <LI><CODE>IPP_TAG_MIMETYPE</CODE> - Tag for values of type mimetype</LI>
3420 </UL>
3421 <H3><A NAME="8_3_3">Resolution Units</A></H3>
3422 <P>The <CODE>IPP_RES_PER_INCH</CODE> and <CODE>IPP_RES_PER_CM</CODE>
3423  constants specify dots per inch and dots per centimeter, respectively.</P>
3424 <H3><A NAME="8_3_4">Finishings</A></H3>
3425 <P>The finishing values specify special finishing operations to be
3426  performed on the job.</P>
3427 <UL>
3428 <LI><CODE>IPP_FINISH_NONE</CODE> - Do no finishing</LI>
3429 <LI><CODE>IPP_FINISH_STAPLE</CODE> - Staple the job</LI>
3430 <LI><CODE>IPP_FINISH_PUNCH</CODE> - Punch the job</LI>
3431 <LI><CODE>IPP_FINISH_COVER</CODE> - Cover the job</LI>
3432 <LI><CODE>IPP_FINISH_BIND</CODE> - Bind the job</LI>
3433 </UL>
3434 <H3><A NAME="8_3_5">Orientations</A></H3>
3435 <P>The orientation values specify the orientation of the job.</P>
3436 <UL>
3437 <LI><CODE>IPP_PORTRAIT</CODE> - No rotation</LI>
3438 <LI><CODE>IPP_LANDSCAPE</CODE> - 90 degrees counter-clockwise</LI>
3439 <LI><CODE>IPP_REVERSE_LANDSCAPE</CODE> - 90 degrees clockwise</LI>
3440 <LI><CODE>IPP_REVERSE_PORTRAIT</CODE> - 180 degrees</LI>
3441 </UL>
3442 <H3><A NAME="8_3_6">Qualities</A></H3>
3443 <P>The quality values specify the desired quality of the print.</P>
3444 <UL>
3445 <LI><CODE>IPP_QUALITY_DRAFT</CODE> - Draft quality</LI>
3446 <LI><CODE>IPP_QUALITY_NORMAL</CODE> - Normal quality</LI>
3447 <LI><CODE>IPP_QUALITY_HIGH</CODE> - High quality</LI>
3448 </UL>
3449 <H3><A NAME="8_3_7">Job States</A></H3>
3450 <P>The job state values are used to represent the current job state.</P>
3451 <UL>
3452 <LI><CODE>IPP_JOB_PENDING</CODE> - Job is pending</LI>
3453 <LI><CODE>IPP_JOB_HELD</CODE> - Job is held</LI>
3454 <LI><CODE>IPP_JOB_PROCESSING</CODE> - Job is processing</LI>
3455 <LI><CODE>IPP_JOB_STOPPED</CODE> - Job is stopped</LI>
3456 <LI><CODE>IPP_JOB_CANCELLED</CODE> - Job is cancelled</LI>
3457 <LI><CODE>IPP_JOB_ABORTED</CODE> - Job is aborted</LI>
3458 <LI><CODE>IPP_JOB_COMPLETED</CODE> - Job is completed</LI>
3459 </UL>
3460 <H3><A NAME="8_3_8">Printer States</A></H3>
3461 <P>The printer state values are used to represent the current printer
3462  state.</P>
3463 <UL>
3464 <LI><CODE>IPP_PRINTER_IDLE</CODE> - Printer is idle</LI>
3465 <LI><CODE>IPP_PRINTER_PROCESSING</CODE> - Printer is processing</LI>
3466 <LI><CODE>IPP_PRINTER_STOPPED</CODE> - Printer is stopped</LI>
3467 </UL>
3468 <H3><A NAME="8_3_9">Operations</A></H3>
3469 <P>The operation values represent the available IPP operations.</P>
3470 <UL>
3471 <LI><CODE>IPP_PRINT_JOB</CODE> - Print a file</LI>
3472 <LI><CODE>IPP_PRINT_URI</CODE> - Print a URI</LI>
3473 <LI><CODE>IPP_VALIDATE_JOB</CODE> - Validate job attributes</LI>
3474 <LI><CODE>IPP_CREATE_JOB</CODE> - Create a new job</LI>
3475 <LI><CODE>IPP_SEND_DOCUMENT</CODE> - Send a document to a job</LI>
3476 <LI><CODE>IPP_SEND_URI</CODE> - Send a URI to a job</LI>
3477 <LI><CODE>IPP_CANCEL_JOB</CODE> - Cancel a job</LI>
3478 <LI><CODE>IPP_GET_JOB_ATTRIBUTES</CODE> - Get job attributes</LI>
3479 <LI><CODE>IPP_GET_JOBS</CODE> - Get a list of all jobs</LI>
3480 <LI><CODE>IPP_GET_PRINTER_ATTRIBUTES</CODE> - Get printer attributes</LI>
3481 <LI><CODE>IPP_HOLD_JOB</CODE> - Hold a pending job</LI>
3482 <LI><CODE>IPP_RELEASE_JOB</CODE> - Release a held job</LI>
3483 <LI><CODE>IPP_RESTART_JOB</CODE> - Restart a completed job</LI>
3484 <LI><CODE>IPP_PAUSE_PRINTER</CODE> - Pause a printer</LI>
3485 <LI><CODE>IPP_RESUME_PRINTER</CODE> - Restart a paused printer</LI>
3486 <LI><CODE>IPP_PURGE_JOBS</CODE> - Purge jobs from the queue</LI>
3487 <LI><CODE>IPP_SET_PRINTER_ATTRIBUTES</CODE> - Set printer attributes</LI>
3488 <LI><CODE>IPP_SET_JOB_ATTRIBUTES</CODE> - Set job attributes</LI>
3489 <LI><CODE>IPP_GET_PRINTER_SUPPORTED_VALUES</CODE> - Get printer
3490  supported values</LI>
3491 <LI><CODE>CUPS_GET_DEFAULT</CODE> - Get the default destination</LI>
3492 <LI><CODE>CUPS_GET_PRINTERS</CODE> - Get a list of all printers</LI>
3493 <LI><CODE>CUPS_ADD_PRINTER</CODE> - Add or modify a printer</LI>
3494 <LI><CODE>CUPS_DELETE_PRINTER</CODE> - Delete a printer</LI>
3495 <LI><CODE>CUPS_GET_CLASSES</CODE> - Get a list of all classes</LI>
3496 <LI><CODE>CUPS_ADD_CLASS</CODE> - Add or modify a class</LI>
3497 <LI><CODE>CUPS_DELETE_CLASS</CODE> - Delete a class</LI>
3498 <LI><CODE>CUPS_ACCEPT_JOBS</CODE> - Accept jobs on a printer or class</LI>
3499 <LI><CODE>CUPS_REJECT_JOBS</CODE> - Reject jobs on a printer or class</LI>
3500 <LI><CODE>CUPS_SET_DEFAULT</CODE> - Set the default destination</LI>
3501 <LI><CODE>CUPS_GET_DEVICES</CODE> - Get a list of all devices</LI>
3502 <LI><CODE>CUPS_GET_PPDS</CODE> - Get a list of all PPDs</LI>
3503 <LI><CODE>CUPS_MOVE_JOB</CODE> - Move a job to a new destination</LI>
3504 </UL>
3505 <H3><A NAME="8_3_10">Status Codes</A></H3>
3506 <P>Status codes are returned by all IPP requests.</P>
3507 <UL>
3508 <LI><CODE>IPP_OK</CODE> - Request completed with no errors</LI>
3509 <LI><CODE>IPP_OK_SUBST</CODE> - Request completed but some attribute
3510  values were substituted</LI>
3511 <LI><CODE>IPP_OK_CONFLICT</CODE> - Request completed but some attributes
3512  conflicted</LI>
3513 <LI><CODE>IPP_BAD_REQUEST</CODE> - The request was bad</LI>
3514 <LI><CODE>IPP_FORBIDDEN</CODE> - You don't have access to the resource</LI>
3515 <LI><CODE>IPP_NOT_AUTHENTICATED</CODE> - You are not authenticated for
3516  the resource</LI>
3517 <LI><CODE>IPP_NOT_AUTHORIZED</CODE> - You not authorized to access the
3518  resource</LI>
3519 <LI><CODE>IPP_NOT_POSSIBLE</CODE> - The requested operation cannot be
3520  completed</LI>
3521 <LI><CODE>IPP_TIMEOUT</CODE> - A timeout occurred</LI>
3522 <LI><CODE>IPP_NOT_FOUND</CODE> - The resource was not found</LI>
3523 <LI><CODE>IPP_GONE</CODE> - The resource has gone away</LI>
3524 <LI><CODE>IPP_REQUEST_ENTITY</CODE> - The request was too large</LI>
3525 <LI><CODE>IPP_REQUEST_VALUE</CODE> - The request contained a value that
3526  was unknown to the server</LI>
3527 <LI><CODE>IPP_DOCUMENT_FORMAT</CODE> - The document format is not
3528  supported by the server</LI>
3529 <LI><CODE>IPP_ATTRIBUTES</CODE> - Required attributes are missing</LI>
3530 <LI><CODE>IPP_URI_SCHEME</CODE> - The URI scheme is not supported</LI>
3531 <LI><CODE>IPP_CHARSET</CODE> - The charset is not supported</LI>
3532 <LI><CODE>IPP_CONFLICT</CODE> - One or more attributes conflict</LI>
3533 <LI><CODE>IPP_COMPRESSION_NOT_SUPPORTED</CODE> - The specified
3534  compression is not supported</LI>
3535 <LI><CODE>IPP_COMPRESSION_ERROR</CODE> - The compressed data contained
3536  an error</LI>
3537 <LI><CODE>IPP_DOCUMENT_FORMAT_ERROR</CODE> - The document data contained
3538  an error in it</LI>
3539 <LI><CODE>IPP_DOCUMENT_ACCESS_ERROR</CODE> - The remote document could
3540  not be accessed</LI>
3541 <LI><CODE>IPP_INTERNAL_ERROR</CODE> - The server encountered an internal
3542  error</LI>
3543 <LI><CODE>IPP_OPERATION_NOT_SUPPORTED</CODE> - The requested operation
3544  is not supported</LI>
3545 <LI><CODE>IPP_SERVICE_UNAVAILABLE</CODE> - The requested service is
3546  unavailable</LI>
3547 <LI><CODE>IPP_VERSION_NOT_SUPPORTED</CODE> - The IPP request version is
3548  not supported</LI>
3549 <LI><CODE>IPP_DEVICE_ERROR</CODE> - The output device encountered an
3550  error</LI>
3551 <LI><CODE>IPP_TEMPORARY_ERROR</CODE> - A temporary error occurred</LI>
3552 <LI><CODE>IPP_NOT_ACCEPTING</CODE> - The destination is not accepting
3553  jobs</LI>
3554 <LI><CODE>IPP_PRINTER_BUSY</CODE> - The destination is busy</LI>
3555 <LI><CODE>IPP_ERROR_JOB_CANCELLED</CODE> - The requested job has been
3556  cancelled</LI>
3557 <LI><CODE>IPP_MULTIPLE_JOBS_NOT_SUPPORTED</CODE> - The server does not
3558  support multiple jobs</LI>
3559 </UL>
3560 <H2><A NAME="8_4">PPD Constants</A></H2>
3561 <H3><A NAME="8_4_1">PPD Format Version</A></H3>
3562 <P>The <CODE>PPD_VERSION</CODE> constant defines a floating point number
3563  representing the newest format version that is supported by CUPS,
3564  currently 4.3.</P>
3565 <H3><A NAME="8_4_2">PPD User-Interface Types</A></H3>
3566 <P>Each printer option has a type associated with it:</P>
3567 <UL>
3568 <LI><CODE>PPD_UI_BOOLEAN</CODE> - The user can turn this option on or
3569  off</LI>
3570 <LI><CODE>PPD_UI_PICKONE</CODE> - The user can choose one option value
3571  to use.</LI>
3572 <LI><CODE>PPD_UI_PICKMANY</CODE> - The user can choose zero or more
3573  option values.</LI>
3574 </UL>
3575 <H3><A NAME="8_4_3">PPD Sections</A></H3>
3576 <P>Some options must be output before others, or in different sections
3577  of the output document. The <CODE>ppd_section_t</CODE> enumeration
3578  defines which section the option must be output in:</P>
3579 <UL>
3580 <LI><CODE>PPD_ORDER_ANY</CODE> - The option can be output in any of the
3581  document, page, or prolog sections of the document</LI>
3582 <LI><CODE>PPD_ORDER_DOCUMENT</CODE> - The option must be output in the
3583  DocumentSetup section of the document</LI>
3584 <LI><CODE>PPD_ORDER_EXIT</CODE> - The option must be output before the
3585  document</LI>
3586 <LI><CODE>PPD_ORDER_JCL</CODE> - The option must be output in the job
3587  control section of the document</LI>
3588 <LI><CODE>PPD_ORDER_PAGE</CODE> - The option must be output in the
3589  PageSetup section of the document</LI>
3590 <LI><CODE>PPD_ORDER_PROLOG</CODE> - The option must be output in the
3591  Prolog section of the document</LI>
3592 </UL>
3593 <H3><A NAME="8_4_4">PPD Colorspaces</A></H3>
3594 <P>Each printer has a default colorspace:</P>
3595 <UL>
3596 <LI><CODE>PPD_CS_CMYK</CODE> - The printer uses CMYK colors by default</LI>
3597 <LI><CODE>PPD_CS_CMY</CODE> - The printer uses CMY colors by default</LI>
3598 <LI><CODE>PPD_CS_GRAY</CODE> - The printer uses grayscale by default</LI>
3599 <LI><CODE>PPD_CS_RGB</CODE> - The printer uses RGB colors by default</LI>
3600 <LI><CODE>PPD_CS_RGBK</CODE> - The printer uses RGBK colors by default</LI>
3601 <LI><CODE>PPD_CS_N</CODE> - The printer uses a DeviceN colorspace by
3602  default</LI>
3603 </UL>
3604 <H2><A NAME="8_5">Raster Constants</A></H2>
3605 <H3><A NAME="8_5_1">Raster Sync Words</A></H3>
3606 <P>The <CODE>CUPS_RASTER_SYNC</CODE> and <CODE>CUPS_RASTER_REVSYNC</CODE>
3607  constants define the standard sync words at the beginning of each CUPS
3608  raster file.</P>
3609 <H3><A NAME="8_5_2">Raster Stream Modes</A></H3>
3610 <P>The <CODE>CUPS_RASTER_READ</CODE> and <CODE>CUPS_RASTER_WRITE</CODE>
3611  constants are used with the<A HREF="#cupsRasterOpen"> <CODE>
3612 cupsRasterOpen()</CODE></A> function to specify a stream for reading or
3613  writing.</P>
3614 <H3><A NAME="8_5_3">Raster Boolean Constants</A></H3>
3615 <P>The <CODE>CUPS_FALSE</CODE> and <CODE>CUPS_TRUE</CODE> constants
3616  represent boolean values in the page header.</P>
3617 <H3><A NAME="8_5_4">Raster Jog Values</A></H3>
3618 <P>The <CODE>cups_jog_t</CODE> enumeration defines constants for the Jog
3619  page device dictionary variable:</P>
3620 <UL>
3621 <LI><CODE>CUPS_JOG_NONE</CODE> - Do no jogging</LI>
3622 <LI><CODE>CUPS_JOG_FILE</CODE> - Jog pages after each file</LI>
3623 <LI><CODE>CUPS_JOG_JOB</CODE> - Jog pages after each job</LI>
3624 <LI><CODE>CUPS_JOG_SET</CODE> - Jog pages after each set of jobs</LI>
3625 </UL>
3626 <H3><A NAME="8_5_5">Raster Orientation Values</A></H3>
3627 <P>The <CODE>cups_orient_t</CODE> enumeration defines constants for the
3628  Orientation page device dictionary variable:</P>
3629 <UL>
3630 <LI><CODE>CUPS_ORIENT_0</CODE> - Portrait orientation</LI>
3631 <LI><CODE>CUPS_ORIENT_90</CODE> - Landscape orientation</LI>
3632 <LI><CODE>CUPS_ORIENT_180</CODE> - Reverse-portrait orientation</LI>
3633 <LI><CODE>CUPS_ORIENT_270</CODE> - Reverse-landscape orientation</LI>
3634 </UL>
3635 <H3><A NAME="8_5_6">Raster CutMedia Values</A></H3>
3636 <P>The <CODE>cups_cut_t</CODE> enumeration defines constants for the
3637  CutMedia page device dictionary variable:</P>
3638 <UL>
3639 <LI><CODE>CUPS_CUT_NONE</CODE> - Do no jogging</LI>
3640 <LI><CODE>CUPS_CUT_FILE</CODE> - Cut pages after each file</LI>
3641 <LI><CODE>CUPS_CUT_JOB</CODE> - Cut pages after each job</LI>
3642 <LI><CODE>CUPS_CUT_SET</CODE> - Cut pages after each set of jobs</LI>
3643 <LI><CODE>CUPS_CUT_PAGE</CODE> - Cut each page</LI>
3644 </UL>
3645 <H3><A NAME="8_5_7">Raster AdvanceMedia Values</A></H3>
3646 <P>The <CODE>cups_advance_t</CODE> enumeration defines constants for the
3647  AdvanceMedia page device dictionary variable:</P>
3648 <UL>
3649 <LI><CODE>CUPS_ADVANCE_NONE</CODE> - Do no jogging</LI>
3650 <LI><CODE>CUPS_ADVANCE_FILE</CODE> - Advance media after each file</LI>
3651 <LI><CODE>CUPS_ADVANCE_JOB</CODE> - Advance media after each job</LI>
3652 <LI><CODE>CUPS_ADVANCE_SET</CODE> - Advance media after each set of jobs</LI>
3653 <LI><CODE>CUPS_ADVANCE_PAGE</CODE> - Advance media for each page</LI>
3654 </UL>
3655 <H3><A NAME="8_5_8">Raster LeadingEdge Values</A></H3>
3656 <P>The <CODE>cups_edge_t</CODE> enumeration defines constants for the
3657  LeadingEdge page device dictionary variable:</P>
3658 <UL>
3659 <LI><CODE>CUPS_EDGE_TOP</CODE> - The top of the media is the leading
3660  edge</LI>
3661 <LI><CODE>CUPS_EDGE_RIGHT</CODE> - The right of the media is the leading
3662  edge</LI>
3663 <LI><CODE>CUPS_EDGE_BOTTOM</CODE> - The bottom of the media is the
3664  leading edge</LI>
3665 <LI><CODE>CUPS_EDGE_LEFT</CODE> - The left of the media is the leading
3666  edge</LI>
3667 </UL>
3668 <H3><A NAME="8_5_9">Raster Color Order Values</A></H3>
3669 <P>The <CODE>cups_order_t</CODE> enumeration defines the possible color
3670  value orderings:</P>
3671 <UL>
3672 <LI><CODE>CUPS_ORDER_CHUNKED</CODE> - CMYK&nbsp;CMYK&nbsp;CMYK</LI>
3673 <LI><CODE>CUPS_ORDER_BANDED</CODE> - CCC&nbsp;MMM&nbsp;YYY&nbsp;KKK</LI>
3674 <LI><CODE>CUPS_ORDER_PLANAR</CODE> - CCC&nbsp;...&nbsp;MMM&nbsp;...&nbsp;YYY&nbsp;...&nbsp;KKK&nbsp;...</LI>
3675 </UL>
3676 <H3><A NAME="8_5_10">Raster Colorspace Values</A></H3>
3677 <P>The <CODE>cups_cspace_t</CODE> enumeration defines the possible
3678  colorspaces:</P>
3679 <UL>
3680 <LI><CODE>CUPS_CSPACE_W</CODE> - White (luminance)</LI>
3681 <LI><CODE>CUPS_CSPACE_RGB</CODE> - Red, green, blue</LI>
3682 <LI><CODE>CUPS_CSPACE_RGBA</CODE> - Red, green, blue, alpha</LI>
3683 <LI><CODE>CUPS_CSPACE_K</CODE> - Black</LI>
3684 <LI><CODE>CUPS_CSPACE_CMY</CODE> - Cyan, magenta, yellow</LI>
3685 <LI><CODE>CUPS_CSPACE_YMC</CODE> - Yellow, magenta, cyan</LI>
3686 <LI><CODE>CUPS_CSPACE_CMYK</CODE> - Cyan, magenta, yellow, black</LI>
3687 <LI><CODE>CUPS_CSPACE_YMCK</CODE> - Yellow, magenta, cyan, black</LI>
3688 <LI><CODE>CUPS_CSPACE_KCMY</CODE> - Black, cyan, magenta, yellow</LI>
3689 <LI><CODE>CUPS_CSPACE_KCMYcm</CODE> - Black, cyan, magenta, yellow,
3690  light cyan, light magenta</LI>
3691 <LI><CODE>CUPS_CSPACE_GMCK</CODE> - Metallic yellow (gold), metallic
3692  magenta, metallic cyan, black</LI>
3693 <LI><CODE>CUPS_CSPACE_GMCS</CODE> - Metallic yellow (gold), metallic
3694  magenta, metallic cyan, metallic grey (silver)</LI>
3695 <LI><CODE>CUPS_CSPACE_WHITE</CODE> - White pigment (black as white
3696  pigment)</LI>
3697 <LI><CODE>CUPS_CSPACE_GOLD</CODE> - Gold foil (black as gold foil)</LI>
3698 <LI><CODE>CUPS_CSPACE_SILVER</CODE> - Silver foil (black as silver foil)</LI>
3699 </UL>
3700 <H1 ALIGN="RIGHT"><A NAME="STRUCTURES">C - Structures</A></H1>
3701 <P>This appendix describes all of the structures that are defined by the
3702  CUPS API.</P>
3703 <H2><A NAME="9_1">Raster Structures</A></H2>
3704 <H3><A NAME="9_1_1">Raster Page Header</A></H3>
3705 <P>The raster page header consists of the PostScript page device
3706  dictionary for the page:
3707 <CENTER>
3708 <TABLE BORDER="1" WIDTH="90%">
3709 <TR><TH>Member</TH><TH>Type</TH><TH>Description</TH></TR>
3710 <TR><TD>MediaClass</TD><TD>char[64]</TD><TD>The media class name</TD></TR>
3711 <TR><TD>MediaColor</TD><TD>char[64]</TD><TD>The media color name</TD></TR>
3712 <TR><TD>MediaType</TD><TD>char[64]</TD><TD>The media type name</TD></TR>
3713 <TR><TD>OutputType</TD><TD>char[64]</TD><TD>The output type name</TD></TR>
3714 <TR><TD>AdvanceDistance</TD><TD>unsigned</TD><TD>The distance to advance
3715  the media in points</TD></TR>
3716 <TR><TD>AdvanceMedia</TD><TD>cups_adv_t</TD><TD>When to advance the
3717  media</TD></TR>
3718 <TR><TD>Collate</TD><TD>cups_bool_t</TD><TD>Whether or not to produce
3719  collated copies</TD></TR>
3720 <TR><TD>CutMedia</TD><TD>cups_cut_t</TD><TD>When to cut the media</TD></TR>
3721 <TR><TD>Duplex</TD><TD>cups_bool_t</TD><TD>Whether or not to print on
3722  both sides of the paper</TD></TR>
3723 <TR><TD>HWResolution</TD><TD>unsigned[2]</TD><TD>The resolution of the
3724  page image in pixels per inch; the HWResolution[0] represents the
3725  horizontal resolution and HWResolution[1] represents the vertical
3726  resolution</TD></TR>
3727 <TR><TD>ImagingBoundingBox</TD><TD>unsigned[4]</TD><TD>The bounding box
3728  for the page in points; the elements represent the left, bottom, right,
3729  and top coordinates of the imaged area (if 0 then the whole page is
3730  imaged)</TD></TR>
3731 <TR><TD>InsertSheet</TD><TD>cups_bool_t</TD><TD>Whether or not to insert
3732  a sheet before this page</TD></TR>
3733 <TR><TD>Jog</TD><TD>cups_jog_t</TD><TD>When to jog copies of the page</TD>
3734 </TR>
3735 <TR><TD>LeadingEdge</TD><TD>cups_edge_t</TD><TD>The leading edge of the
3736  page</TD></TR>
3737 <TR><TD>Margins</TD><TD>unsigned[2]</TD><TD>The lower-lefthand margin of
3738  the page in points</TD></TR>
3739 <TR><TD>ManualFeed</TD><TD>cups_bool_t</TD><TD>Whether or not to
3740  manually feed the page</TD></TR>
3741 <TR><TD>MediaPosition</TD><TD>unsigned</TD><TD>The input slot number to
3742  use</TD></TR>
3743 <TR><TD>MediaWeight</TD><TD>unsigned</TD><TD>The weight of the output
3744  media in grams/m<SUP>2</SUP></TD></TR>
3745 <TR><TD>MirrorPrint</TD><TD>cups_bool_t</TD><TD>Whether or not to mirror
3746  the print</TD></TR>
3747 <TR><TD>NegativePrint</TD><TD>cups_bool_t</TD><TD>Whether or not to
3748  invert the print</TD></TR>
3749 <TR><TD>NumCopies</TD><TD>unsigned</TD><TD>The number of copies to
3750  produce</TD></TR>
3751 <TR><TD>Orientation</TD><TD>cups_orient_t</TD><TD>The orientation of the
3752  page image</TD></TR>
3753 <TR><TD>OutputFaceUp</TD><TD>cups_bool_t</TD><TD>Whether or not to
3754  output the page face up</TD></TR>
3755 <TR><TD>PageSize</TD><TD>unsigned[2]</TD><TD>The width and height of the
3756  page in points</TD></TR>
3757 <TR><TD>Separations</TD><TD>cups_bool_t</TD><TD>Whether or not to output
3758  separations</TD></TR>
3759 <TR><TD>TraySwitch</TD><TD>cups_bool_t</TD><TD>Whether or not to
3760  automatically switch trays for the requested media size/type</TD></TR>
3761 <TR><TD>Tumble</TD><TD>cups_bool_t</TD><TD>Whether or not to rotate the
3762  back side of the page</TD></TR>
3763 <TR><TD>cupsWidth</TD><TD>unsigned</TD><TD>The width of the page image
3764  in pixels</TD></TR>
3765 <TR><TD>cupsHeight</TD><TD>unsigned</TD><TD>The height of the page image
3766  in pixels</TD></TR>
3767 <TR><TD>cupsMediaType</TD><TD>unsigned</TD><TD>The device-specific media
3768  type code</TD></TR>
3769 <TR><TD>cupsBitsPerColor</TD><TD>unsigned</TD><TD>The number of bits per
3770  color</TD></TR>
3771 <TR><TD>cupsBitsPerPixel</TD><TD>unsigned</TD><TD>The number of bits per
3772  pixel</TD></TR>
3773 <TR><TD>cupsBytesPerLine</TD><TD>unsigned</TD><TD>The number of bytes
3774  per line of image data</TD></TR>
3775 <TR><TD>cupsColorOrder</TD><TD>cups_order_t</TD><TD>The order of color
3776  values</TD></TR>
3777 <TR><TD>cupsColorSpace</TD><TD>cups_cspace_t</TD><TD>The type of color
3778  values</TD></TR>
3779 <TR><TD>cupsCompression</TD><TD>unsigned</TD><TD>The device-specific
3780  compression code</TD></TR>
3781 <TR><TD>cupsRowCount</TD><TD>unsigned</TD><TD>The device-specific row
3782  count</TD></TR>
3783 <TR><TD>cupsRowFeed</TD><TD>unsigned</TD><TD>The device-specific row
3784  feed</TD></TR>
3785 <TR><TD>cupsRowStep</TD><TD>unsigned</TD><TD>The device-specific row
3786  step</TD></TR>
3787 </TABLE>
3788 </CENTER>
3789 </P>
3790 <H1 ALIGN="RIGHT"><A HREF="FUNCTIONS" NAME="10">D - Functions</A></H1>
3791 <P>This appendix provides a reference for all of the CUPS API functions.
3792 <!-- NEW PAGE -->
3793 </P>
3794 <H2><A NAME="cupsAddOption">cupsAddOption()</A></H2>
3795 <H3><A NAME="10_1_1">Usage</A></H3>
3796 <PRE>
3797 int
3798 cupsAddOption(const char *name,
3799               const char *value,
3800               int num_options,
3801               cups_option_t **options);
3802 </PRE>
3803 <H3><A NAME="10_1_2">Arguments</A></H3>
3804 <CENTER>
3805 <TABLE BORDER WIDTH="80%">
3806 <TR><TH>Argument</TH><TH>Description</TH></TR>
3807 <TR><TD>name</TD><TD>The name of the option.</TD></TR>
3808 <TR><TD>value</TD><TD>The value of the option.</TD></TR>
3809 <TR><TD>num_options</TD><TD>Number of options currently in the array.</TD>
3810 </TR>
3811 <TR><TD>options</TD><TD>Pointer to the options array.</TD></TR>
3812 </TABLE>
3813 </CENTER>
3814 <H3><A NAME="10_1_3">Returns</A></H3>
3815 <P>The new number of options.</P>
3816 <H3><A NAME="10_1_4">Description</A></H3>
3817 <P><CODE>cupsAddOption()</CODE> adds an option to the specified array.</P>
3818 <H3><A NAME="10_1_5">Example</A></H3>
3819 <PRE>
3820 #include &lt;cups.h&gt;
3821
3822 ...
3823
3824 /* Declare the options array */
3825 int           num_options;
3826 <A HREF="#cups_option_t">cups_option_t</A> *options;
3827
3828 /* Initialize the options array */
3829 num_options = 0;
3830 options     = (cups_option_t *)0;
3831
3832 /* Add options using cupsAddOption() */
3833 num_options = cupsAddOption(&quot;media&quot;, &quot;letter&quot;, num_options, &amp;options);
3834 num_options = cupsAddOption(&quot;resolution&quot;, &quot;300dpi&quot;, num_options, &amp;options);
3835 </PRE>
3836 <H3><A NAME="10_1_6">See Also</A></H3>
3837 <A HREF="#cupsFreeOptions"> <CODE>cupsFreeOptions()</CODE></A>,<A HREF="#cupsGetOption">
3838  <CODE>cupsGetOption()</CODE></A>,<A HREF="#cupsParseOptions"> <CODE>
3839 cupsParseOptions()</CODE></A>
3840 <!-- NEW PAGE -->
3841
3842 <H2><A NAME="cupsCancelJob">cupsCancelJob()</A></H2>
3843 <H3><A NAME="10_2_1">Usage</A></H3>
3844 <PRE>
3845 int
3846 cupsCancelJob(const char *dest,
3847               int job);
3848 </PRE>
3849 <H3><A NAME="10_2_2">Arguments</A></H3>
3850 <CENTER>
3851 <TABLE BORDER WIDTH="80%">
3852 <TR><TH>Argument</TH><TH>Description</TH></TR>
3853 <TR><TD>dest</TD><TD>Printer or class name</TD></TR>
3854 <TR><TD>job</TD><TD>Job ID</TD></TR>
3855 </TABLE>
3856 </CENTER>
3857 <H3><A NAME="10_2_3">Returns</A></H3>
3858 <P>1 on success, 0 on failure. On failure the error can be found by
3859  calling<A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>.</P>
3860 <H3><A NAME="10_2_4">Description</A></H3>
3861 <P><CODE>cupsCancelJob()</CODE> cancels the specifies job.</P>
3862 <H3><A NAME="10_2_5">Example</A></H3>
3863 <PRE>
3864 #include &lt;cups.h&gt;
3865
3866 cupsCancelJob(&quot;LaserJet&quot;, 1);
3867 </PRE>
3868 <H3><A NAME="10_2_6">See Also</A></H3>
3869 <P><A HREF="#cupsLastError"> <CODE>cupsLastError()</CODE></A>,<A HREF="#cupsPrintFile">
3870  <CODE>cupsPrintFile()</CODE></A>
3871 <!-- NEW PAGE -->
3872 </P>
3873 <H2><A NAME="cupsDoFileRequest">cupsDoFileRequest()</A></H2>
3874 <H3><A NAME="10_3_1">Usage</A></H3>
3875 <PRE>
3876 ipp_t *
3877 cupsDoFileRequest(http_t *http,
3878                   ipp_t *request,
3879                   const char *resource,
3880                   const char *filename);
3881 </PRE>
3882 <H3><A NAME="10_3_2">Arguments</A></H3>
3883 <CENTER>
3884 <TABLE BORDER WIDTH="80%">
3885 <TR><TH>Argument</TH><TH>Description</TH></TR>
3886 <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR>
3887 <TR><TD>request</TD><TD>IPP request data.</TD></TR>
3888 <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR>
3889 <TR><TD>filename</TD><TD>File to send with POST request (<CODE>NULL</CODE>
3890  pointer if none.)</TD></TR>
3891 </TABLE>
3892 </CENTER>
3893 <H3><A NAME="10_3_3">Returns</A></H3>
3894 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On
3895  failure the error can be found by calling<A HREF="#cupsLastError"> <CODE>
3896 cupsLastError()</CODE></A>.</P>
3897 <H3><A NAME="10_3_4">Description</A></H3>
3898 <P><CODE>cupsDoFileRequest()</CODE> does a HTTP POST request and
3899  provides the IPP request and optionally the contents of a file to the
3900  IPP server. It also handles resubmitting the request and performing
3901  password authentication as needed.</P>
3902 <H3><A NAME="10_3_5">Example</A></H3>
3903 <PRE>
3904 #include &lt;cups.h&gt;
3905
3906 <A HREF="#http_t">http_t</A>      *http;
3907 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
3908 <A HREF="#ipp_t">ipp_t</A>       *request;
3909 ipp_t       *response;
3910
3911 ...
3912
3913 /* Get the default language */
3914 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3915
3916 /* Create a new IPP request */
3917 request  = <A HREF="#ippNew">ippNew()</A>;
3918
3919 request-&gt;request.op.operation_id = IPP_PRINT_FILE;
3920 request-&gt;request.op.request_id   = 1;
3921
3922 /* Add required attributes */
3923 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3924              &quot;attributes-charset&quot;, NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3925
3926 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3927              &quot;attributes-natural-language&quot;, NULL,
3928              language != NULL ? language-&gt;language : &quot;C&quot;);
3929
3930 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, &quot;printer-uri&quot;,
3931              NULL, &quot;ipp://hostname/resource&quot;);
3932
3933 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_NAME, &quot;requesting-user-name&quot;,
3934              NULL, <A HREF="#cupsUser">cupsUser()</A>);
3935
3936 /* Do the request... */
3937 response = cupsDoFileRequest(http, request, &quot;/resource&quot;, &quot;filename.txt&quot;);
3938 </PRE>
3939 <H3><A NAME="10_3_6">See Also</A></H3>
3940 <P><A HREF="#cupsLangDefault"> <CODE>cupsLangDefault()</CODE></A>,<A HREF="#cupsLangEncoding">
3941  <CODE>cupsLangEncoding()</CODE></A>,<A HREF="#cupsUser"> <CODE>
3942 cupsUser()</CODE></A>,<A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
3943 ,<A HREF="#ippAddString"> <CODE>ippAddString()</CODE></A>,<A HREF="#ippNew">
3944  <CODE>ippNew()</CODE></A>
3945 <!-- NEW PAGE -->
3946 </P>
3947 <H2><A NAME="cupsDoRequest">cupsDoRequest()</A></H2>
3948 <H3><A NAME="10_4_1">Usage</A></H3>
3949 <PRE>
3950 ipp_t *
3951 cupsDoRequest(http_t *http,
3952               ipp_t *request,
3953               const char *resource);
3954 </PRE>
3955 <H3><A NAME="10_4_2">Arguments</A></H3>
3956 <CENTER>
3957 <TABLE BORDER WIDTH="80%">
3958 <TR><TH>Argument</TH><TH>Description</TH></TR>
3959 <TR><TD>http</TD><TD>HTTP connection to server.</TD></TR>
3960 <TR><TD>request</TD><TD>IPP request data.</TD></TR>
3961 <TR><TD>resource</TD><TD>HTTP resource name for POST.</TD></TR>
3962 </TABLE>
3963 </CENTER>
3964 <H3><A NAME="10_4_3">Returns</A></H3>
3965 <P>IPP response data or <CODE>NULL</CODE> if the request fails. On
3966  failure the error can be found by calling<A HREF="#cupsLastError"> <CODE>
3967 cupsLastError()</CODE></A>.</P>
3968 <H3><A NAME="10_4_4">Description</A></H3>
3969 <P><CODE>cupsDoRequest()</CODE> does a HTTP POST request and provides
3970  the IPP request to the IPP server. It also handles resubmitting the
3971  request and performing password authentication as needed.</P>
3972 <H3><A NAME="10_4_5">Example</A></H3>
3973 <PRE>
3974 #include &lt;cups.h&gt;
3975
3976 <A HREF="#http_t">http_t</A>      *http;
3977 <A HREF="#cups_lang_t">cups_lang_t</A> *language;
3978 <A HREF="#ipp_t">ipp_t</A>       *request;
3979 ipp_t       *response;
3980
3981 ...
3982
3983 /* Get the default language */
3984 language = <A HREF="#cupsLangDefault">cupsLangDefault()</A>;
3985
3986 /* Create a new IPP request */
3987 request  = <A HREF="#ippNew">ippNew()</A>;
3988
3989 request-&gt;request.op.operation_id = IPP_GET_PRINTER_ATTRIBUTES;
3990 request-&gt;request.op.request_id   = 1;
3991
3992 /* Add required attributes */
3993 <A HREF="#ippAddString">ippAddString</A>(request, IPP_TAG_OPERATION, IPP_TAG_CHARSET,
3994              &quot;attributes-charset&quot;, NULL, <A HREF="#cupsLangEncoding">cupsLangEncoding</A>(language));
3995
3996 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_LANGUAGE,
3997              &quot;attributes-natural-language&quot;, NULL,
3998              language != NULL ? language-&gt;language : &quot;C&quot;);
3999
4000 ippAddString(request, IPP_TAG_OPERATION, IPP_TAG_URI, &quot;printer-uri&quot;,
4001              NULL, &quot;ipp://hostname/resource&quot;);
4002
4003 /* Do the request... */
4004 response = cupsDoRequest(http, request, &quot;/resource&quot;);
4005 </PRE>
4006 <H3><A NAME="10_4_6">See Also</A></H3>
4007 <P><A HREF="#cupsLangDefault"> <CODE>cupsLangDefault()</CODE></A>,<A HREF="#cupsLangEncoding">
4008  <CODE>cupsLangEncoding()</CODE></A>,<A HREF="#cupsUser"> <CODE>
4009 cupsUser()</CODE></A>,<A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
4010 ,<A HREF="#ippAddString"> <CODE>ippAddString()</CODE></A>,<A HREF="#ippNew">
4011  <CODE>ippNew()</CODE></A>
4012 <!-- NEW PAGE -->
4013 </P>
4014 <H2><A NAME="cupsFreeOptions">cupsFreeOptions()</A></H2>
4015 <H3><A NAME="10_5_1">Usage</A></H3>
4016 <PRE>
4017 void
4018 cupsFreeOptions(int num_options,
4019                 cups_option_t *options);
4020
4021 </PRE>
4022 <H3><A NAME="10_5_2">Arguments</A></H3>
4023 <CENTER>
4024 <TABLE BORDER WIDTH="80%">
4025 <TR><TH>Argument</TH><TH>Description</TH></TR>
4026 <TR><TD>num_options</TD><TD>Number of options in array.</TD></TR>
4027 <TR><TD>options</TD><TD>Pointer to options array.</TD></TR>
4028 </TABLE>
4029 </CENTER>
4030 <H3><A NAME="10_5_3">Description</A></H3>
4031 <P><CODE>cupsFreeOptions()</CODE> frees all memory associated with the
4032  option array specified.</P>
4033 <H3><A NAME="10_5_4">Example</A></H3>
4034 <PRE>
4035 #include &lt;cups/cups.h&gt;
4036
4037 int           num_options;
4038 cups_option_t *options;
4039
4040 ...
4041
4042 cupsFreeOptions(num_options, options);
4043 </PRE>
4044 <H3><A NAME="10_5_5">See Also</A></H3>
4045 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsGetOption">
4046  cupsGetOption()</A>,<A HREF="#cupsMarkOptions"> cupsMarkOptions()</A>,<A
4047 HREF="#cupsParseOptions"> cupsParseOptions()</A>
4048 <!-- NEW PAGE -->
4049 </P>
4050 <H2><A NAME="cupsGetClasses">cupsGetClasses()</A></H2>
4051 <H3><A NAME="10_6_1">Usage</A></H3>
4052 <PRE>
4053 int
4054 cupsGetClasses(char ***classes);
4055 </PRE>
4056 <H3><A NAME="10_6_2">Arguments</A></H3>
4057 <CENTER>
4058 <TABLE BORDER WIDTH="80%">
4059 <TR><TH>Argument</TH><TH>Description</TH></TR>
4060 <TR><TD>classes</TD><TD>Pointer to character pointer array.</TD></TR>
4061 </TABLE>
4062 </CENTER>
4063 <H3><A NAME="10_6_3">Returns</A></H3>
4064 <P>The number of printer classes available.</P>
4065 <H3><A NAME="10_6_4">Description</A></H3>
4066 <P><CODE>cupsGetClasses()</CODE> gets a list of the available printer
4067  classes. The returned array should be freed using the <CODE>free()</CODE>
4068  when it is no longer needed.</P>
4069 <H3><A NAME="10_6_5">Example</A></H3>
4070 <PRE>
4071 #include &lt;cups/cups.h&gt;
4072
4073 int  i;
4074 int  num_classes;
4075 char **classes;
4076
4077 ...
4078
4079 num_classes = cupsGetClasses(
4080
4081 ...
4082
4083 if (num_classes &gt; 0)
4084 {
4085   for (i = 0; i &lt;num_classes; i ++)
4086     free(classes[i]);
4087
4088   free(classes);
4089 }
4090 </PRE>
4091 <H3><A NAME="10_6_6">See Also</A></H3>
4092 <P><A HREF="#cupsGetDefault"> cupsGetDefault(),<A HREF="#cupsGetPrinters">
4093  cupsGetPrinters()
4094 <!-- NEW PAGE -->
4095 </A></A></P>
4096 <H2><A NAME="cupsGetDefault">cupsGetDefault()</A></H2>
4097 <H3><A NAME="10_7_1">Usage</A></H3>
4098 <PRE>
4099 const char *
4100 cupsGetDefault(void);
4101 </PRE>
4102 <H3><A NAME="10_7_2">Returns</A></H3>
4103 <P>A pointer to the default destination.</P>
4104 <H3><A NAME="10_7_3">Description</A></H3>
4105 <P><CODE>cupsGetDefault()</CODE> gets the default destination printer or
4106  class. The default destination is stored in a static string and will be
4107  overwritten (usually with the same value) after each call.</P>
4108 <H3><A NAME="10_7_4">Example</A></H3>
4109 <PRE>
4110 #include &lt;cups/cups.h&gt;
4111
4112 printf(&quot;The default destination is %s\n&quot;, cupsGetDefault());
4113 </PRE>
4114 <H3><A NAME="10_7_5">See Also</A></H3>
4115 <P><A HREF="#cupsGetClasses"> cupsGetClasses(),<A HREF="#cupsGetPrinters">
4116  cupsGetPrinters()
4117 <!-- NEW PAGE -->
4118 </A></A></P>
4119 <H2><A NAME="cupsGetOption">cupsGetOption()</A></H2>
4120 <H3><A NAME="10_8_1">Usage</A></H3>
4121 <PRE>
4122 const char *
4123 cupsGetOption(const char *name,
4124               int num_options,
4125               cups_option_t *options);
4126 </PRE>
4127 <H3><A NAME="10_8_2">Arguments</A></H3>
4128 <CENTER>
4129 <TABLE BORDER WIDTH="80%">
4130 <TR><TH>Argument</TH><TH>Description</TH></TR>
4131 <TR><TD>name</TD><TD>The name of the option.</TD></TR>
4132 <TR><TD>num_options</TD><TD>The number of options in the array.</TD></TR>
4133 <TR><TD>options</TD><TD>The options array.</TD></TR>
4134 </TABLE>
4135 </CENTER>
4136 <H3><A NAME="10_8_3">Returns</A></H3>
4137 <P>A pointer to the option values or <CODE>NULL</CODE> if the option is
4138  not defined.</P>
4139 <H3><A NAME="10_8_4">Description</A></H3>
4140 <P><CODE>cupsGetOption()</CODE> returns the first occurrence of the
4141  named option. If the option is not included in the options array then a
4142  <CODE>NULL</CODE> pointer is returned.</P>
4143 <PRE>
4144 #include &lt;cups/cups.h&gt;
4145
4146 int           num_options;
4147 cups_option_t *options;
4148 const char    *media;
4149
4150 ...
4151
4152 media = cupsGetOption(&quot;media&quot;, num_options, options);
4153 </PRE>
4154 <H3><A NAME="10_8_5">See Also</A></H3>
4155 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4156  cupsFreeOptions()</A>,<A HREF="#cupsMarkOptions"> cupsMarkOptions()</A>
4157 ,<A HREF="#cupsParseOptions"> cupsParseOptions()</A>
4158 <!-- NEW PAGE -->
4159 </P>
4160 <H2><A NAME="cupsGetPassword">cupsGetPassword()</A></H2>
4161 <H3><A NAME="10_9_1">Usage</A></H3>
4162 <PRE>
4163 const char *
4164 cupsGetPassword(const char *prompt);
4165 </PRE>
4166 <H3><A NAME="10_9_2">Arguments</A></H3>
4167 <CENTER>
4168 <TABLE BORDER WIDTH="80%">
4169 <TR><TH>Argument</TH><TH>Description</TH></TR>
4170 <TR><TD>prompt</TD><TD>The prompt to display to the user.</TD></TR>
4171 </TABLE>
4172 </CENTER>
4173 <H3><A NAME="10_9_3">Returns</A></H3>
4174 <P>A pointer to the password that was entered or <CODE>NULL</CODE> if no
4175  password was entered.</P>
4176 <H3><A NAME="10_9_4">Description</A></H3>
4177 <P><CODE>cupsGetPassword()</CODE> displays the prompt string and asks
4178  the user for a password. The password text is not echoed to the user.</P>
4179 <H3><A NAME="10_9_5">Example</A></H3>
4180 <PRE>
4181 #include &lt;cups/cups.h&gt;
4182
4183 char *password;
4184
4185 ...
4186
4187 password = cupsGetPassword(&quot;Please enter a password:&quot;);
4188 </PRE>
4189 <H3><A NAME="10_9_6">See Also</A></H3>
4190 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
4191  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
4192 HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser()"> cupsUser()</A>
4193 <!-- NEW PAGE -->
4194
4195 </P>
4196 <H2><A NAME="cupsGetPPD">cupsGetPPD()</A></H2>
4197 <H3><A NAME="10_10_1">Usage</A></H3>
4198 <PRE>
4199 const char *
4200 cupsGetPPD(const char *printer);
4201 </PRE>
4202 <H3><A NAME="10_10_2">Arguments</A></H3>
4203 <CENTER>
4204 <TABLE BORDER WIDTH="80%">
4205 <TR><TH>Argument</TH><TH>Description</TH></TR>
4206 <TR><TD>printer</TD><TD>The name of the printer.</TD></TR>
4207 </TABLE>
4208 </CENTER>
4209 <H3><A NAME="10_10_3">Returns</A></H3>
4210 <P>The name of a temporary file containing the PPD file or <CODE>NULL</CODE>
4211  if the printer cannot be located or does not have a PPD file.</P>
4212 <H3><A NAME="10_10_4">Description</A></H3>
4213 <P><CODE>cupsGetPPD()</CODE> gets a copy of the PPD file for the named
4214  printer. The printer name can be of the form &quot;printer&quot; or
4215  &quot;printer@hostname&quot;.</P>
4216 <P>You should remove (unlink) the PPD file after you are done using it.
4217  The filename is stored in a static buffer and will be overwritten with
4218  each call to <CODE>cupsGetPPD()</CODE>.</P>
4219 <H3><A NAME="10_10_5">Example</A></H3>
4220 <PRE>
4221 #include &lt;cups/cups.h&gt;
4222
4223 char *ppd;
4224
4225 ...
4226
4227 ppd = cupsGetPPD(&quot;printer@hostname&quot;);
4228
4229 ...
4230
4231 unlink(ppd);
4232 </PRE>
4233
4234 <!-- NEW PAGE -->
4235 <H2><A NAME="cupsGetPrinters">cupsGetPrinters()</A></H2>
4236 <H3><A NAME="10_11_1">Usage</A></H3>
4237 <PRE>
4238 int
4239 cupsGetPrinters(char ***printers);
4240 </PRE>
4241 <H3><A NAME="10_11_2">Arguments</A></H3>
4242 <CENTER>
4243 <TABLE BORDER WIDTH="80%">
4244 <TR><TH>Argument</TH><TH>Description</TH></TR>
4245 <TR><TD>printers</TD><TD>Pointer to character pointer array.</TD></TR>
4246 </TABLE>
4247 </CENTER>
4248 <H3><A NAME="10_11_3">Returns</A></H3>
4249 <P>The number of printer printers available.</P>
4250 <H3><A NAME="10_11_4">Description</A></H3>
4251 <P><CODE>cupsGetPrinters()</CODE> gets a list of the available printers.
4252  The returned array should be freed using the <CODE>free()</CODE> when
4253  it is no longer needed.</P>
4254 <H3><A NAME="10_11_5">Example</A></H3>
4255 <PRE>
4256 #include &lt;cups/cups.h&gt;
4257
4258 int  i;
4259 int  num_printers;
4260 char **printers;
4261
4262 ...
4263
4264 num_printers = cupsGetPrinters(
4265
4266 ...
4267
4268 if (num_printers &gt; 0)
4269 {
4270   for (i = 0; i &lt;num_printers; i ++)
4271     free(printers[i]);
4272
4273   free(printers);
4274 }
4275 </PRE>
4276 <H3><A NAME="10_11_6">See Also</A></H3>
4277 <P><A HREF="#cupsGetClasses"> cupsGetClasses(),<A HREF="#cupsGetDefault">
4278  cupsGetDefault()
4279 <!-- NEW PAGE -->
4280 </A></A></P>
4281 <H2><A NAME="cupsLangDefault">cupsLangDefault()</A></H2>
4282 <H3><A NAME="10_12_1">Usage</A></H3>
4283 <PRE>
4284 const char *
4285 cupsLangDefault(void);
4286 </PRE>
4287 <H3><A NAME="10_12_2">Returns</A></H3>
4288 <P>A pointer to the default language structure.</P>
4289 <H3><A NAME="10_12_3">Description</A></H3>
4290 <P><CODE>cupsLangDefault()</CODE> returns a language structure for the
4291  default language. The default language is defined by the <CODE>LANG</CODE>
4292  environment variable. If the specified language cannot be located then
4293  the POSIX (English) locale is used.</P>
4294 <P>Call <CODE>cupsLangFree()</CODE> to free any memory associated with
4295  the language structure when you are done.</P>
4296 <H3><A NAME="10_12_4">Example</A></H3>
4297 <PRE>
4298 #include &lt;cups/language.h&gt;
4299
4300 cups_lang_t *language;
4301 ...
4302
4303 language = cupsLangDefault();
4304
4305 ...
4306
4307 cupsLangFree(language);
4308 </PRE>
4309 <H3><A NAME="10_12_5">See Also</A></H3>
4310 <P><A HREF="#cupsLangEncoding"> cupsLangEncoding()</A>,<A HREF="#cupsLangFlush">
4311  cupsLangFlush()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4312  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4313 <!-- NEW PAGE -->
4314 </P>
4315 <H2><A NAME="cupsLangEncoding">cupsLangEncoding()</A></H2>
4316 <H3><A NAME="10_13_1">Usage</A></H3>
4317 <PRE>
4318 char *
4319 cupsLangEncoding(cups_lang_t *language);
4320 </PRE>
4321 <H3><A NAME="10_13_2">Arguments</A></H3>
4322 <CENTER>
4323 <TABLE BORDER WIDTH="80%">
4324 <TR><TH>Argument</TH><TH>Description</TH></TR>
4325 <TR><TD>language</TD><TD>The language structure.</TD></TR>
4326 </TABLE>
4327 </CENTER>
4328 <H3><A NAME="10_13_3">Returns</A></H3>
4329 <P>A pointer to the encoding string.</P>
4330 <H3><A NAME="10_13_4">Description</A></H3>
4331 <P><CODE>cupsLangEncoding()</CODE> returns the language encoding used
4332  for the specified language, e.g. &quot;iso-8859-1&quot;, &quot;utf-8&quot;, etc.</P>
4333 <H3><A NAME="10_13_5">Example</A></H3>
4334 <PRE>
4335 #include &lt;cups/language.h&gt;
4336
4337 cups_lang_t *language;
4338 char        *encoding;
4339 ...
4340
4341 language = cupsLangDefault();
4342 encoding = cupsLangEncoding(language);
4343 ...
4344
4345 cupsLangFree(language);
4346 </PRE>
4347 <H3><A NAME="10_13_6">See Also</A></H3>
4348 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangFlush">
4349  cupsLangFlush()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4350  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4351 <!-- NEW PAGE -->
4352 </P>
4353 <H2><A NAME="cupsLangFlush">cupsLangFlush()</A></H2>
4354 <H3><A NAME="10_14_1">Usage</A></H3>
4355 <PRE>
4356 void
4357 cupsLangFlush(void);
4358 </PRE>
4359 <H3><A NAME="10_14_2">Description</A></H3>
4360 <P><CODE>cupsLangFlush()</CODE> frees all language structures that have
4361  been allocated.</P>
4362 <H3><A NAME="10_14_3">Example</A></H3>
4363 <PRE>
4364 #include &lt;cups/language.h&gt;
4365
4366 ...
4367
4368 cupsLangFlush();
4369 </PRE>
4370 <H3><A NAME="10_14_4">See Also</A></H3>
4371 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4372  cupsLangEncoding()</A>,<A HREF="#cupsLangFree"> cupsLangFree()</A>,<A HREF="#cupsLangGet">
4373  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4374 <!-- NEW PAGE -->
4375 </P>
4376 <H2><A NAME="cupsLangFree">cupsLangFree()</A></H2>
4377 <H3><A NAME="10_15_1">Usage</A></H3>
4378 <PRE>
4379 void
4380 cupsLangFree(cups_lang_t *language);
4381 </PRE>
4382 <H3><A NAME="10_15_2">Arguments</A></H3>
4383 <CENTER>
4384 <TABLE BORDER WIDTH="80%">
4385 <TR><TH>Argument</TH><TH>Description</TH></TR>
4386 <TR><TD>language</TD><TD>The language structure to free.</TD></TR>
4387 </TABLE>
4388 </CENTER>
4389 <H3><A NAME="10_15_3">Description</A></H3>
4390 <P><CODE>cupsLangFree()</CODE> frees the specified language structure.</P>
4391 <H3><A NAME="10_15_4">Example</A></H3>
4392 <PRE>
4393 #include &lt;cups/language.h&gt;
4394
4395 cups_lang_t *language;
4396 ...
4397
4398 cupsLangFree(language);
4399 </PRE>
4400 <H3><A NAME="10_15_5">See Also</A></H3>
4401 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4402  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangGet">
4403  cupsLangGet()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4404 <!-- NEW PAGE -->
4405 </P>
4406 <H2><A NAME="cupsLangGet">cupsLangGet()</A></H2>
4407 <H3><A NAME="10_16_1">Usage</A></H3>
4408 <PRE>
4409 cups_lang_t *
4410 cupsLangGet(const char *name);
4411 </PRE>
4412 <H3><A NAME="10_16_2">Arguments</A></H3>
4413 <CENTER>
4414 <TABLE BORDER WIDTH="80%">
4415 <TR><TH>Argument</TH><TH>Description</TH></TR>
4416 <TR><TD>name</TD><TD>The name of the locale.</TD></TR>
4417 </TABLE>
4418 </CENTER>
4419 <H3><A NAME="10_16_3">Returns</A></H3>
4420 <P>A pointer to a language structure.</P>
4421 <H3><A NAME="10_16_4">Description</A></H3>
4422 <P><CODE>cupsLangGet()</CODE> returns a language structure for the
4423  specified locale. If the locale is not defined then the POSIX (English)
4424  locale is substituted.</P>
4425 <H3><A NAME="10_16_5">Example</A></H3>
4426 <PRE>
4427 #include &lt;cups/language.h&gt;
4428
4429 cups_lang_t *language;
4430
4431 ...
4432
4433 language = cupsLangGet(&quot;fr&quot;);
4434
4435 ...
4436
4437 cupsLangFree(language);
4438 </PRE>
4439 <H3><A NAME="10_16_6">See Also</A></H3>
4440 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4441  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangFree">
4442  cupsLangFree()</A>,<A HREF="#cupsLangString"> cupsLangString()</A>
4443 <!-- NEW PAGE -->
4444 </P>
4445 <H2><A NAME="cupsLangString">cupsLangString()</A></H2>
4446 <H3><A NAME="10_17_1">Usage</A></H3>
4447 <PRE>
4448 char *
4449 cupsLangString(cups_lang_t *language,
4450                int         message);
4451 </PRE>
4452 <H3><A NAME="10_17_2">Arguments</A></H3>
4453 <CENTER>
4454 <TABLE BORDER WIDTH="80%">
4455 <TR><TH>Argument</TH><TH>Description</TH></TR>
4456 <TR><TD>language</TD><TD>The language to query.</TD></TR>
4457 <TR><TD>message</TD><TD>The message number.</TD></TR>
4458 </TABLE>
4459 </CENTER>
4460 <H3><A NAME="10_17_3">Returns</A></H3>
4461 <P>A pointer to the message string or <CODE>NULL</CODE> if the message
4462  is not defined.</P>
4463 <H3><A NAME="10_17_4">Description</A></H3>
4464 <P><CODE>cupsLangString()</CODE> returns a pointer to the specified
4465  message string in the specified language.</P>
4466 <H3><A NAME="10_17_5">Example</A></H3>
4467 <PRE>
4468 #include &lt;cups/language.h&gt;
4469
4470 cups_lang_t *language;
4471 char        *s;
4472 ...
4473
4474 language = cupsLangGet(&quot;fr&quot;);
4475
4476 s = cupsLangString(language, CUPS_MSG_YES);
4477
4478 ...
4479
4480 cupsLangFree(language);
4481 </PRE>
4482 <H3><A NAME="10_17_6">See Also</A></H3>
4483 <P><A HREF="#cupsLangDefault"> cupsLangDefault()</A>,<A HREF="#cupsLangEncoding">
4484  cupsLangEncoding()</A>,<A HREF="#cupsLangFlush"> cupsLangFlush()</A>,<A HREF="#cupsLangFree">
4485  cupsLangFree()</A>,<A HREF="#cupsLangGet"> cupsLangGet()</A>
4486 <!-- NEW PAGE -->
4487 </P>
4488 <H2><A NAME="cupsLastError">cupsLastError()</A></H2>
4489 <H3><A NAME="10_18_1">Usage</A></H3>
4490 <PRE>
4491 ipp_status_t
4492 cupsLastError(void);
4493 </PRE>
4494 <H3><A NAME="10_18_2">Returns</A></H3>
4495 <P>An enumeration containing the last IPP error.</P>
4496 <H3><A NAME="10_18_3">Description</A></H3>
4497 <P><CODE>cupsLastError()</CODE> returns the last IPP error that
4498  occurred. If no error occurred then it will return <CODE>IPP_OK</CODE>
4499  or <CODE>IPP_OK_CONFLICT</CODE>.</P>
4500 <H3><A NAME="10_18_4">Example</A></H3>
4501 <PRE>
4502 #include &lt;cups/cups.h&gt;
4503
4504 ipp_status_t status;
4505
4506 ...
4507
4508 status = cupsLastError();
4509 </PRE>
4510 <H3><A NAME="10_18_5">See Also</A></H3>
4511 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsPrintFile">
4512  cupsPrintFile()</A>
4513 <!-- NEW PAGE -->
4514 </P>
4515 <H2><A NAME="cupsMarkOptions">cupsMarkOptions()</A></H2>
4516 <H3><A NAME="10_19_1">Usage</A></H3>
4517 <PRE>
4518 int
4519 cupsMarkOptions(ppd_file_t *ppd,
4520                 int num_options,
4521                 cups_option_t *options);
4522 </PRE>
4523 <H3><A NAME="10_19_2">Arguments</A></H3>
4524 <CENTER>
4525 <TABLE BORDER WIDTH="80%">
4526 <TR><TH>Argument</TH><TH>Description</TH></TR>
4527 <TR><TD>ppd</TD><TD>The PPD file to mark.</TD></TR>
4528 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4529 </TR>
4530 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4531 </TABLE>
4532 </CENTER>
4533 <H3><A NAME="10_19_3">Returns</A></H3>
4534 <P>The number of conflicts found.</P>
4535 <H3><A NAME="10_19_4">Description</A></H3>
4536 <P><CODE>cupsMarkOptions()</CODE> marks options in the PPD file. It also
4537  handles mapping of IPP option names and values to PPD option names.</P>
4538 <H3><A NAME="10_19_5">Example</A></H3>
4539 <PRE>
4540 #include &lt;cups/cups.h&gt;
4541
4542 int           num_options;
4543 cups_option_t *options;
4544 ppd_file_t    *ppd;
4545
4546 ...
4547
4548 cupsMarkOptions(ppd, num_options, options);
4549 </PRE>
4550 <H3><A NAME="10_19_6">See Also</A></H3>
4551 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4552  cupsFreeOptions()</A>,<A HREF="#cupsGetOption"> cupsGetOption()</A>,<A HREF="#cupsParseOptions">
4553  cupsParseOptions()</A>
4554 <!-- NEW PAGE -->
4555 </P>
4556 <H2><A NAME="cupsParseOptions">cupsParseOptions()</A></H2>
4557 <H3><A NAME="10_20_1">Usage</A></H3>
4558 <PRE>
4559 int
4560 cupsParseOptions(const char *arg,
4561                  int num_options,
4562                  cups_option_t **options);
4563 </PRE>
4564 <H3><A NAME="10_20_2">Arguments</A></H3>
4565 <CENTER>
4566 <TABLE BORDER WIDTH="80%">
4567 <TR><TH>Argument</TH><TH>Description</TH></TR>
4568 <TR><TD>arg</TD><TD>The string containing one or more options.</TD></TR>
4569 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4570 </TR>
4571 <TR><TD>options</TD><TD>A pointer to the options array pointer.</TD></TR>
4572 </TABLE>
4573 </CENTER>
4574 <H3><A NAME="10_20_3">Returns</A></H3>
4575 <P>The new number of options in the array.</P>
4576 <H3><A NAME="10_20_4">Description</A></H3>
4577 <P><CODE>cupsParseOptions()</CODE> parses the specifies string for one
4578  or more options of the form &quot;name=value&quot;, &quot;name&quot;, or &quot;noname&quot;. It can
4579  be called multiple times to combine the options from several strings.</P>
4580 <H3><A NAME="10_20_5">Example</A></H3>
4581 <PRE>
4582 #include &lt;cups/cups.h&gt;
4583
4584 int           num_options;
4585 cups_option_t *options;
4586
4587 ...
4588
4589 num_options = 0;
4590 options     = (cups_option_t *)0;
4591 num_options = cupsParseOptions(argv[5], num_options, &amp;options);
4592 </PRE>
4593 <H3><A NAME="10_20_6">See Also</A></H3>
4594 <P><A HREF="#cupsAddOption"> cupsAddOption()</A>,<A HREF="#cupsFreeOptions">
4595  cupsFreeOptions()</A>,<A HREF="#cupsGetOption"> cupsGetOption()</A>,<A HREF="#cupsMarkOptions">
4596  cupsMarkOptions()</A>
4597 <!-- NEW PAGE -->
4598 </P>
4599 <H2><A NAME="cupsPrintFile">cupsPrintFile()</A></H2>
4600 <H3><A NAME="10_21_1">Usage</A></H3>
4601 <PRE>
4602 int
4603 cupsPrintFile(const char    *printer,
4604               const char    *filename,
4605               const char    *title,
4606               int           num_options,
4607               cups_option_t *options);
4608 </PRE>
4609 <H3><A NAME="10_21_2">Arguments</A></H3>
4610 <CENTER>
4611 <TABLE BORDER WIDTH="80%">
4612 <TR><TH>Argument</TH><TH>Description</TH></TR>
4613 <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR>
4614 <TR><TD>filename</TD><TD>The file to print.</TD></TR>
4615 <TR><TD>title</TD><TD>The job title.</TD></TR>
4616 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4617 </TR>
4618 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4619 </TABLE>
4620 </CENTER>
4621 <H3><A NAME="10_21_3">Returns</A></H3>
4622 <P>The new job ID number or 0 on error.</P>
4623 <H3><A NAME="10_21_4">Description</A></H3>
4624 <P><CODE>cupsPrintFile()</CODE> sends a file to the specified printer or
4625  class for printing. If the job cannot be printed the error code can be
4626  found by calling <CODE>cupsLastError()</CODE>.</P>
4627 <H3><A NAME="10_21_5">Example</A></H3>
4628 <PRE>
4629 #include &lt;cups/cups.h&gt;
4630
4631 int           num_options;
4632 cups_option_t *options;
4633 int           jobid;
4634
4635 ...
4636
4637 jobid = cupsPrintFile(&quot;printer@hostname&quot;, &quot;filename.ps&quot;, &quot;Job Title&quot;,
4638                       num_options, options);
4639 </PRE>
4640 <H3><A NAME="10_21_6">See Also</A></H3>
4641 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsLastError">
4642  cupsLastError()</A>,<A HREF="#cupsPrintFiles"> cupsPrintFiles()</A>
4643 <!-- NEW PAGE -->
4644 </P>
4645 <H2><A NAME="cupsPrintFiles">cupsPrintFiles()</A></H2>
4646 <H3><A NAME="10_22_1">Usage</A></H3>
4647 <PRE>
4648 int
4649 cupsPrintFiles(const char    *printer,
4650                int           num_files,
4651                const char    **files,
4652                const char    *title,
4653                int           num_options,
4654                cups_option_t *options);
4655 </PRE>
4656 <H3><A NAME="10_22_2">Arguments</A></H3>
4657 <CENTER>
4658 <TABLE BORDER WIDTH="80%">
4659 <TR><TH>Argument</TH><TH>Description</TH></TR>
4660 <TR><TD>printer</TD><TD>The printer or class to print to.</TD></TR>
4661 <TR><TD>num_files</TD><TD>The number of files to print.</TD></TR>
4662 <TR><TD>files</TD><TD>The files to print.</TD></TR>
4663 <TR><TD>title</TD><TD>The job title.</TD></TR>
4664 <TR><TD>num_options</TD><TD>The number of options in the options array.</TD>
4665 </TR>
4666 <TR><TD>options</TD><TD>A pointer to the options array.</TD></TR>
4667 </TABLE>
4668 </CENTER>
4669 <H3><A NAME="10_22_3">Returns</A></H3>
4670 <P>The new job ID number or 0 on error.</P>
4671 <H3><A NAME="10_22_4">Description</A></H3>
4672 <P><CODE>cupsPrintFiles()</CODE> sends multiple files to the specified
4673  printer or class for printing. If the job cannot be printed the error
4674  code can be found by calling <CODE>cupsLastError()</CODE>.</P>
4675 <H3><A NAME="10_22_5">Example</A></H3>
4676 <PRE>
4677 #include &lt;cups/cups.h&gt;
4678
4679 int           num_files;
4680 const char    *files[100];
4681 int           num_options;
4682 cups_option_t *options;
4683 int           jobid;
4684
4685 ...
4686
4687 jobid = cupsPrintFiles(&quot;printer@hostname&quot;, num_files, files,
4688                        &quot;Job Title&quot;, num_options, options);
4689 </PRE>
4690 <H3><A NAME="10_22_6">See Also</A></H3>
4691 <P><A HREF="#cupsCancelJob"> cupsCancelJob()</A>,<A HREF="#cupsLastError">
4692  cupsLastError()</A>,<A HREF="#cupsPrintFile"> cupsPrintFile()</A>
4693 <!-- NEW PAGE -->
4694 </P>
4695 <H2><A NAME="cupsRasterClose">cupsRasterClose()</A></H2>
4696 <H3><A NAME="10_23_1">Usage</A></H3>
4697 <PRE>
4698 void
4699 cupsRasterClose(cups_raster_t *ras);
4700 </PRE>
4701 <H3><A NAME="10_23_2">Arguments</A></H3>
4702 <CENTER>
4703 <TABLE BORDER WIDTH="80%">
4704 <TR><TH>Argument</TH><TH>Description</TH></TR>
4705 <TR><TD>ras</TD><TD>The raster stream to close.</TD></TR>
4706 </TABLE>
4707 </CENTER>
4708 <H3><A NAME="10_23_3">Description</A></H3>
4709 <P><CODE>cupsRasterClose()</CODE> closes the specified raster stream.</P>
4710 <H3><A NAME="10_23_4">Example</A></H3>
4711 <PRE>
4712 #include &lt;cups/raster.h&gt;
4713
4714 cups_raster_t *ras;
4715
4716 ...
4717
4718 cupsRasterClose(ras);
4719 </PRE>
4720 <H3><A NAME="10_23_5">See Also</A></H3>
4721 <P><A HREF="#cupsRasterOpen"> cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4722  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4723  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4724  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4725  cupsRasterWritePixels()</A>
4726 <!-- NEW PAGE -->
4727 </P>
4728 <H2><A NAME="cupsRasterOpen">cupsRasterOpen()</A></H2>
4729 <H3><A NAME="10_24_1">Usage</A></H3>
4730 <PRE>
4731 cups_raster_t *
4732 cupsRasterOpen(int fd,
4733                cups_mode_t mode);
4734 </PRE>
4735 <H3><A NAME="10_24_2">Arguments</A></H3>
4736 <CENTER>
4737 <TABLE BORDER WIDTH="80%">
4738 <TR><TH>Argument</TH><TH>Description</TH></TR>
4739 <TR><TD>fd</TD><TD>The file descriptor to use.</TD></TR>
4740 <TR><TD>mode</TD><TD>The mode to use; <CODE>CUPS_RASTER_READ</CODE> or <CODE>
4741 CUPS_RASTER_WRITE</CODE>.</TD></TR>
4742 </TABLE>
4743 </CENTER>
4744 <H3><A NAME="10_24_3">Returns</A></H3>
4745 <P>A pointer to a raster stream or <CODE>NULL</CODE> if there was an
4746  error.</P>
4747 <H3><A NAME="10_24_4">Description</A></H3>
4748 <P><CODE>cupsRasterOpen()</CODE> opens a raster stream for reading or
4749  writing.</P>
4750 <H3><A NAME="10_24_5">Example</A></H3>
4751 <PRE>
4752 #include &lt;cups/raster.h&gt;
4753
4754 cups_raster_t *ras;
4755
4756 ...
4757
4758 ras = cupsRasterOpen(0, CUPS_RASTER_READ);
4759 </PRE>
4760 <H3><A NAME="10_24_6">See Also</A></H3>
4761 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterReadHeader">
4762  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4763  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4764  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4765  cupsRasterWritePixels()</A>
4766 <!-- NEW PAGE -->
4767 </P>
4768 <H2><A NAME="cupsRasterReadHeader">cupsRasterReadHeader()</A></H2>
4769 <H3><A NAME="10_25_1">Usage</A></H3>
4770 <PRE>
4771 unsigned
4772 cupsRasterReadHeader(cups_raster_t *ras,
4773                      cups_page_header_t *header);
4774 </PRE>
4775 <H3><A NAME="10_25_2">Arguments</A></H3>
4776 <CENTER>
4777 <TABLE BORDER WIDTH="80%">
4778 <TR><TH>Argument</TH><TH>Description</TH></TR>
4779 <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR>
4780 <TR><TD>header</TD><TD>A pointer to a page header structure to read
4781  into.</TD></TR>
4782 </TABLE>
4783 </CENTER>
4784 <H3><A NAME="10_25_3">Returns</A></H3>
4785 <P>1 on success, 0 on EOF or error.</P>
4786 <H3><A NAME="10_25_4">Description</A></H3>
4787 <P><CODE>cupsRasterReadHeader()</CODE> reads a page header from the
4788  specified raster stream.</P>
4789 <H3><A NAME="10_25_5">Example</A></H3>
4790 <PRE>
4791 #include &lt;cups/raster.h&gt;
4792
4793 int                  line;
4794 cups_raster_t        *ras;
4795 cups_raster_header_t header;
4796 unsigned char        pixels[8192];
4797 ...
4798
4799 while (cupsRasterReadHeader(ras, &amp;header))
4800 {
4801   ...
4802
4803   for (line = 0; line &lt; header.cupsHeight; line ++)
4804   {
4805     cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
4806
4807     ...
4808   }
4809 }
4810 </PRE>
4811 <H3><A NAME="10_25_6">See Also</A></H3>
4812 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4813  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadPixels">
4814  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4815  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4816  cupsRasterWritePixels()</A>
4817 <!-- NEW PAGE -->
4818 </P>
4819 <H2><A NAME="cupsRasterReadPixels">cupsRasterReadPixels()</A></H2>
4820 <H3><A NAME="10_26_1">Usage</A></H3>
4821 <PRE>
4822 unsigned
4823 cupsRasterReadPixels(cups_raster_t *ras,
4824                      unsigned char *pixels,
4825                      unsigned length);
4826 </PRE>
4827 <H3><A NAME="10_26_2">Arguments</A></H3>
4828 <CENTER>
4829 <TABLE BORDER WIDTH="80%">
4830 <TR><TH>Argument</TH><TH>Description</TH></TR>
4831 <TR><TD>ras</TD><TD>The raster stream to read from.</TD></TR>
4832 <TR><TD>pixels</TD><TD>The pointer to a pixel buffer.</TD></TR>
4833 <TR><TD>length</TD><TD>The number of bytes of pixel data to read.</TD></TR>
4834 </TABLE>
4835 </CENTER>
4836 <H3><A NAME="10_26_3">Returns</A></H3>
4837 <P>The number of bytes read or 0 on EOF or error.</P>
4838 <H3><A NAME="10_26_4">Description</A></H3>
4839 <P><CODE>cupsRasterReadPixels()</CODE> reads pixel data from the
4840  specified raster stream.</P>
4841 <H3><A NAME="10_26_5">Example</A></H3>
4842 <PRE>
4843 #include &lt;cups/raster.h&gt;
4844
4845 int                  line;
4846 cups_raster_t        *ras;
4847 cups_raster_header_t header;
4848 unsigned char        pixels[8192];
4849 ...
4850
4851 while (cupsRasterReadHeader(ras, &amp;header))
4852 {
4853   ...
4854
4855   for (line = 0; line &lt; header.cupsHeight; line ++)
4856   {
4857     cupsRasterReadPixels(ras, pixels, header.cupsBytesPerLine);
4858
4859     ...
4860   }
4861 }
4862 </PRE>
4863 <H3><A NAME="10_26_6">See Also</A></H3>
4864 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4865  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4866  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterWriteHeader">
4867  cupsRasterWriteHeader()</A>,<A HREF="#cupsRasterWritePixels">
4868  cupsRasterWritePixels()</A>
4869 <!-- NEW PAGE -->
4870 </P>
4871 <H2><A NAME="cupsRasterWriteHeader">cupsRasterWriteHeader()</A></H2>
4872 <H3><A NAME="10_27_1">Usage</A></H3>
4873 <PRE>
4874 unsigned
4875 cupsRasterWriteHeader(cups_raster_t *ras,
4876                       cups_page_header_t *header);
4877 </PRE>
4878 <H3><A NAME="10_27_2">Arguments</A></H3>
4879 <CENTER>
4880 <TABLE BORDER WIDTH="80%">
4881 <TR><TH>Argument</TH><TH>Description</TH></TR>
4882 <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR>
4883 <TR><TD>header</TD><TD>A pointer to the page header to write.</TD></TR>
4884 </TABLE>
4885 </CENTER>
4886 <H3><A NAME="10_27_3">Returns</A></H3>
4887 <P>1 on success, 0 on error.</P>
4888 <H3><A NAME="10_27_4">Description</A></H3>
4889 <P><CODE>cupsRasterWriteHeader()</CODE> writes the specified page header
4890  to a raster stream.</P>
4891 <H3><A NAME="10_27_5">Example</A></H3>
4892 <PRE>
4893 #include &lt;cups/raster.h&gt;
4894
4895 int                  line;
4896 cups_raster_t        *ras;
4897 cups_raster_header_t header;
4898 unsigned char        pixels[8192];
4899 ...
4900
4901 cupsRasterWriteHeader(ras, &amp;header);
4902
4903 for (line = 0; line &lt; header.cupsHeight; line ++)
4904 {
4905   ...
4906
4907   cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
4908 }
4909 </PRE>
4910 <H3><A NAME="10_27_6">See Also</A></H3>
4911 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4912  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4913  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4914  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWritePixels">
4915  cupsRasterWritePixels()</A>
4916 <!-- NEW PAGE -->
4917 </P>
4918 <H2><A NAME="cupsRasterWritePixels">cupsRasterWritePixels()</A></H2>
4919 <H3><A NAME="10_28_1">Usage</A></H3>
4920 <PRE>
4921 unsigned
4922 cupsRasterWritePixels(cups_raster_t *ras,
4923                       unsigned char *pixels,
4924                       unsigned length);
4925 </PRE>
4926 <H3><A NAME="10_28_2">Arguments</A></H3>
4927 <CENTER>
4928 <TABLE BORDER WIDTH="80%">
4929 <TR><TH>Argument</TH><TH>Description</TH></TR>
4930 <TR><TD>ras</TD><TD>The raster stream to write to.</TD></TR>
4931 <TR><TD>pixels</TD><TD>The pixel data to write.</TD></TR>
4932 <TR><TD>length</TD><TD>The number of bytes to write.</TD></TR>
4933 </TABLE>
4934 </CENTER>
4935 <H3><A NAME="10_28_3">Returns</A></H3>
4936 <P>The number of bytes written.</P>
4937 <H3><A NAME="10_28_4">Description</A></H3>
4938 <P><CODE>cupsRasterWritePixels()</CODE> writes the specified pixel data
4939  to a raster stream.</P>
4940 <H3><A NAME="10_28_5">Example</A></H3>
4941 <PRE>
4942 #include &lt;cups/raster.h&gt;
4943
4944 int                  line;
4945 cups_raster_t        *ras;
4946 cups_raster_header_t header;
4947 unsigned char        pixels[8192];
4948 ...
4949
4950 cupsRasterWriteHeader(ras, &amp;header);
4951
4952 for (line = 0; line &lt; header.cupsHeight; line ++)
4953 {
4954   ...
4955
4956   cupsRasterWritePixels(ras, pixels, header.cupsBytesPerLine);
4957 }
4958 </PRE>
4959 <H3><A NAME="10_28_6">See Also</A></H3>
4960 <P><A HREF="#cupsRasterClose"> cupsRasterClose()</A>,<A HREF="#cupsRasterOpen">
4961  cupsRasterOpen()</A>,<A HREF="#cupsRasterReadHeader">
4962  cupsRasterReadHeader()</A>,<A HREF="#cupsRasterReadPixels">
4963  cupsRasterReadPixels()</A>,<A HREF="#cupsRasterWriteHeader">
4964  cupsRasterWriteHeader()</A>
4965 <!-- NEW PAGE -->
4966 </P>
4967 <H2><A NAME="cupsServer">cupsServer()</A></H2>
4968 <H3><A NAME="10_29_1">Usage</A></H3>
4969 <PRE>
4970 const char *
4971 cupsServer(void);
4972 </PRE>
4973 <H3><A NAME="10_29_2">Returns</A></H3>
4974 <P>A pointer to the default server name.</P>
4975 <H3><A NAME="10_29_3">Description</A></H3>
4976 <P><CODE>cupsServer()</CODE> returns a pointer to the default server
4977  name. The server name is stored in a static location and will be
4978  overwritten with every call to <CODE>cupsServer()</CODE></P>
4979 <P>The default server is determined from the following locations:</P>
4980 <OL>
4981 <LI>The <CODE>CUPS_SERVER</CODE> environment variable,</LI>
4982 <LI>The <CODE>ServerName</CODE> directive in the<VAR> client.conf</VAR>
4983  file,</LI>
4984 <LI>The default host, &quot;localhost&quot;.</LI>
4985 </OL>
4986 <H3><A NAME="10_29_4">Example</A></H3>
4987 <PRE>
4988 #include &lt;cups/cups.h&gt;
4989
4990 const char *server;
4991
4992 server = cupsServer();
4993 </PRE>
4994 <H3><A NAME="10_29_5">See Also</A></H3>
4995 <P><A HREF="#cupsGetPassword"> cupsGetPassword()</A>,<A HREF="#cupsSetPasswordCB">
4996  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
4997 HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser"> cupsUser()</A>
4998 <!-- NEW PAGE -->
4999
5000 </P>
5001 <H2><A NAME="cupsSetPasswordCB">cupsSetPasswordCB()</A></H2>
5002 <H3><A NAME="10_30_1">Usage</A></H3>
5003 <PRE>
5004 void
5005 cupsSetPasswordCB(const char *(*cb)(const char *prompt));
5006 </PRE>
5007 <H3><A NAME="10_30_2">Arguments</A></H3>
5008 <CENTER>
5009 <TABLE BORDER WIDTH="80%">
5010 <TR><TH>Argument</TH><TH>Description</TH></TR>
5011 <TR><TD>cb</TD><TD>The password callback function.</TD></TR>
5012 </TABLE>
5013 </CENTER>
5014 <H3><A NAME="10_30_3">Description</A></H3>
5015 <P><CODE>cupsSetPasswordCB()</CODE> sets the callback function to use
5016  when asking the user for a password. The callback function must accept
5017  a single character string pointer (the prompt string) and return <CODE>
5018 NULL</CODE> if the user did not enter a password string or a pointer to
5019  the password string otherwise.</P>
5020 <H3><A NAME="10_30_4">Example</A></H3>
5021 <PRE>
5022 #include &lt;cups/cups.h&gt;
5023
5024 const char *
5025 my_password_cb(const char *prompt)
5026 {
5027   return (getpass(prompt));
5028 }
5029
5030 ...
5031
5032 char *password;
5033
5034 ...
5035
5036 cupsSetPasswordCB(my_password_cb);
5037 password = cupsGetPassword(&quot;Please enter a password:&quot;);
5038 </PRE>
5039 <H3><A NAME="10_30_5">See Also</A></H3>
5040 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetServer">
5041  cupsSetServer()</A>,<A HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser()">
5042  cupsUser()</A>
5043 <!-- NEW PAGE -->
5044 </P>
5045 <H2><A NAME="cupsSetServer">cupsSetServer()</A></H2>
5046 <H3><A NAME="10_31_1">Usage</A></H3>
5047 <PRE>
5048 void
5049 cupsSetServer(const char *server);
5050 </PRE>
5051 <H3><A NAME="10_31_2">Arguments</A></H3>
5052 <CENTER>
5053 <TABLE BORDER WIDTH="80%">
5054 <TR><TH>Argument</TH><TH>Description</TH></TR>
5055 <TR><TD>server</TD><TD>The default server to use.</TD></TR>
5056 </TABLE>
5057 </CENTER>
5058 <H3><A NAME="10_31_3">Description</A></H3>
5059 <P><CODE>cupsSetServer()</CODE> sets the default server to use for the
5060  CUPS API. If the <CODE>server</CODE> argument is <CODE>NULL</CODE>, the
5061  default server is used.</P>
5062 <H3><A NAME="10_31_4">Example</A></H3>
5063 <PRE>
5064 #include &lt;cups/cups.h&gt;
5065
5066 cupsSetServer(&quot;foo.bar.com&quot;);
5067 </PRE>
5068 <H3><A NAME="10_31_5">See Also</A></H3>
5069 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
5070  cupsSetPasswordCB()</A>,<A HREF="#cupsSetUser"> cupsSetUser()</A>,<A HREF="#cupsUser()">
5071  cupsUser()</A>
5072 <!-- NEW PAGE -->
5073 </P>
5074 <H2><A NAME="cupsSetUser">cupsSetUser()</A></H2>
5075 <H3><A NAME="10_32_1">Usage</A></H3>
5076 <PRE>
5077 void
5078 cupsSetUser(const char *user);
5079 </PRE>
5080 <H3><A NAME="10_32_2">Arguments</A></H3>
5081 <CENTER>
5082 <TABLE BORDER WIDTH="80%">
5083 <TR><TH>Argument</TH><TH>Description</TH></TR>
5084 <TR><TD>user</TD><TD>The user name string to use.</TD></TR>
5085 </TABLE>
5086 </CENTER>
5087 <H3><A NAME="10_32_3">Description</A></H3>
5088 <P><CODE>cupsSetUser()</CODE> sets the default user name for
5089  authentication. If the <CODE>user</CODE> argument is <CODE>NULL</CODE>
5090  then the current login user is used.</P>
5091 <H3><A NAME="10_32_4">Example</A></H3>
5092 <PRE>
5093 #include &lt;cups/cups.h&gt;
5094
5095 ...
5096
5097 cupsSetUser(&quot;root&quot;);
5098 </PRE>
5099 <H3><A NAME="10_32_5">See Also</A></H3>
5100 <P><A HREF="#cupsServer"> cupsServer()</A>,<A HREF="#cupsSetPasswordCB">
5101  cupsSetPasswordCB()</A>,<A HREF="#cupsSetServer"> cupsSetServer()</A>,<A
5102 HREF="#cupsUser()"> cupsUser()</A>
5103 <!-- NEW PAGE -->
5104 </P>
5105 <H2><A NAME="cupsTempFile">cupsTempFile()</A></H2>
5106 <H3><A NAME="10_33_1">Usage</A></H3>
5107 <PRE>
5108 char *
5109 cupsTempFile(char *filename,
5110              int length);
5111 </PRE>
5112 <H3><A NAME="10_33_2">Arguments</A></H3>
5113 <CENTER>
5114 <TABLE BORDER WIDTH="80%">
5115 <TR><TH>Argument</TH><TH>Description</TH></TR>
5116 <TR><TD>filename</TD><TD>The character string to hold the temporary
5117  filename.</TD></TR>
5118 <TR><TD>length</TD><TD>The size of the filename string in bytes.</TD></TR>
5119 </TABLE>
5120 </CENTER>
5121 <H3><A NAME="10_33_3">Returns</A></H3>
5122 <P>A pointer to <CODE>filename</CODE>.</P>
5123 <H3><A NAME="10_33_4">Description</A></H3>
5124 <P><CODE>cupsTempFile()</CODE> generates a temporary filename for the<VAR>
5125  /var/tmp</VAR> directory or the directory specified by the <CODE>TMPDIR</CODE>
5126  environment variable.</P>
5127 <H3><A NAME="10_33_5">Example</A></H3>
5128 <PRE>
5129 #include &lt;cups/cups.h&gt;
5130
5131 char filename[256];
5132
5133 cupsTempFile(filename, sizeof(filename));
5134 </PRE>
5135
5136 <!-- NEW PAGE -->
5137 <H2><A NAME="cupsUser">cupsUser()</A></H2>
5138 <H3><A NAME="10_34_1">Usage</A></H3>
5139 <PRE>
5140 const char *
5141 cupsUser(void);
5142 </PRE>
5143 <H3><A NAME="10_34_2">Returns</A></H3>
5144 <P>A pointer to the current username or <CODE>NULL</CODE> if the user ID
5145  is undefined.</P>
5146 <H3><A NAME="10_34_3">Description</A></H3>
5147 <P><CODE>cupsUser()</CODE> returns the name associated with the current
5148  user ID as reported by the <CODE>getuid()</CODE> system call.</P>
5149 <H3><A NAME="10_34_4">Example</A></H3>
5150 <PRE>
5151 #include &lt;cups/cups.h&gt;
5152
5153 const char *user;
5154
5155 user = cupsUser();
5156 </PRE>
5157 <H3><A NAME="10_34_5">See Also</A></H3>
5158 <P><A HREF="#cupsGetPassword"> cupsGetPassword()</A>,<A HREF="#cupsServer">
5159  cupsServer()</A>
5160 <!-- NEW PAGE -->
5161 </P>
5162 <H2><A NAME="httpBlocking">httpBlocking()</A></H2>
5163 <H3><A NAME="10_35_1">Usage</A></H3>
5164 <PRE>
5165 void httpBlocking(http_t *http, int blocking)
5166 </PRE>
5167 <H3><A NAME="10_35_2">Arguments</A></H3>
5168 <CENTER>
5169 <TABLE BORDER WIDTH="80%">
5170 <TR><TH>Argument</TH><TH>Description</TH></TR>
5171 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5172 <TR><TD>blocking</TD><TD>0 if the connection should be non-blocking, 1
5173  if it should be blocking</TD></TR>
5174 </TABLE>
5175 </CENTER>
5176 <H3><A NAME="10_35_3">Description</A></H3>
5177 <P>The <CODE>httpBlocking()</CODE> function sets the blocking mode for
5178  the HTTP connection. By default HTTP connections will block (stop) the
5179  client program until data is available or can be sent to the server.</P>
5180 <H3><A NAME="10_35_4">Example</A></H3>
5181 <PRE>
5182 #include &lt;cups/http.h&gt;
5183
5184 http_t *http;
5185
5186 http = httpConnect(&quot;server&quot;, port);
5187 httpBlocking(http, 0);
5188 </PRE>
5189 <H3><A NAME="10_35_5">See Also</A></H3>
5190 <A HREF="#httpCheck"> <CODE>httpCheck()</CODE></A>,<A HREF="#httpConnect">
5191  <CODE>httpConnect()</CODE></A>
5192 <!-- NEW PAGE -->
5193
5194 <H2><A NAME="httpCheck">httpCheck()</A></H2>
5195 <H3><A NAME="10_36_1">Usage</A></H3>
5196 <PRE>
5197 int httpCheck(http_t *http);
5198 </PRE>
5199 <H3><A NAME="10_36_2">Arguments</A></H3>
5200 <CENTER>
5201 <TABLE BORDER WIDTH="80%">
5202 <TR><TH>Argument</TH><TH>Description</TH></TR>
5203 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5204 </TABLE>
5205 </CENTER>
5206 <H3><A NAME="10_36_3">Returns</A></H3>
5207 <P>0 if there is no data pending, 1 otherwise.</P>
5208 <H3><A NAME="10_36_4">Description</A></H3>
5209 <P>The <CODE>httpCheck()</CODE> function checks to see if there is any
5210  data pending on an HTTP connection.</P>
5211 <H3><A NAME="10_36_5">Example</A></H3>
5212 <PRE>
5213 #include &lt;cups/http.h&gt;
5214
5215 http_t *http;
5216
5217 if (httpCheck(http))
5218 {
5219   ... do something ...
5220 }
5221 </PRE>
5222 <H3><A NAME="10_36_6">See Also</A></H3>
5223 <A HREF="#httpBlocking"> <CODE>httpBlocking()</CODE></A>,<A HREF="#httpConnect">
5224  <CODE>httpConnect()</CODE></A>,<A HREF="#httpGets"> <CODE>httpGets()</CODE>
5225 </A>,<A HREF="#httpRead"> <CODE>httpRead()</CODE></A>
5226 <!-- NEW PAGE -->
5227
5228 <H2><A NAME="httpClearFields">httpClearFields()</A></H2>
5229 <H3><A NAME="10_37_1">Usage</A></H3>
5230 <PRE>
5231 void httpClearFields(http_t *http)
5232 </PRE>
5233 <H3><A NAME="10_37_2">Arguments</A></H3>
5234 <CENTER>
5235 <TABLE BORDER WIDTH="80%">
5236 <TR><TH>Argument</TH><TH>Description</TH></TR>
5237 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5238 </TABLE>
5239 </CENTER>
5240 <H3><A NAME="10_37_3">Description</A></H3>
5241 <P>The <CODE>httpClearFields()</CODE> function clears all HTTP request
5242  fields for the HTTP connection.</P>
5243 <H3><A NAME="10_37_4">Example</A></H3>
5244 <PRE>
5245 #include &lt;cups/http.h&gt;
5246
5247 http_t *http;
5248
5249 httpClearFields(http);
5250 </PRE>
5251 <H3><A NAME="10_37_5">See Also</A></H3>
5252 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpGetField">
5253  <CODE>httpGetField()</CODE></A>,<A HREF="#httpSetField"> <CODE>
5254 httpSetField()</CODE></A>
5255 <!-- NEW PAGE -->
5256
5257 <H2><A NAME="httpClose">httpClose()</A></H2>
5258 <H3><A NAME="10_38_1">Usage</A></H3>
5259 <PRE>
5260 void httpClose(http_t *http);
5261 </PRE>
5262 <H3><A NAME="10_38_2">Arguments</A></H3>
5263 <CENTER>
5264 <TABLE BORDER WIDTH="80%">
5265 <TR><TH>Argument</TH><TH>Description</TH></TR>
5266 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5267 </TABLE>
5268 </CENTER>
5269 <H3><A NAME="10_38_3">Description</A></H3>
5270 <P>The <CODE>httpClose()</CODE> function closes an active HTTP
5271  connection.</P>
5272 <H3><A NAME="10_38_4">Example</A></H3>
5273 <PRE>
5274 #include &lt;cups/http.h&gt;
5275
5276 http_t *http;
5277
5278 httpClose(http);
5279 </PRE>
5280 <H3><A NAME="10_38_5">See Also</A></H3>
5281 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5282 <!-- NEW PAGE -->
5283
5284 <H2><A NAME="httpConnect">httpConnect()</A></H2>
5285 <H3><A NAME="10_39_1">Usage</A></H3>
5286 <PRE>
5287 http_t *httpConnect(const char *hostname, int port);
5288 </PRE>
5289 <H3><A NAME="10_39_2">Arguments</A></H3>
5290 <CENTER>
5291 <TABLE BORDER WIDTH="80%">
5292 <TR><TH>Argument</TH><TH>Description</TH></TR>
5293 <TR><TD>hostname</TD><TD>The name or IP address of the server to connect
5294  to</TD></TR>
5295 <TR><TD>port</TD><TD>The port number to use</TD></TR>
5296 </TABLE>
5297 </CENTER>
5298 <H3><A NAME="10_39_3">Returns</A></H3>
5299 <P>A pointer to a HTTP connection structure or NULL if the connection
5300  could not be made.</P>
5301 <H3><A NAME="10_39_4">Description</A></H3>
5302 <P>The <CODE>httpConnect()</CODE> function opens a HTTP connection to
5303  the specified server and port.</P>
5304 <H3><A NAME="10_39_5">Example</A></H3>
5305 <PRE>
5306 #include &lt;cups/http.h&gt;
5307
5308 http_t *http;
5309
5310 http = httpConnect(cupsServer(), ippPort());
5311 </PRE>
5312 <H3><A NAME="10_39_6">See Also</A></H3>
5313 <A HREF="#httpClose"> <CODE>httpClose()</CODE></A>,<A HREF="#httpGet"> <CODE>
5314 httpGet()</CODE></A>,<A HREF="#httpGets"> <CODE>httpGets()</CODE></A>,<A HREF="#httpPost">
5315  <CODE>httpPost()</CODE></A>,<A HREF="#httpRead"> <CODE>httpRead()</CODE>
5316 </A>,<A HREF="#httpWrite"> <CODE>httpWrite()</CODE></A>
5317 <!-- NEW PAGE -->
5318
5319 <H2><A NAME="httpDecode64">httpDecode64()</A></H2>
5320 <H3><A NAME="10_40_1">Usage</A></H3>
5321 <PRE>
5322 char *httpDecode64(char *out, const char *in);
5323 </PRE>
5324 <H3><A NAME="10_40_2">Arguments</A></H3>
5325 <CENTER>
5326 <TABLE BORDER WIDTH="80%">
5327 <TR><TH>Argument</TH><TH>Description</TH></TR>
5328 <TR><TD>out</TD><TD>The output string</TD></TR>
5329 <TR><TD>in</TD><TD>The input string</TD></TR>
5330 </TABLE>
5331 </CENTER>
5332 <H3><A NAME="10_40_3">Returns</A></H3>
5333 <P>A pointer to the decoded string.</P>
5334 <H3><A NAME="10_40_4">Description</A></H3>
5335 <P>The <CODE>httpDecode64()</CODE> function decodes a base-64 encoded
5336  string to the original string.</P>
5337 <H3><A NAME="10_40_5">Example</A></H3>
5338 <PRE>
5339 #include &lt;cups/http.h&gt;
5340
5341 char encoded_string[255];
5342 char original_string[255];
5343
5344 httpDecode64(original_string, encoded_string);
5345 </PRE>
5346 <H3><A NAME="10_40_6">See Also</A></H3>
5347 <A HREF="#httpEncode64"> <CODE>httpEncode64()</CODE></A>
5348 <!-- NEW PAGE -->
5349
5350 <H2><A NAME="httpDelete">httpDelete()</A></H2>
5351 <H3><A NAME="10_41_1">Usage</A></H3>
5352 <PRE>
5353 int httpDelete(http_t *http, const char *uri);
5354 </PRE>
5355 <H3><A NAME="10_41_2">Arguments</A></H3>
5356 <CENTER>
5357 <TABLE BORDER WIDTH="80%">
5358 <TR><TH>Argument</TH><TH>Description</TH></TR>
5359 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5360 <TR><TD>uri</TD><TD>The URI to delete</TD></TR>
5361 </TABLE>
5362 </CENTER>
5363 <H3><A NAME="10_41_3">Returns</A></H3>
5364 <P>0 on success, non-zero on failure.</P>
5365 <H3><A NAME="10_41_4">Description</A></H3>
5366 <P>The <CODE>httpDelete()</CODE> function sends a HTTP DELETE request to
5367  the server.</P>
5368 <H3><A NAME="10_41_5">Example</A></H3>
5369 <PRE>
5370 #include &lt;cups/http.h&gt;
5371
5372 http_t *http;
5373
5374 httpDelete(http, &quot;/some/uri&quot;);
5375 </PRE>
5376 <H3><A NAME="10_41_6">See Also</A></H3>
5377 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5378  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5379 httpUpdate()</CODE></A>
5380 <!-- NEW PAGE -->
5381
5382 <H2><A NAME="httpEncode64">httpEncode64()</A></H2>
5383 <H3><A NAME="10_42_1">Usage</A></H3>
5384 <PRE>
5385 char *httpEncode64(char *out, const char *in);
5386 </PRE>
5387 <H3><A NAME="10_42_2">Arguments</A></H3>
5388 <CENTER>
5389 <TABLE BORDER WIDTH="80%">
5390 <TR><TH>Argument</TH><TH>Description</TH></TR>
5391 <TR><TD>out</TD><TD>The output string</TD></TR>
5392 <TR><TD>in</TD><TD>The input string</TD></TR>
5393 </TABLE>
5394 </CENTER>
5395 <H3><A NAME="10_42_3">Returns</A></H3>
5396 <P>A pointer to the encoded string.</P>
5397 <H3><A NAME="10_42_4">Description</A></H3>
5398 <P>The <CODE>httpEncode64()</CODE> function decodes a base-64 encoded
5399  string to the original string.</P>
5400 <H3><A NAME="10_42_5">Example</A></H3>
5401 <PRE>
5402 #include &lt;cups/http.h&gt;
5403
5404 char encoded_string[255];
5405 char original_string[255];
5406
5407 httpEncode64(encoded_string, original_string);
5408 </PRE>
5409 <H3><A NAME="10_42_6">See Also</A></H3>
5410 <A HREF="#httpDecode64"> <CODE>httpDecode64()</CODE></A>
5411 <!-- NEW PAGE -->
5412
5413 <H2><A NAME="httpError">httpError()</A></H2>
5414 <H3><A NAME="10_43_1">Usage</A></H3>
5415 <PRE>
5416 int httpError(http_t *http);
5417 </PRE>
5418 <H3><A NAME="10_43_2">Arguments</A></H3>
5419 <CENTER>
5420 <TABLE BORDER WIDTH="80%">
5421 <TR><TH>Argument</TH><TH>Description</TH></TR>
5422 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5423 </TABLE>
5424 </CENTER>
5425 <H3><A NAME="10_43_3">Returns</A></H3>
5426 <P>The last error that occurred or 0 if no error has occurred.</P>
5427 <H3><A NAME="10_43_4">Description</A></H3>
5428 <P>The <CODE>httpError()</CODE> function returns the last error that
5429  occurred on the HTTP connection.</P>
5430 <H3><A NAME="10_43_5">Example</A></H3>
5431 <PRE>
5432 #include &lt;cups/http.h&gt;
5433
5434 http_t *http;
5435
5436 if (httpError(http))
5437 {
5438   ... show an error message ...
5439 }
5440 </PRE>
5441 <H3><A NAME="10_43_6">See Also</A></H3>
5442 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5443 <!-- NEW PAGE -->
5444
5445 <H2><A NAME="httpFlush">httpFlush()</A></H2>
5446 <H3><A NAME="10_44_1">Usage</A></H3>
5447 <PRE>
5448 void httpFlush(http_t *http);
5449 </PRE>
5450 <H3><A NAME="10_44_2">Arguments</A></H3>
5451 <CENTER>
5452 <TABLE BORDER WIDTH="80%">
5453 <TR><TH>Argument</TH><TH>Description</TH></TR>
5454 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5455 </TABLE>
5456 </CENTER>
5457 <H3><A NAME="10_44_3">Description</A></H3>
5458 <P>The <CODE>httpFlush()</CODE> function flushes any remaining data left
5459  from a GET or POST operation.</P>
5460 <H3><A NAME="10_44_4">Example</A></H3>
5461 <PRE>
5462 #include &lt;cups/http.h&gt;
5463
5464 http_t *http;
5465
5466 httpFlush(http);
5467 </PRE>
5468 <H3><A NAME="10_44_5">See Also</A></H3>
5469 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,
5470 <!-- NEW PAGE -->
5471
5472 <H2><A NAME="httpGet">httpGet()</A></H2>
5473 <H3><A NAME="10_45_1">Usage</A></H3>
5474 <PRE>
5475 int httpGet(http_t *http, const char *uri);
5476 </PRE>
5477 <H3><A NAME="10_45_2">Arguments</A></H3>
5478 <CENTER>
5479 <TABLE BORDER WIDTH="80%">
5480 <TR><TH>Argument</TH><TH>Description</TH></TR>
5481 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5482 <TR><TD>uri</TD><TD>The URI to get</TD></TR>
5483 </TABLE>
5484 </CENTER>
5485 <H3><A NAME="10_45_3">Returns</A></H3>
5486 <P>0 on success, non-zero on failure.</P>
5487 <H3><A NAME="10_45_4">Description</A></H3>
5488 <P>The <CODE>httpGet()</CODE> function sends a HTTP GET request to the
5489  server.</P>
5490 <H3><A NAME="10_45_5">Example</A></H3>
5491 <PRE>
5492 #include &lt;cups/http.h&gt;
5493
5494 http_t *http;
5495
5496 httpGet(http, &quot;/some/uri&quot;);
5497 </PRE>
5498 <H3><A NAME="10_45_6">See Also</A></H3>
5499 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5500  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5501 httpUpdate()</CODE></A>
5502 <!-- NEW PAGE -->
5503
5504 <H2><A NAME="httpGets">httpGets()</A></H2>
5505 <H3><A NAME="10_46_1">Usage</A></H3>
5506 <PRE>
5507 char *httpGets(char *line, int length, http_t *http)
5508 </PRE>
5509 <H3><A NAME="10_46_2">Arguments</A></H3>
5510 <CENTER>
5511 <TABLE BORDER WIDTH="80%">
5512 <TR><TH>Argument</TH><TH>Description</TH></TR>
5513 <TR><TD>line</TD><TD>The string to fill with a line from the HTTP
5514  connection</TD></TR>
5515 <TR><TD>length</TD><TD>The maximum length of the string</TD></TR>
5516 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5517 </TABLE>
5518 </CENTER>
5519 <H3><A NAME="10_46_3">Returns</A></H3>
5520 <P>A pointer to the string or NULL if no line could be retrieved.</P>
5521 <H3><A NAME="10_46_4">Description</A></H3>
5522 <P>The <CODE>httpGets()</CODE> function is used to read a request line
5523  from the HTTP connection. It is not normally used by a client program.</P>
5524 <H3><A NAME="10_46_5">Example</A></H3>
5525 <PRE>
5526 #include &lt;cups/http.h&gt;
5527
5528 http_t *http;
5529 char line[1024];
5530
5531 if (httpGets(line, sizeof(line), http))
5532 {
5533   ... process the line ...
5534 }
5535 </PRE>
5536 <H3><A NAME="10_46_6">See Also</A></H3>
5537 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpUpdate">
5538  <CODE>httpUpdate()</CODE></A>
5539 <!-- NEW PAGE -->
5540
5541 <H2><A NAME="httpGetDateString">httpGetDateString()</A></H2>
5542 <H3><A NAME="10_47_1">Usage</A></H3>
5543 <PRE>
5544 const char *httpGetDateString(time_t time)
5545 </PRE>
5546 <H3><A NAME="10_47_2">Arguments</A></H3>
5547 <CENTER>
5548 <TABLE BORDER WIDTH="80%">
5549 <TR><TH>Argument</TH><TH>Description</TH></TR>
5550 <TR><TD>time</TD><TD>The UNIX date/time value</TD></TR>
5551 </TABLE>
5552 </CENTER>
5553 <H3><A NAME="10_47_3">Returns</A></H3>
5554 <P>A pointer to a static string containing the HTTP date/time string for
5555  the specified UNIX time value.</P>
5556 <H3><A NAME="10_47_4">Description</A></H3>
5557 <P>The <CODE>httpGetDateString()</CODE> function generates a date/time
5558  string suitable for HTTP requests from a UNIX time value.</P>
5559 <H3><A NAME="10_47_5">Example</A></H3>
5560 <PRE>
5561 #include &lt;cups/http.h&gt;
5562
5563 puts(httpGetDateString(time(NULL)));
5564 </PRE>
5565 <H3><A NAME="10_47_6">See Also</A></H3>
5566 <A HREF="#httpGetDateTime"> <CODE>httpGetDateTime()</CODE></A>
5567 <!-- NEW PAGE -->
5568
5569 <H2><A NAME="httpGetDateTime">httpGetDateTime()</A></H2>
5570 <H3><A NAME="10_48_1">Usage</A></H3>
5571 <PRE>
5572 time_t httpGetDateTime(const char *date)
5573 </PRE>
5574 <H3><A NAME="10_48_2">Arguments</A></H3>
5575 <CENTER>
5576 <TABLE BORDER WIDTH="80%">
5577 <TR><TH>Argument</TH><TH>Description</TH></TR>
5578 <TR><TD>date</TD><TD>The HTTP date/time string</TD></TR>
5579 </TABLE>
5580 </CENTER>
5581 <H3><A NAME="10_48_3">Returns</A></H3>
5582 <P>A UNIX time value.</P>
5583 <H3><A NAME="10_48_4">Description</A></H3>
5584 <P>The <CODE>httpGetDateTime()</CODE> function converts a HTTP date/time
5585  string to a UNIX time value.</P>
5586 <H3><A NAME="10_48_5">Example</A></H3>
5587 <PRE>
5588 #include &lt;cups/http.h&gt;
5589
5590 printf(&quot;%d\n&quot;, httpGetDateTime(&quot;Fri, 30 June 2000 12:34:56 GMT&quot;));
5591 </PRE>
5592 <H3><A NAME="10_48_6">See Also</A></H3>
5593 <A HREF="#httpGetDateString"> <CODE>httpGetDateString()</CODE></A>
5594 <!-- NEW PAGE -->
5595
5596 <H2><A NAME="httpGetField">httpGetField()</A></H2>
5597 <H3><A NAME="10_49_1">Usage</A></H3>
5598 <PRE>
5599 const char *httpGetField(http_t *http, http_field_t field);
5600 </PRE>
5601 <H3><A NAME="10_49_2">Arguments</A></H3>
5602 <CENTER>
5603 <TABLE BORDER WIDTH="80%">
5604 <TR><TH>Argument</TH><TH>Description</TH></TR>
5605 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5606 <TR><TD>field</TD><TD>The HTTP field</TD></TR>
5607 </TABLE>
5608 </CENTER>
5609 <H3><A NAME="10_49_3">Returns</A></H3>
5610 <P>A pointer to the field value string.</P>
5611 <H3><A NAME="10_49_4">Description</A></H3>
5612 <P>The <CODE>httpGetField()</CODE> function returns the current value
5613  for the specified HTTP field.</P>
5614 <H3><A NAME="10_49_5">Example</A></H3>
5615 <PRE>
5616 #include &lt;cups/http.h&gt;
5617
5618 http_t *http;
5619
5620 httpGet(http, &quot;/some/uri&quot;);
5621 while (httpUpdate(http) == HTTP_CONTINUE);
5622
5623 puts(httpGetField(http, HTTP_FIELD_CONTENT_TYPE));
5624 </PRE>
5625 <H3><A NAME="10_49_6">See Also</A></H3>
5626 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5627  <CODE>httpSetField()</CODE></A>
5628 <!-- NEW PAGE -->
5629
5630 <H2><A NAME="httpHead">httpHead()</A></H2>
5631 <H3><A NAME="10_50_1">Usage</A></H3>
5632 <PRE>
5633 int httpHead(http_t *http, const char *uri);
5634 </PRE>
5635 <H3><A NAME="10_50_2">Arguments</A></H3>
5636 <CENTER>
5637 <TABLE BORDER WIDTH="80%">
5638 <TR><TH>Argument</TH><TH>Description</TH></TR>
5639 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5640 <TR><TD>uri</TD><TD>The URI to head</TD></TR>
5641 </TABLE>
5642 </CENTER>
5643 <H3><A NAME="10_50_3">Returns</A></H3>
5644 <P>0 on success, non-zero on failure.</P>
5645 <H3><A NAME="10_50_4">Description</A></H3>
5646 <P>The <CODE>httpHead()</CODE> function sends a HTTP HEAD request to the
5647  server.</P>
5648 <H3><A NAME="10_50_5">Example</A></H3>
5649 <PRE>
5650 #include &lt;cups/http.h&gt;
5651
5652 http_t *http;
5653
5654 httpHead(http, &quot;/some/uri&quot;);
5655 </PRE>
5656 <H3><A NAME="10_50_6">See Also</A></H3>
5657 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5658  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5659 httpUpdate()</CODE></A>
5660 <!-- NEW PAGE -->
5661
5662 <H2><A NAME="httpInitialize">httpInitialize()</A></H2>
5663 <H3><A NAME="10_51_1">Usage</A></H3>
5664 <PRE>
5665 void httpInitialize(void);
5666 </PRE>
5667 <H3><A NAME="10_51_2">Description</A></H3>
5668 <P>The <CODE>httpInitialize()</CODE> function initializes the networking
5669  code as needed by the underlying platform. It is called automatically
5670  by the <CODE>httpConnect()</CODE> function.</P>
5671 <H3><A NAME="10_51_3">Example</A></H3>
5672 <PRE>
5673 #include &lt;cups/http.h&gt;
5674
5675 httpInitialize();
5676 </PRE>
5677 <H3><A NAME="10_51_4">See Also</A></H3>
5678 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5679 <!-- NEW PAGE -->
5680
5681 <H2><A NAME="httpOptions">httpOptions()</A></H2>
5682 <H3><A NAME="10_52_1">Usage</A></H3>
5683 <PRE>
5684 int httpOptions(http_t *http, const char *uri);
5685 </PRE>
5686 <H3><A NAME="10_52_2">Arguments</A></H3>
5687 <CENTER>
5688 <TABLE BORDER WIDTH="80%">
5689 <TR><TH>Argument</TH><TH>Description</TH></TR>
5690 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5691 <TR><TD>uri</TD><TD>The URI to check for options</TD></TR>
5692 </TABLE>
5693 </CENTER>
5694 <H3><A NAME="10_52_3">Returns</A></H3>
5695 <P>0 on success, non-zero on failure.</P>
5696 <H3><A NAME="10_52_4">Description</A></H3>
5697 <P>The <CODE>httpOptions()</CODE> function sends a HTTP OPTIONS request
5698  to the server.</P>
5699 <H3><A NAME="10_52_5">Example</A></H3>
5700 <PRE>
5701 #include &lt;cups/http.h&gt;
5702
5703 http_t *http;
5704
5705 httpOptions(http, &quot;/some/uri&quot;);
5706 </PRE>
5707 <H3><A NAME="10_52_6">See Also</A></H3>
5708 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5709  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5710 httpUpdate()</CODE></A>
5711 <!-- NEW PAGE -->
5712
5713 <H2><A NAME="httpPost">httpPost()</A></H2>
5714 <H3><A NAME="10_53_1">Usage</A></H3>
5715 <PRE>
5716 int httpPost(http_t *http, const char *uri);
5717 </PRE>
5718 <H3><A NAME="10_53_2">Arguments</A></H3>
5719 <CENTER>
5720 <TABLE BORDER WIDTH="80%">
5721 <TR><TH>Argument</TH><TH>Description</TH></TR>
5722 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5723 <TR><TD>uri</TD><TD>The URI to post to</TD></TR>
5724 </TABLE>
5725 </CENTER>
5726 <H3><A NAME="10_53_3">Returns</A></H3>
5727 <P>0 on success, non-zero on failure.</P>
5728 <H3><A NAME="10_53_4">Description</A></H3>
5729 <P>The <CODE>httpPost()</CODE> function sends a HTTP POST request to the
5730  server.</P>
5731 <H3><A NAME="10_53_5">Example</A></H3>
5732 <PRE>
5733 #include &lt;cups/http.h&gt;
5734
5735 http_t *http;
5736
5737 httpPost(http, &quot;/some/uri&quot;);
5738 </PRE>
5739 <H3><A NAME="10_53_6">See Also</A></H3>
5740 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5741  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5742 httpUpdate()</CODE></A>
5743 <!-- NEW PAGE -->
5744
5745 <H2><A NAME="httpPrintf">httpPrintf()</A></H2>
5746 <H3><A NAME="10_54_1">Usage</A></H3>
5747 <PRE>
5748 int httpPrintf(http_t *http, const char *format, ...);
5749 </PRE>
5750 <H3><A NAME="10_54_2">Arguments</A></H3>
5751 <CENTER>
5752 <TABLE BORDER WIDTH="80%">
5753 <TR><TH>Argument</TH><TH>Description</TH></TR>
5754 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5755 <TR><TD>format</TD><TD>A printf-style format string</TD></TR>
5756 </TABLE>
5757 </CENTER>
5758 <H3><A NAME="10_54_3">Returns</A></H3>
5759 <P>The number of bytes written.</P>
5760 <H3><A NAME="10_54_4">Description</A></H3>
5761 <P>The <CODE>httpPrintf()</CODE> function sends a formatted string to
5762  the HTTP connection. It is normally only used by the CUPS API and
5763  scheduler.</P>
5764 <H3><A NAME="10_54_5">Example</A></H3>
5765 <PRE>
5766 #include &lt;cups/http.h&gt;
5767
5768 http_t *http;
5769
5770 httpPrintf(http, &quot;GET / HTTP/1.1 \r\n&quot;);
5771 </PRE>
5772 <H3><A NAME="10_54_6">See Also</A></H3>
5773 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5774 <!-- NEW PAGE -->
5775
5776 <H2><A NAME="httpPut">httpPut()</A></H2>
5777 <H3><A NAME="10_55_1">Usage</A></H3>
5778 <PRE>
5779 int httpPut(http_t *http, const char *uri);
5780 </PRE>
5781 <H3><A NAME="10_55_2">Arguments</A></H3>
5782 <CENTER>
5783 <TABLE BORDER WIDTH="80%">
5784 <TR><TH>Argument</TH><TH>Description</TH></TR>
5785 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5786 <TR><TD>uri</TD><TD>The URI to put</TD></TR>
5787 </TABLE>
5788 </CENTER>
5789 <H3><A NAME="10_55_3">Returns</A></H3>
5790 <P>0 on success, non-zero on failure.</P>
5791 <H3><A NAME="10_55_4">Description</A></H3>
5792 <P>The <CODE>httpPut()</CODE> function sends a HTTP PUT request to the
5793  server.</P>
5794 <H3><A NAME="10_55_5">Example</A></H3>
5795 <PRE>
5796 #include &lt;cups/http.h&gt;
5797
5798 http_t *http;
5799
5800 httpDelete(http, &quot;/some/uri&quot;);
5801 </PRE>
5802 <H3><A NAME="10_55_6">See Also</A></H3>
5803 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5804  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5805 httpUpdate()</CODE></A>
5806 <!-- NEW PAGE -->
5807
5808 <H2><A NAME="httpRead">httpRead()</A></H2>
5809 <H3><A NAME="10_56_1">Usage</A></H3>
5810 <PRE>
5811 int httpRead(http_t *http, char *buffer, int length);
5812 </PRE>
5813 <H3><A NAME="10_56_2">Arguments</A></H3>
5814 <CENTER>
5815 <TABLE BORDER WIDTH="80%">
5816 <TR><TH>Argument</TH><TH>Description</TH></TR>
5817 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5818 <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR>
5819 <TR><TD>length</TD><TD>The number of bytes to read</TD></TR>
5820 </TABLE>
5821 </CENTER>
5822 <H3><A NAME="10_56_3">Returns</A></H3>
5823 <P>The number of bytes read or -1 on error.</P>
5824 <H3><A NAME="10_56_4">Description</A></H3>
5825 <P>The <CODE>httpRead()</CODE> function reads data from the HTTP
5826  connection, possibly the result of a GET or POST request.</P>
5827 <H3><A NAME="10_56_5">Example</A></H3>
5828 <PRE>
5829 #include &lt;cups/http.h&gt;
5830
5831 http_t *http;
5832 char buffer[1024];
5833 int  bytes;
5834
5835 httpGet(http, &quot;/&quot;);
5836 while (httpUpdate(http) != HTTP_CONTINUE);
5837 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) &gt; 0)
5838 {
5839   buffer[bytes] = '\0';
5840   fputs(buffer, stdout);
5841 }
5842 </PRE>
5843 <H3><A NAME="10_56_6">See Also</A></H3>
5844 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpWrite">
5845  <CODE>httpWrite()</CODE></A>
5846 <!-- NEW PAGE -->
5847
5848 <H2><A NAME="httpReconnect">httpReconnect()</A></H2>
5849 <H3><A NAME="10_57_1">Usage</A></H3>
5850 <PRE>
5851 int httpReconnect(http_t *http);
5852 </PRE>
5853 <H3><A NAME="10_57_2">Arguments</A></H3>
5854 <CENTER>
5855 <TABLE BORDER WIDTH="80%">
5856 <TR><TH>Argument</TH><TH>Description</TH></TR>
5857 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5858 </TABLE>
5859 </CENTER>
5860 <H3><A NAME="10_57_3">Returns</A></H3>
5861 <P>0 on success, non-zero on failure.</P>
5862 <H3><A NAME="10_57_4">Description</A></H3>
5863 <P>The <CODE>httpReconnect()</CODE> function reconnects to the HTTP
5864  server. This is usually done automatically if the HTTP functions detect
5865  that the server connection has terminated.</P>
5866 <H3><A NAME="10_57_5">Example</A></H3>
5867 <PRE>
5868 #include &lt;cups/http.h&gt;
5869
5870 http_t *http;
5871
5872 httpReconnect(http);
5873 </PRE>
5874 <H3><A NAME="10_57_6">See Also</A></H3>
5875 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5876 <!-- NEW PAGE -->
5877
5878 <H2><A NAME="httpSeparate">httpSeparate()</A></H2>
5879 <H3><A NAME="10_58_1">Usage</A></H3>
5880 <PRE>
5881 void httpSeparate(const char *uri, char *method,
5882                   char *username, char *host, int *port,
5883                   char *resource);
5884 </PRE>
5885 <H3><A NAME="10_58_2">Arguments</A></H3>
5886 <CENTER>
5887 <TABLE BORDER WIDTH="80%">
5888 <TR><TH>Argument</TH><TH>Description</TH></TR>
5889 <TR><TD>uri</TD><TD>The URI to separate</TD></TR>
5890 <TR><TD>method</TD><TD>The method (scheme) of the URI</TD></TR>
5891 <TR><TD>username</TD><TD>The username (and password) portion of the URI,
5892  if any</TD></TR>
5893 <TR><TD>host</TD><TD>The hostname portion of the URI, if any</TD></TR>
5894 <TR><TD>port</TD><TD>The port number for the URI, either as specified or
5895  as default for the method/scheme</TD></TR>
5896 <TR><TD>resource</TD><TD>The resource string, usually a filename on the
5897  server</TD></TR>
5898 </TABLE>
5899 </CENTER>
5900 <H3><A NAME="10_58_3">Description</A></H3>
5901 <P>The <CODE>httpSeparate()</CODE> function separates the specified URI
5902  into its component parts. The method, username, hostname, and resource
5903  strings should be at least <CODE>HTTP_MAX_URI</CODE> characters long to
5904  avoid potential buffer overflow problems.</P>
5905 <H3><A NAME="10_58_4">Example</A></H3>
5906 <PRE>
5907 char uri[HTTP_MAX_URI];
5908 char method[HTTP_MAX_URI];
5909 char username[HTTP_MAX_URI];
5910 char host[HTTP_MAX_URI];
5911 char resource[HTTP_MAX_URI];
5912 int port;
5913
5914 httpSeparate(uri, method, username, host, &amp;port, resource);
5915 </PRE>
5916 <H3><A NAME="10_58_5">See Also</A></H3>
5917 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>
5918 <!-- NEW PAGE -->
5919
5920 <H2><A NAME="httpSetField">httpSetField()</A></H2>
5921 <H3><A NAME="10_59_1">Usage</A></H3>
5922 <PRE>
5923 void httpSetField(http_t *http, http_field_t field, const char *value);
5924 </PRE>
5925 <H3><A NAME="10_59_2">Arguments</A></H3>
5926 <CENTER>
5927 <TABLE BORDER WIDTH="80%">
5928 <TR><TH>Argument</TH><TH>Description</TH></TR>
5929 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5930 <TR><TD>field</TD><TD>The HTTP field</TD></TR>
5931 <TR><TD>value</TD><TD>The string value for the field</TD></TR>
5932 </TABLE>
5933 </CENTER>
5934 <H3><A NAME="10_59_3">Description</A></H3>
5935 <P>The <CODE>httpSetField()</CODE> function sets the current value for
5936  the specified HTTP field.</P>
5937 <H3><A NAME="10_59_4">Example</A></H3>
5938 <PRE>
5939 #include &lt;cups/http.h&gt;
5940
5941 http_t *http;
5942
5943 httpSetField(http, HTTP_FIELD_AUTHORIZATION, &quot;Basic dfdr34453454325&quot;));
5944 httpGet(http, &quot;/some/uri&quot;);
5945 while (httpUpdate(http) == HTTP_CONTINUE);
5946 </PRE>
5947 <H3><A NAME="10_59_5">See Also</A></H3>
5948 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpGetField">
5949  <CODE>httpGetField()</CODE></A>
5950 <!-- NEW PAGE -->
5951
5952 <H2><A NAME="httpTrace">httpTrace()</A></H2>
5953 <H3><A NAME="10_60_1">Usage</A></H3>
5954 <PRE>
5955 int httpTrace(http_t *http, const char *uri);
5956 </PRE>
5957 <H3><A NAME="10_60_2">Arguments</A></H3>
5958 <CENTER>
5959 <TABLE BORDER WIDTH="80%">
5960 <TR><TH>Argument</TH><TH>Description</TH></TR>
5961 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5962 <TR><TD>uri</TD><TD>The URI to trace</TD></TR>
5963 </TABLE>
5964 </CENTER>
5965 <H3><A NAME="10_60_3">Returns</A></H3>
5966 <P>0 on success, non-zero on failure.</P>
5967 <H3><A NAME="10_60_4">Description</A></H3>
5968 <P>The <CODE>httpTrace()</CODE> function sends a HTTP TRACE request to
5969  the server.</P>
5970 <H3><A NAME="10_60_5">Example</A></H3>
5971 <PRE>
5972 #include &lt;cups/http.h&gt;
5973
5974 http_t *http;
5975
5976 httpTrace(http, &quot;/some/uri&quot;);
5977 </PRE>
5978 <H3><A NAME="10_60_6">See Also</A></H3>
5979 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpSetField">
5980  <CODE>httpSetField()</CODE></A>,<A HREF="#httpUpdate"> <CODE>
5981 httpUpdate()</CODE></A>
5982 <!-- NEW PAGE -->
5983
5984 <H2><A NAME="httpUpdate">httpUpdate()</A></H2>
5985 <H3><A NAME="10_61_1">Usage</A></H3>
5986 <PRE>
5987 http_status_t httpUpdate(http_t *http);
5988 </PRE>
5989 <H3><A NAME="10_61_2">Arguments</A></H3>
5990 <CENTER>
5991 <TABLE BORDER WIDTH="80%">
5992 <TR><TH>Argument</TH><TH>Description</TH></TR>
5993 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
5994 </TABLE>
5995 </CENTER>
5996 <H3><A NAME="10_61_3">Returns</A></H3>
5997 <P>The HTTP status of the current request.</P>
5998 <H3><A NAME="10_61_4">Description</A></H3>
5999 <P>The <CODE>httpUpdate()</CODE> function updates the current request
6000  status. It is used after any DELETE, GET, HEAD, OPTIONS, POST, PUT, or
6001  TRACE request to finalize the HTTP request and retrieve the request
6002  status.</P>
6003 <P>Since proxies and the current blocking mode can cause the request to
6004  take longer, programs should continue calling <CODE>httpUpdate()</CODE>
6005  until the return status is not the constant value <CODE>HTTP_CONTINUE</CODE>
6006 .</P>
6007 <H3><A NAME="10_61_5">Example</A></H3>
6008 <PRE>
6009 #include &lt;cups/http.h&gt;
6010
6011 http_t *http;
6012 http_status_t status;
6013
6014 httpGet(http, &quot;/some/uri&quot;);
6015 while ((status = httpUpdate(http)) == HTTP_CONTINUE);
6016 printf(&quot;Request status is %d\n&quot;, status);
6017 </PRE>
6018 <H3><A NAME="10_61_6">See Also</A></H3>
6019 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpDelete">
6020  <CODE>httpDelete()</CODE></A>,<A HREF="#httpGet"> <CODE>httpGet()</CODE>
6021 </A>,<A HREF="#httpHead"> <CODE>httpHead()</CODE></A>,<A HREF="#httpOptions">
6022  <CODE>httpOptions()</CODE></A>,<A HREF="#httpPost"> <CODE>httpPost()</CODE>
6023 </A>,<A HREF="#httpPut"> <CODE>httpPut()</CODE></A>,<A HREF="#httpTrace">
6024  <CODE>httpTrace()</CODE></A>
6025 <!-- NEW PAGE -->
6026
6027 <H2><A NAME="httpWrite">httpWrite()</A></H2>
6028 <H3><A NAME="10_62_1">Usage</A></H3>
6029 <PRE>
6030 int httpWrite(http_t *http, char *buffer, int length);
6031 </PRE>
6032 <H3><A NAME="10_62_2">Arguments</A></H3>
6033 <CENTER>
6034 <TABLE BORDER WIDTH="80%">
6035 <TR><TH>Argument</TH><TH>Description</TH></TR>
6036 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6037 <TR><TD>buffer</TD><TD>The buffer to read into</TD></TR>
6038 <TR><TD>length</TD><TD>The number of bytes to read</TD></TR>
6039 </TABLE>
6040 </CENTER>
6041 <H3><A NAME="10_62_3">Returns</A></H3>
6042 <P>The number of bytes read or -1 on error.</P>
6043 <H3><A NAME="10_62_4">Description</A></H3>
6044 <P>The <CODE>httpWrite()</CODE> function reads data from the HTTP
6045  connection, possibly the result of a GET or POST request.</P>
6046 <H3><A NAME="10_62_5">Example</A></H3>
6047 <PRE>
6048 #include &lt;cups/http.h&gt;
6049
6050 http_t *http;
6051 FILE *fp;
6052 char buffer[1024];
6053 int  bytes;
6054
6055 httpPost(http, &quot;/&quot;);
6056
6057 while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) &gt; 0)
6058   httpWrite(http, buffer, bytes);
6059
6060 while (httpUpdate(http) != HTTP_CONTINUE);
6061
6062 while ((bytes = httpRead(http, buffer, sizeof(buffer) - 1)) &gt; 0)
6063 {
6064   buffer[bytes] = '\0';
6065   fputs(buffer, stdout);
6066 }
6067 </PRE>
6068 <H3><A NAME="10_62_6">See Also</A></H3>
6069 <A HREF="#httpConnect"> <CODE>httpConnect()</CODE></A>,<A HREF="#httpRead">
6070  <CODE>httpRead()</CODE></A>
6071 <!-- NEW PAGE -->
6072
6073 <H2><A NAME="ippAddBoolean">ippAddBoolean()</A></H2>
6074 <H3><A NAME="10_63_1">Usage</A></H3>
6075 <PRE>
6076 ipp_attribute_t *ippAddBoolean(ipp_t *ipp, ipp_tag_t group,
6077                                const char *name, char value);
6078 </PRE>
6079 <H3><A NAME="10_63_2">Arguments</A></H3>
6080 <CENTER>
6081 <TABLE BORDER WIDTH="80%">
6082 <TR><TH>Argument</TH><TH>Description</TH></TR>
6083 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6084 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6085 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6086 <TR><TD>value</TD><TD>The boolean value</TD></TR>
6087 </TABLE>
6088 </CENTER>
6089 <H3><A NAME="10_63_3">Returns</A></H3>
6090 <P>A pointer to the new attribute or NULL if the attribute could not be
6091  created.</P>
6092 <H3><A NAME="10_63_4">Description</A></H3>
6093 <P>The <CODE>ippAddBoolean()</CODE> function adds a single boolean
6094  attribute value to the specified IPP request.</P>
6095 <H3><A NAME="10_63_5">Example</A></H3>
6096 <PRE>
6097 #include &lt;cups/ipp.h&gt;
6098
6099 ipp_t *ipp;
6100
6101 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;my-jobs&quot;, 1);
6102 </PRE>
6103 <H3><A NAME="10_63_6">See Also</A></H3>
6104 <A HREF="#ippAddBooleans"> <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate">
6105  <CODE>ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6106 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6107 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6108 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6109  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6110 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6111 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6112 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6113 ippAddStrings()</CODE></A>
6114 <!-- NEW PAGE -->
6115
6116 <H2><A NAME="ippAddBooleans">ippAddBooleans()</A></H2>
6117 <H3><A NAME="10_64_1">Usage</A></H3>
6118 <PRE>
6119 ipp_attribute_t *ippAddBooleans(ipp_t *ipp, ipp_tag_t group,
6120                                 const char *name, int num_values,
6121                                 const char *values);
6122 </PRE>
6123 <H3><A NAME="10_64_2">Arguments</A></H3>
6124 <CENTER>
6125 <TABLE BORDER WIDTH="80%">
6126 <TR><TH>Argument</TH><TH>Description</TH></TR>
6127 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6128 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6129 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6130 <TR><TD>num_values</TD><TD>The number of values</TD></TR>
6131 <TR><TD>values</TD><TD>The boolean values</TD></TR>
6132 </TABLE>
6133 </CENTER>
6134 <H3><A NAME="10_64_3">Returns</A></H3>
6135 <P>A pointer to the new attribute or NULL if the attribute could not be
6136  created.</P>
6137 <H3><A NAME="10_64_4">Description</A></H3>
6138 <P>The <CODE>ippAddBooleans()</CODE> function adds one or more boolean
6139  attribute values to the specified IPP request. If the <CODE>values</CODE>
6140  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE>
6141  false values is created.</P>
6142 <H3><A NAME="10_64_5">Example</A></H3>
6143 <PRE>
6144 #include &lt;cups/ipp.h&gt;
6145
6146 ipp_t *ipp;
6147 char values[10];
6148
6149 ippAddBooleans(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;, 10, values);
6150 </PRE>
6151 <H3><A NAME="10_64_6">See Also</A></H3>
6152 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddDate">
6153  <CODE>ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6154 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6155 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6156 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6157  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6158 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6159 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6160 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6161 ippAddStrings()</CODE></A>
6162 <!-- NEW PAGE -->
6163
6164 <H2><A NAME="ippAddDate">ippAddDate()</A></H2>
6165 <H3><A NAME="10_65_1">Usage</A></H3>
6166 <PRE>
6167 ipp_attribute_t *ippAddDate(ipp_t *ipp, ipp_tag_t group,
6168                             const char *name, ipp_uchar_t *value);
6169 </PRE>
6170 <H3><A NAME="10_65_2">Arguments</A></H3>
6171 <CENTER>
6172 <TABLE BORDER WIDTH="80%">
6173 <TR><TH>Argument</TH><TH>Description</TH></TR>
6174 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6175 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6176 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6177 <TR><TD>value</TD><TD>The date value</TD></TR>
6178 </TABLE>
6179 </CENTER>
6180 <H3><A NAME="10_65_3">Returns</A></H3>
6181 <P>A pointer to the new attribute or NULL if the attribute could not be
6182  created.</P>
6183 <H3><A NAME="10_65_4">Description</A></H3>
6184 <P>The <CODE>ippAddDate()</CODE> function adds a single date-time
6185  attribute value to the specified IPP request.</P>
6186 <H3><A NAME="10_65_5">Example</A></H3>
6187 <PRE>
6188 #include &lt;cups/ipp.h&gt;
6189
6190 ipp_t *ipp;
6191
6192 ippAddDate(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;,
6193            ippTimeToDate(time(NULL));
6194 </PRE>
6195 <H3><A NAME="10_65_6">See Also</A></H3>
6196 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6197  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>
6198 ippAddInteger()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6199 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6200 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6201  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6202 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6203 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6204 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6205 ippAddStrings()</CODE></A>,<A HREF="#ippTimeToDate"> <CODE>
6206 ippTimeToDate()</CODE></A>
6207 <!-- NEW PAGE -->
6208
6209 <H2><A NAME="ippAddInteger">ippAddInteger()</A></H2>
6210 <H3><A NAME="10_66_1">Usage</A></H3>
6211 <PRE>
6212 ipp_attribute_t *ippAddInteger(ipp_t *ipp, ipp_tag_t group,
6213                                ipp_tag_t tag, const char *name,
6214                                int value);
6215 </PRE>
6216 <H3><A NAME="10_66_2">Arguments</A></H3>
6217 <CENTER>
6218 <TABLE BORDER WIDTH="80%">
6219 <TR><TH>Argument</TH><TH>Description</TH></TR>
6220 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6221 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6222 <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or
6223  IPP_TAG_ENUM)</TD></TR>
6224 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6225 <TR><TD>value</TD><TD>The integer value</TD></TR>
6226 </TABLE>
6227 </CENTER>
6228 <H3><A NAME="10_66_3">Returns</A></H3>
6229 <P>A pointer to the new attribute or NULL if the attribute could not be
6230  created.</P>
6231 <H3><A NAME="10_66_4">Description</A></H3>
6232 <P>The <CODE>ippAddInteger()</CODE> function adds a single integer
6233  attribute value to the specified IPP request.</P>
6234 <H3><A NAME="10_66_5">Example</A></H3>
6235 <PRE>
6236 #include &lt;cups/ipp.h&gt;
6237
6238 ipp_t *ipp;
6239
6240 ippAddInteger(ipp, IPP_TAG_OPERATION, &quot;limit&quot;, 100);
6241 </PRE>
6242 <H3><A NAME="10_66_6">See Also</A></H3>
6243 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6244  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6245 ippAddDate()</CODE></A>,<A HREF="#ippAddIntegers"> <CODE>
6246 ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE>
6247 </A>,<A HREF="#ippAddRanges"> <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution">
6248  <CODE>ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6249 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6250 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6251 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6252 ippAddStrings()</CODE></A>
6253 <!-- NEW PAGE -->
6254
6255 <H2><A NAME="ippAddIntegers">ippAddIntegers()</A></H2>
6256 <H3><A NAME="10_67_1">Usage</A></H3>
6257 <PRE>
6258 ipp_attribute_t *ippAddIntegers(ipp_t *ipp, ipp_tag_t group,
6259                                 ipp_tag_t tag, const char *name,
6260                                 int num_values, const int *values);
6261 </PRE>
6262 <H3><A NAME="10_67_2">Arguments</A></H3>
6263 <CENTER>
6264 <TABLE BORDER WIDTH="80%">
6265 <TR><TH>Argument</TH><TH>Description</TH></TR>
6266 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6267 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6268 <TR><TD>tag</TD><TD>The type of integer value (IPP_TAG_INTEGER or
6269  IPP_TAG_ENUM)</TD></TR>
6270 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6271 <TR><TD>num_values</TD><TD>The number of values</TD></TR>
6272 <TR><TD>values</TD><TD>The integer values</TD></TR>
6273 </TABLE>
6274 </CENTER>
6275 <H3><A NAME="10_67_3">Returns</A></H3>
6276 <P>A pointer to the new attribute or NULL if the attribute could not be
6277  created.</P>
6278 <H3><A NAME="10_67_4">Description</A></H3>
6279 <P>The <CODE>ippAddIntegers()</CODE> function adds one or more integer
6280  attribute values to the specified IPP request. If the <CODE>values</CODE>
6281  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE> 0
6282  values is created.</P>
6283 <H3><A NAME="10_67_5">Example</A></H3>
6284 <PRE>
6285 #include &lt;cups/ipp.h&gt;
6286
6287 ipp_t *ipp;
6288 int values[100];
6289
6290 ippAddIntegers(ipp, IPP_TAG_OPERATION, &quot;some-attribute&quot;, 100, values);
6291 </PRE>
6292 <H3><A NAME="10_67_6">See Also</A></H3>
6293 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6294  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6295 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6296 </A>,<A HREF="#ippAddRange"> <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges">
6297  <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6298 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6299 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6300 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6301 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6302 ippAddStrings()</CODE></A>
6303 <!-- NEW PAGE -->
6304
6305 <H2><A NAME="ippAddRange">ippAddRange()</A></H2>
6306 <H3><A NAME="10_68_1">Usage</A></H3>
6307 <PRE>
6308 ipp_attribute_t *ippAddRange(ipp_t *ipp, ipp_tag_t group,
6309                              const char *name, int low,
6310                              int high);
6311 </PRE>
6312 <H3><A NAME="10_68_2">Arguments</A></H3>
6313 <CENTER>
6314 <TABLE BORDER WIDTH="80%">
6315 <TR><TH>Argument</TH><TH>Description</TH></TR>
6316 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6317 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6318 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6319 <TR><TD>low</TD><TD>The lower value</TD></TR>
6320 <TR><TD>high</TD><TD>The higher value</TD></TR>
6321 </TABLE>
6322 </CENTER>
6323 <H3><A NAME="10_68_3">Returns</A></H3>
6324 <P>A pointer to the new attribute or NULL if the attribute could not be
6325  created.</P>
6326 <H3><A NAME="10_68_4">Description</A></H3>
6327 <P>The <CODE>ippAddRange()</CODE> function adds a single range attribute
6328  value to the specified IPP request.</P>
6329 <H3><A NAME="10_68_5">Example</A></H3>
6330 <PRE>
6331 #include &lt;cups/ipp.h&gt;
6332
6333 ipp_t *ipp;
6334
6335 ippAddRange(ipp, IPP_TAG_OPERATION, &quot;page-ranges&quot;, 1, 10);
6336 </PRE>
6337 <H3><A NAME="10_68_6">See Also</A></H3>
6338 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6339  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6340 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6341 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRanges">
6342  <CODE>ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6343 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6344 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6345 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6346 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6347 ippAddStrings()</CODE></A>
6348 <!-- NEW PAGE -->
6349
6350 <H2><A NAME="ippAddRanges">ippAddRanges()</A></H2>
6351 <H3><A NAME="10_69_1">Usage</A></H3>
6352 <PRE>
6353 ipp_attribute_t *ippAddRanges(ipp_t *ipp, ipp_tag_t group,
6354                               const char *name, int num_values,
6355                               const int *lows, const int *highs);
6356 </PRE>
6357 <H3><A NAME="10_69_2">Arguments</A></H3>
6358 <CENTER>
6359 <TABLE BORDER WIDTH="80%">
6360 <TR><TH>Argument</TH><TH>Description</TH></TR>
6361 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6362 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6363 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6364 <TR><TD>num_values</TD><TD>The number of range values</TD></TR>
6365 <TR><TD>lows</TD><TD>The lower values</TD></TR>
6366 <TR><TD>highs</TD><TD>The higher values</TD></TR>
6367 </TABLE>
6368 </CENTER>
6369 <H3><A NAME="10_69_3">Returns</A></H3>
6370 <P>A pointer to the new attribute or NULL if the attribute could not be
6371  created.</P>
6372 <H3><A NAME="10_69_4">Description</A></H3>
6373 <P>The <CODE>ippAddRanges()</CODE> function adds one or more range
6374  attribute values to the specified IPP request. If the <CODE>values</CODE>
6375  pointer is <CODE>NULL</CODE> then an array of <CODE>num_values</CODE>
6376  0,0 ranges is created.</P>
6377 <H3><A NAME="10_69_5">Example</A></H3>
6378 <PRE>
6379 #include &lt;cups/ipp.h&gt;
6380
6381 ipp_t *ipp;
6382 int lows[2];
6383 int highs[2];
6384
6385 ippAddRanges(ipp, IPP_TAG_OPERATION, &quot;page-ranges&quot;, 2, lows, highs);
6386 </PRE>
6387 <H3><A NAME="10_69_6">See Also</A></H3>
6388 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6389  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6390 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6391 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6392  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6393 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6394 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6395 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6396 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6397 ippAddStrings()</CODE></A>
6398 <!-- NEW PAGE -->
6399
6400 <H2><A NAME="ippAddResolution">ippAddResolution()</A></H2>
6401 <H3><A NAME="10_70_1">Usage</A></H3>
6402 <PRE>
6403 ipp_attribute_t *ippAddResolution(ipp_t *ipp, ipp_tag_t group,
6404                                   const char *name, int xres,
6405                                   int yres, ipp_res_t units);
6406 </PRE>
6407 <H3><A NAME="10_70_2">Arguments</A></H3>
6408 <CENTER>
6409 <TABLE BORDER WIDTH="80%">
6410 <TR><TH>Argument</TH><TH>Description</TH></TR>
6411 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6412 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6413 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6414 <TR><TD>xres</TD><TD>The horizontal resolution</TD></TR>
6415 <TR><TD>yres</TD><TD>The vertical resolution</TD></TR>
6416 <TR><TD>units</TD><TD>The resolution units</TD></TR>
6417 </TABLE>
6418 </CENTER>
6419 <H3><A NAME="10_70_3">Returns</A></H3>
6420 <P>A pointer to the new attribute or NULL if the attribute could not be
6421  created.</P>
6422 <H3><A NAME="10_70_4">Description</A></H3>
6423 <P>The <CODE>ippAddResolution()</CODE> function adds a single resolution
6424  attribute value to the specified IPP request.</P>
6425 <H3><A NAME="10_70_5">Example</A></H3>
6426 <PRE>
6427 #include &lt;cups/ipp.h&gt;
6428
6429 ipp_t *ipp;
6430
6431 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;printer-resolution&quot;,
6432               720, 720, IPP_RES_PER_INCH);
6433 </PRE>
6434 <H3><A NAME="10_70_6">See Also</A></H3>
6435 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6436  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6437 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6438 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6439  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6440 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6441 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6442 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6443 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6444 ippAddStrings()</CODE></A>
6445 <!-- NEW PAGE -->
6446
6447 <H2><A NAME="ippAddResolutions">ippAddResolutions()</A></H2>
6448 <H3><A NAME="10_71_1">Usage</A></H3>
6449 <PRE>
6450 ipp_attribute_t *ippAddResolutions(ipp_t *ipp, ipp_tag_t group,
6451                                    const char *name, int num_values,
6452                                    const int *xres, const int *yres,
6453                                    const ipp_res_t *units);
6454 </PRE>
6455 <H3><A NAME="10_71_2">Arguments</A></H3>
6456 <CENTER>
6457 <TABLE BORDER WIDTH="80%">
6458 <TR><TH>Argument</TH><TH>Description</TH></TR>
6459 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6460 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6461 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6462 <TR><TD>num_values</TD><TD>The number of resolution values</TD></TR>
6463 <TR><TD>xres</TD><TD>The horizontal resolutions</TD></TR>
6464 <TR><TD>yres</TD><TD>The vertical resolutions</TD></TR>
6465 <TR><TD>units</TD><TD>The resolution units</TD></TR>
6466 </TABLE>
6467 </CENTER>
6468 <H3><A NAME="10_71_3">Returns</A></H3>
6469 <P>A pointer to the new attribute or NULL if the attribute could not be
6470  created.</P>
6471 <H3><A NAME="10_71_4">Description</A></H3>
6472 <P>The <CODE>ippAddResolutions()</CODE> function adds one or more
6473  resolution attribute values to the specified IPP request. If the <CODE>
6474 values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>
6475 num_values</CODE> 0,0 resolutions is created.</P>
6476 <H3><A NAME="10_71_5">Example</A></H3>
6477 <PRE>
6478 #include &lt;cups/ipp.h&gt;
6479
6480 ipp_t *ipp;
6481 int xres[5];
6482 int yres[5];
6483 ipp_res_t units[5];
6484
6485 ippAddBoolean(ipp, IPP_TAG_OPERATION, &quot;printer-resolutions-supported&quot;,
6486               5, xres, yres, units);
6487 </PRE>
6488 <H3><A NAME="10_71_6">See Also</A></H3>
6489 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6490  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6491 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6492 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6493  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6494 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6495 ippAddResolution()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6496 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6497 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6498 ippAddStrings()</CODE></A>
6499 <!-- NEW PAGE -->
6500
6501 <H2><A NAME="ippAddSeparator">ippAddSeparator()</A></H2>
6502 <H3><A NAME="10_72_1">Usage</A></H3>
6503 <PRE>
6504 ipp_attribute_t *ippAddSeparator(ipp_t *ipp);
6505 </PRE>
6506 <H3><A NAME="10_72_2">Arguments</A></H3>
6507 <CENTER>
6508 <TABLE BORDER WIDTH="80%">
6509 <TR><TH>Argument</TH><TH>Description</TH></TR>
6510 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6511 </TABLE>
6512 </CENTER>
6513 <H3><A NAME="10_72_3">Returns</A></H3>
6514 <P>A pointer to the new separator or NULL if the separator could not be
6515  created.</P>
6516 <H3><A NAME="10_72_4">Description</A></H3>
6517 <P>The <CODE>ippAddSeparator()</CODE> function adds a group separator to
6518  the specified IPP request.</P>
6519 <H3><A NAME="10_72_5">Example</A></H3>
6520 <PRE>
6521 #include &lt;cups/ipp.h&gt;
6522
6523 ipp_t *ipp;
6524
6525 ippAddSeparator(ipp);
6526 </PRE>
6527 <H3><A NAME="10_72_6">See Also</A></H3>
6528 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6529  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6530 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6531 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6532  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6533 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6534 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6535 ippAddResolutions()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6536 ippAddString()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6537 ippAddStrings()</CODE></A>
6538 <!-- NEW PAGE -->
6539
6540 <H2><A NAME="ippAddString">ippAddString()</A></H2>
6541 <H3><A NAME="10_73_1">Usage</A></H3>
6542 <PRE>
6543 ipp_attribute_t *ippAddString(ipp_t *ipp, ipp_tag_t group,
6544                               ipp_tag_t tag, const char *name,
6545                               const char *charset, const char *value);
6546 </PRE>
6547 <H3><A NAME="10_73_2">Arguments</A></H3>
6548 <CENTER>
6549 <TABLE BORDER WIDTH="80%">
6550 <TR><TH>Argument</TH><TH>Description</TH></TR>
6551 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6552 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6553 <TR><TD>tag</TD><TD>The type of string value</TD></TR>
6554 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6555 <TR><TD>charset</TD><TD>The character set for the string</TD></TR>
6556 <TR><TD>value</TD><TD>The string value</TD></TR>
6557 </TABLE>
6558 </CENTER>
6559 <H3><A NAME="10_73_3">Returns</A></H3>
6560 <P>A pointer to the new attribute or NULL if the attribute could not be
6561  created.</P>
6562 <H3><A NAME="10_73_4">Description</A></H3>
6563 <P>The <CODE>ippAddString()</CODE> function adds a single string
6564  attribute value to the specified IPP request. For <CODE>
6565 IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the
6566  charset value is provided with the string to identify the string
6567  encoding used. Otherwise the charset value is ignored.</P>
6568 <H3><A NAME="10_73_5">Example</A></H3>
6569 <PRE>
6570 #include &lt;cups/ipp.h&gt;
6571
6572 ipp_t *ipp;
6573
6574 ippAddString(ipp, IPP_TAG_OPERATION, IPP_TAG_NAME, &quot;job-name&quot;,
6575              NULL, &quot;abc123&quot;);
6576 </PRE>
6577 <H3><A NAME="10_73_6">See Also</A></H3>
6578 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6579  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6580 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6581 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6582  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6583 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6584 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6585 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6586 ippAddSeparator()</CODE></A>,<A HREF="#ippAddStrings"> <CODE>
6587 ippAddStrings()</CODE></A>
6588 <!-- NEW PAGE -->
6589
6590 <H2><A NAME="ippAddStrings">ippAddStrings()</A></H2>
6591 <H3><A NAME="10_74_1">Usage</A></H3>
6592 <PRE>
6593 ipp_attribute_t *ippAddStrings(ipp_t *ipp, ipp_tag_t group,
6594                                ipp_tag_t tag, const char *name,
6595                                int num_values, const char *charset,
6596                                const char **values);
6597 </PRE>
6598 <H3><A NAME="10_74_2">Arguments</A></H3>
6599 <CENTER>
6600 <TABLE BORDER WIDTH="80%">
6601 <TR><TH>Argument</TH><TH>Description</TH></TR>
6602 <TR><TD>ipp</TD><TD>The IPP request</TD></TR>
6603 <TR><TD>group</TD><TD>The IPP group</TD></TR>
6604 <TR><TD>tag</TD><TD>The type of string value</TD></TR>
6605 <TR><TD>name</TD><TD>The name of attribute</TD></TR>
6606 <TR><TD>num_values</TD><TD>The number of strings</TD></TR>
6607 <TR><TD>charset</TD><TD>The character set for the strings</TD></TR>
6608 <TR><TD>values</TD><TD>The string values</TD></TR>
6609 </TABLE>
6610 </CENTER>
6611 <H3><A NAME="10_74_3">Returns</A></H3>
6612 <P>A pointer to the new attribute or NULL if the attribute could not be
6613  created.</P>
6614 <H3><A NAME="10_74_4">Description</A></H3>
6615 <P>The <CODE>ippAddStrings()</CODE> function adds one or more string
6616  attribute values to the specified IPP request. For <CODE>
6617 IPP_TAG_NAMELANG</CODE> and <CODE>IPP_TAG_TEXTLANG</CODE> strings, the
6618  charset value is provided with the strings to identify the string
6619  encoding used. Otherwise the charset value is ignored. If the <CODE>
6620 values</CODE> pointer is <CODE>NULL</CODE> then an array of <CODE>
6621 num_values</CODE> NULL strings is created.</P>
6622 <H3><A NAME="10_74_5">Example</A></H3>
6623 <PRE>
6624 #include &lt;cups/ipp.h&gt;
6625
6626 ipp_t *ipp;
6627 char *values[2] = { &quot;one&quot;, &quot;two&quot; };
6628
6629 ippAddStrings(ipp, IPP_TAG_OPERATION, IPP_TAG_KEYWORD, &quot;attr-name&quot;,
6630               2, NULL, values);
6631 </PRE>
6632 <H3><A NAME="10_74_6">See Also</A></H3>
6633 <A HREF="#ippAddBoolean"> <CODE>ippAddBoolean()</CODE></A>,<A HREF="#ippAddBooleans">
6634  <CODE>ippAddBooleans()</CODE></A>,<A HREF="#ippAddDate"> <CODE>
6635 ippAddDate()</CODE></A>,<A HREF="#ippAddInteger"> <CODE>ippAddInteger()</CODE>
6636 </A>,<A HREF="#ippAddIntegers"> <CODE>ippAddIntegers()</CODE></A>,<A HREF="#ippAddRange">
6637  <CODE>ippAddRange()</CODE></A>,<A HREF="#ippAddRanges"> <CODE>
6638 ippAddRanges()</CODE></A>,<A HREF="#ippAddResolution"> <CODE>
6639 ippAddResolution()</CODE></A>,<A HREF="#ippAddResolutions"> <CODE>
6640 ippAddResolutions()</CODE></A>,<A HREF="#ippAddSeparator"> <CODE>
6641 ippAddSeparator()</CODE></A>,<A HREF="#ippAddString"> <CODE>
6642 ippAddString()</CODE></A>
6643 <!-- NEW PAGE -->
6644
6645 <H2><A NAME="ippDateToTime">ippDateToTime()</A></H2>
6646 <H3><A NAME="10_75_1">Usage</A></H3>
6647 <PRE>
6648 time_t ippDateToTime(const ipp_uchar_t date[11]);
6649 </PRE>
6650 <H3><A NAME="10_75_2">Arguments</A></H3>
6651 <CENTER>
6652 <TABLE BORDER WIDTH="80%">
6653 <TR><TH>Argument</TH><TH>Description</TH></TR>
6654 <TR><TD>date</TD><TD>The IPP date-time value</TD></TR>
6655 </TABLE>
6656 </CENTER>
6657 <H3><A NAME="10_75_3">Returns</A></H3>
6658 <P>A UNIX time value.</P>
6659 <H3><A NAME="10_75_4">Description</A></H3>
6660 <P>The <CODE>ippDateToTime()</CODE> function converts an IPP date-time
6661  value to a UNIX time value.</P>
6662 <H3><A NAME="10_75_5">Example</A></H3>
6663 <PRE>
6664 #include &lt;cups/ipp.h&gt;
6665
6666 ipp_uchar_t date[11];
6667
6668 printf(&quot;UNIX time is %d\n&quot;, ippDateToTime(date));
6669 </PRE>
6670 <H3><A NAME="10_75_6">See Also</A></H3>
6671 <A HREF="#ippTimeToDate"> <CODE>ippTimeToDate()</CODE></A>
6672 <!-- NEW PAGE -->
6673
6674 <H2><A NAME="ippDelete">ippDelete()</A></H2>
6675 <H3><A NAME="10_76_1">Usage</A></H3>
6676 <PRE>
6677 void ippDelete(ipp_t *ipp);
6678 </PRE>
6679 <H3><A NAME="10_76_2">Arguments</A></H3>
6680 <CENTER>
6681 <TABLE BORDER WIDTH="80%">
6682 <TR><TH>Argument</TH><TH>Description</TH></TR>
6683 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6684 </TABLE>
6685 </CENTER>
6686 <H3><A NAME="10_76_3">Description</A></H3>
6687 <P>The <CODE>ippDelete()</CODE> function deletes all memory used by an
6688  IPP request or response.</P>
6689 <H3><A NAME="10_76_4">Example</A></H3>
6690 <PRE>
6691 #include &lt;cups/ipp.h&gt;
6692
6693 ipp_t *ipp;
6694
6695 ippDelete(ipp);
6696 </PRE>
6697 <H3><A NAME="10_76_5">See Also</A></H3>
6698 <A HREF="#ippNew"> <CODE>ippNew()</CODE></A>
6699 <!-- NEW PAGE -->
6700
6701 <H2><A NAME="ippFindAttribute">ippFindAttribute()</A></H2>
6702 <H3><A NAME="10_77_1">Usage</A></H3>
6703 <PRE>
6704 ipp_attribute_t *ippFindAttribute(ipp_t *ipp, const char *name, ipp_tag_t tag);
6705 </PRE>
6706 <H3><A NAME="10_77_2">Arguments</A></H3>
6707 <CENTER>
6708 <TABLE BORDER WIDTH="80%">
6709 <TR><TH>Argument</TH><TH>Description</TH></TR>
6710 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6711 <TR><TD>name</TD><TD>The name of the attribute</TD></TR>
6712 <TR><TD>tag</TD><TD>The required value tag for the attribute or <CODE>
6713 IPP_TAG_ZERO</CODE> for any type of value.</TD></TR>
6714 </TABLE>
6715 </CENTER>
6716 <H3><A NAME="10_77_3">Returns</A></H3>
6717 <P>A pointer to the first occurrence of the requested attribute, or <CODE>
6718 NULL</CODE> if it was not found.</P>
6719 <H3><A NAME="10_77_4">Description</A></H3>
6720 <P><CODE>ippFindAttribute()</CODE> finds the first occurrence of the
6721  named attribute. The <CODE>tag</CODE> parameter restricts the search to
6722  a specific value type - use <CODE>IPP_TAG_ZERO</CODE> to find any value
6723  with the name.</P>
6724 <P>The value tags <CODE>IPP_TAG_NAME</CODE> and <CODE>IPP_TAG_TEXT</CODE>
6725  match the name/text values with or without the language code.</P>
6726 <H3><A NAME="10_77_5">Example</A></H3>
6727 <PRE>
6728 ipp_attribute_t *attr;
6729
6730 attr = ippFindAttribute(response, &quot;printer-state-message&quot;, IPP_TAG_TEXT);
6731 </PRE>
6732 <H3><A NAME="10_77_6">See Also</A></H3>
6733 <A HREF="#cupsDoFileRequest"> <CODE>cupsDoFileRequest()</CODE></A>,<A HREF="#cupsDoRequest">
6734  <CODE>cupsDoRequest()</CODE></A>,<A HREF="#ippDelete"> <CODE>
6735 ippDelete()</CODE></A>,<A HREF="#ippNew"> <CODE>ippNew()</CODE></A>
6736 <!-- NEW PAGE -->
6737
6738 <H2><A NAME="ippLength">ippLength()</A></H2>
6739 <H3><A NAME="10_78_1">Usage</A></H3>
6740 <PRE>
6741 int ippLength(ipp_t *ipp);
6742 </PRE>
6743 <H3><A NAME="10_78_2">Arguments</A></H3>
6744 <CENTER>
6745 <TABLE BORDER WIDTH="80%">
6746 <TR><TH>Argument</TH><TH>Description</TH></TR>
6747 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6748 </TABLE>
6749 </CENTER>
6750 <H3><A NAME="10_78_3">Returns</A></H3>
6751 <P>The total encoded length of the IPP request or response in bytes.</P>
6752 <H3><A NAME="10_78_4">Description</A></H3>
6753 <P><CODE>ippLength()</CODE> returns the length of the IPP request or
6754  response in bytes.</P>
6755 <H3><A NAME="10_78_5">Example</A></H3>
6756 <PRE>
6757 printf(&quot;The length of the response is %d bytes.\n&quot;, ippLength(response));
6758 </PRE>
6759 <H3><A NAME="10_78_6">See Also</A></H3>
6760 <A HREF="#ippDelete"> <CODE>ippDelete()</CODE></A>,<A HREF="#ippNew"> <CODE>
6761 ippNew()</CODE></A>
6762 <!-- NEW PAGE -->
6763
6764 <H2><A NAME="ippNew">ippNew()</A></H2>
6765 <H3><A NAME="10_79_1">Usage</A></H3>
6766 <PRE>
6767 ipp_t *ippNew(void);
6768 </PRE>
6769 <H3><A NAME="10_79_2">Returns</A></H3>
6770 <P>A pointer to a new IPP request or response.</P>
6771 <H3><A NAME="10_79_3">Description</A></H3>
6772 <P>The <CODE>ippNew()</CODE> function creates a new IPP request or
6773  response.</P>
6774 <H3><A NAME="10_79_4">Example</A></H3>
6775 <PRE>
6776 #include &lt;cups/ipp.h&gt;
6777
6778 ipp_t *ipp;
6779
6780 ipp = ippNew();
6781 </PRE>
6782 <H3><A NAME="10_79_5">See Also</A></H3>
6783 <A HREF="#ippDelete"> <CODE>ippDelete()</CODE></A>
6784 <!-- NEW PAGE -->
6785
6786 <H2><A NAME="ippPort">ippPort()</A></H2>
6787 <H3><A NAME="10_80_1">Usage</A></H3>
6788 <PRE>
6789 int ippPort(void);
6790 </PRE>
6791 <H3><A NAME="10_80_2">Returns</A></H3>
6792 <P>The default TCP/IP port number for IPP requests.</P>
6793 <H3><A NAME="10_80_3">Description</A></H3>
6794 <P>The <CODE>ippPort()</CODE> function returns the default IPP port
6795  number for requests.</P>
6796 <H3><A NAME="10_80_4">Example</A></H3>
6797 <PRE>
6798 #include &lt;cups/http.h&gt;
6799 #include &lt;cups/ipp.h&gt;
6800
6801 http_t *http;
6802
6803 http = httpConnect(cupsServer(), ippPort());
6804 </PRE>
6805 <H3><A NAME="10_80_5">See Also</A></H3>
6806 <A HREF="#cupsServer"> <CODE>cupsServer()</CODE></A>,<A HREF="#ippSetPort">
6807  <CODE>ippSetPort()</CODE></A>
6808 <!-- NEW PAGE -->
6809
6810 <H2><A NAME="ippRead">ippRead()</A></H2>
6811 <H3><A NAME="10_81_1">Usage</A></H3>
6812 <PRE>
6813 ipp_state_t ippRead(http_t *http, ipp_t *ipp);
6814 </PRE>
6815 <H3><A NAME="10_81_2">Arguments</A></H3>
6816 <CENTER>
6817 <TABLE BORDER WIDTH="80%">
6818 <TR><TH>Argument</TH><TH>Description</TH></TR>
6819 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6820 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6821 </TABLE>
6822 </CENTER>
6823 <H3><A NAME="10_81_3">Returns</A></H3>
6824 <P>The current read state.</P>
6825 <H3><A NAME="10_81_4">Description</A></H3>
6826 <P>The <CODE>ippRead()</CODE> function reads IPP attributes from the
6827  specified HTTP connection. Programs should continue calling <CODE>
6828 ippRead()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE>
6829  is returned.</P>
6830 <H3><A NAME="10_81_5">Example</A></H3>
6831 <PRE>
6832 #include &lt;cups/http.h&gt;
6833 #include &lt;cups/ipp.h&gt;
6834
6835 http_t *http;
6836 ipp_t *ipp;
6837 ipp_state_t status;
6838
6839 ipp = ippNew();
6840
6841 while ((status = ippRead(http, ipp)) != IPP_ERROR)
6842   if (status == IPP_DATA)
6843     break;
6844
6845 if (status == IPP_DATA)
6846 {
6847   ... read additional non-IPP data using httpRead() ...
6848 }
6849 </PRE>
6850 <H3><A NAME="10_81_6">See Also</A></H3>
6851 <A HREF="#ippWrite"> <CODE>ippWrite()</CODE></A>
6852 <!-- NEW PAGE -->
6853
6854 <H2><A NAME="ippSetPort">ippSetPort()</A></H2>
6855 <H3><A NAME="10_82_1">Usage</A></H3>
6856 <PRE>
6857 void
6858 ippSetPort(int port);
6859 </PRE>
6860 <H3><A NAME="10_82_2">Arguments</A></H3>
6861 <CENTER>
6862 <TABLE BORDER WIDTH="80%">
6863 <TR><TH>Argument</TH><TH>Description</TH></TR>
6864 <TR><TD>port</TD><TD>The port number to use</TD></TR>
6865 </TABLE>
6866 </CENTER>
6867 <H3><A NAME="10_82_3">Description</A></H3>
6868 <P>The <CODE>ippSetPort()</CODE> function sets the default IPP port
6869  number for requests.</P>
6870 <H3><A NAME="10_82_4">Example</A></H3>
6871 <PRE>
6872 #include &lt;cups/http.h&gt;
6873 #include &lt;cups/ipp.h&gt;
6874
6875 ...
6876
6877 ippSetPort(8631);
6878 </PRE>
6879 <H3><A NAME="10_82_5">See Also</A></H3>
6880 <A HREF="#ippPort"> <CODE>ippPort()</CODE></A>
6881 <!-- NEW PAGE -->
6882
6883 <H2><A NAME="ippTimeToDate">ippTimeToDate()</A></H2>
6884 <H3><A NAME="10_83_1">Usage</A></H3>
6885 <PRE>
6886 ipp_uchar_t *ippTimeToDate(time_t time);
6887 </PRE>
6888 <H3><A NAME="10_83_2">Arguments</A></H3>
6889 <CENTER>
6890 <TABLE BORDER WIDTH="80%">
6891 <TR><TH>Argument</TH><TH>Description</TH></TR>
6892 <TR><TD>time</TD><TD>The UNIX time value</TD></TR>
6893 </TABLE>
6894 </CENTER>
6895 <H3><A NAME="10_83_3">Returns</A></H3>
6896 <P>A static pointer to an IPP date-time value.</P>
6897 <H3><A NAME="10_83_4">Description</A></H3>
6898 <P>The <CODE>ippTimeToDate()</CODE> function converts a UNIX time to an
6899  IPP date-time value.</P>
6900 <H3><A NAME="10_83_5">Example</A></H3>
6901 <PRE>
6902 #include &lt;cups/ipp.h&gt;
6903
6904 ipp_uchar_t *date;
6905
6906 date = ippTimeToDate(time(NULL));
6907 </PRE>
6908 <H3><A NAME="10_83_6">See Also</A></H3>
6909 <A HREF="#ippDateToTime"> <CODE>ippDateToTime()</CODE></A>
6910 <!-- NEW PAGE -->
6911
6912 <H2><A NAME="ippWrite">ippWrite()</A></H2>
6913 <H3><A NAME="10_84_1">Usage</A></H3>
6914 <PRE>
6915 ipp_state_t ippWrite(http_t *http, ipp_t *ipp);
6916 </PRE>
6917 <H3><A NAME="10_84_2">Arguments</A></H3>
6918 <CENTER>
6919 <TABLE BORDER WIDTH="80%">
6920 <TR><TH>Argument</TH><TH>Description</TH></TR>
6921 <TR><TD>http</TD><TD>The HTTP connection</TD></TR>
6922 <TR><TD>ipp</TD><TD>The IPP request or response</TD></TR>
6923 </TABLE>
6924 </CENTER>
6925 <H3><A NAME="10_84_3">Returns</A></H3>
6926 <P>The current write state.</P>
6927 <H3><A NAME="10_84_4">Description</A></H3>
6928 <P>The <CODE>ippWrite()</CODE> function writes IPP attributes to the
6929  specified HTTP connection. Programs should continue calling <CODE>
6930 ippWrite()</CODE> until <CODE>IPP_ERROR</CODE> or <CODE>IPP_DATA</CODE>
6931  is returned.</P>
6932 <H3><A NAME="10_84_5">Example</A></H3>
6933 <PRE>
6934 #include &lt;cups/http.h&gt;
6935 #include &lt;cups/ipp.h&gt;
6936
6937 http_t *http;
6938 ipp_t *ipp;
6939 ipp_state_t status;
6940
6941 ipp = ippNew();
6942 ... add attributes ...
6943
6944 while ((status = ippWrite(http, ipp)) != IPP_ERROR)
6945   if (status == IPP_DATA)
6946     break;
6947
6948 if (status == IPP_DATA)
6949 {
6950   ... read additional non-IPP data using httpWrite() ...
6951 }
6952 </PRE>
6953 <H3><A NAME="10_84_6">See Also</A></H3>
6954 <A HREF="#ippRead"> <CODE>ippRead()</CODE></A>
6955 <!-- NEW PAGE -->
6956
6957 <H2><A NAME="ppdClose">ppdClose()</A></H2>
6958 <H3><A NAME="10_85_1">Usage</A></H3>
6959 <PRE>
6960 void ppdClose(ppd_file_t *ppd);
6961 </PRE>
6962 <H3><A NAME="10_85_2">Arguments</A></H3>
6963 <CENTER>
6964 <TABLE BORDER WIDTH="80%">
6965 <TR><TH>Argument</TH><TH>Description</TH></TR>
6966 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
6967 </TABLE>
6968 </CENTER>
6969 <H3><A NAME="10_85_3">Description</A></H3>
6970 <P>The <CODE>ppdClose()</CODE> function frees all memory associated with
6971  the PPD file.</P>
6972 <H3><A NAME="10_85_4">Example</A></H3>
6973 <PRE>
6974 #include &lt;cups/ppd.h&gt;
6975
6976 ppd_file_t *ppd;
6977
6978 ppdClose(ppd);
6979 </PRE>
6980 <H3><A NAME="10_85_5">See Also</A></H3>
6981 <A HREF="#ppdOpen"> <CODE>ppdOpen()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>
6982 ppdOpenFd()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE>
6983 </A>
6984 <!-- NEW PAGE -->
6985
6986 <H2><A NAME="ppdConflicts">ppdConflicts()</A></H2>
6987 <H3><A NAME="10_86_1">Usage</A></H3>
6988 <PRE>
6989 int ppdConflicts(ppd_file_t *ppd);
6990 </PRE>
6991 <H3><A NAME="10_86_2">Arguments</A></H3>
6992 <CENTER>
6993 <TABLE BORDER WIDTH="80%">
6994 <TR><TH>Argument</TH><TH>Description</TH></TR>
6995 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
6996 </TABLE>
6997 </CENTER>
6998 <H3><A NAME="10_86_3">Returns</A></H3>
6999 <P>The number of option conflicts in the file.</P>
7000 <H3><A NAME="10_86_4">Description</A></H3>
7001 <P>The <CODE>ppdConflicts()</CODE> function returns the number of
7002  conflicts with the currently selected options.</P>
7003 <H3><A NAME="10_86_5">Example</A></H3>
7004 <PRE>
7005 #include &lt;cups/ppd.h&gt;
7006
7007 ppd_file_t *ppd;
7008
7009 printf(&quot;%d conflicts\n&quot;, ppdConflicts(ppd));
7010 </PRE>
7011 <H3><A NAME="10_86_6">See Also</A></H3>
7012 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdIsMarked">
7013  <CODE>ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7014 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7015 ppdMarkOption()</CODE></A>
7016 <!-- NEW PAGE -->
7017
7018 <H2><A NAME="ppdEmit">ppdEmit()</A></H2>
7019 <H3><A NAME="10_87_1">Usage</A></H3>
7020 <PRE>
7021 int ppdEmit(ppd_file_t *ppd, FILE *file, ppd_section_t section);
7022 </PRE>
7023 <H3><A NAME="10_87_2">Arguments</A></H3>
7024 <CENTER>
7025 <TABLE BORDER WIDTH="80%">
7026 <TR><TH>Argument</TH><TH>Description</TH></TR>
7027 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7028 <TR><TD>file</TD><TD>The file to write to</TD></TR>
7029 <TR><TD>section</TD><TD>The option section to write</TD></TR>
7030 </TABLE>
7031 </CENTER>
7032 <H3><A NAME="10_87_3">Returns</A></H3>
7033 <P>0 on success, -1 on error.</P>
7034 <H3><A NAME="10_87_4">Description</A></H3>
7035 <P>The <CODE>ppdEmit()</CODE> function sends printer-specific option
7036  commands to the specified file.</P>
7037 <H3><A NAME="10_87_5">Example</A></H3>
7038 <PRE>
7039 #include &lt;cups/ppd.h&gt;
7040
7041 ppd_file_t *ppd;
7042
7043 ppdEmit(ppd, stdout, PPD_ORDER_PAGE);
7044 </PRE>
7045 <H3><A NAME="10_87_6">See Also</A></H3>
7046 <A HREF="#ppdEmitFd"> <CODE>ppdEmitFd()</CODE></A>
7047 <!-- NEW PAGE -->
7048
7049 <H2><A NAME="ppdEmitFd">ppdEmitFd()</A></H2>
7050 <H3><A NAME="10_88_1">Usage</A></H3>
7051 <PRE>
7052 int ppdEmitFd(ppd_file_t *ppd, int fd, ppd_section_t section);
7053 </PRE>
7054 <H3><A NAME="10_88_2">Arguments</A></H3>
7055 <CENTER>
7056 <TABLE BORDER WIDTH="80%">
7057 <TR><TH>Argument</TH><TH>Description</TH></TR>
7058 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7059 <TR><TD>fd</TD><TD>The file descriptor to write to</TD></TR>
7060 <TR><TD>section</TD><TD>The option section to write</TD></TR>
7061 </TABLE>
7062 </CENTER>
7063 <H3><A NAME="10_88_3">Returns</A></H3>
7064 <P>0 on success, -1 on error.</P>
7065 <H3><A NAME="10_88_4">Description</A></H3>
7066 <P>The <CODE>ppdEmitFd()</CODE> function sends printer-specific option
7067  commands to the specified file descriptor.</P>
7068 <H3><A NAME="10_88_5">Example</A></H3>
7069 <PRE>
7070 #include &lt;cups/ppd.h&gt;
7071
7072 ppd_file_t *ppd;
7073
7074 ppdEmitFd(ppd, 1, PPD_ORDER_PAGE);
7075 </PRE>
7076 <H3><A NAME="10_88_6">See Also</A></H3>
7077 <A HREF="#ppdEmit"> <CODE>ppdEmit()</CODE></A>
7078 <!-- NEW PAGE -->
7079
7080 <H2><A NAME="ppdFindChoice">ppdFindChoice()</A></H2>
7081 <H3><A NAME="10_89_1">Usage</A></H3>
7082 <PRE>
7083 ppd_choice_t *ppdFindChoice(ppd_option_t *option, const char *choice);
7084 </PRE>
7085 <H3><A NAME="10_89_2">Arguments</A></H3>
7086 <CENTER>
7087 <TABLE BORDER WIDTH="80%">
7088 <TR><TH>Argument</TH><TH>Description</TH></TR>
7089 <TR><TD>option</TD><TD>A pointer to the option</TD></TR>
7090 <TR><TD>choice</TD><TD>The name of the choice</TD></TR>
7091 </TABLE>
7092 </CENTER>
7093 <H3><A NAME="10_89_3">Returns</A></H3>
7094 <P>A pointer to the choice data or NULL if the choice does not exist.</P>
7095 <H3><A NAME="10_89_4">Description</A></H3>
7096 <P>The <CODE>ppdFindChoice()</CODE> function returns a pointer to the
7097  choice data for the specified option.</P>
7098 <H3><A NAME="10_89_5">Example</A></H3>
7099 <PRE>
7100 #include &lt;cups/ppd.h&gt;
7101
7102 ppd_file_t *ppd;
7103 ppd_option_t *option;
7104 ppd_choice_t *choice;
7105
7106 option = ppdFindOption(ppd, &quot;PageSize&quot;);
7107 choice = ppdFindChoice(option, &quot;Letter&quot;);
7108 </PRE>
7109 <H3><A NAME="10_89_6">See Also</A></H3>
7110 <A HREF="#ppdFindMarkedChoice"> <CODE>ppdFindMarkedChoice()</CODE></A>,<A
7111 HREF="#ppdFindOption"> <CODE>ppdFindOption()</CODE></A>
7112 <!-- NEW PAGE -->
7113
7114 <H2><A NAME="ppdFindMarkedChoice">ppdFindMarkedChoice()</A></H2>
7115 <H3><A NAME="10_90_1">Usage</A></H3>
7116 <PRE>
7117 ppd_choice_t *ppdFindMarkedChoice(ppd_file_t *ppd, const char *keyword);
7118 </PRE>
7119 <H3><A NAME="10_90_2">Arguments</A></H3>
7120 <CENTER>
7121 <TABLE BORDER WIDTH="80%">
7122 <TR><TH>Argument</TH><TH>Description</TH></TR>
7123 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7124 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7125 </TABLE>
7126 </CENTER>
7127 <H3><A NAME="10_90_3">Returns</A></H3>
7128 <P>A pointer to the choice data or NULL if the choice does not exist or
7129  is not marked.</P>
7130 <H3><A NAME="10_90_4">Description</A></H3>
7131 <P>The <CODE>ppdFindMarkedChoice()</CODE> function returns a pointer to
7132  the marked choice data for the specified option.</P>
7133 <H3><A NAME="10_90_5">Example</A></H3>
7134 <PRE>
7135 #include &lt;cups/ppd.h&gt;
7136
7137 ppd_file_t *ppd;
7138 ppd_choice_t *choice;
7139
7140 choice = ppdFindMarkedChoice(ppd, &quot;PageSize&quot;);
7141 </PRE>
7142 <H3><A NAME="10_90_6">See Also</A></H3>
7143 <A HREF="#ppdFindChoice"> <CODE>ppdFindChoice()</CODE></A>,<A HREF="#ppdFindOption">
7144  <CODE>ppdFindOption()</CODE></A>
7145 <!-- NEW PAGE -->
7146
7147 <H2><A NAME="ppdFindOption">ppdFindOption()</A></H2>
7148 <H3><A NAME="10_91_1">Usage</A></H3>
7149 <PRE>
7150 ppd_option_t *ppdFindOption(ppd_file_t *ppd, const char *keyword);
7151 </PRE>
7152 <H3><A NAME="10_91_2">Arguments</A></H3>
7153 <CENTER>
7154 <TABLE BORDER WIDTH="80%">
7155 <TR><TH>Argument</TH><TH>Description</TH></TR>
7156 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7157 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7158 </TABLE>
7159 </CENTER>
7160 <H3><A NAME="10_91_3">Returns</A></H3>
7161 <P>A pointer to the option data or NULL if the option does not exist.</P>
7162 <H3><A NAME="10_91_4">Description</A></H3>
7163 <P>The <CODE>ppdFindOption()</CODE> function returns a pointer to the
7164  option data for the specified option.</P>
7165 <H3><A NAME="10_91_5">Example</A></H3>
7166 <PRE>
7167 #include &lt;cups/ppd.h&gt;
7168
7169 ppd_file_t *ppd;
7170 ppd_option_t *option;
7171
7172 option = ppdFindOption(ppd, &quot;PageSize&quot;);
7173 </PRE>
7174 <H3><A NAME="10_91_6">See Also</A></H3>
7175 <A HREF="#ppdFindChoice"> <CODE>ppdFindChoice()</CODE></A>,<A HREF="#ppdFindMarkedChoice">
7176  <CODE>ppdFindMarkedChoice()</CODE></A>
7177 <!-- NEW PAGE -->
7178
7179 <H2><A NAME="ppdIsMarked">ppdIsMarked()</A></H2>
7180 <H3><A NAME="10_92_1">Usage</A></H3>
7181 <PRE>
7182 int ppdIsMarked(ppd_file_t *ppd, const char *keyword, char char *choice);
7183 </PRE>
7184 <H3><A NAME="10_92_2">Arguments</A></H3>
7185 <CENTER>
7186 <TABLE BORDER WIDTH="80%">
7187 <TR><TH>Argument</TH><TH>Description</TH></TR>
7188 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7189 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7190 <TR><TD>choice</TD><TD>The name of the option choice</TD></TR>
7191 </TABLE>
7192 </CENTER>
7193 <H3><A NAME="10_92_3">Returns</A></H3>
7194 <P>1 if the choice is marked, 0 otherwise.</P>
7195 <H3><A NAME="10_92_4">Description</A></H3>
7196 <P>The <CODE>ppdIsMarked()</CODE> function returns whether or not the
7197  specified option choice is marked.</P>
7198 <H3><A NAME="10_92_5">Example</A></H3>
7199 <PRE>
7200 #include &lt;cups/ppd.h&gt;
7201
7202 ppd_file_t *ppd;
7203
7204 printf(&quot;Letter size %s selected.\n&quot;,
7205        ppdIsMarked(ppd, &quot;PageSize&quot;, &quot;Letter&quot;) ? &quot;is&quot; : &quot;is not&quot;);
7206 </PRE>
7207 <H3><A NAME="10_92_6">See Also</A></H3>
7208 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7209  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7210 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7211 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7212 ppdMarkOption()</CODE></A>
7213 <!-- NEW PAGE -->
7214
7215 <H2><A NAME="ppdMarkDefaults">ppdMarkDefaults()</A></H2>
7216 <H3><A NAME="10_93_1">Usage</A></H3>
7217 <PRE>
7218 void ppdMarkDefaults(ppd_file_t *ppd);
7219 </PRE>
7220 <H3><A NAME="10_93_2">Arguments</A></H3>
7221 <CENTER>
7222 <TABLE BORDER WIDTH="80%">
7223 <TR><TH>Argument</TH><TH>Description</TH></TR>
7224 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7225 </TABLE>
7226 </CENTER>
7227 <H3><A NAME="10_93_3">Description</A></H3>
7228 <P>The <CODE>ppdMarkDefaults()</CODE> function marks all of the default
7229  choices in the PPD file.</P>
7230 <H3><A NAME="10_93_4">Example</A></H3>
7231 <PRE>
7232 #include &lt;cups/ppd.h&gt;
7233
7234 ppd_file_t *ppd;
7235
7236 ppdMarkDefaults(ppd);
7237 </PRE>
7238 <H3><A NAME="10_93_5">See Also</A></H3>
7239 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7240  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7241 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7242 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7243 ppdMarkOption()</CODE></A>
7244 <!-- NEW PAGE -->
7245
7246 <H2><A NAME="ppdMarkOption">ppdMarkOption()</A></H2>
7247 <H3><A NAME="10_94_1">Usage</A></H3>
7248 <PRE>
7249 int ppdMarkOption(ppd_file_t *ppd, const char *keyword, const char *choice);
7250 </PRE>
7251 <H3><A NAME="10_94_2">Arguments</A></H3>
7252 <CENTER>
7253 <TABLE BORDER WIDTH="80%">
7254 <TR><TH>Argument</TH><TH>Description</TH></TR>
7255 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7256 <TR><TD>keyword</TD><TD>The name of the option</TD></TR>
7257 <TR><TD>choice</TD><TD>The name of the choice</TD></TR>
7258 </TABLE>
7259 </CENTER>
7260 <H3><A NAME="10_94_3">Returns</A></H3>
7261 <P>The number of conflicts in the PPD file.</P>
7262 <H3><A NAME="10_94_4">Description</A></H3>
7263 <P>The <CODE>ppdMarkOption()</CODE> function marks the specified option
7264  choice.</P>
7265 <H3><A NAME="10_94_5">Example</A></H3>
7266 <PRE>
7267 #include &lt;cups/ppd.h&gt;
7268
7269 ppd_file_t *ppd;
7270
7271 ppdMarkOption(ppd, &quot;PageSize&quot;, &quot;Letter&quot;);
7272 </PRE>
7273 <H3><A NAME="10_94_6">See Also</A></H3>
7274 <A HREF="#cupsMarkOptions"> <CODE>cupsMarkOptions()</CODE></A>,<A HREF="#ppdConflicts">
7275  <CODE>ppdConflicts()</CODE></A>,<A HREF="#ppdIsMarked"> <CODE>
7276 ppdIsMarked()</CODE></A>,<A HREF="#ppdMarkDefaults"> <CODE>
7277 ppdMarkDefaults()</CODE></A>,<A HREF="#ppdMarkOption"> <CODE>
7278 ppdMarkOption()</CODE></A>
7279 <!-- NEW PAGE -->
7280
7281 <H2><A NAME="ppdOpen">ppdOpen()</A></H2>
7282 <H3><A NAME="10_95_1">Usage</A></H3>
7283 <PRE>
7284 ppd_file_t *ppdOpen(FILE *file);
7285 </PRE>
7286 <H3><A NAME="10_95_2">Arguments</A></H3>
7287 <CENTER>
7288 <TABLE BORDER WIDTH="80%">
7289 <TR><TH>Argument</TH><TH>Description</TH></TR>
7290 <TR><TD>file</TD><TD>The file to read from</TD></TR>
7291 </TABLE>
7292 </CENTER>
7293 <H3><A NAME="10_95_3">Returns</A></H3>
7294 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7295  be read.</P>
7296 <H3><A NAME="10_95_4">Description</A></H3>
7297 <P>The <CODE>ppdOpen()</CODE> function reads a PPD file from the
7298  specified file into memory.</P>
7299 <H3><A NAME="10_95_5">Example</A></H3>
7300 <PRE>
7301 #include &lt;cups/ppd.h&gt;
7302
7303 ppd_file_t *ppd;
7304 FILE *file;
7305
7306 file = fopen(&quot;filename.ppd&quot;, &quot;rb&quot;);
7307 ppd = ppdOpen(file);
7308 fclose(file);
7309 </PRE>
7310 <H3><A NAME="10_95_6">See Also</A></H3>
7311 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>
7312 ppdOpenFd()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE>
7313 </A>
7314 <!-- NEW PAGE -->
7315
7316 <H2><A NAME="ppdOpenFd">ppdOpenFd()</A></H2>
7317 <H3><A NAME="10_96_1">Usage</A></H3>
7318 <PRE>
7319 ppd_file_t *ppdOpenFd(int fd);
7320 </PRE>
7321 <H3><A NAME="10_96_2">Arguments</A></H3>
7322 <CENTER>
7323 <TABLE BORDER WIDTH="80%">
7324 <TR><TH>Argument</TH><TH>Description</TH></TR>
7325 <TR><TD>fd</TD><TD>The file descriptor to read from</TD></TR>
7326 </TABLE>
7327 </CENTER>
7328 <H3><A NAME="10_96_3">Returns</A></H3>
7329 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7330  be read.</P>
7331 <H3><A NAME="10_96_4">Description</A></H3>
7332 <P>The <CODE>ppdOpenFd()</CODE> function reads a PPD file from the
7333  specified file descriptor into memory.</P>
7334 <H3><A NAME="10_96_5">Example</A></H3>
7335 <PRE>
7336 #include &lt;cups/ppd.h&gt;
7337
7338 ppd_file_t *ppd;
7339 int        fd;
7340
7341 fd = open(&quot;filename.ppd&quot;, O_RDONLY);
7342 ppd = ppdOpenFd(fd);
7343 close(fd);
7344 </PRE>
7345 <H3><A NAME="10_96_6">See Also</A></H3>
7346 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpen"> <CODE>
7347 ppdOpen()</CODE></A>,<A HREF="#ppdOpenFile"> <CODE>ppdOpenFile()</CODE></A>
7348 <!-- NEW PAGE -->
7349
7350 <H2><A NAME="ppdOpenFile">ppdOpenFile()</A></H2>
7351 <H3><A NAME="10_97_1">Usage</A></H3>
7352 <PRE>
7353 ppd_file_t *ppdOpenFile(const char *filename);
7354 </PRE>
7355 <H3><A NAME="10_97_2">Arguments</A></H3>
7356 <CENTER>
7357 <TABLE BORDER WIDTH="80%">
7358 <TR><TH>Argument</TH><TH>Description</TH></TR>
7359 <TR><TD>filename</TD><TD>The name of the file to read from</TD></TR>
7360 </TABLE>
7361 </CENTER>
7362 <H3><A NAME="10_97_3">Returns</A></H3>
7363 <P>A pointer to a PPD file structure or NULL if the PPD file could not
7364  be read.</P>
7365 <H3><A NAME="10_97_4">Description</A></H3>
7366 <P>The <CODE>ppdOpenFile()</CODE> function reads a PPD file from the
7367  named file into memory.</P>
7368 <H3><A NAME="10_97_5">Example</A></H3>
7369 <PRE>
7370 #include &lt;cups/ppd.h&gt;
7371
7372 ppd_file_t *ppd;
7373
7374 ppd = ppdOpenFile(&quot;filename.ppd&quot;);
7375 </PRE>
7376 <H3><A NAME="10_97_6">See Also</A></H3>
7377 <A HREF="#ppdClose"> <CODE>ppdClose()</CODE></A>,<A HREF="#ppdOpen"> <CODE>
7378 ppdOpen()</CODE></A>,<A HREF="#ppdOpenFd"> <CODE>ppdOpenFd()</CODE></A>
7379 <!-- NEW PAGE -->
7380
7381 <H2><A NAME="ppdPageLength">ppdPageLength()</A></H2>
7382 <H3><A NAME="10_98_1">Usage</A></H3>
7383 <PRE>
7384 float ppdPageLength(ppd_file_t *ppd, const char *name);
7385 </PRE>
7386 <H3><A NAME="10_98_2">Arguments</A></H3>
7387 <CENTER>
7388 <TABLE BORDER WIDTH="80%">
7389 <TR><TH>Argument</TH><TH>Description</TH></TR>
7390 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7391 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7392 </TABLE>
7393 </CENTER>
7394 <H3><A NAME="10_98_3">Returns</A></H3>
7395 <P>The length of the specified page size in points or 0 if the page size
7396  does not exist.</P>
7397 <H3><A NAME="10_98_4">Description</A></H3>
7398 <P>The <CODE>ppdPageLength()</CODE> function returns the page length of
7399  the specified page size.</P>
7400 <H3><A NAME="10_98_5">Example</A></H3>
7401 <PRE>
7402 #include &lt;cups/ppd.h&gt;
7403
7404 ppd_file_t *ppd;
7405
7406 printf(&quot;Length = %.0f\n&quot;, ppdPageLength(ppd, &quot;Letter&quot;));
7407 </PRE>
7408 <H3><A NAME="10_98_6">See Also</A></H3>
7409 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageSize">
7410  <CODE>ppdPageSize()</CODE></A>,<A HREF="#ppdPageWidth"> <CODE>
7411 ppdPageWidth()</CODE></A>
7412 <!-- NEW PAGE -->
7413
7414 <H2><A NAME="ppdPageSize">ppdPageSize()</A></H2>
7415 <H3><A NAME="10_99_1">Usage</A></H3>
7416 <PRE>
7417 ppd_size_t *ppdPageSize(ppd_file_t *ppd, const char *name);
7418 </PRE>
7419 <H3><A NAME="10_99_2">Arguments</A></H3>
7420 <CENTER>
7421 <TABLE BORDER WIDTH="80%">
7422 <TR><TH>Argument</TH><TH>Description</TH></TR>
7423 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7424 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7425 </TABLE>
7426 </CENTER>
7427 <H3><A NAME="10_99_3">Returns</A></H3>
7428 <P>A pointer to the page size record of the specified page size in
7429  points or NULL if the page size does not exist.</P>
7430 <H3><A NAME="10_99_4">Description</A></H3>
7431 <P>The <CODE>ppdPageSize()</CODE> function returns the page size record
7432  for the specified page size.</P>
7433 <H3><A NAME="10_99_5">Example</A></H3>
7434 <PRE>
7435 #include &lt;cups/ppd.h&gt;
7436
7437 ppd_file_t *ppd;
7438 ppd_size_t *size;
7439
7440 size = ppdPageSize(ppd, &quot;Letter&quot;);
7441 if (size != NULL)
7442 {
7443   printf(&quot; Width = %.0f\n&quot;, size-&gt;width);
7444   printf(&quot;Length = %.0f\n&quot;, size-&gt;length);
7445   printf(&quot;  Left = %.0f\n&quot;, size-&gt;left);
7446   printf(&quot; Right = %.0f\n&quot;, size-&gt;right);
7447   printf(&quot;Bottom = %.0f\n&quot;, size-&gt;bottom);
7448   printf(&quot;   Top = %.0f\n&quot;, size-&gt;top);
7449 }
7450 </PRE>
7451 <H3><A NAME="10_99_6">See Also</A></H3>
7452 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageWidth">
7453  <CODE>ppdPageWidth()</CODE></A>
7454 <!-- NEW PAGE -->
7455
7456 <H2><A NAME="ppdPageWidth">ppdPageWidth()</A></H2>
7457 <H3><A NAME="10_100_1">Usage</A></H3>
7458 <PRE>
7459 float ppdPageWidth(ppd_file_t *ppd, const char *name);
7460 </PRE>
7461 <H3><A NAME="10_100_2">Arguments</A></H3>
7462 <CENTER>
7463 <TABLE BORDER WIDTH="80%">
7464 <TR><TH>Argument</TH><TH>Description</TH></TR>
7465 <TR><TD>ppd</TD><TD>The PPD file</TD></TR>
7466 <TR><TD>name</TD><TD>The name of the page size</TD></TR>
7467 </TABLE>
7468 </CENTER>
7469 <H3><A NAME="10_100_3">Returns</A></H3>
7470 <P>The width of the specified page size in points or 0 if the page size
7471  does not exist.</P>
7472 <H3><A NAME="10_100_4">Description</A></H3>
7473 <P>The <CODE>ppdPageWidth()</CODE> function returns the page width of
7474  the specified page size.</P>
7475 <H3><A NAME="10_100_5">Example</A></H3>
7476 <PRE>
7477 #include &lt;cups/ppd.h&gt;
7478
7479 ppd_file_t *ppd;
7480
7481 printf(&quot;Width = %.0f\n&quot;, ppdPageWidth(ppd, &quot;Letter&quot;));
7482 </PRE>
7483 <H3><A NAME="10_100_6">See Also</A></H3>
7484 <A HREF="#ppdPageLength"> <CODE>ppdPageLength()</CODE></A>,<A HREF="#ppdPageSize">
7485  <CODE>ppdPageSize()</CODE></A></BODY>
7486 </HTML>